Protocol

This page describes the native communications protocol with the device. It is binary based, with a small header, and no other requirements on the data.

By convention, most (if not all) endpoints accept and provide data that is CBOR encoded.

Header

All packets have a simple four byte header that precedes the payload, regardless of the underlying transport:

• 1 byte: Message type
  • Indicates the "endpoint" inside the protocol handler that should receive this message
• 1 byte: Tag
  • Can be used to differentiate multiple outstanding requests and their replies
• 2 bytes: Length
  • Indicates the number of bytes of payload data that follow

Note that all multi-byte values in the header are sent in big endian (network) byte order.

Message Types

Below are all currently implemented message types/endpoints:

Transports

This same protocol can be carried over a variety of physical transports. The format of messages, including the packet header, are the same; however, the transport may add additional headers and padding, if needed. At this time, the following transports are supported:

USB

The first interface exposed by the device is a vendor specific interface, which consists of two bulk endpoints (one in and one out) used to transmit and receive the packets and their responses; as well as an interrupt endpoint, used to notify the host that the state of the device changed.

In this case, the device does not send unsolicited data. No additional headers are added to payloads sent over the endpoints, beyond the above packet headers.