Core API Documentation ¶

Contents

Core API Documentation

Commands ¶

Caproto lets you work with Channel Access communication in terms of Commands instead of thinking in terms of bytes.

Take VersionRequest as an example.

In [1]: import caproto

In [2]: com = caproto.VersionRequest(version=13, priority=0)

A Command has a useful __repr__():

In [3]: com
Out[3]: VersionRequest(priority=0, version=13)

Every Command has a header and a payload. The data in them fully describe the Command. The header has generically-named fields provided by the Channel Access specification.

In [4]: com.header
Out[4]: MessageHeader(command=0, payload_size=0, data_type=0, data_count=13, parameter1=0, parameter2=0)

These names are rather opaque, but each Command provides views on this same data through type-specific attributes with more obvious names. These are the same names used in the Command’s __repr__() and __init__ arguments.

In [5]: com.version
Out[5]: 13

In [6]: com.priority
Out[6]: 0

This is a complete list of the Commands. They are sorted in Command ID order, designated by the Channel Access specification.

class caproto.VersionRequest(priority, version)[source]¶

Initiate a new connection or broadcast between the client and the server.

Fields:

priority¶: Between 0 (low) and 99 (high) designating this connection’s priority in the event of congestion.

version¶: The version of the Channel Access protocol.

class caproto.VersionResponse(version)[source]¶

Respond to a client’s initiation of a new connection or broadcast.

Fields:

version¶: The version of the Channel Access protocol.

class caproto.SearchRequest(name, cid, version, reply=5)[source]¶

Query for the address of the server that provides a given Channel.

Fields:

name¶: String name of the channel (i.e. ‘PV’)

cid¶: Integer that uniquely identifies this search query on the client side.

version¶: The version of the Channel Access protocol.

payload_size¶: Padded length of name string

reply¶: Hard-coded to NO_REPLY (5) meaning that only the server(s) with an affirmative response should reply.

class caproto.SearchResponse(port, ip, cid, version)[source]¶

Answer a SearchRequest giving the address of a Channel.

Fields:

port¶: Port number that will accept TCP connections with clients.

ip¶: IP address (as a string) that will accept TCP connections with clients.

cid¶: Echoing cid of SearchRequest to let the client match this response with the original request.

version¶: The version of the Channel Access protocol.

class caproto.NotFoundResponse(version, cid)[source]¶

Answer a SearchResponse in the negative.

Fields:

cid¶: Echoing cid of SearchRequest to let the client match this response with the original request.

version¶: The version of the Channel Access protocol.

class caproto.EchoRequest[source]¶

Request an EchoResponse.

This command has no fields.

class caproto.EchoResponse[source]¶

Respond to an EchoRequest.

This command has no fields.

class caproto.Beacon(version, server_port, beacon_id, address)[source]¶

Heartbeat beacon sent by the server.

Fields:

version¶: The version of the Channel Access protocol.

server_port¶: Port number.

beacon_id¶: Sequentially incremented integer.

address¶: IP address encoded as integer.

address_string¶: IP address as string.

class caproto.RepeaterRegisterRequest(client_address='0.0.0.0')[source]¶

Register a client with the Repeater.

Fields:

client_address¶: IP address of the client (as a string).

class caproto.RepeaterConfirmResponse(repeater_address)[source]¶

Confirm successful client registration with the Repeater.

Fields:

repeater_address¶: IP address of repeater (as a string).

class caproto.EventAddRequest(data_type, data_count, sid, subscriptionid, low, high, to, mask)[source]¶

Subscribe; i.e. request to notified of changes in a Channel’s value.

Fields:

data_type¶: Integer code of desired DBR type of readings.

data_count¶: Desired number of elements per reading.

sid¶: Integer ID of this Channel designated by the server.

subscriptionid¶: New integer ID designated by the client uniquely identifying this subscription on this Virtual Circuit.

low¶: Deprecated. (Use mask.)

high¶: Deprecated. (Use mask.)

to¶: Deprecated. (Use mask.)

mask¶: Mask indicating which changes to report.

class caproto.EventAddResponse(data, data_type, data_count, status, subscriptionid, *, metadata=None)[source]¶

Notify the client of a change in a Channel’s value.

Fields:

data¶: data as built-in Python or numpy types

data_type¶: Integer code of DBR type of reading.

data_count¶: Number of elements in this reading.

sid¶: Integer ID of this Channel designated by the server.

status¶: As per Channel Access spec, 1 is success; 0 or >1 are various failures.

subscriptionid¶: Echoing the subscriptionid in the EventAddRequest

class caproto.EventCancelRequest(data_type, sid, subscriptionid)[source]¶

End notifcations about chnages in a Channel’s value.

Fields:

data_type¶: Integer code of DBR type of reading.

sid¶: Integer ID of this Channel designated by the server.

subscriptionid¶: Integer ID for this subscription.

class caproto.EventCancelResponse(data_type, sid, subscriptionid, data_count)[source]¶

Confirm receipt of EventCancelRequest.

Fields:

data_type¶: Integer code of DBR type of reading.

sid¶: Integer ID of this Channel designated by the server.

subscriptionid¶: Integer ID for this subscription.

class caproto.ReadRequest(data_type, data_count, sid, ioid)[source]¶: Deprecated by Channel Access since 3.13. See ReadNotifyRequest.

class caproto.ReadResponse(data, data_type, data_count, sid, ioid, *, metadata=None)[source]¶: Deprecated by Channel Access since 3.13. See ReadNotifyResponse.

class caproto.WriteRequest(data, data_type, data_count, sid, ioid, *, metadata=None)[source]¶: Deprecated: See WriteNotifyRequest.

class caproto.EventsOffRequest[source]¶

Temporarily turn off EventAddResponse notifications.

This command has no fields.

class caproto.EventsOnRequest[source]¶

Restore EventAddResponse notifications.

This command has no fields.

class caproto.ReadSyncRequest[source]¶: Deprecated by Channel Access: See ReadNotifyRequest

class caproto.ErrorResponse(original_request, cid, status, error_message)[source]¶

Notify client of a server-side error, including some details about error.

Fields:

cid¶: Integer ID for this Channel designated by the client.

status¶: As per Channel Access spec, 1 is success; 0 or >1 are various failures.

class caproto.ClearChannelRequest(sid, cid)[source]¶

Close a Channel.

Fields:

cid¶: Integer ID for this Channel designated by the client.

sid¶: Integer ID for this Channel designated by the server.

class caproto.ClearChannelResponse(sid, cid)[source]¶

Confirm that a Channel has been closed.

Fields:

cid¶: Integer ID for this Channel designated by the client.

sid¶: Integer ID for this Channel designated by the server.

class caproto.ReadNotifyRequest(data_type, data_count, sid, ioid)[source]¶

Request a fresh reading of a Channel.

Fields:

data_type¶: Integer code of desired DBR type of readings.

data_count¶: Desired number of elements per reading.

sid¶: Integer ID for this Channel designated by the server.

ioid¶: New integer ID uniquely identifying this I/O transaction on this Virtual Circuit.

class caproto.ReadNotifyResponse(data, data_type, data_count, status, ioid, *, metadata=None)[source]¶

Request a fresh reading of a Channel.

Fields:

data¶: data as built-in Python or numpy types

metadata¶: metadata in a ctypes.Structure

data_type¶: Integer code of desired DBR type of readings.

data_count¶: Desired number of elements per reading.

status¶: As per Channel Access spec, 1 is success; 0 or >1 are various failures.

ioid¶: Integer ID for I/O transaction, echoing ReadNotifyRequest.

class caproto.WriteNotifyRequest(data, data_type, data_count, sid, ioid, *, metadata=None)[source]¶

Write a value to a Channel.

Fields:

data¶: data as built-in Python or numpy types

metadata¶: metadata in a ctypes.Structure

data_type¶: Integer code of DBR type.

data_count¶: Number of elements.

sid¶: Integer ID for this Channel designated by the server.

ioid¶: New integer ID uniquely identifying this I/O transaction on this Virtual Circuit.

class caproto.WriteNotifyResponse(data_type, data_count, status, ioid)[source]¶

Confirm the receipt of a WriteNotifyRequest.

Fields:

data_type¶: Integer code of DBR type.

data_count¶: Number of elements.

sid¶: Integer ID for this Channel designated by the server.

ioid¶: Integer ID for this I/O transaction, echoing WriteNotifyRequest.

status¶: As per Channel Access spec, 1 is success; 0 or >1 are various failures.

class caproto.ClientNameRequest(name)[source]¶

Tell the server the client name (i.e., user name) of the client.

Fields:

name¶: Client name.

class caproto.HostNameRequest(name)[source]¶

Tell the server the host name of the client.

Fields:

name¶: Host name.

class caproto.AccessRightsResponse(cid, access_rights)[source]¶

Notify the client that channel creation failed.

Fields:

cid¶: Integer ID for this Channel designated by the client.

access_rights¶: Integer designated level of read or write access. (See Channel Access spec for details about meanings.)

class caproto.CreateChFailResponse(cid)[source]¶

Notify the client that channel creation failed.

Fields:

cid¶: Integer ID for this Channel designated by the client.

class caproto.ServerDisconnResponse(cid)[source]¶

Notify the client that server will disconnect from this Channel.

Fields:

cid¶: Integer ID for this Channel designated by the client.

The State Machine ¶

To validate commands being sent and received, the caproto VirtualCircuit object maintains several state machines. It keeps track of what the client is doing and what server is doing, whether it is playing the role of the client or server.

A single VirtualCircuit maintains:

exactly one client-side circuit state machine
exactly one server-side circuit state machine
one client-side channel state machine per channel
one server-side channel per channel

The basic interaction looks like this:

Client specifies the priority and protocol version of a new Virtual Circuit.
Server confirms.
Client (optionally) provides its host name and client name.
Client requests the creation of a new Channel.
Server announces access rights for this Channel and confirms Channel creation.

With the Channel open, the client may send unlimited requests to read, write, or subscribe. The Server responds. The server or the client may initiate closing the Channel.

The state machines look like this. Click on each to expand.

Channel (Client)

Channel (Server)

Circuit (Client)

Circuit (Server)

Special Constants ¶

Caproto uses special constants to represent the states of the state machine:

caproto.SEND_SEARCH_REQUEST¶
caproto.AWAIT_SEARCH_RESPONSE¶
caproto.SEND_SEARCH_RESPONSE¶
caproto.SEND_VERSION_REQUEST¶
caproto.AWAIT_VERSION_RESPONSE¶
caproto.SEND_VERSION_RESPONSE¶
caproto.SEND_CREATE_CHAN_REQUEST¶
caproto.AWAIT_CREATE_CHAN_RESPONSE¶
caproto.SEND_CREATE_CHAN_RESPONSE¶
caproto.CONNECTED¶
caproto.MUST_CLOSE¶
caproto.CLOSED¶
caproto.DISCONNECTED¶
caproto.IDLE¶
caproto.FAILED¶

For example, a new VirtualCiruit starts with these states:

In [7]: circuit = caproto.VirtualCircuit(our_role=caproto.CLIENT,
   ...:                                  address=('0.0.0.0', 5555),
   ...:                                  priority=0)
   ...: 

In [8]: circuit.states
Out[8]: <CircuitState states={CLIENT: SEND_VERSION_REQUEST, SERVER: IDLE}>

When a VersionRequest is sent through the VirtualCircuit, both the client and the server state update.

In [9]: circuit.send(caproto.VersionRequest(version=13, priority=0));

In [10]: circuit.states
Out[10]: <CircuitState states={CLIENT: AWAIT_VERSION_RESPONSE, SERVER: SEND_VERSION_RESPONSE}>

And we can test the current state using constants like SEND_VERSION_RESPONSE.

In [11]: circuit.states[caproto.SERVER] is caproto.SEND_VERSION_RESPONSE
Out[11]: True

Notice the special constants to represent which role a peer is playing.

caproto.CLIENT¶
caproto.SERVER¶

Special constants are also used to represent the “direction” of a command.

caproto.RESPONSE¶
caproto.REQUEST¶

Another special constant serves as a sentinel “Command” returned by read_from_bytestream() when more data needs to be received before any new Commands can be parsed.

caproto.NEED_DATA¶

Similarly, the sentinel DISCONNECTED is re-used as a “Command” allowing for consistent handling of disconnection events through the command queues.

caproto.DISCONNECTED

The VirtualCircuit object ¶

class caproto.VirtualCircuit(our_role, address, priority, protocol_version=13)[source]¶

An object encapulating the state of one CA client–server connection.

It is a companion to a TCP socket managed by the user. All data received over the socket should be passed to recv(). Any data sent over the socket should first be passed through send().

Parameters

our_roleCLIENT or SERVER
addresstuple: (host, port) as a string and an integer respectively
priorityinteger or None: May be used by the server to prioritize requests when under high load. Lowest priority is 0; highest is 99.

our_role¶: caproto.CLIENT or caproto.SERVER

log¶: Python logger instance

host¶: peer host name

port¶: peer port number

key¶: a unique identifer for this instance: ((host, port), priority)

send(*commands, extra=None)[source]¶

Convert one or more high-level Commands into buffers of bytes that may be broadcast together in one TCP packet. Update our internal state machine.

Parameters

*commands: any number of Message objects
extradict or None: Used for logging purposes. This is merged into the extra parameter passed to the logger to provide information like 'pv' to the logger.

Returns

buffers_to_sendlist: list of buffers to send over a socket

recv(*buffers)[source]¶

Parse commands from buffers received over TCP.

When the caller is ready to process the commands, each command should first be passed to VirtualCircuit.process_command() to validate it against the protocol and update the VirtualCircuit’s state.

Parameters

*buffers: any number of bytes-like buffers

Returns

(commands, num_bytes_needed)

process_command(command)[source]¶

Update internal state machine and raise if protocol is violated.

Received commands should be passed through here before any additional processing by a server or client layer.

disconnect()[source]¶

Notify all channels on this circuit that they are disconnected.

Clients should call this method when a TCP connection is lost.

new_channel_id()[source]¶: Return a valid value for a cid or sid.

new_subscriptionid()[source]¶: This is used by the convenience methods to obtain an unused integer ID. It does not update any important state.

new_ioid()[source]¶: This is used by the convenience methods to obtain an unused integer ID. It does not update any important state.

The Broadcaster object ¶

class caproto.Broadcaster(our_role, protocol_version=13)[source]¶

An object encapsulating the state of one CA UDP connection.

It is a companion to a UDP socket managed by a client or server implementation. All data received over the socket should be passed to recv(). Any data sent over the socket should first be passed through send().

Parameters

our_roleCLIENT or SERVER
protocol_versioninteger: Default is DEFAULT_PROTOCOL_VERSION.

our_role¶: caproto.CLIENT or caproto.SERVER

log¶: Python logger instance

send(*commands)[source]¶

Convert one or more high-level Commands into bytes that may be broadcast together in one UDP datagram. Update our internal state machine.

Parameters

*commands: any number of Message objects

Returns

bytes_to_sendbytes: bytes to send over a socket

recv(byteslike, address)[source]¶

Parse commands from a UDP datagram.

When the caller is ready to process the commands, each command should first be passed to Broadcaster.process_command() to validate it against the protocol and update the Broadcaster’s state.

Parameters

byteslikebytes-like
addresstuple: (host, port) as a string and an integer respectively

Returns

commandslist

process_commands(commands)[source]¶

Update internal state machine and raise if protocol is violated.

Received commands should be passed through here before any additional processing by a server or client layer.

register(ip='0.0.0.0')[source]¶

Generate a valid RepeaterRegisterRequest.

Parameters

ipstring, optional: Our IP address. Defaults is ‘0.0.0.0’, which ends up being converted by the repeater to the IP from which it receives the packet.

Returns

RepeaterRegisterRequest

Channel objects ¶

These objects are used internally by VirtualCircuit to track the state of individual channels. The user can optionally use them as a convenience for generating valid commands.

class caproto.ClientChannel(name, circuit, cid=None, string_encoding='latin-1')[source]¶

An object encapsulating the state of the EPICS Channel on a Client.

A ClientChannel may be created in one of two ways: (1) The user instantiates a ClientChannel with a name, server address, priority, and optional cid. The server address and priority are used to assign the ClientChannel to a VirtualCircuit. If no cid is given, a unique one is allocated by the VirtualCircuit. (2) A VirtualCircuit processes a CreateChanRequest that refers to a cid that it has not yet seen. A ClientChannel will be automatically instantiated with the name and cid indicated that command and the address and priority of that VirtualCircuit. It can be accessed in the circuit’s channels attribute.

Parameters

namestring: Channnel name (PV)
circuitVirtualCircuit
cidinteger, optional
string_encodingstring: Default is ‘latin-1’ or value of CAPROTO_STRING_ENCODING environment variable.

version()[source]¶

Generate a valid VersionRequest.

Parameters

priorityinteger, optional: May be used by the server to prioritize requests when under high load. Lowest priority is 0; highest is 99. Default is 0.

Returns

VersionRequest

host_name(host_name)[source]¶

Generate a valid HostNameRequest.

Parameters

host_namestring

Returns

HostNameRequest

client_name(client_name)[source]¶

Generate a valid ClientNameRequest.

Parameters

client_namestring, optional: defaults to output of getpass.getuser()

Returns

ClientNameRequest

create()[source]¶

Generate a valid CreateChanRequest.

Returns

CreateChanRequest

read(data_type=None, data_count=None, ioid=None, notify=True)[source]¶

Generate a valid ReadRequest or ReadNotifyRequest.

Parameters

data_type{‘native’, ‘status’, ‘time’, ‘graphic’, ‘control’} or ChannelType or int ID, optional: Requested Channel Access data type. Default is the channel’s native data type, which can be checked in the Channel’s attribute native_data_type.
data_countinteger, optional: Requested number of values. Default is the channel’s native data count, which can be checked in the Channel’s attribute native_data_count.
ioidinteger, optional: Input/output ID. If None, one is generated.
notifyboolean, optional: True by default. If True, send a ReadNotifyRequest instead of a ReadRequest. Note that ReadRequest has been deprecated by Channel Access in 3.13 and is not well-supported by caproto.

Returns

ReadNotifyRequest

write(data, data_type=None, data_count=None, metadata=None, ioid=None, notify=False)[source]¶

Generate a valid WriteRequest or `:class:`WriteNotifyRequest.

Parameters

datatuple, numpy.ndarray, array.array, or bytes
data_type{‘native’, ‘status’, ‘time’, ‘graphic’, ‘control’} or ChannelType or int ID, optional: Requested Channel Access data type. Default is the channel’s native data type, which can be checked in the Channel’s attribute native_data_type.
data_countinteger, optional: Requested number of values. Default is the channel’s native data count, which can be checked in the Channel’s attribute native_data_count.
metadatactypes.BigEndianStructure or tuple: Status and control metadata for the values
ioidinteger, optional: Input/output ID. If None, one is generated.
notifyboolean, optional: False by default. If True, send a WriteNotifyRequest instead of a WriteRequest.

Returns

WriteNotifyRequest

subscribe(data_type=None, data_count=None, subscriptionid=None, low=0.0, high=0.0, to=0.0, mask=None)[source]¶

Generate a valid EventAddRequest.

Parameters

data_type{‘native’, ‘status’, ‘time’, ‘graphic’, ‘control’} or ChannelType or int ID, optional: Requested Channel Access data type. Default is the channel’s native data type, which can be checked in the Channel’s attribute native_data_type.
data_countinteger, optional: Requested number of values. Default is the channel’s native data count, which can be checked in the Channel’s attribute native_data_count.
subscriptionidinteger, optional
lownumber: Default is 0.
highnumber: Default is 0.
tonumber: Default is 0.
mask: Default is None, which resolves to: (SubscriptionType.DBE_VALUE | `` `` SubscriptionType.DBE_ALARM | `` `` SubscriptionType.DBE_PROPERTY)

Returns

EventAddRequest

unsubscribe(subscriptionid)[source]¶

Generate a valid EventAddRequest.

Parameters

subscriptionidinteger: The subscriptionid that was originally sent in the corresponding EventAddRequest.

Returns

EventAddRequest

clear()[source]¶

Generate a valid ClearChannelRequest.

Returns

ClearChannelRequest

class caproto.ServerChannel(name, circuit, cid=None, string_encoding='latin-1')[source]¶

A server-side Channel.

Parameters

namestring: Channnel name (PV)
circuitVirtualCircuit
cidinteger, optional
string_encodingstring: Default is ‘latin-1’ or value of CAPROTO_STRING_ENCODING environment variable.

version()[source]¶

Generate a valid VersionResponse.

Returns

VersionResponse

create(native_data_type, native_data_count, sid)[source]¶

Generate a valid CreateChanResponse.

Parameters

native_data_typea ChannelType or corresponding integer ID, optional: Default Channel Access data type.
native_data_countinteger: Default number of values
sidinteger: server-allocated sid

Returns

CreateChanResponse

create_fail()[source]¶

Generate a valid CreateChFailResponse.

Returns

CreateChFailResponse

read(data, ioid, data_type=None, data_count=None, status=1, *, metadata=None, notify=True)[source]¶

Generate a valid ReadResponse or ReadNotifyResponse.

Parameters

datatuple, numpy.ndarray, array.array, or bytes
ioidinteger
data_type{‘native’, ‘status’, ‘time’, ‘graphic’, ‘control’} or ChannelType or int ID, optional: Requested Channel Access data type. Default is the channel’s native data type, which can be checked in the Channel’s attribute native_data_type.
data_countinteger, optional: Requested number of values. Default is the channel’s native data count, which can be checked in the Channel’s attribute native_data_count.
statusinteger, optional: Default is 1 (success).
metadatactypes.BigEndianStructure or tuple: Status and control metadata for the values
notifyboolean, optional: True by default. If True, send a ReadNotifyRequest instead of a ReadRequest. Note that ReadRequest has been deprecated by Channel Access in 3.13 and is not well-supported by caproto.

Returns

ReadResponse or ReadNotifyResponse

write(ioid, data_type=None, data_count=None, status=1)[source]¶

Generate a valid WriteNotifyResponse.

Parameters

ioidinteger
data_type{‘native’, ‘status’, ‘time’, ‘graphic’, ‘control’} or ChannelType or int ID, optional: Requested Channel Access data type. Default is the channel’s native data type, which can be checked in the Channel’s attribute native_data_type.
data_countinteger, optional: Requested number of values. Default is the channel’s native data count, which can be checked in the Channel’s attribute native_data_count.
statusinteger, optional: Default is 1 (success).

Returns

WriteNotifyResponse

subscribe(data, subscriptionid, data_type=None, data_count=None, status=<CAStatus.ECA_NEWCONN: CAStatusCode(name='ECA_NEWCONN', code=32, code_with_severity=259, severity=<CASeverity.INFO: 3>, success=1, defunct=True, description='New or resumed network connection')>, metadata=None)[source]¶

Generate a valid EventAddResponse.

Parameters

datatuple, numpy.ndarray, array.array, or bytes
subscriptionidinteger
data_type{‘native’, ‘status’, ‘time’, ‘graphic’, ‘control’} or ChannelType or int ID, optional: Requested Channel Access data type. Default is the channel’s native data type, which can be checked in the Channel’s attribute native_data_type.
data_countinteger, optional: Requested number of values. Default is the channel’s native data count, which can be checked in the Channel’s attribute native_data_count.
statusCAStatus or corresponding integer code: Default is CAStatus.ECA_NEWCONN
metadatactypes.BigEndianStructure or tuple: Status and control metadata for the values

Returns

EventAddResponse

unsubscribe(subscriptionid, data_type=None, data_count=None)[source]¶

Generate a valid EventCancelResponse.

Parameters

subscriptionidinteger
data_type{‘native’, ‘status’, ‘time’, ‘graphic’, ‘control’} or ChannelType or int ID, optional: Requested Channel Access data type. Default is the channel’s native data type, which can be checked in the Channel’s attribute native_data_type.

Returns

EventCancelResponse

clear()[source]¶

Generate a valid ClearChannelResponse

Returns

ClearChannelResposne

disconnect()[source]¶

Generate a valid ServerDisconnResponse

Returns

ServerDisconnResponse

Payload Data Types ¶

Channel Access implements a system of data structures (“Database Records”) that encode metadata like time, alarm status, and control limits with the data value(s). Each Channel Access data type has an integer ID, encoded by caproto in the ChannelType enum:

class caproto.ChannelType(value)[source]¶

All channel types supported by Channel Access

The ones that should be used in servers to specify the type of pvproperty or ChannelData are only “native” types (STRING, INT, FLOAT, ENUM, CHAR, LONG, DOUBLE)

The remaining channel data types are used for clients requesting additional metadata from the server.

STRING = 0

INT = 1

FLOAT = 2

ENUM = 3

CHAR = 4

LONG = 5

DOUBLE = 6

STS_STRING = 7

STS_INT = 8

STS_FLOAT = 9

STS_ENUM = 10

STS_CHAR = 11

STS_LONG = 12

STS_DOUBLE = 13

TIME_STRING = 14

TIME_INT = 15

TIME_FLOAT = 16

TIME_ENUM = 17

TIME_CHAR = 18

TIME_LONG = 19

TIME_DOUBLE = 20

GR_STRING = 21

GR_INT = 22

GR_FLOAT = 23

GR_ENUM = 24

GR_CHAR = 25

GR_LONG = 26

GR_DOUBLE = 27

CTRL_STRING = 28

CTRL_INT = 29

CTRL_FLOAT = 30

CTRL_ENUM = 31

CTRL_CHAR = 32

CTRL_LONG = 33

CTRL_DOUBLE = 34

STSACK_STRING = 37

CLASS_NAME = 38

All commands that accept a data_type argument expect one of these ChannelType attributes or the corresponding integer. Here some valid examples using the simple “native” types.

import caproto as ca

ReadNotifyResponse(data_type=ca.ChannelType.FLOAT,
                   data_count=3,
                   data=(3.2, 5.3, 10.6),
                   metadata=None)

ReadNotifyResponse(data_type=2,  # 2 is equivalent to ChannelType.FLOAT
                   data_count=3,
                   data=(3.2, 5.3, 10.6),
                   metadata=None)

ReadNotifyResponse(data_type=ca.ChannelType.FLOAT,
                   data_count=1,
                   data=(3.1,),  # scalars must be given inside an iterable
                   metadata=None)

ReadNotifyResponse(data_type=ca.ChannelType.INT,
                   data_count=5,
                   data=numpy.array([7, 21, 2, 4, 5], dtype='i2'),
                   metadata=None)

And here are some examples using the compound types that include metadata. The metadata is packed into a ctypes.BigEndianStructure with the appropriate fields. The caller can handle the struct directly and pass it in:

metadata = ca.DBR_TIME_DOUBLE(1, 0, 3, 5)
ReadNotifyResponse(data_type=ca.ChannelType.TIME_DOUBLE,
                   data_count=1,
                   data=(7,),
                   metadata=metadata)

or the caller can pass the values as a tuple and let caproto fill in the struct:

ReadNotifyResponse(data_type=ca.ChannelType.TIME_DOUBLE,
                   data_count=5,
                   data=(7,),
                   metadata=(1, 0, 3, 5))

Exceptions ¶

All exceptions directly raised by caproto inherit from CaprotoError.

Errors like CaprotoKeyError inherit from both CaprotoError and the built-in Python KeyError.

The only special exceptions raised by caproto are LocalProtocolError and RemoteProtocolError. These inherit from ProtocolError.

class caproto.LocalProtocolError[source]¶: You tried to do something that caproto thinks is illegal.

class caproto.RemoteProtocolError[source]¶: Your remote peer tried to do something that caproto thinks is illegal.