Tritium 2 - Proxied Device Protocol
- 1 Overview
- 2 Device Discovery
- 3 Device Specification
- 4 Device Control
- 5 Device State - Parameter Values
- 6 Demands
- 7 Special case - Flags Parameter
- 8 Logging
- 9 Device Info
- 10 Device Status
- 11 Capture
- 12 Reading Memory
- 13 Keepalive
- 14 Maintenance Mode
- 15 Device Failure
- 16 Device Reset
This page describes the protocol used for communication between devices running as independent processes and their hosts. Proxied devices are often dynamic devices which supply their own specification details, but are not required to be.
- Device discovery
- Device control - starting & stopping
- Parameter values from the device
- Demands sent to the device
- Raw memory examination
The protocol messages are formatted as Protocol Buffers defined in tritium_proxy.proto. Messages from the proxy host node to the device are ProxyCommand messages. Devices send ProxyMessage messages, often in response to a command from the host. The numeric command ID is included in the reply to allow the host to match them up.
The underlying transport layer may be unreliable, either by design (UDP) or in practice (USB).
The essential feature of Dynamic Devices is that they can be added to a Tritium system and become available for use without needing configuration. The device itself supplies all the information required.
As soon as it is ready to do so, the firmware running on a device starts sending DEVICE_AVAILABLE. This message may be repeated until the host responds if the transport is unreliable (e.g UDP).
- Device name
- Device class name
- Device class version
- Device serial
DEVICE_AVAILABLE must be the first message sent by a device. Other messages from a device will be ignored by the host until this is received and acknowledged.
From the host's point of view, receiving a DEVICE_AVAILABLE from an unknown source is the first thing it knows about a new device. This triggers the start of the process whose end result is the device becoming available for use by all other parts the Tritium system.
Host reply: DEVICE_REGISTERED
Sent in acknowledgement of DEVICE_AVAILABLE. No more such messages should be sent by the device.
- Keepalive value - an arbitrary value to be sent with future messages. Messages received by the host with an unexpected keepalive value are dropped (assumed to be from a previous Tritium run)
- Device ID - host assigned identifier
Sent if the host does not already have a complete specification for the device's class and version. On the other hand, if the host does have full details of the device class already, it can skip this step and proceed directly to configuration and activation.
Device reply: SPECIFICATION
The full specification may be quite large and, depending on the transport layer, too big to fit in a single message. Therefore multiple SPECIFICATION messages may be sent by the device with the more field set to indicate further messages to come.
The messages combine to provide a complete device class specification, most importantly a collection of parameter specifications:
- Parameter ID
- Type - double, boolean etc
- Flags - readable, writable, persistent, requires configuration
- Group name
- Parent ID - for dependent parameters, eg min/max of the parent (deprecated, dependent parameters are matched up by name and may be shared)
Depending on the parameter type, there may be extra information:
- Default value
- Minimum / maximum value
- Unit of measurement
The protocol also provides a way to send individual device (not device class) specifications, but this is not currently used.
Sent by the device when it itself considers itself ready to go. Exactly when this is depends on the device - some simple devices may be ready immediately, but many will have parameters that need configuring. Parameters which need configuring must have the MUST_CONFIGURE flag set in their specification. This tells the host to send PARAMETER_DEMAND messages with values retrieved from the persistent state of the device. Once all such parameters have initial values the device will then send the DEVICE_READY message.
Instructs the device to begin operating.
If the robot is in maintenance mode, the device must also remain in maintenance mode - see below.
Device reply: DEVICE_STARTED
Stop device operation.
Device reply: DEVICE_STOPPED
Device State - Parameter Values
The device state is the set of the values of all the parameters that belong to the device.
Indicates that the value of the given parameter should be included in future DEVICE_STATE messages.
The value of the given parameter is no longer required, and should not be included future DEVICE_STATE message data.
Sent to indicate how frequently a parameter value should be recalculated. The device may ignore this message if it is unable to honour the request.
- Parameter ID
- Desired time interval between updates in μs
A list of parameter ID and value pairs.
- Only subscribed parameters whose values have changed since the last DEVICE_STATE message (or have never been sent)
- Multiple DEVICE_STATE messages may be used to send parameter values in batches, default batch size 32
Demand messages tell the device that it should do something, specifically whatever action is required to set the given parameter value to the demand value.
A single parameter ID and value pair. How the value is applied to the parameter is up to the device, and the demand may be ignored if invalid. There is no acknowledgement.
Special case - Flags Parameter
Although stored as a single integer value, flag may be treated as independent values.
- Parameter ID
- Mask, indicating which bits of the value bitfield should be applied
- Parameter ID
- Mask, indicating which bits of the value bitfield are required
Device reply: PARAMETER_FLAGS
- Parameter ID
- Mask, indicating which bits of the value bitfield contain meaningful data
Informational and error log messages from the device.
- Log level - DEBUG, INFO, WARNING, ERROR or CRITICAL
- Parameter ID, if applicable
Requests the device info (name, firmware version etc) from the device.
Device reply: DEVICE_INFO
- Firmware version
- Hardware version
Requests the device status.
Device reply: DEVICE_STATUS
- State, one of
- In maintenance mode
- Demand count
- Demand error count (?)
- Value count
- Value error count (?)
- Command count
- Command error count (?)
- Reply count
- Reply error count (?)
This provides a mechanism for extracting data from the device which is not suitable to obtain via parameters. Typically this is used for diagnostic data generated at too a high frequency to send one value at a time.
Prepare a hardware data capture. Must be sent before START_CAPTURE.
- Channel number (allows multiple capture scenarios even though only one capture may be active at a time)
- Capture rate, Hz
- Number of samples to capture
Device reply: CAPTURE_SETUP
- Channel, capture rate & num samples as in SETUP_CAPTURE
- Captured data address in memory and size in bytes
Starts capturing data as configured in the last SETUP_CAPTURE.
Device reply: CAPTURE_COMPLETE
Sent when the capture set in motion by START_CAPTURE has reached the required number of samples. The captured data may then be retrieved using READ_MEMORY below.
Device reply: CAPTURE_FAILED
Queries the device memory. The data is returned as raw bytes.
- Memory address
- Number of bytes to read
Device reply: MEMORY_READ
- Raw memory data as bytes
Note that the data is sent in a single message. Behaviour is undefined if the amount requested is too big for the underlying transport.
Devices are considered to be offline if no message is received from them for some time, by default five seconds.
Sent periodically to all devices, default once per second.
Device reply: PONG
Puts the device in maintenance mode, where it should accept parameter values for configuration but otherwise be inactive. For safety no physical movement is allowed while in this mode.
Device reply: DEVICE_IN_MAINTENANCE_MODE
Sent by the device when it detects an error condition it cannot recover from itself.
- Human readable reason
Attempt to recover after failure. It is up to the device implementation to determine if and how this is possible.
Stop the device and return to initial state, as determined by the device itself.
- Bootloader flag (?)
Device reply: DEVICE_RESET
Acknowledges RESET_DEVICE (without implying success).