Introduction

The gateway scans for tags and reports a change of their state to a pc over a USB CDC serial port. Everything on the link is a frame: a small binary message with an opcode, a sequence number, a payload and a checksum.

• Open the port at any baud rate; the setting has no effect on a USB CDC port. Assert DTR, as most serial libraries do by default.
• All multi-byte values are little-endian; signed values are two's complement.
• The gateway has no clock. The pc stamps an event when it arrives.
• A seq gap in the events shows that events were dropped; the statistics count them.
• The Tags and Settings tabs of this tool use exactly these messages.

USB framing

Defines how frames are delimited, encoded and protected on the USB CDC link between the gateway and the pc.

Summary

transport

USB CDC byte stream

encoding

COBS

delimiter

0x00

integrity

CRC-16/CCITT-FALSE

byte order

little-endian

maximum decoded frame size

64 bytes

minimum decoded frame size

4 bytes

Layers

Frame

• The frame length is implied by the delimiters; there is no length field.

Sequence number

• Each side keeps one counter per originating role: the gateway counts the events it emits, the pc counts the requests it sends.
• A counter starts at 0, increments by 1 per frame it originates, and wraps from 255 to 0.
• A response carries the seq of the request it answers and does not advance any counter.
• A receiver detects lost frames when the received seq differs from the previous seq plus 1.

CRC

• Algorithm: CRC-16/CCITT-FALSE.
• Polynomial: 0x1021; initial value: 0xFFFF; no input or output reflection; final xor 0x0000.
• Check value: the CRC of the ASCII bytes 123456789 is 0x29B1.
• Transmitted low byte first.

COBS

• A 0x00 byte ends every cobs frame; the encoded data contains no 0x00.
• Each code byte gives the distance to the next 0x00 of the original data, or to the end of the frame; a block holds at most 254 data bytes.
• An encoded frame of 64 decoded bytes takes at most 66 bytes including the delimiter.

Sender behaviour

• Sends one cobs frame per frame, followed by 0x00.
• May send a leading 0x00 before a frame to end any partial frame in the receiver.

Receiver behaviour

• Collects bytes until 0x00, then decodes the collected bytes as a cobs frame.
• Ignores empty cobs frames (consecutive 0x00 bytes).
• Drops a cobs frame that fails to decode, has fewer than 4 or more than 64 decoded bytes, or whose CRC does not match.
• Continues at the byte after the next 0x00, so any error costs at most the frames inside the damaged region.
• Answers a frame with an unknown opcode with an error response, as defined in Opcodes.

Worked example

A tag event frame with tag id 1100123, sensor open, rssi -67 dBm, battery 54 % and seq 0x2A.

• opcode 10 = tag event
• seq 2a = 42
• tag id 5b c9 10 00 = 1100123
• sensor 01 = open
• rssi bd = -67 dBm
• battery 36 = 54 %
• crc 5c fb = 0xFB5C

• 06 code byte: 5 data bytes follow, then a 0x00 of the original data
• 10 2a 5b c9 10 data
• 06 code byte: 5 data bytes follow, then the end of the frame
• 01 bd 36 5c fb data
• 00 delimiter

More examples

Frames as they are sent, with the crc and the cobs encoding applied; the gateway answers the request with the same seq.

Opcodes

Defines the opcode space of the USB protocol and the conventions every message follows.

Summary

opcode size

1 byte

request confirmation

every request is answered by a response or an error

settings storage

a set request stores in nvm and applies immediately

mcu restart

only after the response to an update activate request

Opcode ranges

Opcode table

Conventions

• A get request has an empty payload.
• A set request carries the same payload layout as the matching response.
• The response to a set request carries the values in effect after the change.
• A response carries the seq of its request.
• Multi-byte values are little-endian; signed values are two's complement.
• Enum values not listed in a table are invalid.

Request handling

• The pc keeps at most one request outstanding: it sends the next request after the response or the error response of the previous one has arrived. The gateway is specified for that case only.
• A request has failed when no frame with its seq arrives within 1 s; for the update requests 0x40 to 0x45 the limit is 5 s, because they write flash. The reference tools use these limits.
• After a timeout the pc may send the same get or set request again with a new seq. A late response to the earlier try carries the old seq and is ignored.
• Tag events can arrive at any time, also between a request and its response. The pc recognises a response by its seq and its opcode, and handles every other frame as an event.

Gateway behaviour

• Answers every request with its response opcode, or with the error response.
• Validates the full payload of a set request before applying any part of it.
• Stores accepted settings in nvm and applies them immediately; when a setting needs the scanner to stop, the gateway stops and starts the scanner itself without restarting the mcu.
• Emits tag events without being asked.

Error response (0x0F)

Tag event

Message sent by the gateway when the state of a tag differs from its last reported state.

Summary

opcode

0x10

direction

gateway to pc

kind

event; no response

payload size

7 bytes

Payload

Sensor

Gateway behaviour

• Sends an event the first time a tag is seen after boot, whatever its sensor: the gateway has no earlier sensor to compare with.
• Counts a tag as seen once an advertisement of it has passed the scan filter and its sensor is decoded.
• Sends a further event only when the sensor differs from the last reported sensor of that tag.
• Reports the rssi of the advertisement that carried the change.
• Reports battery 0xFF when the tag table holds no battery percentage.
• Increments the event seq once per event.

Device info

Messages that report the identity and versions of the gateway.

Summary

request opcode

0x02, pc to gateway, empty payload

response opcode

0x03, gateway to pc

response payload size

23 bytes

Response payload

Ble address type

Gateway behaviour

• Increments the protocol minor version for additions that keep existing messages valid, and the major version for changes that break them.
• Reports the version that the bootloader published before it started the firmware, or 0 for all three parts after a power-on reset without a bootloader, see Firmware Update.
• Reports the bluetooth address and its type from the device address registers of the mcu.
• Sets the two most significant bits of a random static ble address, as the Bluetooth specification requires for that type.

Statistics

Messages that report the counters of the gateway.

Summary

request opcode

0x04, pc to gateway, empty payload

response opcode

0x05, gateway to pc

response payload size

18 bytes

Response payload

Gateway behaviour

• Keeps all counters in ram only; every counter starts at 0 after boot.
• Counters wrap at their maximum value.
• Increments events dropped for every tag event that is not written, so each drop shows as a seq gap at the pc.

Scan filter

Messages that read and write which advertisements the gateway accepts.

Summary

get opcode

0x20, pc to gateway, empty payload

response opcode

0x21, gateway to pc

set opcode

0x22, pc to gateway; answered by 0x21 with the filter in effect after the change

payload size

13 bytes

Payload

Defaults

Gateway behaviour

• Accepts an advertisement only when its address matches the mac prefix and its decoded name matches the name prefix.
• Replies with error code 0x03 when a length exceeds its maximum.
• Keeps the known tag table when the filter changes.

Scan parameters

Messages that read and write how the gateway scans for advertisements.

Summary

get opcode

0x23, pc to gateway, empty payload

response opcode

0x24, gateway to pc

set opcode

0x25, pc to gateway; answered by 0x24 with the parameters in effect after the change

payload size

3 bytes

Payload

Channel

Defaults

Gateway behaviour

• Scans continuously on the selected channel or channels.
• Changes channel every dwell time when the channel is all, and ignores the dwell time otherwise.
• Replies with error code 0x03 when the channel is not listed or the dwell time is outside 2 to 1000 ms, and with 0x02 when the payload is not 3 bytes.
• Reads settings stored by a gateway of protocol 1.3, which held the channel only, with the default dwell time.
• Stops and restarts the scanner to apply a change, without restarting the mcu.

Reporting

Messages that read and write which tag events the gateway reports.

Summary

get opcode

0x26, pc to gateway, empty payload

response opcode

0x27, gateway to pc

set opcode

0x28, pc to gateway; answered by 0x27 with the settings in effect after the change

payload size

1 byte

Payload

Defaults

Gateway behaviour

• Ignores advertisements whose rssi is below the threshold before they reach the tag table.
• Accepts every advertisement at the default value.

Firmware update

Replaces the firmware of the gateway over the USB connection: the pc sends the new image in blocks, the gateway checks it and restarts into it.

Messages

Update begin (0x40, pc to device)

Update block (0x42, pc to device)

Update end (0x43), update activate (0x44) and update abort (0x45)

Empty payload, pc to device.

Update response (0x41, device to pc)

Answers 0x40, 0x42, 0x43, 0x44 and 0x45.

State

Error codes

These are part of the error codes of Opcodes.

Connection loss

• A lost connection, a closed port or a removed cable before the activate request returns the device to idle. The data received so far is discarded, the running firmware keeps scanning and nothing restarts. The pc starts again with update begin.
• A request that gets no response within 5 s is not repeated. The pc sends update abort and starts again with update begin, because it cannot know whether the device processed the lost request.
• After the activate response the device restarts by itself, so the connection is lost on purpose. The pc reconnects and reads Device Info; the reference tool waits up to 40 s for the board to reappear.
• A power loss while the bootloader replaces the firmware is repaired at the next start: the bootloader repeats the interrupted replacement and the board always starts a complete image.
• A new firmware image that does not confirm itself within 10 s is replaced by the previous image at the next restart, and update begin is refused until the trial has ended.

Procedure

1. The pc sends update begin and reads the maximum block size.
2. The pc sends update blocks until the whole image is sent.
3. The pc sends update end; the device answers with state verified or error 0x06.
4. The pc sends update activate; the device answers and restarts.
5. The pc reconnects and reads Device Info to confirm the new version. A firmware image confirms itself after 10 s.