Skip to content

acsys.dpm

Jump to bottom
Beau Harrison edited this page Nov 9, 2022 · 10 revisions

This package lets scripts interact with the ACSys Data Pool Manager (DPM). The DPM service can return live, accelerator readings from both ACNET and EPICS devices. It also gives access to data logger data and allows a script to perform settings (to accelerator devices.)

This API is based upon the one we provided in our Python 2.7 library and tries to be somewhat compatible with it. Future versions may try to incorporate more async concepts. We welcome suggestions for improving this API.

An acsys.dpm_tutorial is provided.

NOTE: This page documents the v0.x branch of the acsys package.

API Reference

Classes

DPM

An instance of the DPM class maintains a connection to a remote Data Pool Manager, along with the current configuration of the connection. These objects allow you to add devices to read, start and stop data acquisition, and even perform settings.

DPM()

Scripts don't create DPM instances. They get them from the DPMContext() in async-with statements.

.add_entries(entries) - async method

A convenience method. entries is a list of tag/drf pairs which will be fed to .add_entry().

.add_entry(tag, drf) - async method

Adds an acquisition request to the set. tag is an integer that identifies this request. It will be provided when data is returned so the script can route the value correctly. drf is a string describing the acquisition request using the DRF format.

.apply_settings(settings) - async method

Allows a script to set control system devices. Before settings can be done, two steps need to be done:

  • The devices to be set need to have been added using .add_entry().
  • Settings need to be enabled (using .enable_settings())

The settings parameter is a list of tag/value pairs. The tag refers to the tag associated with a device request in a previous call to .add_entry(). The value can be a binary, a float, a string, or an array of floats. DPM will return an error if the wrong type is sent to the device.

If this method returns successfully, it only means DPM received the request. Any error statuses will get reported in the DPM object iterator.

.clear_list() - async method

Clears the set of acquisition requests. This is the quickest way to empty the set. This doesn't affect any acquisition in progress; the change will only be seen when .start() is called.

.enable_settings() - async method

Makes a request to the DPM to allow settings. This method accesses the Kerberos credentials of the user account running the script. If the credentials are valid and this method returns successfully, the script may use .apply_settings() to make settings.

.get_entry(tag)

Retrieves the DRF string associated with tag.

.remove_entry(tag) - async method

Removes the entry associated with the tag from the set of requests. This doesn't affect any acquisition in progress; the change will only be seen when .start() is called.

.replies(tmo=None) - async method (available in v0.10.0)

Returns an async generator which yields the replies from DPM. The optional parameter, tmo, specifies a timeout between replies. If this time is exceeded, an asyncio.TimeoutError is raised.

The generator will return ItemData and ItemStatus objects. Each of these objects has a .tag property indicating to which DRF request this object is associated. Use the .is_reading_for() and .is_status_for() methods of these classes to recognize them (instead of using isinstance() or hasattr().)

.start() - async method

Stops acquisition, if it was active, and starts data acquisition using the latest set of requests built using .add_entry(), .add_entries(), .remove_entry(), and .clear_list().

.stop() - async method

Stops data acquisition. The current list of requests is kept and can be restarted with .start(). Due to the asynchronous nature of network communications, there may still be a small number of readings that are delivered after this method is called.

DPMContext

DPMContext(con, *, dpm_node=None)

Creates a context manager class which sets up the environment for using a DPM. con is an acsys.Connection object. dpm_node is an optional parameter. If defined, it is a string containing the node name hosting the DPM to be used. If it isn't provided, service discovery is used to pick an appropriate DPM. Forcing a DPM node is mainly used when debugging new DPM features; most scripts should not specify a DPM.

DPMContext objects are to be used in async-with statements, in which they return a DPM object to be used in the statement's scope. When the async-with block is exited, all DPM resources will be freed.

async def my_app(con):
    async with DPMContext(con) as dpm:
        # Use 'dpm' object here.

    # 'dpm' resources are freed here
    return

NOTE: Creating DPMContext objects is relatively expensive since it needs to do some network chit chat. If you are looping through functions that need access to Data Pool Services, it's better form to pass in the dpm object obtained from the async-with-statement rather than creating new DPMContext objects over and over.

ItemData

ItemData(tag, stamp, cycle, data, micros=None)

Readings from the control system are returned in instances of this class. Scripts don't create instances.

.is_reading_for(*tags)

Returns True if the .tag property is found in the passed list of tags.

.is_status_for(*tags)

This method always returns False for instances of this class.

.tag - property

.stamp - property

.cycle - property

.data - property

.meta - property

Contains a dictionary of meta-information: di holds the device index, name holds the device name, desc is the description, units is the units, and format_hint is an integer indicating how the data should be formatted. We need to ask Brian what this value means. The units field is optional: for RAW readings, it doesn't exist; for primary scaling, it's primary units; and for common transforms, it's the common units.

ItemStatus

ItemStatus(tag, status)

Status information are returned in instances of this class. Scripts don't create instances.

.is_reading_for(*tags)

This method always returns False for instances of this class.

.is_status_for(*tags)

Returns True if the .tag property is found in the passed list of tags.

.tag - property

This field indicates the DRF request with which this status message is associated.

.status - property

The error status reported for the DRF item.

Functions

These are globally available functions defined in this module.

available_dpms(con)

Returns a list of node names hosting a DPM. If no DPMs are running, an empty list is returned.

find_dpm(con, *, node=None)

If node_ is None, this function performs a service discovery to find an available DPM. If one is found, its name is returned. If no DPMs are found, None is returned.

If node_ is set to a node name, the node is queried to see if an actual DPM is running. If so, the name is returned. If not, None is returned.

Clone this wiki locally