Communication

Provides the serial and MQTT communication classes, the command and data message classes, and the message protocol and data prototype definitions used to exchange commands and data between host-machines (PCs) and Arduino / Teensy microcontrollers.

class ataraxis_communication_interface.communication.ControllerIdentification(message=<factory>)

Bases: object

Communicates the unique identifier code of the microcontroller.

property controller_id: uint8

Returns the unique identifier of the microcontroller.

message: NDArray[uint8]

The parsed message header data.

class ataraxis_communication_interface.communication.DequeueModuleCommand(module_type, module_id, return_code=np.uint8(0))

Bases: object

Instructs the addressed Module instance to clear (empty) its command queue.

module_id: uint8

The ID of the specific module instance within the broader module family.

module_type: uint8

The type (family) code of the module to which the command is addressed.

packed_data: NDArray[uint8] | None

Stores the serialized message data.

protocol_code: uint8

Stores the message protocol code.

return_code: uint8

The code to use for acknowledging the reception of the message, if set to a non-zero value.

class ataraxis_communication_interface.communication.KernelCommand(command, return_code=np.uint8(0))

Bases: object

Instructs the Kernel to run the specified command exactly once.

command: uint8

The code of the command to execute.

packed_data: NDArray[uint8] | None

Stores the serialized message data.

protocol_code: uint8

Stores the message protocol code.

return_code: uint8

The code to use for acknowledging the reception of the message, if set to a non-zero value.

class ataraxis_communication_interface.communication.KernelData(message=<factory>, data_object=np.uint8(0))

Bases: object

Communicates that the Kernel has encountered a notable event and includes an additional data object.

Notes

Event codes are unique within the kernel. The same code always carries the same semantic meaning regardless of the command that was executing when the message was sent.

property command: uint8

Returns the code of the command executed by the Kernel when it sent the message.

data_object: PrototypeType

The parsed data object transmitted with the message.

property event: uint8

Returns the code of the event that prompted sending the message.

message: NDArray[uint8]

The parsed message header data.

property prototype_code: uint8

Returns the code that specifies the type of the data object transmitted with the message.

class ataraxis_communication_interface.communication.KernelState(message=<factory>)

Bases: object

Communicates that the Kernel has encountered a notable event.

Notes

Event codes are unique within the kernel. The same code always carries the same semantic meaning regardless of the command that was executing when the message was sent.

property command: uint8

Returns the code of the command executed by the Kernel when it sent the message.

property event: uint8

Returns the code of the event that prompted sending the message.

message: NDArray[uint8]

The parsed message header data.

class ataraxis_communication_interface.communication.MQTTCommunication(ip='127.0.0.1', port=1883, monitored_topics=None)

Bases: object

Provides methods for bidirectionally communicating with other clients connected to the same MQTT broker using the MQTT protocol over the TCP interface.

Notes

The MQTT protocol requires a broker that facilitates the communication, which has to be available to this class at initialization. See https://mqtt.org/ for more details.

Parameters:

• ip (str, default: '127.0.0.1') – The IP address of the MQTT broker. Defaults to “127.0.0.1” (localhost).

• port (int, default: 1883) – The socket port used by the MQTT broker. Defaults to 1883, the standard MQTT port.

• monitored_topics (tuple[str, ...] | None, default: None) – The tuple of MQTT topics to monitor for incoming messages. Defaults to None, which subscribes to no topics.

_ip

Stores the IP address of the MQTT broker.

_port

Stores the port used by the broker’s TCP socket.

_connected

Determines whether the class instance is currently connected to the MQTT broker.

_monitored_topics

Stores the topics monitored by the instance for incoming messages.

_output_queue

Buffers incoming messages received from other MQTT clients before their data is accessed via class methods.

_client

The initialized MQTT client instance that carries out the communication.

connect()

Connects to the MQTT broker and subscribes to the requested list of monitored topics.

Return type:

None

Notes

Any message sent to the MQTT broker from other clients before this method is called may not reach this instance.

If this instance is configured to subscribe (listen) to any topics, it starts a perpetually active thread with a listener callback to monitor the incoming traffic.

Raises:

ConnectionError – If the MQTT broker cannot be connected using the provided IP and port.

disconnect()

Disconnects the client from the MQTT broker.

Return type:

None

get_data()

Extracts and returns the first available message stored inside the instance’s buffer queue.

Return type:

tuple[str, bytes] | None

Returns:

A two-element tuple if there is data to retrieve. The first element is the MQTT topic of the received message. The second element is the payload of the message. If there is no data to retrieve, returns None.

Raises:

ConnectionError – If the instance is not connected to the MQTT broker.

property has_data: bool

Returns True if the instance’s get_data() method can be used to retrieve a message received from another MQTT client.

send_data(topic, payload=None)

Publishes the input payload to the specified MQTT topic.

Parameters:

• topic (str) – The MQTT topic to publish the data to.

• payload (str | bytes | bytearray | float | None, default: None) – The data to be published. Setting this to None sends an empty message.

Raises:

ConnectionError – If the instance is not connected to the MQTT broker or if the client is unable to hand the payload to the broker.

Return type:

None

class ataraxis_communication_interface.communication.ModuleData(message=<factory>, data_object=np.uint8(0))

Bases: object

Communicates that the Module has encountered a notable event and includes an additional data object.

Notes

Event codes are unique within each module. The same code always carries the same semantic meaning regardless of the command that was executing when the message was sent.

property command: uint8

Returns the code of the command executed by the module that sent the message.

data_object: PrototypeType

The parsed data object transmitted with the message.

property event: uint8

Returns the code of the event that prompted sending the message.

message: NDArray[uint8]

The parsed message header data.

property module_id: uint8

Returns the unique identifier code of the module instance that sent the message.

property module_type: uint8

Returns the type (family) code of the module that sent the message.

property prototype_code: uint8

Returns the code that specifies the type of the data object transmitted with the message.

property type_id: uint16

Returns the unique 16-bit unsigned integer value that results from combining the bits of the type-code and the id-code of the module instance that sent the message.

class ataraxis_communication_interface.communication.ModuleIdentification(module_type_id=np.uint16(0))

Bases: object

Identifies a hardware module instance by communicating its combined type and id code.

Notes

The entire message payload is the combined type and ID value, so the class stores that value directly.

module_type_id: uint16

The unique uint16 code that results from combining the type and ID codes of the module instance.

class ataraxis_communication_interface.communication.ModuleParameters(module_type, module_id, parameter_data, return_code=np.uint8(0))

Bases: object

Instructs the addressed Module instance to update its parameters with the included data.

module_id: uint8

The ID of the specific module instance within the broader module family.

module_type: uint8

The type (family) code of the module to which the command is addressed.

packed_data: NDArray[uint8] | None

Stores the serialized message data.

parameter_data: tuple[number[Any] | bool, ...]

The parameter values, ordered and typed to match the addressed module’s parameter structure on the microcontroller. Serialization reads each value through the numpy itemsize and tobytes() interface.

parameters_size: int | None

Stores the total size of the serialized parameters in bytes.

protocol_code: uint8

Stores the message protocol code.

return_code: uint8

The code to use for acknowledging the reception of the message, if set to a non-zero value.

class ataraxis_communication_interface.communication.ModuleState(message=<factory>)

Bases: object

Communicates that the Module has encountered a notable event.

Notes

Event codes are unique within each module. The same code always carries the same semantic meaning regardless of the command that was executing when the message was sent.

property command: uint8

Returns the code of the command executed by the module that sent the message.

property event: uint8

Returns the code of the event that prompted sending the message.

message: NDArray[uint8]

The parsed message header data.

property module_id: uint8

Returns the ID of the specific module instance within the broader module family.

property module_type: uint8

Returns the type (family) code of the module that sent the message.

property type_id: uint16

Returns the unique 16-bit unsigned integer value that results from combining the bits of the type-code and the id-code of the module instance that sent the message.

class ataraxis_communication_interface.communication.OneOffModuleCommand(module_type, module_id, command, return_code=np.uint8(0), noblock=np.True_)

Bases: object

Instructs the addressed Module instance to run the specified command exactly once (non-recurrently).

command: uint8

The code of the command to execute.

module_id: uint8

The ID of the specific module instance within the broader module family.

module_type: uint8

The type (family) code of the module to which the command is addressed.

noblock: bool

Determines whether to allow concurrent execution of other commands while waiting for the requested command to complete.

packed_data: NDArray[uint8] | None

Stores the serialized message data.

protocol_code: uint8

Stores the message protocol code.

return_code: uint8

The code to use for acknowledging the reception of the message, if set to a non-zero value.

class ataraxis_communication_interface.communication.ReceptionCode(message=<factory>)

Bases: object

Communicates the reception code originally received with the message sent by the PC to indicate that the message was received and parsed by the microcontroller.

message: NDArray[uint8]

The parsed message header data.

property reception_code: uint8

Returns the reception code originally sent as part of the outgoing Command or Parameters message.

class ataraxis_communication_interface.communication.RepeatedModuleCommand(module_type, module_id, command, return_code=np.uint8(0), noblock=np.True_, cycle_delay=np.uint32(0))

Bases: object

Instructs the addressed Module instance to run the specified command repeatedly (recurrently).

command: uint8

The code of the command to execute.

cycle_delay: uint32

The delay, in microseconds, before repeating (cycling) the command.

module_id: uint8

The ID of the specific module instance within the broader module family.

module_type: uint8

The type (family) code of the module to which the command is addressed.

noblock: bool

Determines whether to allow concurrent execution of other commands while waiting for the requested command to complete.

packed_data: NDArray[uint8] | None

Stores the serialized message data.

protocol_code: uint8

Stores the message protocol code.

return_code: uint8

The code to use for acknowledging the reception of the message, if set to a non-zero value.

class ataraxis_communication_interface.communication.SerialCommunication(controller_id, microcontroller_serial_buffer_size, port, logger_queue, baudrate=115200, *, test_mode=False)

Bases: object

Provides methods for bidirectionally communicating with a microcontroller running the ataraxis-micro-controller library over the USB or UART serial interface.

Parameters:

• controller_id (uint8) – The identifier code of the microcontroller to communicate with.

• microcontroller_serial_buffer_size (int) – The size, in bytes, of the buffer used by the communicated microcontroller’s serial communication interface. Usually, this information is available from the microcontroller’s manufacturer (UART / USB controller specification). Must be at least 9 bytes. The value bounds the size of the payloads the PC transmits, while reception is bounded by the 254-byte ceiling the COBS encoding imposes.

• port (str) – The name of the serial port to connect to, e.g., ‘COM3’ or ‘/dev/ttyUSB0’.

• logger_queue (Queue) – The multiprocessing Queue object exposed by the DataLogger instance used to pipe the data to be logged to the logger process.

• baudrate (int, default: 115200) – The baudrate to use for communication if the microcontroller uses the UART interface. Must match the value used by the microcontroller. This parameter is ignored when using the USB interface.

• test_mode (bool, default: False) – Determines whether the instance uses a pySerial (real) or a SerialMock (mocked) communication interface.

_transport_layer

The TransportLayer instance that handles the communication.

_module_data

Stores the data of the last received ModuleData message.

_kernel_data

Stores the data of the last received KernelData message.

_module_state

Stores the data of the last received ModuleState message.

_kernel_state

Stores the data of the last received KernelState message.

_controller_identification

Stores the data of the last received ControllerIdentification message.

_module_identification

Stores the data of the last received ModuleIdentification message.

_reception_code

Stores the data of the last received ReceptionCode message.

_timestamp_timer

Stores the PrecisionTimer instance used to timestamp incoming and outgoing data as it is being saved (logged) to disk.

_source_id

Stores the unique identifier of the microcontroller with which the instance communicates at runtime.

_logger_queue

Stores the multiprocessing Queue that buffers and pipes the data to the DataLogger process(es).

_usb_port

Stores the name of the serial port (USB or UART) used for communication.

receive_message()

Receives a message sent by the microcontroller and parses its contents into the appropriate instance attribute.

Notes

Each call to this method overwrites the previously received message data stored in the instance’s attributes. It is advised to finish working with the received message data before receiving another message.

Return type:

ModuleData | ModuleState | KernelData | KernelState | ControllerIdentification | ModuleIdentification | ReceptionCode | None

Returns:

A reference to the parsed message data stored on the matching instance attribute, or None when no message was received.

Raises:

ValueError – If the received message uses an invalid (unrecognized) message protocol code. If the received data message uses an unsupported data object prototype code.

send_message(message)

Serializes the input message and sends it to the connected microcontroller.

Parameters:

message (RepeatedModuleCommand | OneOffModuleCommand | DequeueModuleCommand | KernelCommand | ModuleParameters) – The message to send to the microcontroller.

Return type:

None

class ataraxis_communication_interface.communication.SerialProtocols(*values)

Bases: IntEnum

Defines the protocol codes used to specify incoming and outgoing message layouts during PC-microcontroller communication.

Notes

The elements of this enumeration are accessed through their as_uint8 method, which returns the code in the type the serialized message layout requires.

CONTROLLER_IDENTIFICATION = 11

Used to identify the host-microcontroller to the PC.

DEQUEUE_MODULE_COMMAND = 3

Used by Module-addressed commands that remove all queued commands, including recurrent commands.

KERNEL_COMMAND = 4

Used by Kernel-addressed commands. All Kernel commands are always non-repeatable (one-shot).

KERNEL_DATA = 7

Used by Kernel data or error messages that include an arbitrary data object in addition to event state-code.

KERNEL_STATE = 9

Used by Kernel data or error messages that only include the state-code.

MODULE_DATA = 6

Used by Module data or error messages that include an arbitrary data object in addition to the event state-code.

MODULE_IDENTIFICATION = 12

Used to identify the hardware module instances managed by the microcontroller’s Kernel instance to the PC.

MODULE_PARAMETERS = 5

Used by Module-addressed parameter messages.

MODULE_STATE = 8

Used by Module data or error messages that only include the state-code.

ONE_OFF_MODULE_COMMAND = 2

Used by Module-addressed commands that should not be repeated (executed only once).

RECEPTION_CODE = 10

Used to acknowledge the reception of command and parameter messages from the PC.

REPEATED_MODULE_COMMAND = 1

Used by Module-addressed commands that should be repeated (executed recurrently).

UNDEFINED = 0

Not a valid protocol code. The microcontroller’s Communication class initializes its protocol tracker to this code.

as_uint8()

Returns the specified enumeration element as a numpy uint8 type.

Return type:

uint8

class ataraxis_communication_interface.communication.SerialPrototypes(*values)

Bases: IntEnum

Defines the prototype codes used during data transmission to specify the layout of additional data objects transmitted by KernelData and ModuleData messages.

EIGHTEEN_UINT8S = 174

An array of 18 unsigned 8-bit integers.

EIGHT_BOOLS = 31

An array of 8 8-bit booleans.

EIGHT_FLOAT32S = 108

An array of 8 single-precision 32-bit floating-point numbers.

EIGHT_FLOAT64S = 144

An array of 8 double-precision 64-bit floating-point numbers.

EIGHT_INT16S = 73

An array of 8 signed 16-bit integers.

EIGHT_INT32S = 107

An array of 8 signed 32-bit integers.

EIGHT_INT64S = 143

An array of 8 signed 64-bit integers.

EIGHT_INT8S = 33

An array of 8 signed 8-bit integers.

EIGHT_UINT16S = 72

An array of 8 unsigned 16-bit integers.

EIGHT_UINT32S = 106

An array of 8 unsigned 32-bit integers.

EIGHT_UINT64S = 142

An array of 8 unsigned 64-bit integers.

EIGHT_UINT8S = 32

An array of 8 unsigned 8-bit integers.

ELEVEN_BOOLS = 50

An array of 11 8-bit booleans.

ELEVEN_FLOAT32S = 123

An array of 11 single-precision 32-bit floating-point numbers.

ELEVEN_FLOAT64S = 153

An array of 11 double-precision 64-bit floating-point numbers.

ELEVEN_INT16S = 88

An array of 11 signed 16-bit integers.

ELEVEN_INT32S = 122

An array of 11 signed 32-bit integers.

ELEVEN_INT64S = 152

An array of 11 signed 64-bit integers.

ELEVEN_INT8S = 52

An array of 11 signed 8-bit integers.

ELEVEN_UINT16S = 87

An array of 11 unsigned 16-bit integers.

ELEVEN_UINT32S = 121

An array of 11 unsigned 32-bit integers.

ELEVEN_UINT64S = 151

An array of 11 unsigned 64-bit integers.

ELEVEN_UINT8S = 51

An array of 11 unsigned 8-bit integers.

FIFTEEN_BOOLS = 69

An array of 15 8-bit booleans.

FIFTEEN_FLOAT32S = 141

An array of 15 single-precision 32-bit floating-point numbers.

FIFTEEN_FLOAT64S = 165

An array of 15 double-precision 64-bit floating-point numbers.

FIFTEEN_INT16S = 105

An array of 15 signed 16-bit integers.

FIFTEEN_INT32S = 140

An array of 15 signed 32-bit integers.

FIFTEEN_INT64S = 164

An array of 15 signed 64-bit integers.

FIFTEEN_INT8S = 71

An array of 15 signed 8-bit integers.

FIFTEEN_UINT16S = 104

An array of 15 unsigned 16-bit integers.

FIFTEEN_UINT32S = 139

An array of 15 unsigned 32-bit integers.

FIFTEEN_UINT64S = 163

An array of 15 unsigned 64-bit integers.

FIFTEEN_UINT8S = 70

An array of 15 unsigned 8-bit integers.

FIFTY_TWO_BOOLS = 171

An array of 52 8-bit booleans.

FIFTY_TWO_INT8S = 196

An array of 52 signed 8-bit integers.

FIFTY_TWO_UINT8S = 184

An array of 52 unsigned 8-bit integers.

FIVE_BOOLS = 20

An array of 5 8-bit booleans.

FIVE_FLOAT32S = 86

An array of 5 single-precision 32-bit floating-point numbers.

FIVE_FLOAT64S = 120

An array of 5 double-precision 64-bit floating-point numbers.

FIVE_INT16S = 49

An array of 5 signed 16-bit integers.

FIVE_INT32S = 85

An array of 5 signed 32-bit integers.

FIVE_INT64S = 119

An array of 5 signed 64-bit integers.

FIVE_INT8S = 22

An array of 5 signed 8-bit integers.

FIVE_UINT16S = 48

An array of 5 unsigned 16-bit integers.

FIVE_UINT32S = 84

An array of 5 unsigned 32-bit integers.

FIVE_UINT64S = 118

An array of 5 unsigned 64-bit integers.

FIVE_UINT8S = 21

An array of 5 unsigned 8-bit integers.

FORTY_BOOLS = 169

An array of 40 8-bit booleans.

FORTY_EIGHT_BOOLS = 170

An array of 48 8-bit booleans.

FORTY_EIGHT_FLOAT32S = 239

An array of 48 single-precision 32-bit floating-point numbers.

FORTY_EIGHT_INT16S = 218

An array of 48 signed 16-bit integers.

FORTY_EIGHT_INT32S = 233

An array of 48 signed 32-bit integers.

FORTY_EIGHT_INT8S = 195

An array of 48 signed 8-bit integers.

FORTY_EIGHT_UINT16S = 208

An array of 48 unsigned 16-bit integers.

FORTY_EIGHT_UINT32S = 227

An array of 48 unsigned 32-bit integers.

FORTY_EIGHT_UINT8S = 183

An array of 48 unsigned 8-bit integers.

FORTY_FOUR_UINT8S = 182

An array of 44 unsigned 8-bit integers.

FORTY_INT8S = 194

An array of 40 signed 8-bit integers.

FORTY_UINT8S = 181

An array of 40 unsigned 8-bit integers.

FOURTEEN_BOOLS = 64

An array of 14 8-bit booleans.

FOURTEEN_FLOAT32S = 135

An array of 14 single-precision 32-bit floating-point numbers.

FOURTEEN_FLOAT64S = 162

An array of 14 double-precision 64-bit floating-point numbers.

FOURTEEN_INT16S = 100

An array of 14 signed 16-bit integers.

FOURTEEN_INT32S = 134

An array of 14 signed 32-bit integers.

FOURTEEN_INT64S = 161

An array of 14 signed 64-bit integers.

FOURTEEN_INT8S = 66

An array of 14 signed 8-bit integers.

FOURTEEN_UINT16S = 99

An array of 14 unsigned 16-bit integers.

FOURTEEN_UINT32S = 133

An array of 14 unsigned 32-bit integers.

FOURTEEN_UINT64S = 160

An array of 14 unsigned 64-bit integers.

FOURTEEN_UINT8S = 65

An array of 14 unsigned 8-bit integers.

FOUR_BOOLS = 12

An array of 4 8-bit booleans.

FOUR_FLOAT32S = 76

An array of 4 single-precision 32-bit floating-point numbers.

FOUR_FLOAT64S = 111

An array of 4 double-precision 64-bit floating-point numbers.

FOUR_INT16S = 35

An array of 4 signed 16-bit integers.

FOUR_INT32S = 75

An array of 4 signed 32-bit integers.

FOUR_INT64S = 110

An array of 4 signed 64-bit integers.

FOUR_INT8S = 14

An array of 4 signed 8-bit integers.

FOUR_UINT16S = 34

An array of 4 unsigned 16-bit integers.

FOUR_UINT32S = 74

An array of 4 unsigned 32-bit integers.

FOUR_UINT64S = 109

An array of 4 unsigned 64-bit integers.

FOUR_UINT8S = 13

An array of 4 unsigned 8-bit integers.

NINETY_SIX_INT16S = 220

An array of 96 signed 16-bit integers.

NINETY_SIX_UINT16S = 210

An array of 96 unsigned 16-bit integers.

NINETY_SIX_UINT8S = 186

An array of 96 unsigned 8-bit integers.

NINETY_TWO_INT8S = 197

An array of 92 signed 8-bit integers.

NINE_BOOLS = 42

An array of 9 8-bit booleans.

NINE_FLOAT32S = 114

An array of 9 single-precision 32-bit floating-point numbers.

NINE_FLOAT64S = 147

An array of 9 double-precision 64-bit floating-point numbers.

NINE_INT16S = 81

An array of 9 signed 16-bit integers.

NINE_INT32S = 113

An array of 9 signed 32-bit integers.

NINE_INT64S = 146

An array of 9 signed 64-bit integers.

NINE_INT8S = 44

An array of 9 signed 8-bit integers.

NINE_UINT16S = 80

An array of 9 unsigned 16-bit integers.

NINE_UINT32S = 112

An array of 9 unsigned 32-bit integers.

NINE_UINT64S = 145

An array of 9 unsigned 64-bit integers.

NINE_UINT8S = 43

An array of 9 unsigned 8-bit integers.

ONE_BOOL = 1

1 8-bit boolean.

ONE_FLOAT32 = 19

1 single-precision 32-bit floating-point number.

ONE_FLOAT64 = 41

1 double-precision 64-bit floating-point number.

ONE_HUNDRED_NINETY_TWO_UINT8S = 188

An array of 192 unsigned 8-bit integers.

ONE_HUNDRED_SEVENTY_TWO_INT8S = 199

An array of 172 signed 8-bit integers.

ONE_HUNDRED_THIRTY_TWO_INT8S = 198

An array of 132 signed 8-bit integers.

ONE_HUNDRED_TWENTY_EIGHT_UINT8S = 187

An array of 128 unsigned 8-bit integers.

ONE_HUNDRED_TWENTY_FOUR_INT16S = 222

An array of 124 signed 16-bit integers.

ONE_HUNDRED_TWENTY_FOUR_UINT16S = 212

An array of 124 unsigned 16-bit integers.

ONE_HUNDRED_TWENTY_TWO_INT16S = 221

An array of 122 signed 16-bit integers.

ONE_HUNDRED_TWENTY_TWO_UINT16S = 211

An array of 122 unsigned 16-bit integers.

ONE_INT16 = 8

1 signed 16-bit integer.

ONE_INT32 = 18

1 signed 32-bit integer.

ONE_INT64 = 40

1 signed 64-bit integer.

ONE_INT8 = 3

1 signed 8-bit integer.

ONE_UINT16 = 7

1 unsigned 16-bit integer.

ONE_UINT32 = 17

1 unsigned 32-bit integer.

ONE_UINT64 = 39

1 unsigned 64-bit integer.

ONE_UINT8 = 2

1 unsigned 8-bit integer.

SEVEN_BOOLS = 28

An array of 7 8-bit booleans.

SEVEN_FLOAT32S = 103

An array of 7 single-precision 32-bit floating-point numbers.

SEVEN_FLOAT64S = 138

An array of 7 double-precision 64-bit floating-point numbers.

SEVEN_INT16S = 68

An array of 7 signed 16-bit integers.

SEVEN_INT32S = 102

An array of 7 signed 32-bit integers.

SEVEN_INT64S = 137

An array of 7 signed 64-bit integers.

SEVEN_INT8S = 30

An array of 7 signed 8-bit integers.

SEVEN_UINT16S = 67

An array of 7 unsigned 16-bit integers.

SEVEN_UINT32S = 101

An array of 7 unsigned 32-bit integers.

SEVEN_UINT64S = 136

An array of 7 unsigned 64-bit integers.

SEVEN_UINT8S = 29

An array of 7 unsigned 8-bit integers.

SIXTEEN_BOOLS = 166

An array of 16 8-bit booleans.

SIXTEEN_FLOAT32S = 235

An array of 16 single-precision 32-bit floating-point numbers.

SIXTEEN_FLOAT64S = 249

An array of 16 double-precision 64-bit floating-point numbers.

SIXTEEN_INT16S = 213

An array of 16 signed 16-bit integers.

SIXTEEN_INT32S = 229

An array of 16 signed 32-bit integers.

SIXTEEN_INT64S = 245

An array of 16 signed 64-bit integers.

SIXTEEN_INT8S = 191

An array of 16 signed 8-bit integers.

SIXTEEN_UINT16S = 203

An array of 16 unsigned 16-bit integers.

SIXTEEN_UINT32S = 223

An array of 16 unsigned 32-bit integers.

SIXTEEN_UINT64S = 241

An array of 16 unsigned 64-bit integers.

SIXTEEN_UINT8S = 173

An array of 16 unsigned 8-bit integers.

SIXTY_FOUR_INT16S = 219

An array of 64 signed 16-bit integers.

SIXTY_FOUR_UINT16S = 209

An array of 64 unsigned 16-bit integers.

SIXTY_FOUR_UINT8S = 185

An array of 64 unsigned 8-bit integers.

SIXTY_TWO_FLOAT32S = 240

An array of 62 single-precision 32-bit floating-point numbers.

SIXTY_TWO_INT32S = 234

An array of 62 signed 32-bit integers.

SIXTY_TWO_UINT32S = 228

An array of 62 unsigned 32-bit integers.

SIX_BOOLS = 23

An array of 6 8-bit booleans.

SIX_FLOAT32S = 93

An array of 6 single-precision 32-bit floating-point numbers.

SIX_FLOAT64S = 129

An array of 6 double-precision 64-bit floating-point numbers.

SIX_INT16S = 57

An array of 6 signed 16-bit integers.

SIX_INT32S = 92

An array of 6 signed 32-bit integers.

SIX_INT64S = 128

An array of 6 signed 64-bit integers.

SIX_INT8S = 25

An array of 6 signed 8-bit integers.

SIX_UINT16S = 56

An array of 6 unsigned 16-bit integers.

SIX_UINT32S = 91

An array of 6 unsigned 32-bit integers.

SIX_UINT64S = 127

An array of 6 unsigned 64-bit integers.

SIX_UINT8S = 24

An array of 6 unsigned 8-bit integers.

TEN_BOOLS = 45

An array of 10 8-bit booleans.

TEN_FLOAT32S = 117

An array of 10 single-precision 32-bit floating-point numbers.

TEN_FLOAT64S = 150

An array of 10 double-precision 64-bit floating-point numbers.

TEN_INT16S = 83

An array of 10 signed 16-bit integers.

TEN_INT32S = 116

An array of 10 signed 32-bit integers.

TEN_INT64S = 149

An array of 10 signed 64-bit integers.

TEN_INT8S = 47

An array of 10 signed 8-bit integers.

TEN_UINT16S = 82

An array of 10 unsigned 16-bit integers.

TEN_UINT32S = 115

An array of 10 unsigned 32-bit integers.

TEN_UINT64S = 148

An array of 10 unsigned 64-bit integers.

TEN_UINT8S = 46

An array of 10 unsigned 8-bit integers.

THIRTEEN_BOOLS = 61

An array of 13 8-bit booleans.

THIRTEEN_FLOAT32S = 132

An array of 13 single-precision 32-bit floating-point numbers.

THIRTEEN_FLOAT64S = 159

An array of 13 double-precision 64-bit floating-point numbers.

THIRTEEN_INT16S = 98

An array of 13 signed 16-bit integers.

THIRTEEN_INT32S = 131

An array of 13 signed 32-bit integers.

THIRTEEN_INT64S = 158

An array of 13 signed 64-bit integers.

THIRTEEN_INT8S = 63

An array of 13 signed 8-bit integers.

THIRTEEN_UINT16S = 97

An array of 13 unsigned 16-bit integers.

THIRTEEN_UINT32S = 130

An array of 13 unsigned 32-bit integers.

THIRTEEN_UINT64S = 157

An array of 13 unsigned 64-bit integers.

THIRTEEN_UINT8S = 62

An array of 13 unsigned 8-bit integers.

THIRTY_ONE_FLOAT64S = 252

An array of 31 double-precision 64-bit floating-point numbers.

THIRTY_ONE_INT64S = 248

An array of 31 signed 64-bit integers.

THIRTY_ONE_UINT64S = 244

An array of 31 unsigned 64-bit integers.

THIRTY_SIX_UINT8S = 180

An array of 36 unsigned 8-bit integers.

THIRTY_TWO_BOOLS = 168

An array of 32 8-bit booleans.

THIRTY_TWO_FLOAT32S = 238

An array of 32 single-precision 32-bit floating-point numbers.

THIRTY_TWO_INT16S = 217

An array of 32 signed 16-bit integers.

THIRTY_TWO_INT32S = 232

An array of 32 signed 32-bit integers.

THIRTY_TWO_INT8S = 193

An array of 32 signed 8-bit integers.

THIRTY_TWO_UINT16S = 207

An array of 32 unsigned 16-bit integers.

THIRTY_TWO_UINT32S = 226

An array of 32 unsigned 32-bit integers.

THIRTY_TWO_UINT8S = 179

An array of 32 unsigned 8-bit integers.

THREE_BOOLS = 9

An array of 3 8-bit booleans.

THREE_FLOAT32S = 60

An array of 3 single-precision 32-bit floating-point numbers.

THREE_FLOAT64S = 96

An array of 3 double-precision 64-bit floating-point numbers.

THREE_INT16S = 27

An array of 3 signed 16-bit integers.

THREE_INT32S = 59

An array of 3 signed 32-bit integers.

THREE_INT64S = 95

An array of 3 signed 64-bit integers.

THREE_INT8S = 11

An array of 3 signed 8-bit integers.

THREE_UINT16S = 26

An array of 3 unsigned 16-bit integers.

THREE_UINT32S = 58

An array of 3 unsigned 32-bit integers.

THREE_UINT64S = 94

An array of 3 unsigned 64-bit integers.

THREE_UINT8S = 10

An array of 3 unsigned 8-bit integers.

TWELVE_BOOLS = 53

An array of 12 8-bit booleans.

TWELVE_FLOAT32S = 126

An array of 12 single-precision 32-bit floating-point numbers.

TWELVE_FLOAT64S = 156

An array of 12 double-precision 64-bit floating-point numbers.

TWELVE_INT16S = 90

An array of 12 signed 16-bit integers.

TWELVE_INT32S = 125

An array of 12 signed 32-bit integers.

TWELVE_INT64S = 155

An array of 12 signed 64-bit integers.

TWELVE_INT8S = 55

An array of 12 signed 8-bit integers.

TWELVE_UINT16S = 89

An array of 12 unsigned 16-bit integers.

TWELVE_UINT32S = 124

An array of 12 unsigned 32-bit integers.

TWELVE_UINT64S = 154

An array of 12 unsigned 64-bit integers.

TWELVE_UINT8S = 54

An array of 12 unsigned 8-bit integers.

TWENTY_EIGHT_UINT8S = 178

An array of 28 unsigned 8-bit integers.

TWENTY_FLOAT32S = 236

An array of 20 single-precision 32-bit floating-point numbers.

TWENTY_FLOAT64S = 250

An array of 20 double-precision 64-bit floating-point numbers.

TWENTY_FOUR_BOOLS = 167

An array of 24 8-bit booleans.

TWENTY_FOUR_FLOAT32S = 237

An array of 24 single-precision 32-bit floating-point numbers.

TWENTY_FOUR_FLOAT64S = 251

An array of 24 double-precision 64-bit floating-point numbers.

TWENTY_FOUR_INT16S = 215

An array of 24 signed 16-bit integers.

TWENTY_FOUR_INT32S = 231

An array of 24 signed 32-bit integers.

TWENTY_FOUR_INT64S = 247

An array of 24 signed 64-bit integers.

TWENTY_FOUR_INT8S = 192

An array of 24 signed 8-bit integers.

TWENTY_FOUR_UINT16S = 205

An array of 24 unsigned 16-bit integers.

TWENTY_FOUR_UINT32S = 225

An array of 24 unsigned 32-bit integers.

TWENTY_FOUR_UINT64S = 243

An array of 24 unsigned 64-bit integers.

TWENTY_FOUR_UINT8S = 177

An array of 24 unsigned 8-bit integers.

TWENTY_INT16S = 214

An array of 20 signed 16-bit integers.

TWENTY_INT32S = 230

An array of 20 signed 32-bit integers.

TWENTY_INT64S = 246

An array of 20 signed 64-bit integers.

TWENTY_SIX_INT16S = 216

An array of 26 signed 16-bit integers.

TWENTY_SIX_UINT16S = 206

An array of 26 unsigned 16-bit integers.

TWENTY_TWO_UINT8S = 176

An array of 22 unsigned 8-bit integers.

TWENTY_UINT16S = 204

An array of 20 unsigned 16-bit integers.

TWENTY_UINT32S = 224

An array of 20 unsigned 32-bit integers.

TWENTY_UINT64S = 242

An array of 20 unsigned 64-bit integers.

TWENTY_UINT8S = 175

An array of 20 unsigned 8-bit integers.

TWO_BOOLS = 4

An array of 2 8-bit booleans.

TWO_FLOAT32S = 38

An array of 2 single-precision 32-bit floating-point numbers.

TWO_FLOAT64S = 79

An array of 2 double-precision 64-bit floating-point numbers.

TWO_HUNDRED_FORTY_EIGHT_BOOLS = 172

An array of 248 8-bit booleans.

TWO_HUNDRED_FORTY_EIGHT_INT8S = 202

An array of 248 signed 8-bit integers.

TWO_HUNDRED_FORTY_EIGHT_UINT8S = 190

An array of 248 unsigned 8-bit integers.

TWO_HUNDRED_FORTY_FOUR_INT8S = 201

An array of 244 signed 8-bit integers.

TWO_HUNDRED_FORTY_FOUR_UINT8S = 189

An array of 244 unsigned 8-bit integers.

TWO_HUNDRED_TWELVE_INT8S = 200

An array of 212 signed 8-bit integers.

TWO_INT16S = 16

An array of 2 signed 16-bit integers.

TWO_INT32S = 37

An array of 2 signed 32-bit integers.

TWO_INT64S = 78

An array of 2 signed 64-bit integers.

TWO_INT8S = 6

An array of 2 signed 8-bit integers.

TWO_UINT16S = 15

An array of 2 unsigned 16-bit integers.

TWO_UINT32S = 36

An array of 2 unsigned 32-bit integers.

TWO_UINT64S = 77

An array of 2 unsigned 64-bit integers.

TWO_UINT8S = 5

An array of 2 unsigned 8-bit integers.

as_uint8()

Returns the enumeration value as a numpy uint8 type.

Return type:

uint8

static get_byte_size_for_code(code)

Returns the byte size of the data object associated with the input prototype code.

Uses a pre-built lookup table to avoid instantiating a prototype object, making this suitable for hot paths where only the size is needed.

Parameters:

code (int) – The prototype integer code for which to retrieve the data object’s byte size.

Return type:

int | None

Returns:

The byte size of the data object the code declares, or None if the code is not recognized.

static get_dtype_for_code(code)

Returns the numpy dtype string associated with the input prototype code.

Uses a pre-built lookup table to avoid instantiating a prototype object, making this suitable for hot paths where only the dtype string is needed.

Parameters:

code (int) – The prototype integer code for which to retrieve the dtype string.

Return type:

str | None

Returns:

The numpy dtype string (e.g., 'float32', 'uint16'), or None if the code is not recognized.

static get_prototype_for_code(code)

Returns the prototype object associated with the input prototype code.

Notes

The returned object belongs to the module-level prototype table and is shared by every caller, so it is read-only. Sharing it is safe because the TransportLayer reads the dtype and the element count of a prototype and builds a new object to hold the received data.

Parameters:

code (uint8) – The prototype code for which to retrieve the prototype object.

Return type:

bool | uint8 | int8 | uint16 | int16 | uint32 | int32 | uint64 | int64 | float32 | float64 | NDArray[bool] | NDArray[uint8] | NDArray[int8] | NDArray[uint16] | NDArray[int16] | NDArray[uint32] | NDArray[int32] | NDArray[uint64] | NDArray[int64] | NDArray[float32] | NDArray[float64] | None

Returns:

The prototype object the code declares, or None when the code is not one of the supported codes.

type ataraxis_communication_interface.PrototypeType = numpy.bool_ | numpy.uint8 | numpy.int8 | numpy.uint16 | numpy.int16 | numpy.uint32 | numpy.int32 | numpy.uint64 | numpy.int64 | numpy.float32 | numpy.float64 | NDArray[numpy.bool_] | NDArray[numpy.uint8] | NDArray[numpy.int8] | NDArray[numpy.uint16] | NDArray[numpy.int16] | NDArray[numpy.uint32] | NDArray[numpy.int32] | NDArray[numpy.uint64] | NDArray[numpy.int64] | NDArray[numpy.float32] | NDArray[numpy.float64]

The union of every data object type this library can transmit to and receive from a microcontroller. Each serialized prototype code resolves to one member of this union, so the data object of any received ModuleData or KernelData message is an instance of one of these types.

MicroController

Provides the microcontroller interface classes, the configuration dataclasses, the firmware status code mirrors and their message translators, the log data extraction algorithm, and the extracted message table schema and its access primitives.

class ataraxis_communication_interface.microcontroller.CommunicationStatusCodes(*values)

Bases: IntEnum

Defines the status codes the microcontroller’s Communication class reports for its data manipulations.

Notes

These codes never arrive as message event codes. The firmware attaches the most recent one as the first byte of the two-byte payload that accompanies every reception and transmission error message.

EXTRACTION_FORBIDDEN = 61

Parameter extraction was attempted on a message other than a ModuleParameters message.

INVALID_PROTOCOL = 57

The message protocol code is not valid for the direction the message travelled.

MESSAGE_RECEIVED = 56

The Communication class received a message.

MESSAGE_SENT = 55

The Communication class sent a message.

NO_BYTES_TO_RECEIVE = 58

The Communication class did not receive enough bytes to process a message.

PACKING_ERROR = 54

The Communication class encountered an error while writing a message to the payload.

PARAMETERS_EXTRACTED = 60

The Communication class extracted the parameter data.

PARAMETER_MISMATCH = 59

The size of the received parameter structure does not match the expected size.

PARSING_ERROR = 53

The Communication class encountered an error while reading a received message.

RECEPTION_ERROR = 52

The Communication class encountered an error while receiving a message.

STANDBY = 51

The value the Communication class holds before it completes any operation.

TRANSMISSION_ERROR = 62

The communication interface accepted only a part of the transmitted message.

class ataraxis_communication_interface.microcontroller.ControllerExtractionConfig(controller_id, modules, kernel)

Bases: object

Defines extraction parameters for a single microcontroller source.

controller_id: int

The controller_id used by the MicroControllerInterface when logging.

kernel: KernelExtractionConfig | None

Kernel extraction settings, or None to skip kernel extraction for this controller.

modules: tuple[ModuleExtractionConfig, ...]

The hardware modules to extract data for.

class ataraxis_communication_interface.microcontroller.ExtractedControllerData(modules, kernel)

Bases: object

Stores every message one extraction pass over a microcontroller log archive resolved.

kernel: ExtractedMessages

Columnar storage for the extracted kernel messages, empty when kernel extraction was not configured.

modules: tuple[ExtractedModuleData, ...]

The data of each hardware module that produced at least one matching message.

class ataraxis_communication_interface.microcontroller.ExtractedDataColumns(*values)

Bases: StrEnum

Defines the columns every extracted message table carries, in the order the table stores them.

COMMAND = 'command'

Holds the command code each message was sent under.

DATA = 'data'

Holds the raw payload bytes of each message, or null for a state-only message and for a data message whose prototype code this library does not recognize.

DTYPE = 'dtype'

Holds the numpy dtype string of each message’s data payload, or null for a state-only message and for a data message whose prototype code this library does not recognize.

EVENT = 'event'

Holds the event code of each message.

TIMESTAMP = 'timestamp_us'

Holds the microseconds elapsed since the UTC epoch onset when each message arrived.

class ataraxis_communication_interface.microcontroller.ExtractedMessages(timestamps, commands, events, dtypes, data_payloads)

Bases: object

Stores the data parsed from a set of incoming messages received by the PC from the microcontroller during runtime, in columnar form.

All arrays share the same length, with each index position corresponding to a single message.

commands: NDArray[uint8]

The command code that the module or kernel was executing when it sent each message.

property count: int

Returns the number of messages stored in this columnar block.

data_payloads: tuple[bytes | None, ...]

The serialized binary payload of each message, or None for state-only messages and for data messages whose prototype code this library does not recognize.

dtypes: tuple[str | None, ...]

The numpy dtype string for the data payload of each message (e.g., 'float32', 'uint16'), or None for state-only messages that carry no data and for data messages whose prototype code this library does not recognize.

events: NDArray[uint8]

The event code of each message.

timestamps: NDArray[uint64]

Microseconds elapsed since the UTC epoch onset when each message was received by the PC.

class ataraxis_communication_interface.microcontroller.ExtractedModuleData(module_type, module_id, messages)

Bases: object

Stores the data extracted from all messages sent to the PC by a hardware module instance during runtime that matched the caller’s event code filter, in columnar form.

messages: ExtractedMessages

Columnar storage for all extracted messages from this module.

module_id: int

The unique identifier code of the hardware module instance.

module_type: int

The type (family) code of the hardware module instance.

class ataraxis_communication_interface.microcontroller.ExtractionConfig(controllers)

Bases: YamlConfig

Defines the complete extraction configuration for microcontroller log processing.

Specifies which controllers, modules, and events to extract from log archives. Processing requires a valid configuration file with non-empty event codes for every module and kernel entry.

controllers: list[ControllerExtractionConfig]

The list of controller extraction configurations.

class ataraxis_communication_interface.microcontroller.KernelCommandCodes(*values)

Bases: IntEnum

Defines the command codes the microcontroller’s Kernel class uses, covering both the codes the PC addresses it with and the codes it holds or issues to itself.

IDENTIFY_CONTROLLER = 3

Requests the microcontroller to report its identifier code.

IDENTIFY_MODULES = 4

Requests the microcontroller to report the combined type and id code of every hardware module it manages.

KEEPALIVE = 5

Resets the keepalive watchdog timer, which starts a new keepalive cycle.

RECEIVE_DATA = 1

Checks for and receives PC-sent data. The Kernel issues this command to itself.

RESET_CONTROLLER = 2

Resets the software and hardware state of every asset the Kernel manages.

STANDBY = 0

The placeholder code the Kernel holds while it executes no command.

class ataraxis_communication_interface.microcontroller.KernelExtractionConfig(event_codes)

Bases: object

Defines extraction parameters for kernel messages.

Notes

Event codes must be globally unique within the kernel. The same event code must not be reused with different semantics across commands.

event_codes: tuple[int, ...]

The kernel event codes to extract. Must not be empty. Each event code must be unique within the kernel.

class ataraxis_communication_interface.microcontroller.KernelStatusCodes(*values)

Bases: IntEnum

Defines the status codes the microcontroller’s Kernel class uses to report its runtime state to the PC.

COMMAND_NOT_RECOGNIZED = 8

An unsupported Kernel command was received.

INVALID_MESSAGE_PROTOCOL = 5

A message using an unsupported protocol was received.

KEEPALIVE_TIMEOUT = 10

No keepalive message arrived within the timeout window the Kernel derives from the keepalive interval.

MODULE_PARAMETERS_ERROR = 7

The received parameters could not be applied to the addressed hardware module.

MODULE_PARAMETERS_SET = 6

The received parameters were applied to the addressed hardware module.

MODULE_SETUP_ERROR = 2

The Setup() method runtime failed because a hardware module rejected its setup sequence.

RECEPTION_ERROR = 3

A communication error occurred while receiving data from the PC.

SETUP_COMPLETE = 1

The Setup() method runtime succeeded.

STANDBY = 0

The reserved placeholder code the Kernel never transmits.

TARGET_MODULE_NOT_FOUND = 9

No hardware module matches the combined type and id code the message addressed.

TRANSMISSION_ERROR = 4

A communication error occurred while sending data to the PC.

class ataraxis_communication_interface.microcontroller.MicroControllerInformation(port, description, controller_id=None, error_message=None)

Bases: object

Stores descriptive information about a serial port evaluated for the presence of an Ataraxis microcontroller.

controller_id: int | None

The unique identifier code of the microcontroller connected to the port, or None when the port answered no identification request, which is also the case for every port whose connection failed.

description: str

The description the host operating system reports for the port.

error_message: str | None

The error encountered while connecting to the port, or None when the connection succeeded.

port: str

The name of the evaluated serial port, such as ‘/dev/ttyACM0’ on Linux or ‘COM3’ on Windows.

class ataraxis_communication_interface.microcontroller.MicroControllerInterface(controller_id, data_logger, module_interfaces, buffer_size, port, name, baudrate=115200, keepalive_interval=0)

Bases: object

Interfaces with the hardware module instances managed by the Arduino or Teensy microcontroller running the ataraxis-micro-controller library.

Binds each hardware module managed by the microcontroller to its user-facing interface implemented via this library. Abstracts all necessary steps to bidirectionally communicate with the microcontroller and log the incoming and outgoing message data to disk.

Notes

An instance of this class has to be instantiated for each microcontroller active at the same time.

Initializing this class does not automatically start the communication. Call the start() method of an initialized class instance to start the communication with the microcontroller.

Initializing MicroControllerInterface also completes the configuration of all ModuleInterface instances passed to the instance during initialization.

Parameters:

• controller_id (uint8) – The unique identifier code of the managed microcontroller.

• data_logger (DataLogger) – The destination for all incoming and outgoing messages handled by this MicroControllerInterface instance.

• module_interfaces (tuple[ModuleInterface, ...]) – The custom hardware module interfaces for the hardware module instance managed by the microcontroller. Note, each module instance requires a unique interface instance.

• buffer_size (int) – The size, in bytes, of the buffer used by the microcontroller’s serial communication interface. Usually, this information is available from the microcontroller’s manufacturer (UART / USB controller specification). Must be at least 9 bytes. The value bounds the size of the payloads the PC transmits, while reception is bounded by the 254-byte ceiling the COBS encoding imposes.

• port (str) – The name of the serial port to connect to, e.g.: ‘COM3’ or ‘/dev/ttyUSB0’.

• name (str) – A colloquial human-readable name for this microcontroller (e.g., ‘actor_controller’).

• baudrate (int, default: 115200) – The baudrate to use for communication if the microcontroller uses the UART interface. Must match the value used by the microcontroller. This parameter is ignored when using the USB interface.

• keepalive_interval (int, default: 0) – The interval, in milliseconds, at which to send the keepalive messages to the microcontroller. Setting this argument to 0 disables keepalive messaging functionality.

_started

Determines whether the communication process has been started.

_shutdown_lock

Stores the lock that serializes the shutdown sequence between stop() and the watchdog thread, so exactly one of the two retires the instance.

_controller_id

Stores the id of the managed microcontroller.

_name

Stores the human-readable name of this microcontroller instance.

_port

Stores the serial port used for microcontroller communication.

_baudrate

Stores the baudrate used during communication over the UART serial interface.

_buffer_size

Stores the microcontroller’s serial buffer size, in bytes.

_modules

Stores ModuleInterface instances managed by this MicroControllerInterface.

_logger_queue

The Multiprocessing Queue object used to pipe log data to the DataLogger core(s).

_log_directory

Stores the output directory used by the DataLogger to save temporary log entries and the final .npz log archive.

_multiprocessing_manager

The multiprocessing Manager used to initialize and manage the Queue instance that pipes command and parameter messages to the communication process.

_input_queue

The multiprocessing Queue used to pipe the data to be sent to the microcontroller to the remote communication process.

_terminator_array

Stores the SharedMemoryArray instance used to control the remote communication process.

_communication_process

Stores the Process instance that runs the communication cycle.

_watchdog_thread

Stores the thread used to monitor the runtime status of the remote communication process.

_reset_command

Stores the pre-packaged Kernel-addressed command that resets the managed microcontroller to the default state.

_keepalive_interval

Stores the keepalive interval in milliseconds.

Raises:

• TypeError – If any of the input arguments are not of the expected type.

• ValueError – If two ModuleInterface instances share the same combined module type-code and id-code.

• Timeout – If the microcontroller manifest’s .lock file in the DataLogger output directory cannot be acquired within the timeout period.

property controller_id: uint8

Returns the unique identifier code of the managed microcontroller.

property modules: tuple[ModuleInterface, ...]

Returns the tuple of ModuleInterface instances managed by this MicroControllerInterface.

property name: str

Returns the human-readable name of this microcontroller interface instance.

reset_controller()

Resets the managed microcontroller to use the default hardware and software parameters.

Return type:

None

start()

Starts the instance’s communication process and begins interfacing with the microcontroller.

Return type:

None

Notes

As part of this method runtime, the interface verifies the target microcontroller’s configuration to ensure it matches the interface’s configuration.

Raises:

RuntimeError – If the instance fails to initialize the communication process.

stop()

Stops the instance’s communication process and releases all reserved resources.

Return type:

None

Notes

The shutdown is claimed under a lock the watchdog thread takes as well, so exactly one of the two performs the teardown. The lock is released before this method joins that thread, since the watchdog acquires the same lock and holding it across the join would leave each side waiting on the other.

class ataraxis_communication_interface.microcontroller.MicroControllerManifest(controllers)

Bases: YamlConfig

Stores microcontroller source identification data for all MicroControllerInterface instances sharing a DataLogger.

controllers: list[MicroControllerSourceData]

The list of microcontroller source entries registered in this manifest.

class ataraxis_communication_interface.microcontroller.MicroControllerSourceData(id, name, modules)

Bases: object

Stores the identification data for a single microcontroller registered in a log manifest.

Each entry corresponds to one MicroControllerInterface instance that logs communication data to the same DataLogger output directory.

id: int

The controller_id used by the MicroControllerInterface instance when logging to the DataLogger.

modules: tuple[ModuleSourceData, ...]

The hardware modules managed by this microcontroller, identified by their type, id, and name.

name: str

A colloquial human-readable name for the microcontroller (e.g., ‘actor_controller’).

class ataraxis_communication_interface.microcontroller.ModuleExtractionConfig(module_type, module_id, event_codes)

Bases: object

Defines extraction parameters for a single hardware module.

Notes

Event codes must be globally unique within each module. The same event code must not be reused with different semantics across commands. The microcontroller firmware requires this invariance of every module implementation, which enables extraction to filter by event code alone without requiring command code disambiguation.

event_codes: tuple[int, ...]

The event codes to extract. Must not be empty. Each event code must be unique within this module.

module_id: int

The unique identifier code of the hardware module.

module_type: int

The type (family) code of the hardware module.

class ataraxis_communication_interface.microcontroller.ModuleInterface(module_type, module_id, name, error_codes=None, data_codes=None)

Bases: ABC

Provides the API used to interface with the custom hardware module controlled by the companion Arduino or Teensy microcontroller.

Inheriting from this class provides the user-facing API for sending commands and parameters to the managed hardware module.

Notes

Every custom hardware module interface has to inherit from this base class. The subclass initializer has to call ‘super().__init__()’ during the subclass initialization.

All data received from or sent to the microcontroller is automatically logged to disk. Additional data and error codes are only necessary if the interface carries out ‘online’ error detection or data processing.

Some attributes of this (base) class are assigned by the managing MicroControllerInterface during its initialization. Each module interface that inherits from the base ModuleInterface class has to be bound to an initialized MicroControllerInterface instance to be fully functional.

Use the utility methods inherited from the base ModuleInterface to send command and parameter messages to the managed hardware module instance.

Parameters:

• module_type (uint8) – The code that identifies the type (family) of the interfaced module.

• module_id (uint8) – The code that identifies the specific interfaced module instance.

• name (str) – A colloquial human-readable name for this hardware module (e.g., ‘encoder’, ‘lick_sensor’).

• error_codes (dict[uint8, str] | None, default: None) – An optional mapping of the codes used by the module to communicate runtime errors to the explanations surfaced when those errors arrive. Receiving a message with an event-code from this mapping raises a RuntimeError that carries the matching explanation and aborts the runtime. Every code must fall within the custom event code range the microcontroller reserves for hardware modules, as the library resolves the codes below that range itself.

• data_codes (set[uint8] | None, default: None) – An optional set of codes used by the module to communicate data messages that required online processing. Received messages with an event-code from this set are passed to the interface instance’s process_received_data() method for further processing. Every code must fall within the custom event code range the microcontroller reserves for hardware modules.

_module_type

Stores the id-code of the managed hardware module’s type (family).

_module_id

Stores the specific instance ID of the managed hardware module.

_type_id

Stores the type and id codes combined into a single uint16 value.

_data_codes

Stores all message event-codes that require additional processing.

_error_codes

Maps each message error-code that warrants runtime interruption to its explanation.

_name

Stores the human-readable name of this module instance.

_input_queue

The multiprocessing queue used to send command and parameter messages to the microcontroller communication process.

_dequeue_command

Stores the instance’s DequeueModuleCommand object.

_create_command_message

Creates the command message objects, caching up to 32 unique configurations.

_create_parameters_message

Creates the parameter message objects, caching up to 16 unique configurations.

Raises:

• TypeError – If input arguments are not of the expected type.

• ValueError – If any error or data code falls outside the custom event code range.

property data_codes: set[uint8]

Returns the set of message event-codes that require online processing during runtime.

property error_codes: dict[uint8, str]

Returns the mapping of message event codes that trigger runtime errors to their explanations.

abstractmethod initialize_remote_assets()

Initializes the interface instance assets used in the remote microcontroller communication process.

Runs during the initial setup sequence of the remote microcontroller communication process, before the PC-microcontroller communication cycle.

Return type:

None

Notes

Instantiates all interface assets that do not support pickling, such as PrecisionTimer or SharedMemoryArray instances. All assets initialized here must be destroyed by the terminate_remote_assets() method.

property module_id: uint8

Returns the id-code of the specific module instance managed by this interface instance.

property module_type: uint8

Returns the id-code of the type (family) of modules managed by this interface instance.

property name: str

Returns the human-readable name of this module interface instance.

abstractmethod process_received_data(message)

Processes the input message.

Notes

Implements the custom online data-processing logic associated with each message whose event code is specified in the ‘data_codes’ argument.

All incoming message data is automatically cached (saved) to disk at runtime, so this method should NOT be used for data saving purposes.

The data processing logic implemented via this method should be optimized for runtime speed, as processing the data hogs the communication process, reducing its throughput.

Parameters:

message (ModuleData | ModuleState) – The message data received from the interfaced hardware module instance.

Return type:

None

reset_command_queue()

Instructs the microcontroller to clear the managed hardware module’s command queue.

Return type:

None

send_command(command, *, noblock, repetition_delay=np.uint32(0))

Packages the input command data into the appropriate message structure and sends it to the managed hardware module.

Notes

Caches up to 32 unique command messages in the instance-specific LRU cache to speed up sending previously created command messages.

Parameters:

• command (uint8) – The id-code of the command to execute.

• noblock (bool) – Determines whether the microcontroller managing the hardware module is allowed to concurrently execute other commands while executing the requested command.

• repetition_delay (uint32, default: np.uint32(0)) – The time, in microseconds, to wait before repeating the command. If set to 0, the command is only executed once.

Return type:

None

send_parameters(parameter_data)

Packages the input parameter tuple into the appropriate message structure and sends it to the managed hardware module.

Notes

Caches up to 16 unique parameter messages in the instance-specific LRU cache to speed up sending previously created parameter messages.

Parameters:

parameter_data (tuple[unsignedinteger[Any] | signedinteger[Any] | bool | floating[Any], ...]) – The values for the PC-addressable parameters of the target hardware module. Note, the parameters must appear in the same order and use the same data-types as the module’s parameter structure on the microcontroller.

Return type:

None

set_input_queue(input_queue)

Overwrites the ‘_input_queue’ instance attribute with the reference to the provided queue.

Return type:

None

abstractmethod terminate_remote_assets()

Terminates the interface instance assets used in the remote microcontroller communication process.

Runs as part of the remote communication process shutdown routine to ensure any resources claimed by the interface are properly released before the communication process terminates.

Return type:

None

property type_id: uint16

Returns the unique 16-bit unsigned integer value that results from combining the bits of the type-code and the id-code of the managed module instance.

class ataraxis_communication_interface.microcontroller.ModuleSourceData(module_type, module_id, name)

Bases: object

Stores the identification data for a single hardware module registered in a log manifest.

module_id: int

The unique identifier code of the hardware module.

module_type: int

The type (family) code of the hardware module.

name: str

A colloquial human-readable name for the hardware module (e.g., ‘encoder’, ‘lick_sensor’).

class ataraxis_communication_interface.microcontroller.ModuleStatusCodes(*values)

Bases: IntEnum

Defines the service status codes the shared methods of the microcontroller’s base Module class report to the PC.

Notes

The firmware reserves the codes 0 through 50 for this enumeration, so a custom hardware module assigns its own event codes from the range that MINIMUM_CUSTOM_STATUS_CODE and MAXIMUM_CUSTOM_STATUS_CODE bound.

COMMAND_COMPLETED = 2

The active command completed and was removed from the command queue.

COMMAND_NOT_RECOGNIZED = 3

The RunActiveCommand() method does not implement the requested command.

STANDBY = 0

The reserved placeholder code the base Module class never transmits.

TRANSMISSION_ERROR = 1

An error occurred while sending data to the PC.

class ataraxis_communication_interface.microcontroller.TransportStatusCodes(*values)

Bases: IntEnum

Defines the status codes the microcontroller’s TransportLayer class reports for its packet operations.

Notes

These codes come from the ataraxis-transport-layer-mc library that runs on the microcontroller, and they occupy a value range and carry meanings distinct from the TransportLayerStatus codes that the PC-side ataraxis-transport-layer-pc library reports. The firmware attaches the most recent one as the second byte of the two-byte payload that accompanies every reception and transmission error message.

CRC_CHECK_FAILED = 19

The CRC check failed, which indicates that the incoming packet is corrupted.

DECODING_FAILED = 12

The payload could not be decoded from the received packet.

DELIMITER_FOUND_TOO_EARLY_ERROR = 26

The delimiter byte was found before the end of the packet.

DELIMITER_NOT_FOUND_ERROR = 25

The delimiter byte was not found at the end of the packet.

EMPTY_PAYLOAD_ERROR = 28

The packet could not be sent because the staged payload is empty.

INVALID_PAYLOAD_SIZE = 15

The received payload size is not valid.

NO_BYTES_TO_PARSE = 17

No parseable packet was found in the reception buffer.

OBJECT_READ_FROM_BUFFER = 24

The object was read from the buffer.

OBJECT_WRITTEN_TO_BUFFER = 22

The object was written to the buffer.

PACKET_PARSED = 18

The packet was parsed.

PACKET_PARTIALLY_SENT = 29

The communication interface accepted only a part of the packet.

PACKET_RECEIVED = 20

The packet was received.

PACKET_SENT = 13

The packet was transmitted.

PACKET_TIMEOUT_ERROR = 16

Packet parsing failed because the incoming byte stream stalled.

PAYLOAD_SIZE_BYTE_NOT_FOUND = 14

The payload size byte was not found in the incoming stream.

POSTAMBLE_TIMEOUT_ERROR = 27

The postamble was not received within the reception timeout.

READ_OBJECT_BUFFER_ERROR = 23

The payload region of the buffer does not hold enough bytes to read the object from.

STANDBY = 11

The value the TransportLayer class holds before it completes any operation.

WRITE_OBJECT_BUFFER_ERROR = 21

The payload region of the buffer does not have enough space to write the object.

ataraxis_communication_interface.microcontroller.build_message_dataframe(messages)

Builds a polars DataFrame from an extracted columnar message block.

Parameters:

messages (ExtractedMessages) – The columnar message data to serialize.

Return type:

DataFrame

Returns:

The extracted message columns in the schema the table stores.

ataraxis_communication_interface.microcontroller.create_extraction_config(manifest_path)

Generates a precursor extraction configuration from a microcontroller manifest.

Reads the manifest file and populates a ControllerExtractionConfig entry for each registered controller with placeholder empty event codes. The user must fill in the actual event codes for each module entry before the configuration is usable for processing. Each controller entry leaves kernel extraction unconfigured, so a user who wants kernel messages adds a kernel entry with its own event codes.

Parameters:

manifest_path (Path) – The path to the microcontroller_manifest.yaml file.

Return type:

ExtractionConfig

Returns:

The configuration covering every controller and module the manifest registers, with empty event codes.

Raises:

• FileNotFoundError – If the manifest file does not exist or does not point to a file.

• ValueError – If the manifest contains no controller entries.

ataraxis_communication_interface.microcontroller.discover_microcontrollers(baudrate=115200)

Evaluates every serial port available to the host-machine and reports what each port is connected to.

Queries the ports in parallel across a pool sized to the smaller of the port count and the host’s worker budget.

Parameters:

baudrate (int, default: 115200) – The baudrate to use for communication during identification. Only used by microcontrollers that communicate via the UART serial interface, and ignored by microcontrollers that use the USB interface.

Return type:

tuple[MicroControllerInformation, ...]

Returns:

One entry for each evaluated port, ordered the way the host-machine enumerates its ports. Returns an empty tuple when the host-machine exposes no evaluable port.

ataraxis_communication_interface.microcontroller.extract_logged_microcontroller_data(log_path, module_filters, kernel_event_codes, workers=-1, *, display_progress=True, executor=None)

Extracts the hardware module and kernel message data from the target .npz log archive.

Reads the archive that the assemble_log_archives() function of ataraxis-data-structures builds from a MicroControllerInterface instance’s DataLogger output and returns every incoming message whose event code the caller’s filters admit.

Notes

Works exclusively with the incoming messages the microcontroller sent to the PC. Each module is filtered against its own event code set, which prevents off-target extraction across modules that reuse an event code with different semantics.

An archive holding fewer messages than the parallel processing threshold is read sequentially whatever worker count it is given, since the worker startup and the message transfer cost more than the parallel decode saves.

Parameters:

• log_path (Path) – The path to the .npz log archive to process.

• module_filters (dict[tuple[int, int], frozenset[int]] | None) – The event codes to extract for each module, keyed by the module type and identifier pair, or None to skip module extraction.

• kernel_event_codes (frozenset[int] | None) – The event codes to extract for kernel messages, or None to skip kernel extraction.

• workers (int, default: -1) – The number of parallel worker processes (CPU cores) to use for processing. Setting this to a value below 1 auto-resolves the count to every available CPU core minus the cores reserved for the host system. Setting this to a value of 1 conducts the processing sequentially.

• display_progress (bool, default: True) – Determines whether to display a progress bar during parallel batch processing.

• executor (ProcessPoolExecutor | None, default: None) – When provided, parallel batch work is submitted to this pool instead of a newly created one, and the caller owns the pool’s lifecycle. Its worker count must match the workers value used for batch generation, and the caller is responsible for the worker thread limit its processes inherit.

Return type:

ExtractedControllerData

Returns:

The extracted module and kernel messages in columnar form.

Raises:

ValueError – If the target path does not exist, does not have a .npz suffix, or does not point to a file. Also raised if the archive carries no onset timestamp message, and if a data message carries a data payload of a different size than its prototype code declares.

ataraxis_communication_interface.microcontroller.get_event_data(partition, event_code, values_dtype)

Reads the arrival timestamps and the decoded data values of every message carrying the target event code.

Notes

The firmware assigns each event code a single data object type, so every message sharing an event code also shares a payload dtype. That lets the payloads of a whole event stream be concatenated and decoded through one buffer read rather than one read per message.

An event code declaring a scalar prototype has its trailing value axis squeezed, so it returns a 1-D array holding one value per timestamp.

Parameters:

• partition (dict[int, DataFrame]) – The event-code-keyed partition produced by partition_events().

• event_code (int) – The event code to look up.

• values_dtype (type[TypeVar(ScalarT, bound= generic)]) – The numpy scalar type the decoded values are cast to.

Return type:

tuple[NDArray[uint64], NDArray[TypeVar(ScalarT, bound= generic)]]

Returns:

The timestamps of the requested event code and the values decoded from its payloads, both empty when the partition holds no such code. An event code declaring an array prototype yields one row of values per message, so the value array holds one row per timestamp.

Raises:

ValueError – If the requested event code is a state-only event, whose messages carry no data payload. If a message carrying the event code stores a null payload inside an otherwise decodable stream, which marks its prototype code as unrecognized. If the messages carrying the event code store their payloads under more than one dtype. If the decoded value count is not a whole multiple of the message count.

ataraxis_communication_interface.microcontroller.get_event_timestamps(partition, event_code)

Reads the arrival timestamps of every message carrying the target event code.

Parameters:

• partition (dict[int, DataFrame]) – The event-code-keyed partition produced by partition_events().

• event_code (int) – The event code to look up.

Return type:

NDArray[uint64]

Returns:

The timestamps of the requested event code, empty when the partition holds no such code.

ataraxis_communication_interface.microcontroller.partition_events(module_dataframe)

Partitions an extracted message table into one sub-table per event code, in a single pass.

Parameters:

module_dataframe (DataFrame) – The message table read from a feather file this library wrote.

Return type:

dict[int, DataFrame]

Returns:

The sub-table of each event code the table holds, keyed by that event code.

ataraxis_communication_interface.microcontroller.write_microcontroller_manifest(log_directory, controller_id, controller_name, modules)

Writes or updates the microcontroller manifest file in the specified log directory.

If the manifest file already exists (another MicroControllerInterface instance has already registered), reads the existing manifest, replaces the entry registered under the same controller_id or appends a new entry when the manifest carries none, and writes it back. Otherwise, creates a new manifest with a single entry.

Parameters:

• log_directory (Path) – The path to the DataLogger output directory where the manifest file is stored.

• controller_id (int) – The controller_id of the MicroControllerInterface instance to register.

• controller_name (str) – The colloquial human-readable name for the microcontroller.

• modules (tuple[ModuleSourceData, ...]) – The hardware modules managed by this controller.

Raises:

Timeout – If the manifest’s .lock file cannot be acquired within the timeout period.

Return type:

None

ataraxis_communication_interface.microcontroller.dataclasses.MICROCONTROLLER_MANIFEST_FILENAME: str = 'microcontroller_manifest.yaml'

The filename used for microcontroller log manifest files within DataLogger output directories.

ataraxis_communication_interface.microcontroller.dataclasses.EXTRACTION_CONFIGURATION_FILENAME: str = 'extraction_configuration.yaml'

The default filename used for extraction configuration files.

ataraxis_communication_interface.microcontroller.status_codes.MINIMUM_CUSTOM_STATUS_CODE: int = 51

The lowest event code a custom hardware module is allowed to use. Every code below this bound is reserved for the service status codes the base Module class of the ataraxis-micro-controller library defines, and this library resolves those codes itself instead of routing them to the module interface.

ataraxis_communication_interface.microcontroller.status_codes.MAXIMUM_CUSTOM_STATUS_CODE: int = 250

The highest event code a custom hardware module is allowed to use.

Orchestration

Provides the orchestration layer: the job identity and output layout, the archive-derived sizing model, the manifest-derived job resolution, the single-job runner, the shared-pool batch engine, and the sequential pipeline.

class ataraxis_communication_interface.orchestration.ActiveJob(job, sizing, future)

Bases: object

Tracks one job executing in a worker of the shared job pool.

future: Future[None]

The future the pool returned, which carries the job body’s outcome.

job: JobDescriptor

The descriptor the pool was handed.

sizing: JobSizing

The resource figures this job was admitted at.

class ataraxis_communication_interface.orchestration.ArchiveFootprint(message_count, archive_bytes)

Bases: object

Describes the on-disk properties of one log archive that size the job reading it.

archive_bytes: int

The size of the archive file on disk.

message_count: int

The number of data messages the archive holds.

class ataraxis_communication_interface.orchestration.JobDescriptor(log_directory, archive_path, output_directory, config_path, tracker_path, job_name, job_id, source_id, core_weight)

Bases: object

Describes one microcontroller data extraction job, addressed by the single log archive it reads.

Notes

Every field is a path, a string, or an integer, so an instance pickles into a spawned worker and crosses a scheduler boundary or a tool payload unchanged.

archive_path: Path

The path to the .npz log archive this job reads.

config_path: Path

The path to the ExtractionConfig .yaml file naming the events this job extracts.

core_weight: int

The cores this job occupies while it runs, which is the width of the extraction pool its body opens once the job holds more than one core.

property dispatch_key: tuple[str, str]

Returns the tracker path and job identifier pair that identifies this job across the batch.

classmethod for_archive(archive_path, output_directory, config_path, tracker_path, source_id, log_directory=None, core_weight=1)

Builds a descriptor for one archive an external scheduler has already resolved.

Notes

Derives the job identifier as this library’s own preparation does, so one built here addresses the same tracker entry.

Parameters:

• archive_path (Path) – The path to the .npz log archive the job reads.

• output_directory (Path) – The path to the directory the job writes its output files into.

• config_path (Path) – The path to the ExtractionConfig .yaml file naming the events the job extracts.

• tracker_path (Path) – The path to the ProcessingTracker file that records the job’s outcome.

• source_id (str) – The identifier of the controller source whose archive the job reads.

• log_directory (Path | None, default: None) – The path to the DataLogger output directory holding the archive. Leaving this unset uses the archive’s own parent directory.

• core_weight (int, default: 1) – The cores the job occupies while it runs.

Return type:

JobDescriptor

Returns:

The built descriptor.

classmethod from_mapping(mapping)

Reconstructs a descriptor from the mapping a caller received across a tool boundary.

Parameters:

mapping (Mapping[str, Any]) – The mapping to read, carrying every field name to_mapping writes.

Return type:

JobDescriptor

Returns:

The reconstructed descriptor.

Raises:

ValueError – If a required key is absent, or if a value cannot be read as the type its field declares.

job_id: str

The unique hexadecimal identifier of this job in its tracker.

job_name: str

The tracker job name this job is registered under.

log_directory: Path

The path to the DataLogger output directory whose tree holds the log archive.

output_directory: Path

The path to the directory this job writes its output files into.

source_id: str

The identifier of the controller source whose archive this job reads.

to_mapping()

Renders this descriptor as the flat mapping the interface layer exchanges.

Notes

Every value is a string or an integer, so the mapping reconstructs through from_mapping without loss.

Return type:

dict[str, str | int]

Returns:

The descriptor’s fields keyed by their field names, with every path rendered as a string.

tracker_path: Path

The path to the ProcessingTracker file that records this job’s outcome.

class ataraxis_communication_interface.orchestration.JobExecutionState(all_jobs=<factory>, pending_jobs=<factory>, active_jobs=<factory>, core_budget=1, memory_budget_mb=1024, pool_size=1, lock=<factory>, wakeup=<factory>, manager_thread=None, canceled=False, finished_jobs=<factory>, pool_broken=False, broken_jobs=<factory>, pool_rebuilds=0, requeue_counts=<factory>)

Bases: object

Tracks runtime state for one batch execution session budgeted by both cores and memory.

Notes

Every job body runs in a worker of one shared pool that outlives it. A body admitted at more than one core opens its own extraction pool at that width, and a body admitted at one core reads its archive sequentially. Total live processes are the pool’s slot count plus the cores of the running set that opened a pool, and both terms are budgeted.

active_jobs: dict[tuple[str, str], ActiveJob]

Jobs currently executing, keyed by dispatch key so a broken future is matched to its descriptor.

all_jobs: dict[tuple[str, str], JobDescriptor]

Every submitted job, keyed by its dispatch key.

broken_jobs: list[tuple[JobDescriptor, JobSizing]]

The jobs a pool break killed, awaiting requeue once the pool is rebuilt.

canceled: bool

Determines whether the execution session has been canceled.

core_budget: int

The cores the batch may commit across all concurrently running jobs.

finished_jobs: set[tuple[str, str]]

The dispatch keys of the jobs this session drove to a terminal outcome, whether the job body reached one or the engine recorded one for it. A tracker records every job that ever wrote to its directory, so a session reports its own outcomes by intersecting the tracker against this set. A job a pool break requeues is recorded only once it stops being retried.

lock: lock

The lock guarding every mutation of the job queues.

manager_thread: Thread | None

The background thread running the execution manager, or None before the session starts it.

memory_budget_mb: int

The memory the batch may commit across all concurrently running jobs.

pending_jobs: list[tuple[JobDescriptor, JobSizing]]

Jobs awaiting admission, each paired with the figures it was sized at.

pool_broken: bool

Determines whether the shared pool broke and awaits a rebuild.

pool_rebuilds: int

The times the shared pool has been rebuilt during this session.

pool_size: int

The job slots the shared pool opens, every one of which is warmed when the pool is created.

requeue_counts: dict[tuple[str, str], int]

The requeues charged to each job, keyed by dispatch key. Only a job that broke the pool while running alone is charged, since a break fails every in-flight job whatever caused it.

wakeup: Event

The signal that ends the manager’s wait between dispatch passes. A caller finishing a session sets it, so the manager observes the cleared queue at once rather than after the poll interval.

class ataraxis_communication_interface.orchestration.JobSet(log_directory, output_directory, tracker_path, universe, jobs, skipped_sources)

Bases: object

Describes the dispatchable extraction jobs one invocation prepared for one log directory.

jobs: tuple[JobDescriptor, ...]

Every dispatchable job this set holds, in ascending source identifier order.

log_directory: Path

The root directory holding the manifest and the log archives.

output_directory: Path

The subdirectory the preparation resolves, created once at least one job is prepared, which holds the tracker and every output file.

resolve_job(job_id)

Returns the descriptor of the requested job.

Parameters:

job_id (str) – The hexadecimal identifier of the job to resolve.

Return type:

JobDescriptor

Returns:

The descriptor of the requested job.

Raises:

ValueError – If no job in this set carries the requested identifier.

skipped_sources: tuple[tuple[str, str], ...]

Each source that yielded no job, paired with the reason. Always empty under strict sourcing, where a source that cannot be prepared raises instead.

tracker_path: Path

The path to the ProcessingTracker file recording every job in this set.

universe: tuple[tuple[str, str], ...]

Every job the manifest defines, which is the set the tracker is aligned against.

class ataraxis_communication_interface.orchestration.JobSizing(cores, memory_mb)

Bases: object

Describes the resources one job receives, as one sizing pass resolved them.

cores: int

The CPU cores the job occupies while it runs, which is the width of the extraction pool its body opens once it holds more than one core.

memory_mb: int

The memory the job occupies at its peak, in megabytes.

class ataraxis_communication_interface.orchestration.JobSource(source_id, name, archive_path, modules=())

Bases: object

Describes one controller source the manifest registers and the log archive it produced.

archive_path: Path | None

The path to the source’s log archive, or None when the tree holds no single archive for it.

modules: tuple[ModuleSourceData, ...]

The hardware modules the manifest declares for the source, identified by their type, id, and name.

name: str

The colloquial name the manifest records for the source.

source_id: str

The identifier of the source, as it appears in every job specifier and every archive filename.

class ataraxis_communication_interface.orchestration.JobUniverse(log_directory, manifest_path, sources, universe, possible)

Bases: object

Describes every extraction job one log directory’s manifest defines and the subset its archives back.

property archives: dict[str, Path]

Returns the resolved archive of each source that has one, keyed by that source identifier.

log_directory: Path

The root directory the resolution searched.

manifest_path: Path | None

The path to the single microcontroller manifest the directory holds, or None when the tree holds none.

possible: tuple[tuple[str, str], ...]

The subset of the universe whose archive resolved to exactly one file under the log directory.

sources: tuple[JobSource, ...]

Every source the manifest registers, in ascending source identifier order.

universe: tuple[tuple[str, str], ...]

Every job the manifest defines, as job name and source identifier pairs.

Notes

This is a manifest fingerprint rather than an invocation fingerprint, so every invocation aligns a tracker against the same set and no invocation resets the jobs it did not request.

class ataraxis_communication_interface.orchestration.OutputLayout(*values)

Bases: StrEnum

Defines the filesystem names an extraction job writes its tracker and its output files under.

DIRECTORY_NAME = 'microcontroller_data'

The subdirectory created under a caller’s output path for the tracker and the extracted files.

FILE_PREFIX = 'controller_'

The prefix of every output file an extraction job writes.

FILE_SUFFIX = '.feather'

The filename suffix of every output (Arrow IPC) file an extraction job writes.

KERNEL_INFIX = '_kernel'

The infix marking an output file as holding kernel messages.

MODULE_INFIX = '_module_'

The infix separating the controller source identifier from the module type and identifier codes.

TRACKER_FILENAME = 'microcontroller_processing_tracker.yaml'

The processing tracker file recording the outcome of every job writing to one directory.

ataraxis_communication_interface.orchestration.estimate_job_memory_mb(footprint, cores)

Estimates the memory one extraction job holds at its allocated core count.

Notes

The two job shapes the stage emits hold memory in two different ways. A sequential job opens no pool and holds the body’s reader alone. A pooled job splits its archive across the extraction pool, and every child of that pool opens the archive itself while the job body holds a reader of its own for the whole job. The archive’s message directory is therefore held once per core and once more for the body.

The body and a pool child carry separate baselines, because a body assembles and writes the extracted output while a child returns the messages it decoded and holds nothing else.

Parameters:

• footprint (ArchiveFootprint) – The footprint of the archive this job reads.

• cores (int) – The cores this job holds, which is how many extraction pool children it opens once it holds more than one.

Return type:

int

Returns:

The memory this job holds, in megabytes, carrying the estimate tolerance and rounded up to the reporting quantum.

ataraxis_communication_interface.orchestration.execute_job(log_path, output_directory, source_id, job_id, workers, tracker, config_path, *, display_progress=True, executor=None)

Executes a single data extraction job for the target log archive.

Reads the archive once, routes each incoming message through the event code filters the controller configuration declares, and writes one feather (Arrow IPC) file per module that produced data, plus one holding the kernel messages when the kernel produced data.

Notes

Delegates the job’s state transitions to the tracker’s run_job() context manager, which marks the job as running, completes it when the block returns, and marks it as failed with the exception’s message before re-raising when the block raises an Exception. The configuration is read inside that context, so a configuration error is recorded against the job rather than escaping it.

Writes the feather files directly into the output directory, creating it when it does not exist, and registers no job on the tracker.

Publishes each feather file through a temporary file and a rename, so a job killed mid-write leaves the previously written file intact rather than a truncated one a reader cannot decode.

Parameters:

• log_path (Path) – The path to the .npz log archive to process.

• output_directory (Path) – The path to the directory where the output feather files are written.

• source_id (str) – The identifier of the controller source whose log archive is processed.

• job_id (str) – The unique hexadecimal identifier for this processing job.

• workers (int) – The number of worker processes to use for parallel processing.

• tracker (ProcessingTracker) – The tracker recording this job’s runtime status.

• config_path (Path) – The path to the ExtractionConfig .yaml file declaring this controller’s extraction targets.

• display_progress (bool, default: True) – Determines whether to display a progress bar during parallel batch processing. A job that runs sequentially displays nothing.

• executor (ProcessPoolExecutor | None, default: None) – When provided, parallel processing reuses this pool instead of creating a new one.

Raises:

• FileNotFoundError – If no file exists at the supplied configuration path.

• ValueError – If the configuration declares no entry for this controller, if it declares a module or a kernel entry with empty event codes, or if it declares no extraction targets at all. Also raised if the archive path does not resolve to a readable .npz file, if the archive carries no onset timestamp message, or if a data message’s payload size disagrees with its prototype code. Also raised if the tracker holds no entry for this job identifier.

• TimeoutError – If the tracker’s lock cannot be acquired.

Return type:

None

ataraxis_communication_interface.orchestration.find_kernel_paths(data_directory)

Discovers every kernel output file an extraction job wrote into the target directory.

Parameters:

data_directory (Path) – The directory the extraction jobs write their output into.

Return type:

list[Path]

Returns:

The paths to every kernel output file the directory holds, sorted by path, and an empty list when the directory does not exist.

ataraxis_communication_interface.orchestration.find_module_paths(data_directory)

Discovers every module output file an extraction job wrote into the target directory.

Parameters:

data_directory (Path) – The directory the extraction jobs write their output into.

Return type:

list[Path]

Returns:

The paths to every module output file the directory holds, sorted by path, and an empty list when the directory does not exist.

ataraxis_communication_interface.orchestration.finish_execution_session(state)

Waits for a canceled execution session’s manager thread to end.

Notes

Wakes the manager rather than waiting out its poll interval, so a caller that cleared the queue observes the end of the session as soon as it happens. The wait is bounded, and a manager inside the pool’s warm-up or its shutdown can outlast that bound, so the caller reads the returned flag to learn whether the slot is free.

Parameters:

state (JobExecutionState) – The execution state whose manager thread is awaited.

Return type:

bool

Returns:

True when the state holds no manager thread or its manager thread ended within the allotted time, and False when it is still running.

ataraxis_communication_interface.orchestration.generate_job_ids(source_ids)

Generates the processing job identifier of every requested controller source.

Parameters:

source_ids (Sequence[str]) – The controller source identifiers to generate job identifiers for.

Return type:

dict[str, str]

Returns:

The generated hexadecimal job identifier of each source, keyed by that source identifier.

ataraxis_communication_interface.orchestration.get_execution_state()

Returns the active batch log processing execution state, or None when no session exists.

Return type:

JobExecutionState | None

ataraxis_communication_interface.orchestration.group_jobs_by_tracker(state)

Groups every job in an execution state by the tracker file that records it.

Batches the jobs sharing a tracker so each tracker file is deserialized once when iterating over the groups.

Parameters:

state (JobExecutionState) – The active job execution state holding the job registry.

Return type:

dict[Path, list[JobDescriptor]]

Returns:

The jobs recorded by each tracker, keyed by that tracker’s path.

ataraxis_communication_interface.orchestration.parse_kernel_path(file_path)

Reads the controller source a kernel output filename encodes.

Notes

Inverts resolve_kernel_path().

Parameters:

file_path (Path) – The path to the kernel output file to read the identity of.

Return type:

int

Returns:

The controller source identifier.

Raises:

ValueError – If the filename does not follow the kernel output naming convention, or if its source identifier is not an integer.

ataraxis_communication_interface.orchestration.parse_module_path(file_path)

Reads the controller source, the module type, and the module identifier a module output filename encodes.

Notes

Inverts resolve_module_path().

Parameters:

file_path (Path) – The path to the module output file to read the identity of.

Return type:

tuple[int, int, int]

Returns:

The controller source identifier, the module type code, and the module identifier code, in that order.

Raises:

ValueError – If the filename does not follow the module output naming convention, or if any of its three identity fields is not an integer.

ataraxis_communication_interface.orchestration.prepare_jobs(log_directory, output_directory, config_path, source_ids=None, job_id=None, *, strict_sources=True)

Resolves and registers the microcontroller data extraction jobs of one log directory.

Notes

Materializes the output subdirectory and aligns the tracker against the manifest universe once at least one job is prepared, which is every write this call performs outside a job’s own output. The prepared job list lives in the returned set rather than on disk.

Reads no archive. Every job carries the declared allocation as its width, which the sizing pass replaces with the width the job’s own archive resolves to.

A tree holding no manifest is rejected whatever the configuration declares and whatever the sourcing mode, because the absent manifest is a property of the directory rather than of any one requested source.

The extraction configuration declares which controllers this stage processes, so it bounds the requested set the same way the manifest bounds the universe.

Parameters:

• log_directory (Path) – The root directory whose tree holds the manifest and the log archives.

• output_directory (Path) – The root output directory. The library’s own subdirectory is created under it.

• config_path (Path) – The path to the ExtractionConfig .yaml file naming the controllers and events to extract.

• source_ids (Sequence[str] | None, default: None) – The sources to prepare jobs for, or None to prepare every controller the configuration declares. The argument is ignored when a job identifier selects the work.

• job_id (str | None, default: None) – The hexadecimal identifier of the single job to prepare. Leaving this unset prepares every requested source.

• strict_sources (bool, default: True) – Determines whether a source that cannot be prepared stops the call. When set, a requested source the manifest or the configuration does not register, or one whose archive does not resolve to exactly one file, raises. When unset, such a source is recorded in the returned set’s skipped sources.

Return type:

JobSet

Returns:

The prepared job set.

Raises:

• FileNotFoundError – If the log directory or the configuration file does not exist, if the log directory’s tree holds no microcontroller manifest, or if a requested source’s archive is absent under strict sourcing.

• ValueError – If the tree holds more than one manifest, if a manifest registers no sources, if the configuration declares no controllers, or if a job identifier matches no configured controller. Also raised if a requested source is absent from the microcontroller manifest or from the extraction configuration under strict sourcing, or if the resolved archives span several directories.

• OSError – If any directory beneath the log directory cannot be read.

• TimeoutError – If the tracker’s lock cannot be acquired.

ataraxis_communication_interface.orchestration.resolve_core_budget(requested_budget)

Resolves the cores a batch may commit across all of its concurrently running jobs.

Parameters:

requested_budget (int) – The cores the caller requested. A non-positive value auto-resolves to every available core minus the reserved host cores.

Return type:

int

Returns:

The cores the batch may commit, always at least one.

ataraxis_communication_interface.orchestration.resolve_job_workers(footprint)

Resolves the cores one extraction job receives, from the archive it reads.

Notes

The stage offers no width between the two it emits. The speedup between one core and the declared allocation is smooth enough that a narrower pool costs a job time without returning a core the batch can place elsewhere.

Parameters:

footprint (ArchiveFootprint) – The footprint of the archive this job reads.

Return type:

int

Returns:

The cores this job receives, which is one or the declared allocation.

ataraxis_communication_interface.orchestration.resolve_jobs(log_directory)

Resolves the extraction job universe of one log directory and the subset its archives back.

Notes

Reads the manifest and indexes the archive filenames, decoding no message and writing nothing, so a caller enumerates a directory’s jobs without launching or materializing anything. Two tree walks serve any number of sources, one for the manifest and one indexing every archive name the manifest implies.

One recording writes one MicroControllerInterface set to one DataLogger, so a tree holding several manifests spans several recordings and is rejected rather than resolved against the first manifest found. A tree holding no manifest holds no microcontroller jobs, and yields an empty universe rather than an error.

Parameters:

log_directory (Path) – The root directory whose tree is searched for the manifest and the log archives.

Return type:

JobUniverse

Returns:

The resolved job universe.

Raises:

• FileNotFoundError – If the log directory does not exist or is not a directory.

• ValueError – If the tree holds more than one microcontroller manifest, or if a manifest registers no sources.

• OSError – If any directory beneath the log directory cannot be read.

ataraxis_communication_interface.orchestration.resolve_kernel_path(output_directory, source_id)

Resolves the path of the file holding the target source’s extracted kernel messages.

Parameters:

• output_directory (Path) – The directory the extraction job writes its output into.

• source_id (str) – The identifier of the controller source whose kernel messages the file holds.

Return type:

Path

Returns:

The path to the source’s kernel message file.

ataraxis_communication_interface.orchestration.resolve_memory_budget_mb(requested_budget_mb)

Resolves the memory a batch may commit across all of its concurrently running jobs.

Parameters:

requested_budget_mb (int) – The memory the caller requested, in megabytes. A non-positive value auto-resolves to a share of the host’s physical memory.

Return type:

int

Returns:

The memory the batch may commit, in megabytes. A positive request is returned verbatim, while an auto-resolved budget is held to at least the auto-resolution floor.

ataraxis_communication_interface.orchestration.resolve_module_path(output_directory, source_id, module_type, module_id)

Resolves the path of the file holding the target module’s extracted messages.

Parameters:

• output_directory (Path) – The directory the extraction job writes its output into.

• source_id (str) – The identifier of the controller source that manages the module.

• module_type (int) – The type (family) code of the hardware module.

• module_id (int) – The unique identifier code of the hardware module.

Return type:

Path

Returns:

The path to the module’s message file.

ataraxis_communication_interface.orchestration.resolve_pool_size(job_count, core_budget, memory_budget_mb)

Resolves the job slots one batch’s shared pool opens.

Notes

A slot holds a job rather than a core, so the count covers the widest running set admission can produce. Every slot is warmed at creation and holds a spawned child’s baseline memory for the whole session, so the count is held to the spawned children half the memory budget can hold. The other half covers what each running body holds beyond the slot it occupies.

Parameters:

• job_count (int) – The jobs the batch holds.

• core_budget (int) – The cores the batch may commit across all concurrently running jobs.

• memory_budget_mb (int) – The memory the batch may commit across all concurrently running jobs.

Return type:

int

Returns:

The job slots the shared pool opens, always at least one.

ataraxis_communication_interface.orchestration.run_log_processing_pipeline(log_directory, output_directory, config, job_id=None, source_ids=None, *, workers=-1, display_progress=True)

Processes the requested MicroControllerInterface log archives from a single DataLogger output directory.

Extracts hardware module and kernel message data as the extraction configuration specifies and writes the results to feather (Arrow IPC) files. The controller IDs to process are resolved from the extraction configuration and validated against the microcontroller manifest, which confirms the archives were produced by ataraxis-communication-interface.

Supports both local and external processing modes. In local mode (job_id is None), resolves each requested log archive by controller ID, aligns a processing tracker in the output directory, and executes the jobs sequentially. In external mode (job_id is provided), resolves and executes only the single archive matching the requested ID.

Notes

The tracker is aligned against the full job universe the microcontroller manifest defines in both modes, which lets independent external jobs share one tracker without resetting each other’s state.

Each job runs at the width the caller named, or at the width its own archive resolves to when the caller named none. Jobs run one at a time, so this path weighs nothing against a core or a memory budget.

Parameters:

• log_directory (Path) – The path to the root directory to search for .npz log archives. The directory is searched recursively, so archives may be nested at any depth below this path.

• output_directory (Path) – The path to the root output directory. A microcontroller_data/ subdirectory is created automatically under this path, and all tracker and output files are written there.

• config (Path) – The path to the extraction configuration .yaml file specifying which controllers, modules, and events to extract. Controller IDs in the config determine which archives are processed.

• job_id (str | None, default: None) – The unique hexadecimal identifier for the processing job to execute. If provided, only the job matching this ID is executed (external mode). If not provided, all configured jobs are run sequentially with automatic tracker management (local mode).

• source_ids (Sequence[str] | None, default: None) – The controller IDs to process in local mode. Each ID must be declared in the extraction configuration and resolve to exactly one archive. If not provided, processes every configured controller. This argument is ignored in external mode.

• workers (int, default: -1) – The workers every job receives. A positive value is used verbatim. A non-positive value resolves the width from each archive, which is one worker below the parallel extraction threshold and the declared per-job allocation above it.

• display_progress (bool, default: True) – Determines whether to display progress bars during parallel batch processing. A job that runs sequentially displays nothing.

Raises:

• FileNotFoundError – If the log directory or the configuration file does not exist, if the log directory’s tree holds no microcontroller manifest, or if a requested controller’s archive is absent.

• ValueError – If the tree holds more than one microcontroller manifest, if a manifest registers no controllers, if the configuration declares no controllers, if a requested controller or job identifier is not registered, or if the resolved archives span several directories. Also raised once a job runs, if a configured module or the kernel declares empty event codes, or if a controller declares no extraction targets. Also raised if the archive carries no onset timestamp message, or if a logged data message’s payload size disagrees with its prototype code.

• OSError – If any directory beneath the log directory cannot be read.

• TimeoutError – If the processing tracker’s lock cannot be acquired, which a batch running concurrently over the same output directory can cause.

Return type:

None

ataraxis_communication_interface.orchestration.session_is_active(state)

Determines whether an execution state is still running its manager thread.

Notes

A finished session’s state stays readable, so a status reader consults it after the batch ends.

Parameters:

state (JobExecutionState | None) – The execution state to test, or None when no session exists.

Return type:

bool

Returns:

True when the state holds a manager thread that has started and has not yet ended.

ataraxis_communication_interface.orchestration.size_archive_job(archive_path)

Resolves the cores and the memory one extraction job receives, from the archive it reads.

Notes

Reads the archive once and answers both halves of the sizing model from that read.

Parameters:

archive_path (Path) – The path to the .npz log archive the job reads.

Return type:

JobSizing

Returns:

The cores the job occupies and the memory it holds.

Raises:

FileNotFoundError – If the archive cannot be read, in which case the job that reads it cannot run.

ataraxis_communication_interface.orchestration.size_job(job)

Sizes one prepared job from the archive it reads.

Notes

Reads the archive’s zip directory and its file metadata alone, decoding no message. The footprint accompanies the sizing so a caller recording the job can carry the archive properties it was sized against without reading the archive a second time.

Parameters:

job (JobDescriptor) – The prepared job to size.

Return type:

tuple[JobDescriptor, JobSizing, ArchiveFootprint]

Returns:

The job carrying its resolved width, the resources the sizing produced, and the archive footprint they follow from, in that order.

Raises:

FileNotFoundError – If the archive cannot be read, in which case the job that reads it cannot run.

ataraxis_communication_interface.orchestration.start_execution_session(state)

Publishes one execution state as the session of record and starts the thread that manages it.

Notes

The incumbent test, the publication, and the thread start all happen under one lock. A thread reports itself alive only once it has started, so a state published before its thread runs reads as a finished session. Splitting these steps lets two callers each start a manager and double-commit the host’s cores and memory.

A session whose manager thread has ended is replaced, so a completed or an abandoned batch does not block every later batch.

Parameters:

state (JobExecutionState) – The execution state to publish. Its manager thread is created, recorded, and started here.

Return type:

bool

Returns:

True when this state became the session of record, and False when a live session already holds that place.

ataraxis_communication_interface.orchestration.jobs.CONTROLLER_EXTRACTION_JOB_NAME: str = 'microcontroller_data_extraction'

The job name under which microcontroller data extraction is registered in a ProcessingTracker.

Notes

The value is hashed into every persisted job identifier, so changing the string invalidates every identifier a tracker already holds and every identifier a scheduler derived independently.

ataraxis_communication_interface.orchestration.allocation.CONTROLLER_EXTRACTION_JOB_CORES: int = 4

The core allocation every parallel microcontroller data extraction job receives.

Notes

The value sits at the measured knee of the speedup curve, past which each added core buys under a quarter of the time the cores before it bought. Widening beyond the knee costs the batch more than it gains the job, because the cores a wider job holds would otherwise admit a second job that repays them in full.

CLI

axci

Serves as the entry-point for interfacing with all interactive components of the ataraxis-communication-interface (AXCI) library.

Usage

axci [OPTIONS] COMMAND [ARGS]...

config

Manages extraction configuration files for the log processing pipeline.

Usage

axci config [OPTIONS] COMMAND [ARGS]...

create

Generates a precursor extraction configuration from a microcontroller manifest.

Writes the configuration to the requested output path with all controllers and modules populated from the manifest, but with empty event codes that must be filled in before processing. Edit the generated file to specify the event codes for each module entry. Kernel extraction is left unconfigured, so a user who wants kernel messages adds a kernel entry with its own event codes.

Usage

axci config create [OPTIONS]

Options

-m, --manifest-path <manifest_path>

Required The path to the microcontroller_manifest.yaml file to generate the config from.

-o, --output-path <output_path>

Required The path to the output .yaml file where to save the generated configuration data.

show

Displays the contents of an extraction configuration file.

Reads the specified .yaml file and prints each controller’s modules, event codes, and kernel settings.

Usage

axci config show [OPTIONS]

Options

-c, --config-path <config_path>

Required The path to the extraction configuration .yaml file to display.

id

Discovers all connected Arduino or Teensy microcontrollers running the ataraxis-micro-controller library.

Use this command to identify the hardware available to the local host-machine.

Usage

axci id [OPTIONS]

Options

-b, --baudrate <baudrate>

The baudrate to use for communication during identification. Only used by microcontrollers that communicate via the UART serial interface, and ignored by microcontrollers that use the USB interface.

Default:

115200

mcp

Starts the Model Context Protocol (MCP) server for agentic interaction with the library.

The MCP server exposes microcontroller discovery, MQTT connectivity checking, log archive assembly, recording discovery, microcontroller manifest management, extraction configuration management, log data processing, output verification, output cleanup, and event querying through the MCP protocol. The exposed tools enable AI agents to programmatically interact with the library.

Usage

axci mcp [OPTIONS]

Options

-t, --transport <transport>

The transport protocol to use for MCP communication. Use ‘stdio’ for standard input/output communication (default, recommended for Claude Desktop integration) or ‘streamable-http’ for HTTP-based communication.

Default:

'stdio'

Options:

stdio | streamable-http

mqtt

Checks whether an MQTT broker is reachable at the specified host and port.

Attempts to connect to the MQTT broker and reports the result. Use this command to verify MQTT broker availability before running code that depends on MQTT communication.

Usage

axci mqtt [OPTIONS]

Options

-h, --host <host>

The IP address or hostname of the MQTT broker.

Default:

'127.0.0.1'

-p, --port <port>

The socket port used by the MQTT broker.

Default:

1883

process

Processes MicroControllerInterface log archives to extract hardware module and kernel message data.

Extracts data as specified by the extraction configuration and writes the results to feather (IPC) files. Targets a single recording and runs its archives one at a time. Controller IDs in the extraction config determine which archives are processed. Passing a job ID runs that single job alone, which is how an external scheduler dispatches one unit of work. Requires an extraction configuration .yaml file, which ‘axci config create’ generates from a manifest. Use the MCP server to orchestrate batches spanning many recordings.

Usage

axci process [OPTIONS]

Options

-ld, --log-directory <log_directory>

Required The path to the root directory to search for .npz log archives. Typically this is the root directory of the processed recording session.

-od, --output-directory <output_directory>

Required The path to the directory where processed output files are written. Created automatically if it does not exist. All processed data is saved under microcontroller_data subdirectory created under this target output directory.

-c, --config <config>

Required The path to the .yaml file specifying which controllers, modules, and events to extract.

-id, --job-id <job_id>

The canonical hexadecimal identifier of the single job to run. If provided, runs only the matching job, which is the target an external scheduler names when it dispatches one unit of work.

-s, --specifier <specifier>

Controller ID to process. Repeat to specify multiple IDs. If not provided, processes every controller the extraction config declares. Ignored when a job ID selects the work.

-w, --workers <workers>

The worker processes each job receives. Set to -1 (default) to resolve the width from the archive’s message count, which yields a single worker for a small archive and the declared per-job allocation of 4 cores for a large one.

Default:

-1

-np, --no-progress

Determines whether to suppress the progress bars during data extraction. The progress bars are displayed by default.

Default:

False