auto-trainer-api 0.9.17

API for interfacing with the core acquisition process via platform and language agnostic message queues.

Autotrainer API: Python Integration

The python auto-trainer-api module is intended to provide an efficient means to emit information that is needed for local or remote management of applications running locally on the device and to receive commands from those sources.

The exposed API is intended to be agnostic to the underlying transport layer. The current implementation uses ZeroMQ. The reasons for this decision include:

• Relatively low overhead for the acquisition application
• Does not require either side to manage connections and know when the other side is available or changes availability
• Does not require an additional process or service to maintain a persistent message queue (e.g., RabbitMQ)
  • Persistent data is managed elsewhere

Client Integration

There are two points of integration available for clients to support the remote interface. The first allows publishing "events" for state and property changes that occur in the client. The second is a "command" interface for the client to receive command requests from remote sources.

Both interfaces are provided through an instance of the RpcService class. An instance can be obtained via create_api_service(...) which constructs the specific concrete implementation. After creation, the service must be explicitly started (start(...)) and can be stopped (stop(...)). Once stopped, an instance can not be restarted. If a connection should be reestablished after stopping an instance, a new instance should be created and started.

Events

Events are supported through the send_dict(topic: ApiTopic, message: dict) method on the RpcService instance.

The first argument is the appropriate ApiTopic value for the event. The most common for clients to support are

• ApiTopic.EVENT - the topic for most events representing general activity in the about or high-level state changes
• ApiTopic.EMERGENCY - a dedicated topic for emergency-related events such as emergency-stop/resume, alarm changes, etc. [1]
• ApiTopic.PROPERTY_CHANGE - lower-level property changes on specific objects of interest
• ApiTopic.COMMAND_RESULT - command responses for non-immediate commands (see Commands section)

The second argument is a dictionary whose contents depend on the topic. All elements must serializable to JSON.

ApiTopic.EVENT

The dictionary contains the following entries:

• kind - an ApiEventKind value
• when - a wall-clock value of time
• index - monotonically increasing timestamp w/units if nanoseconds
• context - an object whose contents depend on the ApiEventKind; may be None for some event kinds

ApiTopic.EMERGENCY

Still under development.

ApiTopic.PROPERTY_CHANGE

Still under development.

ApiTopic.COMMAND_RESULT

An instance of ApiCommandRequestResponse.

[1] Currently these are supported as special cases of ApiTopic.EVENT. At some point these should be transitioned to the dedicated topic.

Commands

Commands from external sources are supported by registering a CommandRequestDelegate with the RpcService instance. The delegate receives an instance of ApiCommandRequest and must return an instance of ApiCommandRequestResponse.

The primary property of the ApiCommandRequest is command which is an ApiCommand value. Depending on the command, there may also be a dictionary in the data property with arguments or other information relevant to the command. The nonce property can be ignored if the command is handled synchronously. For commands that send an ApiTopic.COMMAND_RESULT event after completion (see below), the nonce must be stored to associate with that event (along with the command value).

The returned ApiCommandRequestResponse object contains one require field

• result - a value of ApiCommandRequestResult

There are also three optional fields

• data - an optional object with results from the command beyond success/failure (often will be None)
• error_code an integer error code value if the command is not successful or can't be initiated
• error_message an optional string message if the command is not successful or can't be initiated

The expected contents of the data property are defined by the command, but is typically None.

The error_code property should be a non-zero value if there is an error code to report.

There are two fields on the ApiCommandRequestResponse object that are ignored as part of the returned object from the command delegate: command and nonce. See Asynchronous Commands for when these fields are required.

Asynchronous Commands

The command delegate is expected to return "immediately" (low millisecond type of time frame). If the command is not deterministically fast, it is expected to immediately return an ApiCommandRequestResponse with a result value of ApiCommandRequestResult.PENDING_WITH_NOTIFICATION.

Once the action associated with the command is complete, the client should send an Event (previous section), with a topic of ApiTopic.COMMAND_RESULT. The message argument of the send_dict method should be another instance of ApiCommandRequestResponse. The command and nonce properties of the response object should be set to the values received in the ApiCommandRequest (the client is responsible for storing these values until needed). Note that those two properties are ignored for synchronous command handling, but required for asynchronous responses.

Tools

Client Application

scripts/client_application.py starts an interactive process that enables the RpcService as a "real" autotrainer application would. It generates heartbeat events, periodically publishes system status events, and responds to commands (GET_CONFIGURATION, GET_STATUS). The following interactive commands are available:

• app_launch - publish an applicationLaunched event
• detector / d <detector_id> <is_active> - update a detector's status and publish a detectorChanged event
• alarm / a <alarm_id> <is_active> <is_enabled> - update an alarm's status and publish an alarmChanged event
• magnet <intensity> - set the current magnet intensity (0.0-100.0)
• baseline <intensity> - set the baseline magnet intensity (0.0-100.0) and publish a headfixBaselineChanged event

Detector and alarm IDs can be specified by numeric value, exact enum name, or a unique prefix of the name (case-insensitive).

This is primarily useful for testing remote applications/services without running the main autotrainer acquisition application.

Remote Console

scripts/remote_console.py starts an interactive process that connects to an RpcService instance in the same manner full remote management services would. It supports the -H/--host argument to specify a remote host address (defaults to 127.0.0.1). Available commands: start, stop, configuration, status.

Publishing

python -m build

python -m twine upload dist/* (requires PyPi API token)

Installation

The package is published to the PyPi package index and can be installed with standard pip commands.

pip install auto-trainer-api