Server Control

Contents

Server Control#

Establishing a connection#

The communication with the server is done through a TCP socket. 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_latest_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 TCP socket. It includes:

  • The type of connection used by the device

  • A unique session ID with the device (if connected).

  • The state of the datalogger within the device

  • The loaded SFD.

  • etc.

ScrutinyClient.get_latest_server_status()[source]#

Returns an immutable structure of data containing the latest server status that has been broadcast. This makes no request to the server, it simply returns the latest value. See request_server_status_update to fetch a new status update from the server

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.request_server_status_update(wait=False, timeout=None)[source]#

Request the server with an immediate status update. Avoid waiting for the periodic request to be sent.

Parameters:

  • wait (bool) – Wait for the response if True

  • timeout (float | None) – Amount of time to wait for the update. Have no effect if wait=False. Use the SDK default timeout if None

Raises:
Returns:

The server status if wait=True, None otherwise

Return type:

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

ScrutinyClient.get_device_info()[source]#

Gets all the available details about the device. This information includes device id, name, communication parameters, special memory regions, datalogging details, available sampling rates, etc.

Raises:

OperationFailure – If the request to the server fails

Returns:

The device informations or None if not device is connected

Return type:

DeviceInfo | 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.

datalogging: DataloggingInfo#

Datalogging state

sfd_firmware_id: str | None#

The firmware ID of 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

session_id: str#

The unique ID assigned to the communication session between the server abd the device when this data was gathered

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, in seconds

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

datalogging_capabilities: DataloggingCapabilities | None#

Contains the device datalogging capabilities. None if datalogging is not supported

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 | RTTLinkConfig | NoneLinkConfig | CANLinkConfig | None#

A channel type specific configuration

operational: bool#

Tells if the link is opened and working correctly

demo_mode: bool#

True if the server is running an emulated device for demo purpose. False otherwise

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 inclusively

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 (change during the normal operation)

state: DataloggingState#

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.DataloggingState[source]#

(Enum) The state in which the server datalogging manager currently 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

Downloading = 4#

The datalogger has finished logging and data is being transferred to the server

Error = 5#

The datalogger has encountered a problem and is not operational

Diagnostic metrics#

The client can also provide some diagnostic metrics to monitor the well being of the system. Local metrics (measured by the client) are available through get_local_stats(). Server metrics (measured by the server) are available through get_server_stats().

ScrutinyClient.get_local_stats()[source]#

Return internal performance metrics

Return type:

Statistics

class scrutiny.sdk.client.ScrutinyClient.Statistics#

Performance metrics given by the client useful for diagnostic and debugging

rx_data_rate: float#

Returns the approximated data input rate coming from the server in Bytes/sec

rx_message_rate: float#

Returns the approximated message input rate coming from the server in msg/sec

tx_data_rate: float#

Returns the approximated data output rate sent to the server in Bytes/sec

tx_message_rate: float#

Returns the approximated message output rate sent to the server in msg/sec

ScrutinyClient.get_server_stats(timeout=None)[source]#
Parameters:

timeout (float | None) –

Return type:

ServerStatistics

class scrutiny.sdk.ServerStatistics[source]#

Some statistics giving an insight of what’s happening on the server side

uptime: float#

Time in seconds elapsed since the server has been started

invalid_request_count: int#

Number of invalid request the server received

unexpected_error_count: int#

Number of unexpected error the server encountered while processing a request

client_count: int#

Number of clients actually connected to the server

to_all_clients_datarate_byte_per_sec: float#

Datarate (byte/sec) going out of the API, all clients summed together

from_any_client_datarate_byte_per_sec: float#

Datarate (byte/sec) going in the API, all clients summed together

msg_received: int#

Number of message received, all clients summed together

msg_sent: int#

Number of message sent, all clients summed together

device_session_count: int#

Counter indicating how many new working connections has been established with a device

to_device_datarate_byte_per_sec: float#

Datarate (byte/sec) traveling from the server to the device

from_device_datarate_byte_per_sec: float#

Datarate (byte/sec) traveling from the device to the server

device_request_per_sec: float#

Number of request/response per seconds exchanged between the server and the device

Demo Mode#

One can enable the server demo mode with request_demo_mode().

When the demo mode is enabled, the server connects to an emulated device that runs in a python thread and simulate the scrutiny-embedded library. This mode is meant to try Scrutiny without having to go through the process of instrumenting a firmware.

The demo mode is deactivated by the server when the device connection parameters are updated with configure_device_link()

ScrutinyClient.request_demo_mode(enable)[source]#

Enable or disable the server demo mode

Parameters:

enable (bool) – Enable the demo mode when True. Disable it when False

Raises:

  • TypeError – Given parameter not of the expected type

  • OperationFailure – If the request to the server fails

Return type:

None

Contents