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 (u32 LE)        | 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

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):

Flush

The host must send a Flush command to commit any partial page still buffered on the device. Flush is required:

• After 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 first to commit the buffered data at the previous address.

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 Flush was sent after the last Write (and before any address skips).

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  -> Flush
Device -> Ok

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

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