PVAccess API

Circuits

class caproto.pva._circuit.VirtualCircuit(our_role, address, priority)[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

QOS priority

property priority
property host: str

Peer host name

property port: int

Port number

send(*messages, extra: Optional[Dict] = None)List[Union[bytes, memoryview]][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
*messages :

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)Generator[Tuple[Union[caproto.pva._messages.Message, caproto.pva._utils.ConnectionState], Optional[int]], None, None][source]

Parse messages from buffers received over TCP.

When the caller is ready to process the messages, each message 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

Yields
messageMessage

The message/message.

num_bytes_neededint

Number of bytes needed for the next message.

process_command(message: caproto.pva._messages.Message)[source]

Update internal state machine and raise if protocol is violated.

Received messages 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.

set_byte_order(endian_setting: caproto.pva._messages.EndianSetting)caproto.pva._messages.SetByteOrder[source]

Generate a valid SetByteOrder.

Returns
SetByteOrder
acknowledge_marker()caproto.pva._messages.AcknowledgeMarker[source]

Generate a valid AcknowledgeMarker.

Returns
AcknowledgeMarker
create_channel(name: str, cid: Optional[int] = None)caproto.pva._circuit.Channel[source]

Create a ClientChannel or ServerChannel, depending on the role.

Parameters
namestr

The channel name.

cidint

The client channel ID.

class caproto.pva._circuit.ClientVirtualCircuit(our_role, address, priority)[source]
validate_connection(buffer_size: int, registry_size: int, connection_qos: int, auth_nz: str = 'ca', data=None)caproto.pva._messages.ConnectionValidationResponse[source]

Generate a valid _ConnectionValidationResponse.

Parameters
buffer_sizeint

Client buffer size.

registry_sizeint

Client registry size.

connection_qosint

Connection QOS value.

auth_nzstr, optional

Authorization string, defaults to ‘ca’. Caller must confirm that the server supports the given authorization method prior to specifying it.

Returns
ConnectionValidationResponse
class caproto.pva._circuit.ServerVirtualCircuit(our_role, address, priority)[source]
validate_connection(buffer_size: int, registry_size: int, authorization_options: Sequence)caproto.pva._messages.ConnectionValidationRequest[source]

Generate a valid _ConnectionValidationRequest.

Parameters
buffer_sizeint

Server buffer size.

registry_sizeint

Server registry size.

authorization_optionsSequence

Authorization options, such as ‘ca’ or ‘anonymous’.

Returns
ConnectionValidationRequest
validated_connection()caproto.pva._messages.ConnectionValidatedResponse[source]

Generate a valid _ConnectionValidatedResponse.

Server

class caproto.pva.server.common.ServerStatus(running: bool = True, caproto_version: str = '0.8.1')[source]
class caproto.pva.server.common.AuthOperation(value)[source]

Operations which allow for granular authorization on a per-PV basis.

class caproto.pva.server.common.SubscriptionSpec(db_entry: object, bitset: caproto.pva._fields.BitSet, options: tuple)[source]

Subscription specification used to key all subscription updates.

Attributes
db_entryDataWrapperInterface

The database entry.

bitsetBitSet

The bitset to monitor.

optionstuple

Options for the monitor (tuple(options_dict.items()))

class caproto.pva.server.common.Subscription(spec: caproto.pva.server.common.SubscriptionSpec, circuit: caproto.pva.server.common.VirtualCircuit, channel: caproto.pva._circuit.ServerChannel, ioid: int)[source]

An individual subscription from a client.

Attributes
specSubscriptionSpec

The subscription specification information.

circuitVirtualCircuit

The associated virtual circuit.

channelServerChannel

The associated channel.

ioidint

The I/O identifier / request ID.

class caproto.pva.server.common.VirtualCircuit(circuit: caproto.pva._circuit.ServerVirtualCircuit, client, context: caproto.pva.server.common.Context)[source]

The base VirtualCircuit class.

Servers are expected to subclass from this, including additional attributes, noted in the Attributes section.

Attributes
QueueFullclass

Must be implemented in the subclass. (TODO details)

message_queueQueueInterface

Must be implemented in the subclass.

subscription_queueQueueInterface

Must be implemented in the subclass.

get_from_sub_queuemethod

Must be implemented in the subclass.

_start_write_taskmethod

Start a write handler, and return the task.

connected: bool
circuit: caproto.pva._circuit.ServerVirtualCircuit
log: logging.Logger
client: object
context: caproto.pva.server.common.Context
subscriptions: DefaultDict[caproto.pva.server.common.SubscriptionSpec, Deque[caproto.pva.server.common.Subscription]]
most_recent_updates: Dict
async send(*messages)[source]

Process a message and tranport it over the TCP socket for this circuit.

async recv()[source]

Receive bytes over TCP and append them to this circuit’s buffer.

async subscription_queue_loop()[source]

Subscription queue loop.

This is the final spot where we ship updates off to the client.

async message_queue_loop()[source]

Reference implementation of the message queue loop

class caproto.pva.server.common.Context(pvdb, interfaces=None)[source]
port: Optional[int]
async broadcaster_queue_loop()[source]

Reference broadcaster queue loop implementation

async broadcast_beacon_loop()[source]
async circuit_disconnected(circuit)[source]

Notification from circuit that its connection has closed

async tcp_handler(client, addr)[source]

Handler for each new TCP client to the server

stop()[source]
property startup_methods

Notify all instances of the server startup.

property shutdown_methods

Notify all instances of the server shutdown.

async subscription_queue_loop()[source]

Reference implementation of the subscription queue loop.

class caproto.pva.server.common.DataWrapperBase(name: str, data)[source]

A base class to wrap dataclasses and support caproto-pva’s server API.

Parameters
namestr

The associated name of the data.

dataPvaStruct

The dataclass holding the data.

async authorize(operation: caproto.pva.server.common.AuthOperation, *, authorization, request=None)[source]

Authenticate operation, given authorization information.

In the event of successful authorization, a dataclass defining the data contained here must be returned.

In the event of a failed authorization, AuthenticationError or similar should be raised.

Returns
data
Raises
AuthenticationError
async read(request)[source]

A bare read (get) implementation.

async write(update: caproto.pva._data.DataWithBitSet)[source]

A bare write (put) implementation.

async call(request: caproto.pva._data.PVRequest, data: caproto.pva._data.FieldDescAndData)[source]

A bare call (RPC) implementation.

async subscribe(queue, sub: caproto.pva.server.common.Subscription)[source]

Add a subscription from the server.

It is unlikely this would need customization in a subclass.

Parameters
queueQueueInterface

The queue to send updates to.

subSubscription

Subscription information.

Returns
data
async unsubscribe(queue, sub: caproto.pva.server.common.Subscription)[source]

Remove an already-added subscription.

It is unlikely this would need customization in a subclass.

Parameters
queueQueueInterface

The queue used for subscriptions.

subSubscription

Subscription information.

async commit(changes: dict)[source]

Commit changes to the local dataclass and publish monitors.

It is unlikely this would need customization in a subclass.

Parameters
changesdict

A nested dictionary of key to value, indicating changes to be made to the underlying data.

Command-line

caproto.pva.server.commandline.ioc_arg_parser(*, desc, default_prefix, argv=None, macros=None, supported_async_libs=None)[source]

A reusable ArgumentParser for basic example IOCs.

Parameters
descriptionstring

Human-friendly description of what that IOC does

default_prefixstring
argslist, optional

Defaults to sys.argv

macrosdict, optional

Maps macro names to default value (string) or None (indicating that this macro parameter is required).

supported_async_libslist, optional

“White list” of supported server implementations. The first one will be the default. If None specified, the parser will accept all of the (hard-coded) choices.

Returns
ioc_optionsdict

kwargs to be handed into the IOC init.

run_optionsdict

kwargs to be handed to run

caproto.pva.server.commandline.template_arg_parser(*, desc, default_prefix, argv=None, macros=None, supported_async_libs=None)[source]

Construct a template arg parser for starting up an IOC

Parameters
descriptionstring

Human-friendly description of what that IOC does.

default_prefixstring
argslist, optional

Defaults to sys.argv

macrosdict, optional

Maps macro names to default value (string) or None (indicating that this macro parameter is required).

supported_async_libslist, optional

“White list” of supported server implementations. The first one will be the default. If None specified, the parser will accept all of the (hard-coded) choices.

Returns
parserargparse.ArgumentParser
split_argscallable[argparse.Namespace, Tuple[dict, dict]]

A helper function to extract and split the ‘standard’ CL arguments. This function sets the logging level and returns the kwargs for constructing the IOC and for the launching the server.

caproto.pva.server.commandline.run(pvdb, *, module_name, **kwargs)[source]

Magic

class caproto.pva.server.magic.AuthenticationError[source]
class caproto.pva.server.magic.DatabaseDefinitionError[source]
class caproto.pva.server.magic.DataclassOverlayInstance(instance, *, attr=None, parent=None, owner=None, changes=None)[source]
class caproto.pva.server.magic.WriteUpdate(owner, overlay: caproto.pva.server.magic.DataclassOverlayInstance, changes: dict)[source]
property changes
accept(*keys)[source]

Accept only the provided keys.

reject(*keys)[source]

Reject the provided keys, accepting the remainder.

class caproto.pva.server.magic.GroupDataWrapper(name: str, data, *, group: caproto.pva.server.magic.PVAGroup, prop: caproto.pva.server.magic.pvaproperty)[source]

A base class to wrap dataclasses and support caproto-pva’s server API.

Two easy methods are provided for writing multiple changes to a data structure in one block.

async with group.prop as prop:
    prop.attr1 = 1
    prop.attr2 = 2
async with group.prop(changes={'attr1': 1}) as prop:
    prop.attr2 = 2

When the context manager exits, the values written will be committed and sent out over pvAccess.

Parameters
namestr

The associated name of the data.

dataPvaStruct

The dataclass holding the data.

groupPVAGroup

The group associated with the data.

proppvaproperty

The group’s property which help in binding user hooks.

write_update_class

alias of caproto.pva.server.magic.WriteUpdate

async authorize(operation: caproto.pva.server.common.AuthOperation, *, authorization, request=None)[source]

Authenticate operation, given authorization information.

In the event of successful authorization, a dataclass defining the data contained here must be returned.

In the event of a failed authorization, AuthenticationError or similar should be raised.

Returns
data
Raises
AuthenticationError
async read(request)[source]

A read request.

async write(update: caproto.pva._data.DataWithBitSet)[source]

A write request.

async call(request: caproto.pva._data.PVRequest, data: caproto.pva._data.FieldDescAndData)[source]

An rpc-call request.

class caproto.pva.server.magic.pvaproperty(get=None, put=None, startup=None, shutdown=None, call=None, *, value, name=None, alarm_group=None, doc=None, read_only=None, **cls_kwargs)[source]

A property-like descriptor for specifying a PV in a PVGroup.

Parameters
getasync callable, optional

Called when PV is read through channel access

putasync callable, optional

Called when PV is written to through channel access

startupasync callable, optional

Called at start of server; a hook for initialization and background processing

shutdownasync callable, optional

Called at shutdown of server; a hook for cleanup

valuepva dataclass or instance

The initial value - either an instantiated pva dataclass.

namestr, optional

The PV name (defaults to the attribute name of the pvaproperty)

alarm_groupstr, optional

The alarm group the PV should be attached to

read_onlybool, optional

Read-only PV over channel access

docstr, optional

Docstring associated with the property

**cls_kwargs :

Keyword arguments for the dataclass.

Attributes
attrstr

The attribute name of the pvaproperty.

property name

The pvname suffix.

property read_only

Is the pvaproperty read-only?

property cls_kwargs

Keyword arguments to use on creation of the value instance.

property value

The default value.

getter(get)[source]

Usually used as a decorator, this sets the getter method.

putter(put)[source]

Usually used as a decorator, this sets the putter method.

startup(startup)[source]

Usually used as a decorator, this sets startup method.

shutdown(shutdown)[source]

Usually used as a decorator, this sets shutdown method.

call(call)[source]

Usually used as a decorator, this sets the RPC call method.

property hooks

All user-defined hooks.

class caproto.pva.server.magic.PVAGroupMeta(name, bases, dct)[source]

Metaclass that finds all pvaproperties

static find_pvaproperties(dct)[source]
class caproto.pva.server.magic.PVAGroup(prefix, *, macros=None, parent=None, name=None)[source]

Class which groups a set of PVs for a high-level caproto server

Parameters
prefixstr

Prefix for all PVs in the group.

macrosdict, optional

Dictionary of macro name to value.

parentPVGroup, optional

Parent PVGroup.

namestr, optional

Name for the group, defaults to the class name.

type_map = {<class 'int'>: <class 'caproto.pva._normative.NTScalarInt64'>, <class 'float'>: <class 'caproto.pva._normative.NTScalarFloat64'>, <class 'str'>: <class 'caproto.pva._normative.NTScalarString'>, <class 'bool'>: <class 'caproto.pva._normative.NTScalarBoolean'>}
array_type_map = {<class 'int'>: <class 'caproto.pva._normative.NTScalarArrayInt64'>, <class 'float'>: <class 'caproto.pva._normative.NTScalarArrayFloat64'>, <class 'str'>: <class 'caproto.pva._normative.NTScalarArrayString'>, <class 'bool'>: <class 'caproto.pva._normative.NTScalarArrayBoolean'>}
async group_read(instance, request)[source]

Generic read called for channels without get defined

async group_write(instance, update: caproto.pva.server.magic.WriteUpdate)[source]

Generic write called for channels without put defined

class caproto.pva.server.magic.ServerRPC(*args, server_instance, **kwargs)[source]

Helper group for supporting pvlist and other introspection tools.

class HelpInfo(value: str = '')[source]
value: str = ''
class ChannelListing(value: List[str] = <factory>)[source]
value: List[str]
class ServerInfo(version: str = '', implLang: str = '', host: str = '', process: str = '', startTime: str = '')[source]
version: str = ''
implLang: str = ''
host: str = ''
process: str = ''
startTime: str = ''
caproto.pva.server.magic.verify_getter(attr: str, get: callable)callable[source]

Verify a getter’s call signature.

caproto.pva.server.magic.verify_putter(attr: str, put: callable, *, read_only: bool = False)callable[source]

Verify a putter’s call signature.

caproto.pva.server.magic.verify_rpc_call(attr: str, call: callable, *, read_only: bool = False)callable[source]

Verify an RPC call handler’s signature.

caproto.pva.server.magic.verify_startup(attr: str, method: callable)callable[source]

Verify a startup method’s call signature.

caproto.pva.server.magic.verify_shutdown(attr: str, method: callable)callable[source]

Verify a shutdown method’s call signature.

Asyncio

class caproto.pva.asyncio.server.VirtualCircuit(circuit, client, context, *, loop=None)[source]

Wraps a caproto.pva.VirtualCircuit with an asyncio server.

TaskCancelled

alias of asyncio.exceptions.CancelledError

async get_from_sub_queue(timeout=None)[source]

Get one item from the subscription queue.

Notes

The superclass expects us to implement this in our own way due to timeouts.

async send(*messages)[source]

Process a message and tranport it over the TCP socket for this circuit.

async run()[source]
context: caproto.pva.asyncio.server.Context
connected: bool
circuit: caproto.pva._circuit.ServerVirtualCircuit
log: logging.Logger
client: object
most_recent_updates: Dict
subscriptions: DefaultDict[caproto.pva.server.common.SubscriptionSpec, Deque[caproto.pva.server.common.Subscription]]
class caproto.pva.asyncio.server.Context(pvdb, interfaces=None, *, loop=None)[source]
CircuitClass

alias of caproto.pva.asyncio.server.VirtualCircuit

exception ServerExit
TaskCancelled

alias of asyncio.exceptions.CancelledError

async_layer = None
async server_accept_loop(sock)[source]

Start a TCP server on sock and listen for new connections.

property guid: str

The server GUID.

async run(*, log_pv_names=False)[source]

Start the server.

Parameters
log_pv_namesbool, optional

Log all PV names to self.log after starting up.

async broadcaster_receive_loop()[source]
port: Optional[int]
async caproto.pva.asyncio.server.start_server(pvdb, *, interfaces=None, log_pv_names=False)[source]

Start an asyncio server with a given PV database

caproto.pva.asyncio.server.run(pvdb, *, interfaces=None, log_pv_names=False)[source]

A synchronous function that wraps start_server and exits cleanly.

Clients

Synchronous

caproto.pva.sync.client.read(pv_name, *, pvrequest='field()', verbose=False, timeout=1)[source]

Read a Channel.

Parameters
pv_namestr

The PV name.

pvrequeststr, optional

The PVRequest, such as ‘field(value)’. Defaults to ‘field()’ for retrieving all data.

verboseboolean, optional

Verbose logging. Default is False.

timeoutfloat, optional

Default is 1 second.

Examples

Get the value of a Channel named ‘cat’. >>> get(‘cat’)

caproto.pva.sync.client.monitor(pv_name, *, pvrequest='field()', verbose=False, timeout=1, maximum_events=None)[source]

Monitor a Channel.

Parameters
pv_namestr

The PV name.

pvrequeststr

The PVRequest, such as ‘field(value)’.

verboseboolean, optional

Verbose logging. Default is False.

timeoutfloat, optional

Default is 1 second.

caproto.pva.sync.client.read_write_read(pv_name: str, data: dict, *, options: Optional[dict] = None, pvrequest: str = 'field()', cancel_on_keyboardinterrupt: bool = False, timeout=1)[source]

Write to a Channel, but sandwich the write between two reads.

Parameters
pv_namestr

The PV name.

datadict or Mapping

The structured data to write.

pvrequeststr, optional

The PVRequest, such as ‘field(value)’. Defaults to ‘field()’ for retrieving all data.

optionsdict, optional

Options to use in the pvRequest. (TODO not yet implemented)

timeoutfloat, optional

Timeout for the operation.

cancel_on_keyboardinterruptbool, optional

Cancel the write in the event of a KeyboardInterrupt.

Messages

class caproto.pva._messages.MessageHeader(*, flags: caproto.pva._messages.MessageFlags, command: Union[caproto.pva._messages.ControlCommand, caproto.pva._messages.ApplicationCommand], payload_size: int)[source]
magic: int
version: int
message_command: Union[int, caproto.pva._messages.ControlCommand, caproto.pva._messages.ApplicationCommand]
payload_size: int
property flags
property valid
property byte_order

Byte order/endianness of message

get_message(direction: caproto.pva._messages.MessageFlags, *, use_fixed_byte_order=None)[source]
caproto.pva._messages.bytes_needed_for_command(data, direction, cache, *, byte_order=None)[source]
Parameters
data
direction
Returns
(header, num_bytes_needed, segmented)
If segmented, num_bytes_needed only applies to the current segment.
caproto.pva._messages.header_from_wire(data: bytes, byte_order: Optional[caproto.pva._core.UserFacingEndian] = None)caproto.pva._messages.MessageHeader[source]

Deserialize a message header from the wire.

Parameters
databytes

The data to deserialize.

byte_orderLITTLE_ENDIAN or BIG_ENDIAN, optional

Defaults to BIG_ENDIAN, falling back to LITTLE_ENDIAN if incorrect. If specified, the fallback is not attempted.

caproto.pva._messages.read_datagram(data: bytes, address: Tuple[str, int], role: caproto._utils.Role, *, fixed_byte_order: Optional[caproto.pva._core.UserFacingEndian] = None, cache: Optional[caproto.pva._core.CacheContext] = None)caproto.pva._core.Deserialized[source]

Parse bytes from one datagram into one or more commands.

Parameters
databytes

The data to deserialize.

address(addr, port)

The sender’s address.

roleRole

The role of the sender.

fixed_byte_orderUserFacingEndian, optional

Use this specific byte order for deserialization.

cacheCacheContext, optional

The serialization cache.

caproto.pva._messages.read_from_bytestream(data: bytes, role: caproto._utils.Role, segment_state: Optional[Union[caproto.pva._utils.ChannelLifeCycle, bytes]], cache: caproto.pva._core.CacheContext, *, byte_order=<enum 'UserFacingEndian'>)caproto.pva._core.SegmentDeserialized[source]

Handles segmentation but requires the caller to track it for us.

Parameters
databytes

The new data.

roleRole

Their role.

segment_stateChannelLifeCycle, byte, or None

The state of segmentation, if available.

cacheCacheContext

Serialization cache context.

byte_orderLITTLE_ENDIAN or BIG_ENDIAN, optional

Fixed byte order if server message endianness is to be interpreted on a message-by-message basis.

Returns
SegmentDeserialized

Control

class caproto.pva._messages.BeaconMessage(guid: str, sequence_id: int, server_address: Tuple[str, int], server_status: caproto.pva._data.FieldDescAndData, *, change_count: int = 0, flags: int = 0, protocol: str = 'tcp')[source]

A beacon message.

Notes

Servers MUST broadcast or multicast beacons over UDP. Beacons are be used to announce the appearance and continued presense of servers. Clients may use Beacons to detect when new servers appear, and may use this information to more quickly retry unanswered CMD_SEARCH messages.

Attributes
guid12 bytes

GUID for server

flags :

Reserved (unused).

sequence_id :

Beacon sequence ID (counter with rollover). Can be used to detect UDP routing problems.

change_count :

Count (with rollover) that changes every time server’s list of channels changes.

server_address :

Server address. For IP transports IPv6 or IPv6 encoded IPv4 address.

server_portint

Server port. For IP transport socket port where server is listening.

protocolstr

Protocol/transport name. “tcp” for standard pvAccess TCP/IP communication.

server_statusFieldDescAndData

Optional server status Field description, NULL_TYPE_CODE MUST be used indicate absence of data.

ID = 0
flags: int
sequence_id: int
change_count: int
property guid

GUID for server

property server_address
server_port: int
class caproto.pva._messages.MessageHeaderLE(*, flags: caproto.pva._messages.MessageFlags, command: Union[caproto.pva._messages.ControlCommand, caproto.pva._messages.ApplicationCommand], payload_size: int)[source]
magic: int

Structure/Union member

message_command: Union[int, caproto.pva._messages.ControlCommand, caproto.pva._messages.ApplicationCommand]

Structure/Union member

payload_size: int

Structure/Union member

version: int

Structure/Union member

class caproto.pva._messages.MessageHeaderBE(*, flags: caproto.pva._messages.MessageFlags, command: Union[caproto.pva._messages.ControlCommand, caproto.pva._messages.ApplicationCommand], payload_size: int)[source]
magic: int

Structure/Union member

message_command: Union[int, caproto.pva._messages.ControlCommand, caproto.pva._messages.ApplicationCommand]

Structure/Union member

payload_size: int

Structure/Union member

version: int

Structure/Union member

class caproto.pva._messages.SetMarker(*, flags: caproto.pva._messages.MessageFlags, command: Union[caproto.pva._messages.ControlCommand, caproto.pva._messages.ApplicationCommand], payload_size: int)[source]

A control command which sets a marker for total bytes sent.

Notes

(from pva documentation) Note that this message type has so far not been used.

The payload size field holds the value of the total bytes sent. The client SHOULD respond with an acknowledgment control message (0x01) as soon as possible.

ID = 0
class caproto.pva._messages.AcknowledgeMarker(*, flags: caproto.pva._messages.MessageFlags, command: Union[caproto.pva._messages.ControlCommand, caproto.pva._messages.ApplicationCommand], payload_size: int)[source]

A control command to acknowledge the total bytes received.

Notes

(from pva documentation) Note that this message type has so far not been used.

The payload size field holds the acknowledge value of total bytes received. This must match the previously received marked value as described above.

ID = 1
class caproto.pva._messages.SetByteOrder(endian_setting: caproto.pva._messages.EndianSetting, *, flags: caproto.pva._messages.MessageFlags)[source]

An indicator to set the byte order of future messages.

Notes

The 7-th bit of a header flags field indicates the server’s selected byte order for the connection on which this message was received. Client MUST encode all the messages sent via this connection using this byte order.

ID = 2
property byte_order_setting
class caproto.pva._messages.EchoRequest(*, flags: caproto.pva._messages.MessageFlags, command: Union[caproto.pva._messages.ControlCommand, caproto.pva._messages.ApplicationCommand], payload_size: int)[source]

A request to echo the payload.

Notes

Diagnostic/test echo message. The receiver should respond with an Echo response (0x04) message with the same payload size field value.

In protocol version v1: * v1 servers reply to ‘Echo’ with empty payload. * v1 clients never send ‘Echo’. * v1 peers never timeout inactive TCP connections.

In protocol version v2: * v2 clients must send ‘Echo’ more often than $EPICS_PVA_CONN_TMO seconds. The recommended interval is half of $EPICS_PVA_CONN_TMO (default 15 sec.).

ID = 3
class caproto.pva._messages.EchoResponse(*, flags: caproto.pva._messages.MessageFlags, command: Union[caproto.pva._messages.ControlCommand, caproto.pva._messages.ApplicationCommand], payload_size: int)[source]

A response to an echo request.

Notes

The payload size field contains the same value as in the request message.

In protocol version v2: * v2 server’s ‘Echo’ reply must include the request payload. * v2 peers must close TCP connections when no data has been received in $EPICS_PVA_CONN_TMO seconds (default 30 sec.).

ID = 3

Application

class caproto.pva._messages.ConnectionValidationRequest[source]

A validation request from the server.

Notes

A ConnectionValidationRequest message MUST be the first application message sent from the server to a client when a TCP/IP connection is established (after a Set byte order Control message). The client MUST NOT send any messages on the connection until it has received a connection validation message from the server.

The server lists the support authentication methods. Currently supported are “anonymous” and “ca”. In the ConnectionValidationResponse, the client selects one of these. For “anonymous”, no further detail is required. For “ca”, a structure with string elements “user” and “host” needs to follow.

ID = 1
server_buffer_size: int
server_registry_size: int
class caproto.pva._messages.ConnectionValidationResponse[source]

A client’s connection validation response message.

Notes

Each Quality of Service (QoS) parameter value REQUIRES a separate TCP/IP connection. If the Low-latency priority bit is set, this indicates clients should attempt to minimize latency if they have the capacity to do so. If the Throughput priority bit is set, this indicates a client similarly should attempt to maximize throughput. How this is achieved is implementation defined. The Compression bit enables compression for the connection (Which compression? From which support layer?). A matter for a future version of the specification should be whether a streaming mode algorithm should be specified.

ID = 1
client_buffer_size: int
client_registry_size: int
connection_qos: int
auth_nz: str
data: caproto.pva._data.FieldDescAndData
class caproto.pva._messages.Echo[source]

A TCP Echo request/response.

Notes

An Echo diagnostic message is usually sent to check if TCP/IP connection is still valid.

ID = 2
class caproto.pva._messages.ConnectionValidatedResponse(status=Status(OK))[source]

Validation results - success depends on the status.

ID = 9
class caproto.pva._messages.SearchRequest(sequence_id: int, response_address: Tuple[str, int], channels: List[caproto.pva._messages.ChannelWithID], *, protocols=None, flags: caproto.pva._messages.SearchFlags = <SearchFlags.broadcast: 0>)[source]

A search request for PVs by name.

Notes

A channel “search request” message SHOULD be sent over UDP/IP, however UDP congestion control SHOULD be implemented in this case. A server MUST accept this message also over TCP/IP.

Note that the element count for protocol uses the normal size encoding, i.e. unsigned 8-bit integer 1 for one supported protocol. The element count for the channels array, however, always uses an unsigned 16 bit integer. This choice is based on the reference implementations which append channel names to the network buffer and update the count. With normal size encoding, an increment to 254 would change the count from requiring 1 byte to 3 bytes, shifting already added channel names.

In caproto-pva, this becomes the NonstandardArrayField.

ID = 3
sequence_id: int
reserved: bytes
response_port: int
property response_address
serialize(*args, **kwargs)[source]
flags: int
class caproto.pva._messages.SearchResponse(guid: str, sequence_id: int, server_address: Tuple[str, int], search_instance_ids: List[int], *, found: bool = True, protocol: str = 'tcp')[source]

A response to a SearchRequest.

Parameters
guidstr

The server’s globally unique identifier.

sequence_idint

The sequence id, which should correspond to the request.

server_addressAddressTuple

The server that hosts the data.

search_instance_idslist of integers

The search IDs that have been found (or not).

foundbool, optional

Whether the given IDs were found on the server or not. Defaults to True.

protocolstr = ‘tcp’

The protocol where the search results can be retrieved from. tcp is the only supported option here.

Notes

A client MUST examine the protocol member field to verify it supports the given exchange protocol; if not, the search response is ignored.

The count for the number of searchInstanceIDs elements is always sent as an unsigned 16 bit integer, not using the default size encoding.

ID = 4
property guid

GUID for server

sequence_id: int
property server_address
server_port: int
class caproto.pva._messages.CreateChannelRequest[source]

A client’s request to create a channel.

Notes

A channel provides a communication path between a client and a server hosted “process variable.” Each channel instance MUST be bound only to one connection.

The CreateChannelRequest.channels array starts with a short count, not using the normal size encoding. Current PVA server implementations only support requests for creating a single channel, i.e. the count must be 1.

ID = 7
count: int
channels: List[Union[caproto.pva._messages.ChannelWithID, Dict]]
class caproto.pva._messages.CreateChannelResponse(client_chid: int, server_chid: int, access_rights: int = 0, status=Status(OK))[source]

A server’s response to a CreateChannelRequest.

Notes

A server MUST store the client ChannelID and respond with its value in a ChannelDestroyRequest, see below.

A client uses the serverChannelID value for all subsequent requests on the channel. Agents SHOULD NOT make any assumptions about how given IDs are generated. IDs MUST be unique within a connection and MAY be recycled after a channel is disconnected.

ID = 7
client_chid: int
server_chid: int
class caproto.pva._messages.ChannelDestroyRequest[source]

Request to destroy a previously-created channel.

Notes

A “destroy channel” message is sent by a client to a server to destroy a channel that was previously created (with a create channel message).

A server may also send this message to the client when the channel is no longer available. Examples include a PVA gateway that sends this message from its server side when it lost a channel on its client side.

ID = 8
client_chid: int
server_chid: int
class caproto.pva._messages.ChannelDestroyResponse(client_chid: int, server_chid: int, status=Status(OK))[source]

A response to a destroy request.

Notes

If the request (clientChannelID, serverChannelID) pair does not match, the server MUST respond with an error status. The server MAY break its response into several messages.

A server MUST send this message to a client to notify the client about server-side initiated channel destruction. Subsequently, a client MUST mark such channels as disconnected. If the client’s interest in the process variable continues, it MUST start sending search request messages for the channel.

ID = 8
client_chid: int
server_chid: int
class caproto.pva._messages.ChannelGetRequest[source]

A “channel get” set of messages are used to retrieve (get) data from the channel.

ID = 10
server_chid: int
ioid: int
pv_request: caproto.pva._data.PVRequest
to_init(pv_request: caproto.pva._data.PVRequest)caproto.pva._messages.ChannelGetRequest[source]
to_get()caproto.pva._messages.ChannelGetRequest[source]
class caproto.pva._messages.ChannelGetResponse(ioid, status=Status(OK), subcommand=<Subcommand.INIT: 8>)[source]

A response to a ChannelGetRequest.

ID = 10
ioid: int
pv_structure_if: caproto.pva._fields.FieldDesc
pv_data: Any
to_init(pv_structure_if: caproto.pva._fields.FieldDesc)caproto.pva._messages.ChannelGetResponse[source]

Initialize the get response.

Parameters
pv_structure_ifFieldDesc

The field description of the data that can be retrieved with a GET/DEFAULT subcommand.

to_get(pv_data: caproto.pva._data.DataWithBitSet)caproto.pva._messages.ChannelGetResponse[source]

Initialize the get response, including data.

Parameters
pv_dataDataWithBitSet

The data to respond with.

See also

to_default()
to_default(pv_data: caproto.pva._data.DataWithBitSet)caproto.pva._messages.ChannelGetResponse[source]

Initialize the get response, including data. A synonym for “get”.

Parameters
pv_dataDataWithBitSet

The data to respond with.

See also

to_get()
class caproto.pva._messages.ChannelFieldInfoRequest[source]

Used to retrieve a channel’s type introspection data, i.e., a FieldDesc.

ID = 17
server_chid: int
ioid: int
class caproto.pva._messages.ChannelFieldInfoResponse(ioid, interface, status=Status(OK))[source]

A response to a ChannelFieldInfoRequest.

ID = 17
ioid: int
class caproto.pva._messages.ChannelPutRequest[source]

A “channel put” message is used to set (put) data to the channel.

After a put request is successfully initialized, the client can issue actual put request(s) on the channel.

Notes

A “GET_PUT” subcommand here retrieves the remote put structure. This MAY be used by user applications to show data that was set the last time by the application.

ID = 11
server_chid: int
ioid: int
to_init(pv_request: caproto.pva._data.PVRequest)caproto.pva._messages.ChannelPutRequest[source]

Initialize the request.

Parameters
pv_requestPVRequest

The PVRequest for used when requesting to read back the data (not the data to write).

to_default(put_data: caproto.pva._data.DataWithBitSet)caproto.pva._messages.ChannelPutRequest[source]

Perform the put.

Parameters
put_dataDataWithBitSet

The data to write.

to_get()caproto.pva._messages.ChannelPutRequest[source]

Query the data, according to the INIT PVRequest.

class caproto.pva._messages.ChannelPutResponse(ioid, status=Status(OK), subcommand=<Subcommand.INIT: 8>)[source]

A response to a ChannelPutRequest.

ID = 11
ioid: int
put_structure_if: Optional[caproto.pva._fields.FieldDesc] = None
status: caproto.pva._fields.Status
to_init(put_structure_if: caproto.pva._fields.FieldDesc)caproto.pva._messages.ChannelPutResponse[source]

Initialize the request.

Parameters
put_structure_ifFieldDesc

The structure of the data, so the client knows how to write it appropriately.

to_default()caproto.pva._messages.ChannelPutResponse[source]

Respond to the put request.

to_get(data: caproto.pva._data.DataWithBitSet)caproto.pva._messages.ChannelPutResponse[source]

Query the data, according to the client’s INIT PVRequest.

class caproto.pva._messages.ChannelPutGetRequest[source]

A “channel put-get” set of messages are used to set (put) data to the channel and then immediately retrieve data from the channel. Channels are usually “processed” or “updated” by their host between put and get, so that the get reflects changes in the process variable’s state.

After a put-get request is successfully initialized, the client can issue actual put-get request(s) on the channel.

Notes

A “GET_PUT” request retrieves the remote put structure. This MAY be used by user applications to show data that was set the last time by the application.

This is not yet implemented in caproto-pva.

ID = 12
server_chid: int
ioid: int
class caproto.pva._messages.ChannelPutGetResponse[source]

A response to a ChannelPutGetRequest.

Notes

This is not yet implemented in caproto-pva.

ID = 12
ioid: int
get_structure_if: Optional[caproto.pva._fields.FieldDesc]
put_structure_if: Optional[caproto.pva._fields.FieldDesc]
get_data: Optional[Any]
put_data: Optional[Any]
pv_data: Optional[Any]
class caproto.pva._messages.ChannelArrayRequest[source]

A “channel array” set of messages are used to handle remote array values. Requests allow a client agent to: retrieve (get) and set (put) data from/to the array, and to change the array’s length (number of valid elements in the array).

Notes

This is not yet implemented in caproto-pva.

ID = 14
class caproto.pva._messages.ChannelArrayResponse[source]

A response to a ChannelArrayRequest.

Notes

This is not yet implemented in caproto-pva.

ID = 14
class caproto.pva._messages.ChannelRequestDestroy[source]

A “destroy request” messages is used destroy any request instance, i.e. an instance with requestID.

Notes

There is no ChannelRequestDestroyResponse.

ID = 15
server_chid: int
ioid: int
class caproto.pva._messages.ChannelRequestCancel[source]

A “cancel request” messages is used cancel any pending request, i.e. an instance with a requestID.

Notes

This is not yet implemented in caproto-pva.

** There is no response message defined in the protocol. **

ID = 21
class caproto.pva._messages.ChannelMonitorRequest[source]

The “channel monitor” set of messages are used by client agents to indicate that they wish to be asynchronously informed of changes in the state or values of the process variable of a channel.

Notes

This is currently partially supported by caproto-pva.

More details on the wiki.

ID = 13
server_chid: int
ioid: int
to_init(pv_request: caproto.pva._data.PVRequest, queue_size: int = 0)caproto.pva._messages.ChannelMonitorRequest[source]
to_start()[source]
to_stop()[source]
to_pipeline(nfree: int)caproto.pva._messages.ChannelMonitorRequest[source]
class caproto.pva._messages.ChannelMonitorResponse[source]

A response to a ChannelMonitorRequest.

ID = 13
ioid: int
pv_structure_if: caproto.pva._fields.FieldDesc
pv_data: Any
overrun_bitset: caproto.pva._fields.BitSet
status: caproto.pva._fields.Status
to_init(status: caproto.pva._fields.Status, pv_structure_if: caproto.pva._fields.FieldDesc)caproto.pva._messages.ChannelMonitorResponse[source]
to_default(pv_data: caproto.pva._data.DataWithBitSet, overrun_bitset: caproto.pva._fields.BitSet)caproto.pva._messages.ChannelMonitorResponse[source]
to_pipeline(nfree: int)caproto.pva._messages.ChannelMonitorResponse[source]
class caproto.pva._messages.ChannelProcessRequest[source]

A “channel process” set of messages are used to indicate to the server that the computation actions associated with a channel should be executed.

In EPICS terminology, this means that the channel should be “processed”.

Notes

After a process request is successfully initialized, the client can issue the actual process request(s).

ID = 16
server_chid: int
ioid: int
class caproto.pva._messages.ChannelProcessResponse[source]

A response to a ChannelProcessRequest.

ID = 16
ioid: int
class caproto.pva._messages.ChannelRpcRequest[source]

A remote procedure call request.

Notes

The “channel RPC” set of messages are used to provide remote procedure call (RPC) support over pvAccess. After a RPC request is successfully initialized, the client can issue actual RPC request(s).

ID = 20
server_chid: int
ioid: int
to_init(pv_request: caproto.pva._data.PVRequest)caproto.pva._messages.ChannelRpcRequest[source]
to_default(pv_data: caproto.pva._data.FieldDescAndData)caproto.pva._messages.ChannelRpcRequest[source]
class caproto.pva._messages.ChannelRpcResponse[source]

A remote procedure call response.

ID = 20
ioid: int
to_init(status: caproto.pva._fields.Status)caproto.pva._messages.ChannelRpcResponse[source]
to_default(status: caproto.pva._fields.Status, pv_response: caproto.pva._data.FieldDescAndData)caproto.pva._messages.ChannelRpcResponse[source]