All four functions take an argument
pv which can specify the name of a
single PV or can be a list of PVs. In all cases the returned result has the
same “shape” as the
pv argument, in other words, if
pv is a single
string then a single value (error code, value, or subscription) is returned, and
pv is a list then a list of exactly the same length is returned.
Several arguments are common through this API:
throw determines how errors are
timeout determines timeouts, and finally
count determine data formats and are documented in Augmented Values.
timeoutargument specified how long
cagetwill wait for the entire operation to complete. This timeout is in seconds, and can be one of several formats: a timeout interval in seconds, an absolute deadline (in
time.timeformat) as a single element tuple, or None to specify that no timeout will occur. Note that a timeout of 0 will timeout immediately if any waiting is required.
If a timeout occurs then a
CANothingwill be raised unless
throw=Falsehas been set.
This parameter determines the behaviour of
connectwhen an error occurs. If
throw=True(the default) is set then an exception is raised, otherwise if
Falseis specified an error code value is returned for each failing PV.
- async aioca.caput(pv: str, value, datatype: aioca.types.Datatype = None, wait: bool = False, timeout: aioca.types.Timeout = 5.0, throw: bool = True) aioca.CANothing
- async aioca.caput(pvs: Union[List[str], Tuple[str, ...]], values, repeat_value: bool = ..., datatype: aioca.types.Datatype = None, wait: bool = False, timeout: aioca.types.Timeout = 5.0, throw: bool = True) List[aioca.CANothing]
Writes values to one or more PVs
If a list of PVs is given, then normally value will have the same length and value[i] is written to pv[i]. If value is a scalar or repeat_value=True then the same value is written to all PVs.
repeat_value – If True and a list of PVs is given, write the same value to every PV.
datatype – Override
Datatypeto a non-native type
wait – Do a caput with callback, waiting for completion
timeout – After how long should a caput with wait=True
throw – If False then return
CANothinginstead of raising an exception
The return value from
caput is either a list or a single value,
depending on the shape of
pv. For each PV a
code is returned on success, otherwise either an exception is raised or an
appropriate error code is returned for each failing PV if
set. The return code can be tested for boolean success, so for example it
is possible to write:
if not caput(pv, value, throw=False): # process caput error
If all the PVs listed in
pv have already been connected, through a
successful call to any
aioca method, then the library guarantees
that the puts for each PV will occur strictly in sequence. For any PVs
which need a connection to be established the order of execution of puts
is completely undefined.
- async aioca.caget(pv: str, datatype: aioca.types.Datatype = None, format: aioca.types.Format = 0, count: aioca.types.Count = 0, timeout: aioca.types.Timeout = 5.0, throw: bool = True) aioca.types.AugmentedValue
- async aioca.caget(pvs: Union[List[str], Tuple[str, ...]], datatype: aioca.types.Datatype = None, format: aioca.types.Format = 0, count: aioca.types.Count = 0, timeout: aioca.types.Timeout = 5.0, throw: bool = True) List[aioca.types.AugmentedValue]
AugmentedValuefrom one or more PVs.
The various arguments control the behaviour of
caget as follows:
See documentation for Augmented Values below.
Documented in Common Notes above. If a value cannot be retrieved and
throw=Falseis set then for each failing PV an empty value with
The format of values returned depends on the number of values requested for each PV. If only one value is requested then the value is returned as a scalar, otherwise as a numpy array.
- aioca.camonitor(pv: str, callback: Callable[[Any], Union[None, Awaitable]], events: aioca.types.Dbe = None, datatype: aioca.types.Datatype = None, format: aioca.types.Format = 0, count: aioca.types.Count = 0, all_updates: bool = False, notify_disconnect: bool = False, connect_timeout: aioca.types.Timeout = None) aioca.Subscription
- aioca.camonitor(pv: Union[List[str], Tuple[str, ...]], callback: Callable[[Any, int], Union[None, Awaitable]], events: aioca.types.Dbe = None, datatype: aioca.types.Datatype = None, format: aioca.types.Format = 0, count: aioca.types.Count = 0, all_updates: bool = False, notify_disconnect: bool = False, connect_timeout: aioca.types.Timeout = None) List[aioca.Subscription]
Create a subscription to one or more PVs
callback – Regular function or async function
events – Bit-wise or of
Dbetypes to notify about. If not given the default mask depends on the requested format
datatype – Override
Datatypeto a non-native type
format – Request extra
count – Request a specific element
Countin an array
all_updates – If True then every update received from channel access will trigger a callback, otherwise any updates received during the previous callback will be merged into the most recent value, incrementing
notify_disconnect – If True then IOC disconnect events will be reported by calling the callback with a
CANothingerror with .ok False, otherwise only valid values will be passed to the callback routine
connect_timeout – If specified then the camonitor will report a disconnection event after the specified interval if connection has not completed by this time. Note that this notification will be made even if notify_disconnect is False, and that if the PV subsequently connects it will update as normal.
For a single pv callbacks will be called as:
for each update where value is an
AugmentedValue. For a list of pvs then
each update is called as:
where index is the position in the original array of pvs of the name generating this update.
If an async function as passed as a callback, then it will be awaited and no
further callbacks will be run for this particular Subscription until this
completes. This can be useful in conjunction with the default
all_updates=False for running periodic updating code like:
async def about_once_a_second(value): do_something_with(value) await asyncio.sleep(1) camonitor(pv, callback=about_once_a_second)
Subscriptions will remain active until the
is called on the returned subscription object:
- class aioca.Subscription
A Subscription object wraps a single channel access subscription, and notifies all updates through an event queue.
The number of updates that have been dropped as they happened while another callback was in progress
- async aioca.connect(pv: str, wait: bool = True, timeout: aioca.types.Timeout = 5.0, throw: bool = True) aioca.CANothing
- async aioca.connect(pv: Union[List[str], Tuple[str, ...]], wait: bool = True, timeout: aioca.types.Timeout = 5.0, throw: bool = True) List[aioca.CANothing]
Establishes a connection to one or more PVs
A single PV or a list of PVs can be given. This does not normally need to be called, as the ca…() routines will establish their own connections as required, but after a successful connection we can guarantee that caput(…, wait=False) will complete immediately without suspension.
This routine can safely be called repeatedly without any extra side effects.
- async aioca.cainfo(pv: str, wait: bool = True, timeout: aioca.types.Timeout = 5.0, throw: bool = True) aioca.CAInfo
- async aioca.cainfo(pv: Union[List[str], Tuple[str, ...]], wait: bool = True, timeout: aioca.types.Timeout = 5.0, throw: bool = True) List[aioca.CAInfo]
CAInfostructure for the given PVs.
See the documentation for
connect()for details of arguments.
- class aioca.CAInfo
Object representing the information returned from
- state_strings = ['never connected', 'previously connected', 'connected', 'closed']
stateinto a printable description of the connection state.
- datatype_strings = ['string', 'short', 'float', 'enum', 'char', 'long', 'double', 'no access']
Textual descriptions of the possible channel data types, can be used to convert
datatypeinto a printable string
str representation of this structure can be printed to
produce output similar to that produced by the
cainfo command line
It is possible to test whether a channel has successfully connected without
provoking suspension by calling
cainfo(pv, wait=False) and testing the
.state attribute of the result.
All of the above functions will make a connection to a channel which is cached for future calls. If you need to clear this cache (e.g. in tests) you can call:
Remove cached channel connections. This will close all subscriptions
All the async functions in the
aioca interface can be run under the asyncio
event loop. A convenience function is provided to do this:
- aioca.run(coro, forever=False)
Convenience function that makes an event loop and runs the async function within it.
forever – If True then run the event loop forever, otherwise return on completion of the coro
- class aioca.ChannelInfo
Information about a particular Channel
Working with Values
There are two types of values returned by
Augmented Values and Error Code Values. The
caput function only returns
an error code value (which may indicate success), while
camonitor will normally return (or deliver) augmented values, but will
return (or deliver) an error code on failure.
Trueif the data is good,
Falseif there was an error. For augmented values
okis always set to
Name of the pv.
Values and their Types
The type of values returned by
caget or delivered by
callbacks is determined by the requested datatype in the original
camonitor call together with the underlying length of the requested
If the underlying length (
element_count) of the EPICS value is 1 then
the value will be returned as a Python scalar, and will be one of the three
basic scalar types (string, integer or floating point number), but wrapped as an
If on the other hand
element_count is not 1 then the value is treated
as an array and is always returned as a numpy array, again wrapped as an
augmented type. Note that this means that even if
caget(pv, count=1) is
used to fetch a value with one element, if the underlying PV is an array then
the result returned will be an array.
The table below enumerates the possibilities:
- class aioca.ca_str
- class aioca.ca_int
- class aioca.ca_float
Scalar types derived from basic Python types.
Error Code Values
- class aioca.CANothing(name: str, errorcode=1)
The following ECA error codes from
epicscorelibs.ca.cadef are worth noting:
Channel disconnected. This is used by
camonitorto report channel disconnect events.
Channel timed out. Reported if user specified timeout ocurred before completion and if
Augmented values are normally Python or
numpy values with extra fields:
.name fields are already mentioned above, and
further extra fields will be present depending on format requested for the data.
As pointed out above,
.ok is always
True for valid data.
Four different types of augmented value are returned: strings, integers, floating point numbers or arrays, depending on the length of the data requested – an array is only used when the data length is >1.
In almost all circumstances an augmented value will behave exactly like a
normal value, but there are a few rare cases where differences in behaviour are
observed (these are mostly bugs). If this occurs the augumentation can be
stripped from an augmented value
value by writing
+value – this returns
the underlying value.
The type of augmented values is determined both by parameters passed to
camonitor and by the underlying datatype. Both of these functions share
count which can be used to control
the type of the data returned:
None(the default). In this case the “native” datatype provided by the channel will be returned.
Dbrvalue. See items 5 onwards for details of the special values.
numpy.dtypecompatible with any of the above values.
One of the special values
DBR_CHAR_BYTES. This is used to request a char array which is then converted to a Python
bytesstring on receipt. It is not sensible to specify
countwith this option. The options
DBR_CHAR_UNICODEare meaningless and not supported for
Note that if the PV name ends in
datatypeis not specified then
DBR_CHAR_STRwill be used.
The special value
DBR_ENUM_STR, only for
camonitor. In this case the “native” channel datatype is used unless the channel is an enumeration, in which case the corresponding string is returned.
Returns the name of the “enclosing interface”, typically the record type, and typically the same as the EPICS
caputalso two further values are supported:
Formatcontrols how much auxilliary information will be returned with the retrieved data.
Countdetermines how many elements to fetch for arrays
- class aioca.types.AugmentedValue(*args, **kwds)
The value itself depends on the number of values requested for the PV. If only one value is requested then the value is returned as a scalar, otherwise as a numpy array.
DBR_SHORT, DBR_CHAR, DBR_LONG will also have
DBR_FLOAT, DBR_DOUBLE will have the DBR_LONG fiels together with a
DBR_ENUM will have
DBR_STRING does not support FORMAT_CTRL, so FORMAT_TIME data is returned instead
- acks: int
Used for global alarm acknowledgement. The highest alarm severity to acknowledge. If the current alarm severity is less then or equal to this value the alarm is acknowledged.
- ackt: int
Used for global alarm acknowledgement. Do transient alarms have to be acknowledged? (0,1) means (no, yes).
- datetime: datetime.datetime
- element_count: int
Number of elements in the underlying EPICS value. If this is not 1 then the value is treated as an array, otherwise up to this many elements may be present in the value.
- raw_stamp: Tuple[int, int]
Record timestamp in raw format as provided by EPICS (but in the local Unix epoch, not the EPICS epoch). Is a tuple of the form
(secs, nsec)with integer seconds and nanosecond values, provided in case full ns timestamp precision is required.
- severity: int
EPICS alarm severity, normally one of the values listed below.
Alarm condition, minor severity
Alarm condition, major severity.
- timestamp: float
Timestamp in seconds in format compatible with
time.time()rounded to the nearest microsecond: for nanosecond precision use
How many array elements to retrieve from the server. One of the following
Server and data dependent waveform length
The full data length
A maximum of this number of elements
The format of the requested data can be one of the following
None (the default)
In this case the “native” datatype provided by the channel will be returned
To request this type from the IOC
A python type
Compatible with any of the above values, such as int, float or str
A numpy dtype
Compatible with any of the above values
A bitwise or of DBE event codes from epicscorelibs.ca.dbr
Trigger an event when a significant change in the channel’s value occurs. Relies on the monitor deadband field on the server
Trigger an event when an archive significant change in the channel’s value occurs. Relies on the archiver monitor deadband field on the server
Trigger an event when the alarm state changes
Trigger an event when a property change (control limit, graphical limit, status string, enum string …) occurs.
If not specified then the default value depends on the requested
Default value for events
DBE_VALUE | DBE_ALARM
DBE_VALUE | DBE_ALARM | DBE_PROPERTY
A DBR request code from epicscorelibs.ca.dbr. One of
40 character strings
16 bit signed
32 bit float
16 bit unsigned
8 bit unsigned
32 bit signed
64 bit float
Configure global alarm acknowledgement
Acknowledge global alarm
Returns status ack structure
Returns record type (same as .RTYP)
Enums as strings, default otherwise
Long byte strings as char arrays
Long unicode strings as char arrays
Long strings as char arrays
Literal[0, 1, 2, 3, 4, 5, 6, 35, 36, 37, 38, 996, 997, 998, 999]
How much auxilliary information will be returned with the retrieved data. From epicscorelibs.ca.dbr, one of the following
The data is returned unaugmented except for the .name field
The data is augmented by the data timestamp together with .alarm .status and .severity fields.
The data is augmented by channel access “control” fields. This set of fields depends on the underlying datatype
Literal[0, 1, 2]