tinyboot-protocol

Part of the tinyboot project — see the main README to get started.

Wire protocol for tinyboot. Defines the frame format used between host and device over UART/RS-485.

Frame format

A single Frame struct is used for both requests (host to device) and responses (device to host), so we keep code size tiny.

 0       1       2       3       4       5       6       7       8       9       10      10+len  10+len+2
 +-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+- - - -+-------+-------+
 | SYNC0 | SYNC1 |  CMD  |STATUS |     ADDR (u24 LE)     | FLAGS | LEN_LO  LEN_HI | DATA... | CRC_LO  CRC_HI |
 | 0xAA  | 0x55  |       |       |                       |       |                 |         |                 |
 +-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+- - - -+-------+-------+
 |<--------------------- header (10 bytes) --------------------->|<- payload ->|<--- CRC --->|

Total frame size = 12 bytes overhead + payload. Maximum payload is 64 bytes (MAX_PAYLOAD).

Commands

Per-command flags

Byte 3 of the address field carries per-command flags. Each command defines its own bitflags type; unused bits are reserved and must be zero.

WriteFlags (Cmd::Write)

ResetFlags (Cmd::Reset)

With no flag set, Cmd::Reset boots the app (hand-off mode).

Info response

Returns 12 bytes via the InfoData struct:

Versions are packed as (major << 11) | (minor << 6) | patch and read from the last 2 bytes of each binary (boot and app).

Erase

Erases byte_count bytes starting at addr. Both addr and byte_count must be aligned to the device's erase size.

Request payload (2 bytes via EraseData):

Flushing buffered writes

Writes are accumulated in a ring buffer on the device and flushed a page at a time. The host sets WriteFlags::FLUSH on the Write that ends a contiguous region to commit the trailing partial page. Flush is required:

• On the final Write — otherwise the last partial page may not be written to flash, causing Verify to fail.
• Before skipping an address range — if the host advances the write address (e.g. skipping a gap between segments), it must flush the previous region first.

Write alignment

Write payloads must be padded to a 4-byte boundary. The device writes to flash 4 bytes at a time, so unaligned payloads will fail.

Verify

The addr field carries the application size in bytes. The device computes CRC16 over the first addr bytes of flash (the actual firmware, not the full region), stores the checksum and app size in boot metadata, and transitions to Validating state.

If Verify returns CrcMismatch, check that all Write payloads were padded to 4 bytes and that WriteFlags::FLUSH was set on the last Write (and on the last Write of each contiguous region before any address skip).

Response returns 2 bytes via the VerifyData struct:

Status codes

CRC

CRC16-CCITT with polynomial 0x1021 and initial value 0xFFFF. Computed over the entire frame body (SYNC through DATA, excluding the CRC field itself). Bit-bang implementation with no lookup table for minimal flash footprint.

Protocol flow

1. Host sends a request frame with status = Request (0x00)
2. Device reads the frame, processes the command
3. Device sends a response frame with cmd and addr echoed from the request, status set to the result

The same Frame struct is reused: after read(), the device modifies status, len, and data, then calls send(). The cmd and addr fields carry over automatically.

Data union

The data field is a #[repr(C)] union with typed variants for structured payloads:

pub union Data {
    pub raw: [u8; MAX_PAYLOAD],
    pub info: InfoData,
    pub erase: EraseData,
    pub verify: VerifyData,
}

Data starts at offset 10 (even-aligned), so u16 fields in the union variants are naturally aligned.

Example: flash sequence

Host  -> Info request
Device -> Info response (capacity=16384, erase_size=64, mode=0)

Host  -> Erase addr=0x0000 byte_count=16384
Device -> Ok
...

Host  -> Write addr=0x0000 data=[64 bytes]
Device -> Ok
Host  -> Write addr=0x0040 data=[64 bytes]
Device -> Ok
...
Host  -> Write addr=0x13C0 data=[54 bytes] flags=WriteFlags::FLUSH
Device -> Ok

Host  -> Verify addr=5110 (app_size)
Device -> Ok crc=0x1234

Host  -> Reset
Device -> Ok (then resets)