Server Control

Contents

Server Control#

Establishing a connection#

The communication with the server is done through a websocket. One can call connect() and disconnect(). It is also possible to use connect() in a with block

ScrutinyClient.connect(hostname, port, wait_status=True)[source]#

Connect to a Scrutiny server through a TCP socket.

Parameters:

  • hostname (str) – The hostname or ip address of the server

  • port (int) – The listening port of the server

  • wait_status (bool) – Wait for a server status update after the socket connection is established. Ensure that a value is available when calling get_server_status()

Raises:

ConnectionError – In case of failure

Return type:

ScrutinyClient

ScrutinyClient.disconnect()[source]#

Disconnect from the server

Return type:

None

Example#

with client.connect('localhost', 1234):
    pass # Do something

# disconnect automatically called

Getting the server status#

Upon establishing a connection with a client, and at regular intervals thereafter, the server broadcasts a status. This status is a data structure that encapsulates all the pertinent information about what is happening at the other end of the websocket. It includes:

  • The type of connection used by the device

  • Details about the device if one is connected

  • The state of the datalogger within the device

  • The loaded SFD and its metadata if any

  • etc.

ScrutinyClient.get_server_status()[source]#
Returns an immutable structure of data containing the latest server status that has been broadcast.

It contains everything going on the server side

Raises:
Return type:

ServerInfo

ScrutinyClient.wait_server_status_update(timeout=2.5)[source]#

Wait for the server to broadcast a status update. Happens periodically

Parameters:

timeout (float) – Amount of time to wait for the update

Raises:

  • TypeError – Given parameter not of the expected type

  • ValueError – Given parameter has an invalid value

  • TimeoutException – Server status update did not occurred within the timeout time

Return type:

None

ScrutinyClient.wait_device_ready(timeout)[source]#

Wait for a device to be connected to the server and have finished its handshake.

Parameters:

timeout (float) – Amount of time to wait for the device

Raises:

  • TypeError – Given parameter not of the expected type

  • ValueError – Given parameter has an invalid value

  • InvalidValueError – If the watchable becomes invalid while waiting

  • TimeoutException – If the device does not become ready within the required timeout

Return type:

None

class scrutiny.sdk.ServerInfo[source]#

(Immutable struct) A summary of everything going on on the server side. Status broadcast by the server to every client.

device_comm_state: DeviceCommState#

Status of the communication between the server and the device

device_session_id: str | None#

A unique ID created each time a communication with the device is established. None when no communication with a device.

device: DeviceInfo | None#

Information about the connected device. None if no device is connected

datalogging: DataloggingInfo#

Datalogging state

sfd: SFDInfo | None#

The Scrutiny Firmware Description file actually loaded on the server. None if none is loaded

Communication channel presently used to communicate with the device

class scrutiny.sdk.DeviceCommState[source]#

(Enum) The state of the connection with the device

Disconnected = 1#

No device connected

Connecting = 2#

Handshake in progress between the server and the device

ConnectedReady = 3#

A device is connected and ready to respond to queries.

class scrutiny.sdk.DeviceInfo[source]#

(Immutable struct) Information about the device connected to the server

device_id: str#

A unique ID identifying the device and its software (Firmware ID).

display_name: str#

The display name broadcast by the device

max_tx_data_size: int#

Maximum payload size that the device can send

max_rx_data_size: int#

Maximum payload size that the device can receive

max_bitrate_bps: int | None#

Maximum bitrate between the device and the server. Requested by the device. None if no throttling is requested

rx_timeout_us: int#

Amount of time without data being received that the device will wait to restart its reception state machine (new frame)

heartbeat_timeout: float#

Timeout value without heartbeat message response to consider that the communication is broken

address_size_bits: Literal[8, 16, 32, 64, 128]#

Address size in the device

protocol_major: int#

Device communication protocol version (major number)

protocol_minor: int#

Device communication protocol version (minor number)

supported_features: SupportedFeatureMap#

Features supported by the device

forbidden_memory_regions: List[MemoryRegion]#

List of memory region that cannot be access

readonly_memory_regions: List[MemoryRegion]#

List of memory region that are read-only

class scrutiny.sdk.DeviceLinkInfo[source]#

(Immutable struct) Represent a communication link between the server and a device

type: DeviceLinkType#

Type of communication channel between the server and the device

config: UDPLinkConfig | TCPLinkConfig | SerialLinkConfig | None#

A channel type specific configuration

class scrutiny.sdk.SupportedFeatureMap[source]#

(Immutable struct) Represent the list of features that the connected device supports

memory_write: bool#

Indicates if the device allows write to memory

datalogging: bool#

Indicates if the device is able of doing datalogging

user_command: bool#

Indicates if the device has a callback set for the user command

sixtyfour_bits: bool#

Indicates if the device supports 64bits element. 64bits RPV and datalogging of 64bits elements (variable or RPV) are not possible if False. Watching 64 bits variables does not depends on the device and is therefore always possible

class scrutiny.sdk.MemoryRegion[source]#

(Immutable struct) Represent a memory region spanning from start to start+size-1

start: int#

Start address of the region

size: int#

Size in bytes of the region

class scrutiny.sdk.DataloggingInfo[source]#

(Immutable struct) Information about the datalogger that are volatile

state: DataloggerState#

The state of the datalogger in the device

completion_ratio: float | None#

The completion ratio of the actually running acquisition. None if no acquisition being captured

class scrutiny.sdk.DataloggerState[source]#

(Enum) The state in which the C++ datalogger inside the device firmware actually is

NA = 0#

The state is not available

Standby = 1#

The datalogger is doing nothing

WaitForTrigger = 2#

The datalogger is logging and actively monitor for the trigger condition to end the acquisition

Acquiring = 3#

The datalogger is actively logging and the acquisition is ending since the trigger event has been fired

DataReady = 4#

The datalogger has finished logging and data is ready to be read

Error = 5#

The datalogger has encountered a problem and is not operational

Contents