PVAccess API

Circuits

class caproto.pva._circuit.VirtualCircuit(our_role, address, priority)

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]]

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]

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)

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

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.

set_byte_order(endian_setting: caproto.pva._messages.EndianSetting) → caproto.pva._messages.SetByteOrder

Generate a valid SetByteOrder.

Returns

SetByteOrder

acknowledge_marker() → caproto.pva._messages.AcknowledgeMarker

Generate a valid AcknowledgeMarker.

Returns

AcknowledgeMarker

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

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)

validate_connection(buffer_size: int, registry_size: int, connection_qos: int, auth_nz: str = 'ca', data=None) → caproto.pva._messages.ConnectionValidationResponse

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)

validate_connection(buffer_size: int, registry_size: int, authorization_options: Sequence) → caproto.pva._messages.ConnectionValidationRequest

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

Generate a valid _ConnectionValidatedResponse.

Server

class caproto.pva.server.common.ServerStatus(running: bool = True, caproto_version: str = '0.8.1')

class caproto.pva.server.common.AuthOperation(value)

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)

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)

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)

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)

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

async recv()

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

async subscription_queue_loop()

Subscription queue loop.

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

async message_queue_loop()

Reference implementation of the message queue loop

class caproto.pva.server.common.Context(pvdb, interfaces=None)

port: Optional[int]

async broadcaster_queue_loop()

Reference broadcaster queue loop implementation

async broadcast_beacon_loop()

async circuit_disconnected(circuit)

Notification from circuit that its connection has closed

async tcp_handler(client, addr)

Handler for each new TCP client to the server

stop()

property startup_methods

Notify all instances of the server startup.

property shutdown_methods

Notify all instances of the server shutdown.

async subscription_queue_loop()

Reference implementation of the subscription queue loop.

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

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)

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)

A bare read (get) implementation.

async write(update: caproto.pva._data.DataWithBitSet)

A bare write (put) implementation.

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

A bare call (RPC) implementation.

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

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)

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)

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)

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)

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)

Magic

class caproto.pva.server.magic.AuthenticationError

class caproto.pva.server.magic.DatabaseDefinitionError

class caproto.pva.server.magic.DataclassOverlayInstance(instance, *, attr=None, parent=None, owner=None, changes=None)

class caproto.pva.server.magic.WriteUpdate(owner, overlay: caproto.pva.server.magic.DataclassOverlayInstance, changes: dict)

property changes

accept(*keys)

Accept only the provided keys.

reject(*keys)

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)

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)

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)

A read request.

async write(update: caproto.pva._data.DataWithBitSet)

A write request.

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

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)

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)

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

putter(put)

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

startup(startup)

Usually used as a decorator, this sets startup method.

shutdown(shutdown)

Usually used as a decorator, this sets shutdown method.

call(call)

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)

Metaclass that finds all pvaproperties

static find_pvaproperties(dct)

class caproto.pva.server.magic.PVAGroup(prefix, *, macros=None, parent=None, name=None)

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)

Generic read called for channels without get defined

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

Generic write called for channels without put defined

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

Helper group for supporting pvlist and other introspection tools.

class HelpInfo(value: str = '')

value: str = ''

class ChannelListing(value: List[str] = <factory>)

value: List[str]

class ServerInfo(version: str = '', implLang: str = '', host: str = '', process: str = '', startTime: str = '')

version: str = ''

implLang: str = ''

host: str = ''

process: str = ''

startTime: str = ''

caproto.pva.server.magic.verify_getter(attr: str, get: callable) → callable

Verify a getter’s call signature.

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

Verify a putter’s call signature.

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

Verify an RPC call handler’s signature.

caproto.pva.server.magic.verify_startup(attr: str, method: callable) → callable

Verify a startup method’s call signature.

caproto.pva.server.magic.verify_shutdown(attr: str, method: callable) → callable

Verify a shutdown method’s call signature.

Asyncio

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

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

TaskCancelled

alias of asyncio.exceptions.CancelledError

async get_from_sub_queue(timeout=None)

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)

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

async run()

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)

CircuitClass

alias of caproto.pva.asyncio.server.VirtualCircuit

exception ServerExit

TaskCancelled

alias of asyncio.exceptions.CancelledError

async_layer = None

async server_accept_loop(sock)

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

property guid: str

The server GUID.

async run(*, log_pv_names=False)

Start the server.

Parameters

log_pv_namesbool, optional

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

async broadcaster_receive_loop()

port: Optional[int]

async caproto.pva.asyncio.server.start_server(pvdb, *, interfaces=None, log_pv_names=False)

Start an asyncio server with a given PV database

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

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)

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)

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)

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)

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)

caproto.pva._messages.bytes_needed_for_command(data, direction, cache, *, byte_order=None)

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

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

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

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

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)

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)

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)

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)

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)

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)

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)

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

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

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

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

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

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)

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

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

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

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

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

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

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

to_get() → caproto.pva._messages.ChannelGetRequest

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

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

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

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

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

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

A response to a ChannelFieldInfoRequest.

ID = 17

ioid: int

class caproto.pva._messages.ChannelPutRequest

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

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

Perform the put.

Parameters

put_dataDataWithBitSet

The data to write.

to_get() → caproto.pva._messages.ChannelPutRequest

Query the data, according to the INIT PVRequest.

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

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

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

Respond to the put request.

to_get(data: caproto.pva._data.DataWithBitSet) → caproto.pva._messages.ChannelPutResponse

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

class caproto.pva._messages.ChannelPutGetRequest

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

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

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

A response to a ChannelArrayRequest.

Notes

This is not yet implemented in caproto-pva.

ID = 14

class caproto.pva._messages.ChannelRequestDestroy

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

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

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

to_start()

to_stop()

to_pipeline(nfree: int) → caproto.pva._messages.ChannelMonitorRequest

class caproto.pva._messages.ChannelMonitorResponse

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

to_default(pv_data: caproto.pva._data.DataWithBitSet, overrun_bitset: caproto.pva._fields.BitSet) → caproto.pva._messages.ChannelMonitorResponse

to_pipeline(nfree: int) → caproto.pva._messages.ChannelMonitorResponse

class caproto.pva._messages.ChannelProcessRequest

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

A response to a ChannelProcessRequest.

ID = 16

ioid: int

class caproto.pva._messages.ChannelRpcRequest

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

to_default(pv_data: caproto.pva._data.FieldDescAndData) → caproto.pva._messages.ChannelRpcRequest

class caproto.pva._messages.ChannelRpcResponse

A remote procedure call response.

ID = 20

ioid: int

to_init(status: caproto.pva._fields.Status) → caproto.pva._messages.ChannelRpcResponse

to_default(status: caproto.pva._fields.Status, pv_response: caproto.pva._data.FieldDescAndData) → caproto.pva._messages.ChannelRpcResponse