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

#Header

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

This type of header is used

• Over Serial
• 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.