Wire protocol

The device and the host talk over the ESP32-S3’s built-in USB-Serial-JTAG, with the protocol in the irbt-proto crate. It is no_std and shared verbatim by the firmware and the host.

Framing

Every message is a Frame, serialized with postcard, followed by a CRC-16, COBS-encoded and delimited by 0x00 bytes on both sides:

0x00 | COBS( postcard(frame) ‖ crc16_le ) | 0x00

COBS guarantees that the encoded body never contains 0x00, so the delimiter is unambiguous and a receiver can resynchronize at the next 0x00 after garbage.

All device output, logs included, is framed, so responses, events and logs share one stream. Bytes that don’t form a valid frame (ROM bootloader text, panic dumps) are surfaced by the Decoder as Decoded::Raw instead of being lost.

Messages

• The host sends a Request: an id and a Command.
• The device answers each with a response carrying the same id and a Reply or an error.
• Unprompted, the device sends Events (IR received, learn results, BLE connection changes) and Log lines.

Compatibility

postcard is not self-describing: enum variant order is wire ABI. Variants and fields are only ever appended at the end, and PROTOCOL_VERSION is bumped for anything that changes existing encodings. Golden tests in the crate pin the bytes. irbt status shows the firmware’s protocol version.