Protocol and format

Message format

Every message starts with an Header and contains a Payload.

The minimal Payload is a single byte. Payload up to 64kB are introduced by a short Header (LEN field on 2 bytes). Longer Payload may exist in the future, and will be introduced by a long Header (LEN field on 4 bytes).

The format of the header is slightly different depending whether the underlying medium is already a point-to-point link with QoS (for instance, a USB wire, a BLE or a TCP channel) or an unreliable link (for instance, based on UDP raw communication).

Note

The current version of the firmware does not supports long Headers.

P2P medium, short header (payload up to 64kB)

This type of header is used

  • Over USB
  • Over BLE
Byte Name Description
0 PCB Protocol Control Byte - see section "PCB" below
1 CLAss Class of command or response
2-3 LENgth Length of payload minus 1 (0000 = 1 to FFFF = 65536), MSB-first

P2P medium, long header (payload longer than 64kB)

This type of header is RFU

Byte Name Description
0 PCB Protocol Control Byte - see section "PCB" below
1 CLAss Class of command or response
2 Flags Must be 00
3-5 LENgth Length of payload minus 1 (000000 to FFFFFF), MSB-first

As a general rule, it is forbidden for both the host and device to use a long header when the length fits in a short header.

Unreliable or unsecure medium, long header (all size of payloads)

This type of header is used

  • Over UDP
Byte Name Description
0 PCB Protocol Control Byte - see section "PCB" below
1 CLAss Class of command or response
2 Flags Bit combination:
- 01: Reply-to fields are present
- 02: Device MAC field is present
- 04: Session token is present
- 08: Sequence counters are present
- 10: Nonce is present
- 20: MAC is present
- 40: RFU
- 80: RFU
3-5 LENgth Total length of frame minus 7, MSB-first

Optional fields between header and payload

Reply-to fields

These fields are present only if bit 0 (mask 01) is set in the Flags byte.

Offset Name Description
0-3 Reply-to address IPv4 address of the server to send the reply to
4-5 Reply-to port UDP port on the server

Device MAC field

This field is present only if bit 1 (mask 02) is set in the Flags byte.

Offset Name Description
0-5 Device MAC MAC address of the target or sender device

Session token field

This field is present only if bit 2 (mask 04) is set in the Flags byte.

Offset Name Description
0-15 Session token Unique identifier of the current session

Sequence counters fields

These fields are present only if bit 3 (mask 08) is set in the Flags byte.

Offset Name Description
0-3 ACK sequence Echo of the last sequence counter received from the peer
4-7 Sequence counter Current sequence counter for the sender

Nonce field

This field is present only if bit 4 (mask 10) is set in the Flags byte.

Offset Name Description
0-15 Nonce Random number (used as IV for ciphering)

Optional fields after the payload

MAC field

This field is present only if bit 6 (mask 20) is set in the Flags byte.

Offset Name Description
0-15 MAC Message Authentication Code of the frame

PCB : Protocol Control Byte

For the Command and Response endpoints

Bit Name Description
7 Way 0: host to device
1: device to host
6 Channel must be 0 for bulk
5 Secure 0 for plain communication
1 for secure communication
4 Header type 0: short header (LENgth on 2 bytes)
1: long header (LENgth on 4 bytes)
3-0 Sequence Sequence number. Incremented by the host (modulo 16) and echoed by the device.

For the Events endpoint

Bit Name Description
7 Way 1: device to host
6 Channel must be 1 for interrupt
5 Secure 0 for plain communication
1 for secure communication
4 Header type must be 0
(long header not supported on InterruptIn)
3-0 Sequence Sequence number. Incremented by the device (modulo 16).

CLA : Class Byte

The CLA field defines the class of the command or response, helps "routing" the message efficiently to the appropriate handler, and makes it possible to reuse software components efficiently.

The rules regarding the format and the understanding of the Payload are class-dependent.

See chapter List of CLAsses for details.

INStruction and STAtus Bytes

Within every CLAss, the actual INStruction to be exectuted by the device is selected by its opcode, being the first byte of the Command Payload.

The execution result or STAtus is also conveyed by the first byte of the Response Payload.

Every CLAss is free to define its own STAtus codes. Anyway, most CLAsses use the same STAtus as the ones defined for the PROTOCOL CLAss and listed in List of STAtus.