Devices: collections of PVs


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 'Motor %s = %f' % ( motor1.get('DESC'), motor1.get('RBV'))

motor1.VAL = 0
print 'Motor %s = %f' % ( 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

return a dictionary of all current values – the ‘’current 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.


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 '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)
    print '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.

  • 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.description, m.slew_speed
1.030 Fine X 5.0
>>> print m.get('device_type', as_string=True)

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.

  • 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
>>> print m.get('device_type', as_string=True)
motor.put(attr, value[, wait=False[, timeout=30]])

sets a field attribute for the motor.

  • 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.

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.

  • value – target value
  • limits (string) – one of ‘user’, ‘dial’, or ‘raw’ for which limits to consider
Return type:


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.

  • 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:


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

  • 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.

  • 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.

  • 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.


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.


clears a callback on the PV for a particular attribute.


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 'Value: ', This_ai.VAL
print '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.put('CNT', 1, wait=wait)

    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.Count(t=5.0, wait=True)
print 'Names:       ', s1.getNames()
print 'Raw  values: ', s1.Read(use_calc=False)
print '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