API

Python soft IOC module.

softioc

The top level softioc module contains a number of packages that can be used in the creation of IOCs:

softioc.softioc

This module wraps the basic interface to the EPICS IOC. A large number of interactive EPICS commands are wrapped and can be made available through the interpreter by invoking the interpreter through this module.

softioc.asyncio_dispatcher

A dispatcher for asyncio based applications instead of the default cothread one

softioc.alarm

This module simply contains definitions for severity and alarm values taken from the EPICS alarm.h header file.

softioc.builder

This module provides facilities for creating PVs.

softioc.pvlog

The act of importing this module configures the IOC to log every external put to the database.

The following submodules implement internals and should not normally be looked at directly:

softioc.imports

Imports and wraps C functions from EPICS IOC support.

softioc.fields

Used internally as part of record support to implement access to EPICS record fields.

softioc.device_core

Implements the basics of Python EPICS device support.

softioc.device

Implements Python device support for all the record types supported.

softioc.pythonSoftIoc

Implements epicsdbbuilder interface for all of the Python records.

softioc.__version__: str

Version number as calculated by https://github.com/dls-controls/versiongit

Top Level IOC Interface: softioc.softioc

This module provides the following functions for general use (available by importing *):

softioc.softioc.iocInit(dispatcher=None)

This must be called exactly once after loading all EPICS database files. After this point the EPICS IOC is running and serving PVs.

Parameters

dispatcher – A callable with signature dispatcher(func, *args). Will be called in response to caput on a record. If not supplied use cothread as a dispatcher.

See also

softioc.asyncio_dispatcher is a dispatcher for asyncio applications

softioc.softioc.dbLoadDatabase(database, path=None, substitutions=None)

Loads a database file and applies any given substitutions.

Note

This function is not normally called directly, instead softioc.builder.LoadDatabase is normally used to create and load the EPICS database on the fly.

However, if required, an existing EPICS database can be loaded explicitly using this method. Note that dbLoadDatabase cannot be called after iocInit.

softioc.softioc.devIocStats(ioc_name)

This will load a template for the devIocStats library with the specified IOC name. This should be called before iocInit

softioc.softioc.interactive_ioc(context={}, call_exit=True)

Fires up the interactive IOC prompt with the given context.

Parameters

• context – A dictionary of values that will be made available to the interactive Python shell together with a number of EPICS test functions

• call_exit – If True, the IOC will be terminated by calling epicsExit which means that interactive_ioc will not return

While the interactive shell is running a number of EPICS test functions are made available for use together with the constant value exit with special behaviour: typing exit at the interpreter prompt will immediately call epicsExit causing the Python interpreter and IOC to terminate.

This module provides Python wrappers for the following EPICS test functions and makes them available to the interactive_ioc interpreter shell. See the IOC Test Facilities documentation for more details of each function.

softioc.softioc.dba(field)

Prints value of each field in dbAddr structure associated with field.

softioc.softioc.dbl(pattern='', fields='')

Prints the names of records in the database matching pattern. If a (space separated) list of fields is also given then the values of the fields are also printed.

softioc.softioc.dbnr(all=0)

Print number of records of each record type.

softioc.softioc.dbgrep(pattern)

Lists all record names that match the pattern. * matches any number of characters in a record name.

softioc.softioc.dbgf(field)

Prints field type and value.

softioc.softioc.dbpf(field, value)

Writes the given value into the field.

softioc.softioc.dbpr(record, interest=0)

Prints all the fields in record up to the indicated interest level:

0	Application fields which change during record processing
1	Application fields which are fixed during processing
2	System developer fields of major interest
3	System developer fields of minor interest
4	All other fields

softioc.softioc.dbtr(record)

Tests processing of the specified record.

softioc.softioc.dbtgf(field_name)

This performs a dbNameToAddr and then calls dbGetField with all possible request types and options. It prints the results of each call. This routine is of most interest to system developers for testing database access.

softioc.softioc.dbtpf(field_name, value)

This command performs a dbNameToAddr, then calls dbPutField, followed by dbgf for each possible request type. This routine is of interest to system developers for testing database access.

softioc.softioc.dbior(driver='', interest=0)

Prints driver reports for the selected driver (or all drivers if driver is omitted) at the given interest level.

softioc.softioc.dbhcr()

Prints hardware configuration report.

softioc.softioc.gft(field)

Get Field Test for old database access

softioc.softioc.pft(field, value)

Put Field Test for old database access

softioc.softioc.tpn(field, value)

Test Process Notify for old database access

softioc.softioc.dblsr(recordname, level)

This command generates a report showing the lock set to which each record belongs. If recordname is 0, “”, or “*” all records are shown, otherwise only records in the same lock set as recordname are shown.

level can have the following values:

0	Show lock set information only
1	Show each record in the lock set
2	Show each record and all database links in the lock set

softioc.softioc.dbLockShowLocked(level)

This command generates a report showing all locked locksets, the records they contain, the lockset state and the thread that currently owns the lockset. The level argument is passed to epicsMutexShow to adjust the information reported about each locked epicsMutex.

softioc.softioc.scanppl(rate=0.0)

Prints all records with the selected scan rate (or all if rate=0).

softioc.softioc.scanpel(event=0)

Prints all records with selected event number (or all if event=0).

softioc.softioc.scanpiol()

Prints all records in the I/O event scan lists.

softioc.softioc.generalTimeReport(int level)

This routine displays the time providers and their priority levels that have registered with the General Time subsystem for both current and event times. At level 1 it also shows the current time as obtained from each provider.

softioc.softioc.eltc(noYes)

TThis determines if error messages are displayed on the IOC console. 0 means no and any other value means yes.

softioc.softioc.exit

Displaying this value will invoke epicsExit() causing the IOC to terminate immediately.

Asyncio Dispatcher: softioc.asyncio_dispatcher

If your application uses asyncio then this module gives an alternative dispatcher for caput requests.

class softioc.asyncio_dispatcher.AsyncioDispatcher

A dispatcher for asyncio based IOCs. Means that on_update callback functions can be async. Will run an Event Loop in a thread when created.

loop

asyncio event loop that the callbacks will run under.

Creating Records: softioc.builder

This module publishes functions for creating records. All of the other methods in this module must be called before calling LoadDatabase(), after which no function in this module is usable.

See softioc.device for a detailed explanation of record support and creation, but note that only the following records types have direct support from this module:

ai, ao, bi, bo, longin, longout, mbbi, mbbo, stringin, stringout, waveform

The following methods create records of the corresponding type. For all records the initial_value parameter can be used to specify an initial value for the record.

The following optional keyword arguments are available for all of these functions:

initial_value

This is used to specify an initial value for each record.

on_update

This is only available on OUT records (including those created by WaveformOut()). This specifies a function that will be called after record processing has completed.

If used this should be set to a callable taking exactly one argument. After successful record processing this function will be called with the new value just written to the record.

Note that this callback occurs at an unpredictable time after record processing and if repeated high speed channel access puts are in progress it is possible that callbacks may be delayed. Each callback will be passed the value at the time the record was processed.

Note also that on_update callbacks occur as part of cothread processing and normal cothread operations can occur during the callback. However only one callback is dispatched at a time, so if a callback blocks it will delay on_update callbacks for other records.

on_update_name

This is an alternative form of on_update with the same behaviour: note that at most one of on_update and on_update_name may be passed. The difference is that on_update_name is called with the record name as its second argument after the value as the first argument.

validate

Also only available on OUT records, specifies a function called during record processing. If used this should be set to a callable taking two arguments. The first argument will be the record object, and the second will be the new value being written. The validate function can reject the update by returning False or accept it by returning True.

Note

This function is called asynchronously on a thread determined by EPICS and it is not safe to perform any cothread actions within this callback.

always_update

Again only on OUT records, determines whether record writes which don’t change the existing value are passed through. If this field is not set then writing to .PROC will have no visible effect.

This flag defaults to False, in which case updates to the record which don’t change its value will be discarded. In particular this means that such updates don’t call validate or on_update.

For all of these functions any EPICS database field can be assigned a value by passing it as a keyword argument for the corresponding field name (in upper case) or by assigning to the corresponding field of the returned record object. Thus the **fields argument in all of the definitions below refers to both the optional keyword arguments listed above and record field names.

All functions return a wrapped ProcessDeviceSupportIn or ProcessDeviceSupportOut instance.

softioc.builder.aIn(name, LOPR=None, HOPR=None, **fields)

softioc.builder.aOut(name, LOPR=None, HOPR=None, **fields)

Create ai and ao records. The lower and upper limits for the record can be specified, and if specified these will also be used to set the EGUL and EGUF fields.

softioc.builder.boolIn(name, ZNAM=None, ONAM=None, **fields)

softioc.builder.boolOut(name, ZNAM=None, ONAM=None, **fields)

Create bi and bo records with the specified names for false (zero) and true (one).

softioc.builder.longIn(name, LOPR=None, HOPR=None, EGU=None, **fields)

softioc.builder.longOut(name, DRVL=None, DRVH=None, EGU=None, **fields)

Create longin and longout records with specified limits and units.

softioc.builder.stringIn(name, **fields)

softioc.builder.stringOut(name, **fields)

Create stringin and stringout records.

softioc.builder.mbbIn(name, *options, **fields)

softioc.builder.mbbOut(name, *options, **fields)

Create mbbi and mbbo records. Up to 16 options can be specified as either an option name or a tuple of tw fields. The name or first field of the tuple names the option, and the second optional field is the option severity. For example:

status = mbbIn('STATUS',
    'OK',
    ('FAILING', alarm.MINOR_ALARM),
    ('FAILED', alarm.MAJOR_ALARM))

Numerical values are assigned to options sequentially from 0 to 15 and cannot be overridden.

Warning

This is a strictly incompatible change from version 2, but is now compatible with version 2 of epics_device.

softioc.builder.Waveform(name, [value, ]**fields)

softioc.builder.WaveformOut(name, [value, ]**fields)

Create waveform records. Depending on whether Waveform or WaveformOut is called the record is configured to behave as an IN or an OUT record, in particular on_update can only be specified when calling WaveformOut.

If value is specified or if an initial_value is specified (only one of these can be used) the value is used to initialise the waveform and to determine its field type and length. If no initial value is specified then the keyword argument length must be used to specify the length of the waveform.

The field type can be explicitly specified either by setting the datatype keyword to a Python type name, or by setting FTVL to the appropriate EPICS field type name. Otherwise the field type is taken from the initial value if given, or defaults to 'FLOAT'.

The following function generates a specialised record.

softioc.builder.Action(name, **fields)

Creates a record (using boolOut) which will always call the on_update method when processed. Used for action records. The on_update keyword should always be passed.

The following functions manage record names. The record device name must be specified before creating records, then each record will be created with a standard two part name of the form device:name where the device part is specified by the functions below and the name part is specified in the record creation function.

softioc.builder.SetDeviceName(device_name)

Sets up the prefix part of the record name, referred to here as the “device” part. This function must be called before creating any records. Note that only this function need be used, the three other functions below are entirely optional.

softioc.builder.UnsetDevice()

This can optionally be called after completing the creation of records to prevent the accidential creation of records with the currently set device name.

The following helper functions are useful when constructing links between records.

softioc.builder.PP(record)

softioc.builder.CP(record)

softioc.builder.NP(record)

softioc.builder.MS(record)

When assigned to a link field in a record these functions add the appropriate processing attributes to the link. These are not normally used.

The following attributes allow more direct access to record creation.

softioc.builder.records

This is the iocbuilder records object, and is populated with functions named after each available record type. Records created with these calls are created with soft device support and Python is not involved in their processing.

The following example shows a calc record being used to post-process a standard Python IOC record:

from softioc import builder
builder.SetDeviceName('XX-XX-XX-01')
rec = aIn('VALUE')
calc = records.calc('CALC', CALC = 'A*B', A = rec, B = 42)
rec.FLNK = PP(calc)

Finally, the following function is used to load record definitions before starting the IOC.

softioc.builder.LoadDatabase()

This must be called exactly once after creating all the records required by the IOC and before calling iocInit(). After this function has been called none of the functions provided by softioc.builder are usable.

Alarm Value Definitions: softioc.alarm

The following values can be passed to IN record set() and set_alarm() methods.

NO_ALARM = 0

MINOR_ALARM = 1

MAJOR_ALARM = 2

INVALID_ALARM = 3

These are severity values. The default severity is NO_ALARM.

softioc.alarm.READ_ALARM

softioc.alarm.WRITE_ALARM

softioc.alarm.HIHI_ALARM

softioc.alarm.HIGH_ALARM

softioc.alarm.LOLO_ALARM

softioc.alarm.LOW_ALARM

softioc.alarm.STATE_ALARM

softioc.alarm.COS_ALARM

softioc.alarm.COMM_ALARM

softioc.alarm.TIMEOUT_ALARM

softioc.alarm.HW_LIMIT_ALARM

softioc.alarm.CALC_ALARM

softioc.alarm.SCAN_ALARM

softioc.alarm.LINK_ALARM

softioc.alarm.SOFT_ALARM

softioc.alarm.BAD_SUB_ALARM

softioc.alarm.UDF_ALARM

softioc.alarm.DISABLE_ALARM

softioc.alarm.SIMM_ALARM

softioc.alarm.READ_ACCESS_ALARM

softioc.alarm.WRITE_ACCESS_ALARM

Alarm code definitions. Frankly these values aren’t terribly useful, only the severity is used for most notifications, but an alarm code needs to be specified when specifying a non zero severity.

Automatic PV logging: softioc.pvlog

Once this module has been imported all channel access writes to any PV published by this IOC will be logged by writing a suitable message to stdout. There is currently no control or customisation of this feature.

Record Support in the Python Soft IOC: softioc.device

The Python soft IOC implements EPICS device support (almost) entirely in Python. This is used to invoke Python processing in response to record processing, making it easy to integrate Python into the EPICS IOC layer.

Records are created dynamically during IOC startup before calling iocInit() and with the help of the softioc.builder module can be loaded with LoadDatabase().

All records are created internally using methods of the PythonDevice class, one method for each of the supported record types, however the corresponding wrapping functions published by softioc.builder should be used as they configure sensible defaults and are generally easier to use.

Create IN records (used for publishing data from the IOC, the naming of the direction is confusing) using the following softioc.builder methods:

aIn(), boolIn(), longIn(), stringIn(), mbbIn(), Waveform().

Create OUT records for receiving control information into the IOC using the following methods:

aOut(), boolOut(), longOut(), stringOut(), mbbOut(), WaveformOut().

For all records the initial_value keyword argument can be used to specify the records value on startup.

Working with IN records

EPICS IN records are implemented as subclasses of the ProcessDeviceSupportIn class which provides the methods documented below.

class softioc.device.ProcessDeviceSupportIn

This class is used to implement Python device support for the record types ai, bi, longin, mbbi and IN waveform records.

set(value, severity=NO_ALARM, alarm=UDF_ALARM, timestamp=None)

Updates the stored value and severity status and triggers an update. If SCAN has been set to 'I/O Intr' (which is the default if the builder methods have been used) then the record will be processed by EPICS and the given value will be published to all users.

Optionally an explicit timestamp can be set. This is a value in seconds in the Unix epoch, as returned by time.time(). This argument only has any effect if TSE = -2 was set when the record was created.

Note that when calling set() for a waveform record the value is always copied immediately – this avoids accidents with mutable values.

set_alarm(severity, alarm, timestamp=None)

This is exactly equivalent to calling:

rec.set(rec.get(), severity, alarm, timestamp)

and triggers an alarm status change without changing the value.

get()

This returns the value last written to this record with set().

Note that channel access puts to a Python soft IOC input record are completely ineffective, and this includes waveform records.

Working with OUT records

class softioc.device.ProcessDeviceSupportOut

This class is used to implement Python device support for the record types ao, bo, longout, mbbo and OUT waveform records. All OUT records support the following methods.

set(value, process=True)

Updates the value associated with the record. By default this will trigger record processing, and so will cause any associated on_update and validate methods to be called. If process is False then neither of these methods will be called, but the value will still be updated.

get()

Returns the value associated with the record.