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)

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)

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)

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)

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)

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

Request an EchoResponse.

This command has no fields.

class caproto.EchoResponse

Respond to an EchoRequest.

This command has no fields.

class caproto.Beacon(version, server_port, beacon_id, address)

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

Register a client with the Repeater.

Fields:

client_address

IP address of the client (as a string).

class caproto.RepeaterConfirmResponse(repeater_address)

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)

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)

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)

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)

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)

Deprecated by Channel Access since 3.13. See ReadNotifyRequest.

class caproto.ReadResponse(data, data_type, data_count, sid, ioid, *, metadata=None)

Deprecated by Channel Access since 3.13. See ReadNotifyResponse.

class caproto.WriteRequest(data, data_type, data_count, sid, ioid, *, metadata=None)

Deprecated: See WriteNotifyRequest.

class caproto.EventsOffRequest

Temporarily turn off EventAddResponse notifications.

This command has no fields.

class caproto.EventsOnRequest

Restore EventAddResponse notifications.

This command has no fields.

class caproto.ReadSyncRequest

Deprecated by Channel Access: See ReadNotifyRequest

class caproto.ErrorResponse(original_request, cid, status, error_message)

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)

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)

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)

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)

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)

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)

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)

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

Fields:

name

Client name.

class caproto.HostNameRequest(name)

Tell the server the host name of the client.

Fields:

name

Host name.

class caproto.AccessRightsResponse(cid, access_rights)

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)

Notify the client that channel creation failed.

Fields:

cid

Integer ID for this Channel designated by the client.

class caproto.ServerDisconnResponse(cid)

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)

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)

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)

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)

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()

Notify all channels on this circuit that they are disconnected.

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

new_channel_id()

Return a valid value for a cid or sid.

new_subscriptionid()

This is used by the convenience methods to obtain an unused integer ID. It does not update any important state.

new_ioid()

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)

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)

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)

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)

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

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

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()

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)

Generate a valid HostNameRequest.

Parameters:

host_namestring

Returns:

HostNameRequest

client_name(client_name)

Generate a valid ClientNameRequest.

Parameters:

client_namestring, optional

defaults to output of getpass.getuser()

Returns:

ClientNameRequest

create()

Generate a valid CreateChanRequest.

Returns:

CreateChanRequest

read(data_type=None, data_count=None, ioid=None, notify=True)

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)

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)

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)

Generate a valid EventAddRequest.

Parameters:

subscriptionidinteger

The subscriptionid that was originally sent in the corresponding EventAddRequest.

Returns:

EventAddRequest

clear()

Generate a valid ClearChannelRequest.

Returns:

ClearChannelRequest

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

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()

Generate a valid VersionResponse.

Returns:

VersionResponse

create(native_data_type, native_data_count, sid)

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()

Generate a valid CreateChFailResponse.

Returns:

CreateChFailResponse

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

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)

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, metadata=None)

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)

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()

Generate a valid ClearChannelResponse

Returns:

ClearChannelResposne

disconnect()

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)

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

You tried to do something that caproto thinks is illegal.

class caproto.RemoteProtocolError

Your remote peer tried to do something that caproto thinks is illegal.