Tritium 2 - Proxied Device Protocol

From Engineered Arts Wiki
Revision as of 13:11, 25 June 2019 by Rob (talk | contribs) (Created page with "Category:Tritium 2 == Overview == This page describes the protocol used for communication between dynamic devices and their hosts. * De...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search


Overview

This page describes the protocol used for communication between dynamic devices and their hosts.

  • Device discovery
  • Specification
  • Device control - starting & stopping
  • Parameter values from the device
  • Demands sent to the device
  • Logging
  • 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).

Device Discovery

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.

Device: DEVICE_AVAILABLE

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

Device Specification

Host: REQUEST_SPECIFICATION

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
  • Name
  • 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)
  • Aliases

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.

Device Control

Device: DEVICE_READY

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.

Host: START_DEVICE

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

Acknowledges START_DEVICE.

Host: STOP_DEVICE

Stop device operation.

Device reply: DEVICE_STOPPED

Acknowledges STOP_DEVICE.

Device State - Parameter Values

The device state is the set of the values of all the parameters that belong to the device.

Host: SUBSCRIBE_TO_PARAMETER

Indicates that the value of the given parameter should be included in future DEVICE_STATE messages.

Host: UNSUBSCRIBE_FROM_PARAMETER

The value of the given parameter is no longer required, and should not be included future DEVICE_STATE message data.

Host: SET_PARAMETER_UPDATE_INTERVAL

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

Device: DEVICE_STATE

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

Demands

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.

Host: PARAMETER_DEMAND

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.

Host: SET_PARAMETER_FLAGS

  • Parameter ID
  • Value
  • Mask, indicating which bits of the value bitfield should be applied

Host: GET_PARAMETER_FLAGS

  • Parameter ID
  • Value
  • Mask, indicating which bits of the value bitfield are required

Device reply: PARAMETER_FLAGS

  • Parameter ID
  • Value
  • Mask, indicating which bits of the value bitfield contain meaningful data

Logging

Informational and error log messages from the device.

Device: LOG

  • Message
  • Log level - DEBUG, INFO, WARNING, ERROR or CRITICAL
  • Parameter ID, if applicable

Device Info

Host: GET_DEVICE_INFO

Requests the device info (name, firmware version etc) from the device.

Device reply: DEVICE_INFO

  • Name
  • Serial
  • Firmware version
  • Hardware version

Device Status

Host: GET_DEVICE_STATUS

Requests the device status.

Device reply: DEVICE_STATUS

  • State, one of
    • Uninitialized
    • Initializing
    • Configuring
    • Ready
    • Running
    • Stopped
    • Halted
    • In maintenance mode
    • Failed
  • Demand count
  • Demand error count (?)
  • Value count
  • Value error count (?)
  • Command count
  • Command error count (?)
  • Reply count
  • Reply error count (?)

Capture

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.

Host: SETUP_CAPTURE

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

Acknowledges SETUP_CAPTURE

  • Channel, capture rate & num samples as in SETUP_CAPTURE
  • Captured data address in memory and size in bytes

Host: START_CAPTURE

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

Not used.

Reading Memory

Host: READ_MEMORY

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.

Keepalive

Devices are considered to be offline if no message is received from them for some time, by default five seconds.

Host: PING

Sent periodically to all devices, default once per second.

Device reply: PONG

Acknowledges PING.

Maintenance Mode

Host: ENTER_MAINTENANCE_MODE

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

Acknowledges ENTER_MAINTENANCE_MODE.

Device Failure

Device: DEVICE_FAILED

Sent by the device when it detects an error condition it cannot recover from itself.

  • Human readable reason

Host: CLEAR_DEVICE_FAILED

Attempt to recover after failure. It is up to the device implementation to determine if and how this is possible.

Device Reset

Host: RESET_DEVICE

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