Reference

SimpleServer

class pcaspy.SimpleServer

This class encapsulates transactions performed by channel access server. It stands between the channel access client and the driver object. It answers the basic channel access discover requests and forwards the read/write requests to driver object.

It derives from caServer. In addition to implement the virtual methods, it adds method createPV() to create the PVs and process() to process server requests.

server = SimpleServer()
server.createPV(prefix, pvdb)
while True:
    server.process(0.1)
static createPV(prefix, pvdb)

Create PV based on prefix and database definition pvdb

Parameters:
  • prefix (str) – Name prefixing the base_name defined in pvdb

  • pvdb (dict) – PV database configuration

pvdb is a Python dict assuming the following format,

pvdb = {
  'base_name' : {
    'field_name' : value,
  },
}

The base_name is unique and will be prefixed to create PV full name. This PV configuration is expressed again in a dict. The field_name is used to configure the PV properties.

Database Field Definition

Field

Default

Description

type

‘float’

PV data type. enum, string, char, float or int

count

1

Number of elements

enums

[]

String representations of the enumerate states

states

[]

Severity values of the enumerate states. Any of the following, Severity.NO_ALARM, Severity.MINOR_ALARM, Severity.MAJOR_ALARM, Severity.INVALID_ALARM

prec

0

Data precision

unit

‘’

Physical meaning of data

lolim

0

Data low limit for graphics display

hilim

0

Data high limit for graphics display

low

0

Data low limit for alarm

high

0

Data high limit for alarm

lolo

0

Data low low limit for alarm

hihi

0

Data high high limit for alarm

adel

0

Archive deadband

mdel

0

Monitor, value change deadband

scan

0

Scan period in second. 0 means passive

asyn

False

Process finishes asynchronously if True

asg

‘’

Access security group name

value

0 or ‘’

Data initial value

The data type supported has been greatly reduced from C++ PCAS to match Python native types. Numeric types are ‘float’ and ‘int’, corresponding to DBF_DOUBLE and DBF_LONG of EPICS IOC. The display limits are defined by lolim and hilim. The alarm limits are defined by low, high, lolo, hihi.

Fixed width string, 40 characters as of EPICS 3.14, is of type ‘string’. Long string is supported using ‘char’ type and specify the count field large enough. ‘enum’ type defines a list of choices by enums field, and optional associated severity by states.

The adel and mdel fields specify the deadbands to trigger an archive and value change event respectively.

asyn if set to be True. Any channel access client write with callback option, i.e. calling ca_put_callback, will be noticed only when Driver.callbackPV() being called.

static initAccessSecurityFile(asfile, macro)

Load access security configuration file

Parameters:
  • filename (str) – Name of the access security configuration file

  • subst – Substitute macros specified by keyword arguments

Note

This must be called before createPV().

static process(time)

Process server transactions.

Parameters:

delay (float) – Processing time in second

This method should be called so frequent so that the incoming channel access requests are answered in time. Normally called in the loop:

server = SimpleServer()
...
while True:
    server.process(0.1)

Driver

class pcaspy.Driver

This class reacts to PV’s read/write requests. The default behavior is to accept any value of a write request and return it to a read request, an alike echo.

To specify the behavior, override methods read() and write() in a derived class.

__init__()

Initialize parameters database. This method must be called by subclasses in the first place.

read(reason)

Read PV current value

Parameters:

reason (str) – PV base name

Returns:

PV current value

This method is invoked by server library when clients issue read access to a PV. By default it returns the value stored in the parameter library by calling getParam().

The derived class might leave this method untouched and update the PV values from a separate polling thread. See Example 2: Interface to any shell command, Example 3: A Simulated Oscilloscope.

Note

This method is called by the server library main thread. Time consuming tasks should not be performed here. It is suggested to work in an auxiliary thread.

write(reason, value)

Write PV new value

Parameters:
  • reason (str) – PV base name

  • value – PV new value

Returns:

True if the new value is accepted, False if rejected.

This method is invoked by server library when clients write to a PV. By default it stores the value in the parameter library by calling setParam().

Note

This method is called by the server library main thread. Time consuming tasks should not be performed here. It is suggested to work in an auxiliary thread.

getParam(reason)

retrieve PV value

Parameters:

reason (str) – PV base name

Returns:

PV current value

setParam(reason, value, timestamp=None)

set PV value and request update

Parameters:

Store the PV’s new value if it is indeed different from the old. For list and numpy array, a copy will be made. This new value will be pushed to registered client the next time when updatePVs() is called. The PV’s modification time will be updated to timestamp. If timestamp is omitted, the current time is applied.

Alarm and severity status are updated as well. For numeric type, the alarm/severity is determined as the following:

value

alarm

severity

value < lolo

LOLO_ALARM

MAJOR_ALARM

lolo < value < low

LOW_ALARM

MINOR_ALARM

low < value < high

NO_ALARM

NO_ALARM

high < value < hihi

HIGH_ALARM

MINOR_ALARM

value > hihi

HIHI_ALARM

MAJOR_ALARM

For enumerate type, the alarm severity is defined by field states. And if severity is other than NO_ALARM, the alarm status is STATE_ALARM.

Note

The timestamp, if given, must be of pcaspy.cas.epicsTimeStamp type.

setParamStatus(reason, alarm, severity)

set PV status and severity and request update

Parameters:
  • reason (str) – PV base name

  • alarm – alarm state

  • severity – severity state

The PVs’ alarm status and severity are automatically set in setParam(). If the status and severity need to be set explicitly to override the defaults, setParamStatus() must be called after setParam().

The new alarm status/severity will be pushed to registered clients the next time when updatePVs() is called.

setParamEnums(reason, enums, states=None)

set PV enumerate strings and severity states

Parameters:
  • reason (str) – PV base name

  • enums (list) – string representation of the enumerate states

  • states (list) – alarm severity of the enumerate states.

The number of elements in states must match that of enums. If None is given, the list is populated with Severity.NO_ALARM.

The new enumerate strings will be pushed to registered clients the next time when updatePVs() is called.

Note

The monitoring client needs to use DBR_GR_XXX or DBR_CTRL_XXX request type and DBE_PROPERTY event mask when issuing the subscription. This requires EPICS base 3.14.12.6+.

setParamInfo(reason, info)

set PV meta info, limits, precision, limits, units.

Parameters:

The new meta information will be pushed to registered clients the next time when updatePVs() is called.

Note

The monitoring client needs to use DBR_GR_XXX or DBR_CTRL_XXX request type and DBE_PROPERTY event mask when issuing the subscription. This requires EPICS base 3.14.12.6+.

getParamInfo(reason, info_keys=None)

Get PV info fields. This function returns a dictionary with info/value pairs, where each entry of the info_keys-parameter results in a dictionary entry if the PVInfo-object has such an attribute. Attributes that do not exist are ignored. Valid attributes are the same as used in SimpleServer.createPV().

If no info_keys are specified, all PV info keys are returned.

Parameters:
  • reason (str) – PV base name

  • info_keys (list) – List of keys for what information to obtain

Returns:

Dictionary with PV info fields and their current values

Return type:

dict

callbackPV(reason)

Inform asynchronous write completion

Parameters:

reason (str) – PV base name

updatePVs()

Post update events on all PVs with value, alarm status or metadata changed

SimplePV

class pcaspy.SimplePV(name, info)

This class represent the PV entity and its associated attributes.

It is to be created by server application on startup. It derives from PV and implements the virtual methods.

Note

This is considered an internal class and should not be referenced by module users.

ServerThread

class pcaspy.tools.ServerThread(server)

A helper class to run server in a thread.

The following snippet runs the server for 4 seconds and quits:

server = SimpleServer()
server_thread = ServerThread(server)
server_thread.start()
time.sleep(4)
server_thread.stop()
__init__(server)
Parameters:

serverpcaspy.SimpleServer object

start()

Start the thread’s activity.

It must be called at most once per thread object. It arranges for the object’s run() method to be invoked in a separate thread of control.

This method will raise a RuntimeError if called more than once on the same thread object.

stop()

Stop the server processing

pcaspy.cas.POSIX_TIME_AT_EPICS_EPOCH

POSIX time at the EPICS epoch, 00:00:00 Jan. 1, 1990

epicsTimeStamp

class pcaspy.cas.epicsTimeStamp
EPICS time stamp.
secPastEpoch

seconds since 0000 Jan 1, 1990

nsec

nanoseconds within second

epicsTimeStamp()

Current timestamp

epicsTimeStamp(secPastEpoch, nsec)

Timestamp at the given time point

static fromPosixTimeStamp(timestamp)

Convert from a POSIX timestamp in seconds as a floating point number.

static fromPosixTimeStamp(sec, nsec)

Convert from a POSIX timestamp.