PyEpics: Epics Channel Access for Python

# Devices: collections of PVs

## Overview

The `device` module provides a simple interface to a collection of PVs. Here an epics `device.Device` is an object holding a set of PVs, all sharing a prefix, but having many attributes. Many PVs will have names made up of prefix+attribute, with a common prefix for several related PVs. This almost describes an Epics Record, but as it is concerned only with PV names, the mapping to an Epics Record is not exact. On the other hand, the concept of a device is more flexible than a predefined Epics Record as it can actually hold PVs from several different records.:

    motor1 = epics.Device('XXX:motor1.', attrs=('VAL', 'RBV', 'DESC', 'RVAL',
                                               'LVIO', 'HLS', 'LLS'))
    motor1.put('VAL', 1)
    print(f"Motor {motor1.get('DESC')} = {motor1.get('RBV')}")

    motor1.VAL = 0
    print(f'Motor {motor1.DESC} = {motor1.RBV}')

While useful on its own like this, the real point of a device is as a base class, to be inherited and extended. In fact, there is a more sophisticated Motor device described below at Epics Motor Device

class device.Device(prefix=None[, delim=''[, attrs=None]])

The attribute PVs are built as needed and held in an internal buffer `self._pvs`. This class is kept intentionally simple so that it may be subclassed.

To pre-load attribute names on initialization, provide a list or tuple of attributes with the attr option.

Note that prefix is actually optional. When left off, this class can be used as an arbitrary container of PVs, or to turn any subclass into an epics Device.

In general, PV names will be mapped as prefix+delim+attr. See `add_pv()` for details of how to override this.

device.PV(attr[, connect=True[, **kw]]])

  returns the PV object for a device attribute. The connect argument and any other keyword arguments are passed to `epics.PV()`.

device.put(attr, value[, wait=False[, timeout=10.0]])

  put an attribute value, optionally wait for completion or up to a supplied timeout value

device.get(attr[, as_string=False])

  get an attribute value, option as_string returns a string representation

device.add_callback(attr, callback)

  add a callback function to an attribute PV, so that the callback function will be run when the at tribute’s value changes

device.add_pv(pvname[, attr=None[, **kw]])

  adds an explicitly names `epics.PV()` to the device even though it may violate the normal naming rules (in which attr is mapped to epics.PV(prefix+delim+attr). That is, one can say:

      import epics
      m1 = epics.Device('XXX:m1', delim='.')
      m1.add_pv('XXX:m2.VAL', attr='other')
      print(m1.VAL)     # print value of XXX:m1.VAL
      print(m1.other)   # prints value of XXX:m2.VAL

device.save_state()

  return a dictionary of all current values – the ‘’current state’’.

device.restore_state(state)

  restores a saved state, as saved with `save_state()`

device.write_state(fname[, state=None])

  write a saved state to a file. If no state is provide, the current state is written.

device.read_state(fname[, restore=False])

  reads a state from a file, as written with `write_state()`, and returns it. If ‘’restore’’ is `True`, the read state will be restored.

device._pvs

  a dictionary of PVs making up the device.

## Epics Motor Device

The Epics Motor record has over 100 fields associated with it. Of course, it is often preferable to think of 1 Motor with many attributes than 100 or so separate PVs. Many of the fields of the Motor record are interrelated and influence other settings, including limits on the range of motion which need to be respected, and which may send notifications when they are violated. Thus, there is a fair amount of functionality for a Motor. Typically, the user just wants to move the motor by setting its drive position, but a fully enabled Motor should allow the use to change and read many of the Motor parameters.

The `Motor` class helps the user create and use Epics motors. A simple example use would be:

    import epics
    m1 = epics.Motor('XXX:m1')

    print(f'Motor: {m1.DESC} Currently at {m1.RBV}')

    m1.tweak_val = 0.10
    m1.move(0.0, dial=True, wait=True)

    for i in range(10):
        m1.tweak(direction='forward', wait=True)
        time.sleep(1.0)
        print(f'Motor: {m1.DESC} Currently at {m1.RBV}')

Which will step the motor through a set of positions. You’ll notice a few features for Motor:

> 1. Motors can use English-name aliases for attributes for fields of the motor record. Thus ‘VAL’ can be spelled ‘drive’ and ‘DESC’ can be ‘description’. The Table of Motor Attributes give the list of names that can be used.

> 2. The methods for setting positions can use the User, Dial, or Step coordinate system, and can wait for completion.

### The `epics.Motor` class

class motor.Motor(pvname[, timeout=30.])

  create a Motor object for a named Epics Process Variable.

  Parameters:

    - pvname (string) – prefix name (no ‘.VAL’ needed!) of Epics Process Variable for a Motor

    - timeout (float) – time (in seconds) to wait before giving up trying to connect.

Once created, a Motor should be ready to use.

    >>> from epics import Motor
    >>> m = Motor('XX:m1')
    >>> print(m.drive, m.description, m.slew_speed)
    1.030 Fine X 5.0
    >>> print(m.get('device_type', as_string=True))
    'asynMotor'

A Motor has very many fields. Only a few of them are created on initialization – the rest are retrieved as needed. The motor fields can be retrieved either with an attribute or with the `get()` method. A full list of Motor attributes and their aliases for the motor record is given in Table of Motor Attributes.

> Table of Aliases for attributes for the epics `Motor` class, and the corresponding attribute name of the Motor Record field.

alias | Motor Record field |  | alias | Motor Record field
--- | --- | --- | --- | ---
disabled | _able.VAL |  | moving | MOVN
acceleration | ACCL |  | resolution | MRES
back_accel | BACC |  | motor_status | MSTA
backlash | BDST |  | offset | OFF
back_speed | BVEL |  | output_mode | OMSL
card | CARD |  | output | OUT
dial_high_limit | DHLM |  | prop_gain | PCOF
direction | DIR |  | precision | PREC
dial_low_limit | DLLM |  | readback | RBV
settle_time | DLY |  | retry_max | RTRY
done_moving | DMOV |  | retry_count | RCNT
dial_readback | DRBV |  | retry_deadband | RDBD
description | DESC |  | dial_difference | RDIF
dial_drive | DVAL |  | raw_encoder_pos | REP
units | EGU |  | raw_high_limit | RHLS
encoder_step | ERES |  | raw_low_limit | RLLS
freeze_offset | FOFF |  | relative_value | RLV
move_fraction | FRAC |  | raw_motor_pos | RMP
hi_severity | HHSV |  | raw_readback | RRBV
hi_alarm | HIGH |  | readback_res | RRES
hihi_alarm | HIHI |  | raw_drive | RVAL
high_limit | HLM |  | dial_speed | RVEL
high_limit_set | HLS |  | s_speed | S
hw_limit | HLSV |  | s_back_speed | SBAK
home_forward | HOMF |  | s_base_speed | SBAS
home_reverse | HOMR |  | s_max_speed | SMAX
high_op_range | HOPR |  | set | SET
high_severity | HSV |  | stop_go | SPMG
integral_gain | ICOF |  | s_revolutions | SREV
jog_accel | JAR |  | stop | STOP
jog_forward | JOGF |  | t_direction | TDIR
jog_reverse | JOGR |  | tweak_forward | TWF
jog_speed | JVEL |  | tweak_reverse | TWR
last_dial_val | LDVL |  | tweak_val | TWV
low_limit | LLM |  | use_encoder | UEIP
low_limit_set | LLS |  | u_revolutions | UREV
lo_severity | LLSV |  | use_rdbl | URIP
lolo_alarm | LOLO |  | drive | VAL
low_op_range | LOPR |  | base_speed | VBAS
low_alarm | LOW |  | slew_speed | VELO
last_rel_val | LRLV |  | version | VERS
last_dial_drive | LRVL |  | max_speed | VMAX
last_SPMG | LSPG |  | use_home | ATHM
low_severity | LSV |  | deriv_gain | DCOF

### methods for `epics.Motor`

motor.get(attr[, as_string=False])

  sets a field attribute for the motor.

  Parameters:

    - attr (string (from table above)) – attribute name

    - as_string (`True`/ `False`) – whether to return string value.

Note that `get()` can return the string value, while fetching the attribute cannot do so:

    >>> m = epics.Motor('XXX:m1')
    >>> print(m.device_type)
    0
    >>> print(m.get('device_type', as_string=True))
    'asynMotor'

motor.put(attr, value[, wait=False[, timeout=30]])

  sets a field attribute for the motor.

  Parameters:

    - attr (string (from table above)) – attribute name

    - value – value for attribute

    - wait (`True`/`False`) – whether to wait for completion.

    - timeout (float) – time (in seconds) to wait before giving up trying to connect.

motor.check_limits()

  checks whether the current motor position is causing a motor limit violation, and raises a MotorLimitException if it is.

  returns `None` if there is no limit violation.

motor.within_limits(value[, limits='user'])

  checks whether a target value would be a limit violation.

  Parameters:

    - value – target value

    - limits (string) – one of ‘user’, ‘dial’, or ‘raw’ for which limits to consider

  Return type:

    `True`/`False`

motor.move(val=None[, relative=None[, wait=False[, timeout=300.0[, dial=False[, raw=False[, ignore_limits=False[, confirm_move=False]]]]]]])

  moves motor to specified drive position.

  Parameters:

    - val – value to move to (float) [Must be provided]

    - relative – move relative to current position (T/F) [F]

    - wait – whether to wait for move to complete (T/F) [F]

    - timeout – max time for move to complete (in seconds) [300]

    - dial – use dial coordinates (T/F) [F]

    - raw – use raw coordinates (T/F) [F]

    - ignore_limits – try move without regard to limits (T/F) [F]

    - confirm_move – try to confirm that move has begun (when wait=False) (T/F) [F]

  Return type:

    integer

  Returns an integer value, according the table below. Note that a return value of 0 with wait=False does not really guarantee a successful move, just that a move request was issued. If you’re interested in checking that a requested move really did start without waiting for the move to complete, you may want to use the confirm_move=True option.

> Table of return values from `move()`.

> return value | meaning
> --- | ---
> -13 | invalid value (cannot convert to float). Move not attempted.
> -12 | target value outside soft limits. Move not attempted.
> -11 | drive PV is not connected: Move not attempted.
> -8 | move started, but timed-out.
> -7 | move started, timed-out, but appears done.
> -5 | move started, unexpected return value from `put()`
> -4 | move-with-wait finished, soft limit violation seen.
> -3 | move-with-wait finished, hard limit violation seen.
> 0 | move-with-wait finish OK.
> 0 | move-without-wait executed, not confirmed.
> 1 | move-without-wait executed, move confirmed.
> 3 | move-without-wait finished, hard limit violation seen.
> 4 | move-without-wait finished, soft limit violation seen.

motor.tweak(direction='forward'[, wait=False[, timeout=300.]])

  move the motor by the current tweak value

  Parameters:

    - direction (string: 'forward' (default) or 'reverse') – direction of motion

    - wait (`True`/`False`) – whether to wait for completion

    - timeout (float) – max time for move to complete (in seconds) [default=300]

motor.get_position(readback=False[, dial=False[, raw=False]])

  Returns the motor position in user, dial or raw coordinates.

  Parameters:

    - readback – whether to return the readback position in the desired coordinate system. The default is to return the drive position of the motor.

    - dial – whether to return the position in dial coordinates. The default is user coordinates.

    - raw – whether to return the raw position. The default is user coordinates.

  The “raw” and “dial” keywords are mutually exclusive. The “readback” keyword can be used in user, dial or raw coordinates.

motor.set_position(position[ dial=False[, raw=False]])

  set (that is, redefine) the current position to supplied value.

  Parameters:

    - position – The new motor position

    - dial – whether to set in dial coordinates. The default is user coordinates.

    - raw –

      whether to set in raw coordinates. The default is user coordinates.

      The ‘raw’ and ‘dial’ keywords are mutually exclusive.

motor.get_pv(attr)

  returns the PV for the corresponding attribute.

motor.set_callback(attr='drive'[, callback=None[, kw=None]])

  sets a callback on the PV for a particular attribute.

motor.clear_callback(attr='drive')

  clears a callback on the PV for a particular attribute.

motor.show_info()

  prints out a table of attributes and their current values.

## Other Device Examples

An epics Device provides a general way to group together a set of PVs. The examples below show how to build on this generality, and may inspire you to build your own device classes.

### A basic Device without a prefix

Here, we define a very simple device that does not even define a prefix. This is not much more than a collection of PVs. Since there is no prefix given, all PVs in the device must be fully qualified. Note that there is no requirement to share a common prefix in such a collection of PVs:

    from epics import Device
    dev = Device()
    p1 = dev.PV('13IDC:m1.VAL')
    p2 = dev.PV('13IDC:m2.VAL')
    dev.put('13IDC:m1.VAL', 2.8)
    dev.put('13IDC:m2.VAL', 3.0)
    print(dev.PV('13IDC:m3.DIR').get(as_string=True))

Note that this device cannot use the attributes based on field names.

This may not look very interesting – why not just use a bunch of PVs? If ou consider Device to be a starting point for building more complicated objects by subclassing Device and adding specialized methods, then it can start to get interesting.

### Epics ai record as Device

For a slightly more useful and typical example, the pyepics distribution includes a Device for an Epics ai (analog input record). The full implementation of this device is:

    #!/usr/bin/env python
    """Epics analog input record"""
    from .. import Device

    class ai(Device):
        "Simple analog input device"

        attrs = ('VAL', 'EGU', 'HOPR', 'LOPR', 'PREC', 'NAME', 'DESC',
                 'DTYP', 'INP', 'LINR', 'RVAL', 'ROFF', 'EGUF', 'EGUL',
                 'AOFF', 'ASLO', 'ESLO', 'EOFF', 'SMOO', 'HIHI', 'LOLO',
                 'HIGH', 'LOW', 'HHSV', 'LLSV', 'HSV', 'LSV', 'HYST')

        def __init__(self, prefix, **kwargs):
            if prefix.endswith('.'):
                prefix = prefix[:-1]
            Device.__init__(self, prefix, delim='.', attrs=self.attrs, **kwargs)

The code simply pre-defines the fields that are the suffixes of an Epics ai input record, and subclasses `Device` with these fields to create the corresponding PVs. For most record suffixes, these will be available as attributes of the Device object. For example, the `ai` class above can be used simply and cleanly as:

    from epics.devices import ai
    This_ai = ai('XXX.PRES')
    print(f'Value: {This_ai.VAL}')
    print(f'Units: {This_ai.EGU}')

Of course, you can also use the `get()`, `put()` methods above for a basic `Device`:

    This_ai.put('DESC', 'My Pump')

Several of the other standard Epics records can easily be exposed as Devices in this way, and the pyepics distribution includes such simple wrappings for the Epics ao, bi, and bo records, as well as several more complex records from synApps.

### Epics Scaler Record as Device

For a slightly more complicated example: an incomplete, but very useful mapping of the Scaler Record from synApps, including methods for changing modes, and reading and writing data.

    #!/usr/bin/env python
    """Epics Scaler"""
    from .. import Device, poll

    class Scaler(Device):
        """
        Simple implementation of SynApps Scaler Record.
        """
        attrs = ('CNT', 'CONT', 'TP', 'T', 'VAL')
        attr_kws = {'calc_enable': '%s_calcEnable.VAL'}
        chan_attrs = ('NM%i', 'S%i')
        calc_attrs = {'calc%i': '%s_calc%i.VAL', 'expr%i': '%s_calc%i.CALC'}
        _nonpvs = ('_prefix', '_pvs', '_delim', '_nchan', '_chans')

        def __init__(self, prefix, nchan=8):
            self._nchan  = nchan
            self._chans = range(1, nchan+1)

            attrs = list(self.attrs)
            for i in self._chans:
                for att in self.chan_attrs:
                    attrs.append(att % i)

            Device.__init__(self, prefix, delim='.', attrs=attrs)

            for key, val in self.attr_kws.items():
                self.add_pv(val % prefix, attr= key)

            for i in self._chans:
                for key, val in self.calc_attrs.items():
                    self.add_pv(val % (prefix, i), attr = key % i)
            self._mutable = False

        def AutoCountMode(self):
            "set to autocount mode"
            self.put('CONT', 1)

        def OneShotMode(self):
            "set to one shot mode"
            self.put('CONT', 0)

        def CountTime(self, ctime):
            "set count time"
            self.put('TP', ctime)

        def Count(self, ctime=None, wait=False):
            "set count, with optional counttime"
            if ctime is not None:
                self.CountTime(ctime)
            self.put('CNT', 1, wait=wait)
            poll()

        def EnableCalcs(self):
            " enable calculations"
            self.put('calc_enable', 1)

        def setCalc(self, i, calc):
            "set the calculation for scaler i"
            attr = 'expr%i'  % i
            self.put(attr, calc)

        def getNames(self):
            "get all names"
            return [self.get('NM%i' % i) for i in self._chans]

        def Read(self, use_calc=False):
            "read all values"
            attr = 'S%i'
            if use_calc:
                attr = 'calc%i'
            return [self.get(attr % i) for i in self._chans]

Note that we can then create a `scaler` object from its base PV prefix, and use methods like `Count()` and `Read()` without directly invoking epics calls:

    s1 = Scaler('XXX:scaler1')
    s1.setCalc(2, '(B-2000*A/10000000.)')
    s1.enableCalcs()
    s1.OneShotMode()
    s1.Count(t=5.0, wait=True)
    print(f'Names:    {s1.getNames()}')
    print(f'Raw  values: {s1.Read(use_calc=False)}')
    print(f'Calc values: {s1.Read(use_calc=True)}')

### Other Devices included in PyEpics

Several other Epics Records have been exposed as Devices, and included in PyEpics distribution. These vary some in how complete and feature-rich they are, and are definitely skewed toward data collection at synchrotron beamlines. A table of current Devices are listed in the Table of Included Epics Devices table below. For further details, consult the source code for these modules.

> Table of Epics Devices Included in the PyEpics distribution. For those described as “pretty basic”, there are generally only PV suffixes to attributes mapped. Many of the others include one or more methods for specific use of that Device.

module | class | description
--- | --- | ---
ad_base | AD_Camera | areaDetector Camera, pretty basic
ad_fileplugin | AD_FilePlugin | areaDetector File Plugin, many methods
ad_image | AD_ImagePlugin | areaDetector Image, with ArrayData attribute
ad_overlay | AD_OverlayPlugin | areaDetector Overlay, pretty basic
ad_perkinelmer | AD_PerkinElmer | PerkinElmer(xrd1600) detector, several methods
ai | ai | analog input, pretty basic (as above)
ao | ao | analog output, pretty basic
bi | bi | binary input, pretty basic
bo | bo | binary output, pretty basic
mca | MCA | epics DXP record, pretty basic
mca | DXP | epics MCA record, get_rois()/get_calib()
mca | MultiXMAP | Multiple XIA XMaps, several methods
scaler | Scaler | epics Scaler record, many methods
scan | Scan | epics SScan record, some methods
srs570 | SRS570 | SRS570 Amplifier
struck | Struck | SIS Multichannel Scaler, many methods
transform | Transform | epics userTransform record
xspress3 | Xspress3 | Quantum Electronics Xspress3 Multi-MCA