SCPI package (ska_ser_scpi)
This package provides SCPI support.
It is implemented as a three-layer stack:
The bottom layer works with SCPI byte strings;
The middle layer works with device-dependent SCPI queries, commands and set operations;
The top layer works with device-independent attribute queries, commands and set operations.
The following module diagram shows decomposition and “uses” relationships. Though it might not appear layered at first glance, it shows
a client stack in which each layer uses only its own layer and the layer immediately below;
a server stack in which each layer uses only its own layer and the layer immediately above.
- class ska_ser_scpi.AttributeClient(scpi_client, attribute_definitions)
Client interface for attribute payloads.
Used to transmit an attribute request, and then receive an attribute response.
- __init__(scpi_client, attribute_definitions)
Initialise a new instance.
- Parameters:
scpi_client (
ScpiClient) – The underlying SCPI client interface.attribute_definitions (
dict[str,dict[str,AttributeDefinitionType]]) – definitions of the attributes that the SCPI interface supports.
- __weakref__
list of weak references to the object (if defined)
- send_receive(attribute_request)
Send an attribute request, and receive an attribute response.
- Parameters:
attribute_request (
AttributeRequest) – details of the attribute request to be sent.- Return type:
- Returns:
details of the attribute response.
- class ska_ser_scpi.AttributeDefinitionType
Type specification for an attribute definition dictionary.
- __weakref__
list of weak references to the object (if defined)
- class ska_ser_scpi.AttributeRequest
Representation of an attribute request.
An attribute request specifies
the attributes whose values are to be read (“queries”)
values to be written to attributes (“setops”). These setops allow for multiple arguments, so they cover the command invocation case as well.
- __bool__()
Return the boolean value of this object.
Consistent with other container objects, this method returns whether this request is non-empty.
- Return type:
- Returns:
whether this request is non-empty.
- __eq__(other)
Check for equality with another object.
- __ge__(other)
Check if this object is greater than or equal to another object.
See
__lt__()for rationale.
- __hash__ = None
- __init__()
Initialise a new instance.
- __le__(other)
Check if this object is less than or equal to another object.
See
__lt__()for rationale.
- __lt__(other)
Check if this object is less than another object.
When an attribute request is marshalled to a SCPI request, a query on a boolean attribute may marshall down to a query on a SCPI flag field. This will in turn unmarshall to a query on all boolean attributes that contribute to that SCPI flag field. Thus, the final attribute request that results from marshalling an original attribute request, sending it through a SCPI interface, and then unmarshalling it again, may not be exactly equal to the original request, but will always subsume it. This subsumption relationship is implemented here using the “rich comparison” operations, so that it can be used in testing.
- __repr__()
Return a string representation of this object.
- Return type:
- Returns:
a string representation of this object.
- __weakref__
list of weak references to the object (if defined)
- add_setop(attribute, *args)
Add an attribute to be set as part of this request.
- copy()
Return a shallow copy of this attribute request.
- Return type:
- Returns:
a shallow copy of this attribute request.
- property queries: list[str]
Return a list of attributes queried in this request.
- Returns:
a list of queried attributes.
- set_queries(*attributes)
Set the attributes to be queried as part of this request.
- property setops: list[tuple[str, Any]]
Return the set operations to be performed in this request.
- Returns:
a dictionary, keyed by the name of the attribute to be written (or commanded), with values being lists of arguments to the setop. For writes, this list will only have one element, which is the value to be written. For commands, the list will be arguments to the command.
- class ska_ser_scpi.AttributeResponse
Representation of an attribute response.
An attribute response specifies values of attributes that have been queried in an attribute request.
- __eq__(other)
Check for equality with another object.
- __hash__ = None
- __init__()
Initialise a new instance.
- __weakref__
list of weak references to the object (if defined)
- add_query_response(attribute, value)
Add a response to an attribute value query.
- class ska_ser_scpi.AttributeServerProtocol(*args, **kwargs)
Structural subtyping protocol for an attribute server.
- __init__(*args, **kwargs)
- __subclasshook__()
Abstract classes can override this to customize issubclass().
This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).
- __weakref__
list of weak references to the object (if defined)
- receive_send(attribute_request)
Handle an attribute request and send a response.
- Parameters:
attribute_request (
AttributeRequest) – the request info.- Return type:
- Returns:
an attribute response.
- class ska_ser_scpi.InterfaceDefinitionType
- __weakref__
list of weak references to the object (if defined)
- class ska_ser_scpi.ScpiBytesClientFactory
Factory for clients that send/receive bytes to/from servers.
- __init__()
Initialise a new instance.
- __weakref__
list of weak references to the object (if defined)
- create_client(protocol, host, port, timeout, sentinel_string='\\r\\n', logger=None)
Create and return a client for a given protocol and address.
- Parameters:
- Return type:
- Returns:
a client that can use the given protocol and address to send/receive bytes to/from a server.
- class ska_ser_scpi.ScpiBytesServer(scpi_server, argument_separator=' ', encoding='utf-8')
Server receiving/sending SCPI payloads from/to a client.
Used to receive a SCPI request object, and then send a SCPI response object (if required).
- __init__(scpi_server, argument_separator=' ', encoding='utf-8')
Initialise a new instance.
- Parameters:
scpi_server (
ScpiServer) – the underlying SCPI server to be used.argument_separator (
str) – the character which separates the SCPI command and the argument.encoding (
str) – encoding for converting between strings and bytes.
- __weakref__
list of weak references to the object (if defined)
- class ska_ser_scpi.ScpiClient(bytes_client, chain=True, argument_separator=' ', return_response=False, encoding='utf-8', timeout_retries=2)
Client for sending/receiving SCPI payloads to/from a server.
Used to transmit a SCPI request object, and then receive a SCPI response object.
- __init__(bytes_client, chain=True, argument_separator=' ', return_response=False, encoding='utf-8', timeout_retries=2)
Initialise a new instance.
- Parameters:
bytes_client (
ApplicationClient[bytes,bytes]) – the underlying bytes client to be used.chain (
bool) – whether this client should chain SCPI commands.argument_separator (
str) – the character which separates the SCPI command and the argument.return_response (
bool) – whether this device returns a package in response to a sent SCPI command.encoding (
str) – the encoding to use when converting strings to bytes and vice versa.timeout_retries (
int) – number of times to retry communications in the case of socket timeouts. (The number of connection attempts is one more than the number of retries i.e. if we set the number of retries to 0, then we try only once.)
- __weakref__
list of weak references to the object (if defined)
- send_receive(scpi_request)
Send a SCPI request, and receive a SCPI response.
- Parameters:
scpi_request (
ScpiRequest) – details of the SCPI request to be sent.- Raises:
socket.timeout – if we timeout waiting for some data to be received on the socket.
- Return type:
- Returns:
details of the SCPI response.
- class ska_ser_scpi.ScpiRequest
Representation of an attribute request.
A SCPI request specifies:
SCPI fields whose values are to be read (“queries”)
string values to be written to fields (“setops”). These setops allow for multiple arguments, so they cover the command invocation case as well.
- __eq__(other)
Check for equality with another object.
- __hash__ = None
- __init__()
Initialise a new instance.
- __repr__()
Representation of information used for logging.
- Return type:
- Returns:
readable string
- __weakref__
list of weak references to the object (if defined)
- add_query(field)
Add a field to be queried as part of this request.
- add_setop(field, *args, replace=False)
Add a field to be set as part of this request.
- Parameters:
field (
str) – name of the field to be set.args (
str) – arguments to the set operation. For a field write, there will only be one argument. However this method also covers the command invocation case, and so allows for more than one argument.replace (
bool) – whether to replace any existing setop with the same field name.
- Return type:
- property queries: list[str]
Return a list of SCPI fields to be queried in this SCPI request.
- Returns:
list of SCPI fields.
- property setops: list[tuple[str, list[str]]]
Return a set operations to be performed in this SCPI request.
- Returns:
a dictionary, keyed by the name of the SCPI field to be written (or commanded), with values being lists of string arguments to the setop. For writes, this list will only have one element, which is the value to be written. For commands, the list will be arguments to the command.
- class ska_ser_scpi.ScpiResponse
Representation of an SCPI field query response.
A SCPI response specifies values of SCPI fields that have been queried in an attribute request.
- __eq__(other)
Check for equality with another object.
- __hash__ = None
- __init__()
Initialise a new instance.
- __repr__()
Representation of information used for logging.
- Return type:
- Returns:
readable string
- __weakref__
list of weak references to the object (if defined)
- add_query_response(field, value)
Add a response to a SCPI field value query.
- class ska_ser_scpi.ScpiServer(attribute_server, attribute_definitions)
Service for receiving/sending SCPI payloads from/to a client.
Used to receive a SCPI request object, and respond with a SCPI response object.
- __init__(attribute_server, attribute_definitions)
Initialise a new instance.
- Parameters:
attribute_server (
AttributeServerProtocol) – the underlying attribute server to be used.attribute_definitions (
dict[str,dict[str,AttributeDefinitionType]]) – definitions of the attributes that the SCPI interface supports.
- __weakref__
list of weak references to the object (if defined)
- receive_send(scpi_request)
Send a SCPI request, and receive a SCPI response.
- Parameters:
scpi_request (
ScpiRequest) – details of the SCPI request to be sent.- Return type:
- Returns:
details of the SCPI response.
- class ska_ser_scpi.ScpiSimulator(interface_definition, initial_values, argument_separator=' ')
A simple simulator of hardware that talks SCPI over TCP.
- __init__(interface_definition, initial_values, argument_separator=' ')
Initialise a new instance.
- Parameters:
interface_definition (
InterfaceDefinitionType) – definition of the interface to be simulated.initial_values (
dict[str,bool|float|int|str|list[float|int|number[Any]]]) – a dictionary of initial values for the simulator to take.argument_separator (
str) – the character which separates the SCPI command and the argument.
- get_attribute(name)
Return the value of a simulator attribute.
Permitted attributes are the keys of the “attributes” dictionary in the interface definition.
- receive_send(attribute_request)
Receive an attribute request, handle it, and return a response.
- Parameters:
attribute_request (
AttributeRequest) – the request to be handled.- Return type:
- Returns:
a response.
- Raises:
ValueError – if the attribute request contains a setop for an attribute with neither arguments nor a defined method.
- set_attribute(name, value)
Set the value of a simulator attribute.
Permitted attributes are the keys of the “attributes” dictionary in the interface definition.
- ska_ser_scpi.expand_read_write_command(interface_definition)
Process read_write SCPI commands in the interface definition.
- Parameters:
interface_definition (
InterfaceDefinitionType) – the original interface_definition dictionary- Return type:
- Returns:
the updated interface definition which has expanded “read_write” commands into separate “read” and “write” commands.