Update

UPDATEOne firmware session on one chip

UPDATE carries five ops against one target chip. Every frame leads with the op and the chip. Opcode 0x17.

UPDATE 0x17 · payload 2..508 bytes

Reply

  BEGIN --> DATA --> DATA --> ... --> END --> (staged, inert)
    |                                          |
    +-- ABORT ---------------------------------+--> ACTIVATE --> reboot

A target can be staged and activated later. Both chips may be staged before one ACTIVATE commits them together. QUERY(FIRMWARE) reads what each chip runs. Library binding: update_firmware.

BEGINErase the spare slot and open a session

UPDATE op 0 · [target u8][size u32][sha256 u8[32]]

Puts the whole box in update mode: injection and clip playback stop, the host chip stops polling the real device, and the clone disconnects from the game PC.

Then the box erases the whole target slot and replies READY with the credit in arg. Library binding: stage_firmware.

The erase runs up front. A 64 KB block erase disables the cache for 50-100 ms, longer than any receive buffer on either link can absorb mid-stream.

Open a 364784-byte device-chip image (size is 0x000590F0):

DATAOne chunk, in order

UPDATE op 1 · [target u8][seq u16][bytes 1..504]

504 is what the frame has left: 512 less the op, the target and a two-byte index, rounded down to a multiple of four so every flash write is aligned.

READY's arg is how many chunks the box takes before it acknowledges.

Read it. The device chip asks for 16 and the host chip for 6, because a relayed chunk waits in the inter-chip link's receive ring while the host chip writes the previous chunk to flash.

The window is a correctness requirement.

  PC   |-- credit chunks --|                       |-- credit chunks --|
  box                       |-- write, ACK next --|                     |-- ACK next --|
                            ^
                            cache is off here; nothing may be in flight

A sender ignoring its credit overruns the smaller hop. The lost chunk leaves the window one short, so nothing acknowledges the window. The session ends on the idle timer with the sender still waiting. Library binding: stage_firmware.

A chunk one behind the next expected seq (a lost acknowledgement) is acknowledged without being rewritten. Anything older is a SEQGAP and drops the session.

Chunk 3 of a device-chip image, a full 504 bytes of payload:

ENDVerify the digest and stop

UPDATE op 2 · [target u8]

Checks the digest and image header, then replies STAGED with the byte count, or BADSHA if the image isn't what BEGIN promised. Library binding: stage_firmware.

Ten seconds with no traffic ends update mode, so a vanished client can't leave the clone down. A staged image survives the timeout: it is inert, and its transfer already completed.

Close the device-chip session:

ABORTDiscard the transfer

UPDATE op 3 · [target u8]

Drops whatever is staged or in flight for that target and replies OK. Leaving update mode doesn't reboot: the host chip re-sends its descriptor snapshot and the clone is rebuilt as on a re-attach. Library binding: abort_update.

Once ACTIVATE is accepted, the box replies BUSY to new commands. The one exception is ABORT while the box waits on the host chip: the box abandons the wait and replies TIMEOUT to the ACTIVATE.

Past that wait, the boot partition is written, so nothing is left to abort. Cancelling the reboot would leave the box running one image with the loader pointed at the other.

Discard whatever the host chip is holding:

ACTIVATECommit every staged image and boot it

UPDATE op 4 · [target u8] (ignored)

Points each staged chip at its new slot and reboots into it, host chip first. The device chip is the only transport, so it goes last. Library binding: activate_firmware.

  ACTIVATE
     |
     +--> host commits, reboots
     |         |
     |         +--> back on the link at the new slot
     |                    |
     +--------------------+--> device commits, replies OK, reboots

Only staged targets are committed. A failure before ACTIVATE leaves both chips on their running slots, so it costs only a retry.

The reply is OK once both chips are committed, NOSTAGE if nothing was staged, or TIMEOUT if the host chip never came back on the new slot. The reply always names target 0, so match it on the op alone.

Commit everything staged:

UPDATE_RESPReply to one op

One reply per UPDATE frame, and one per acknowledged window of DATA. Opcode 0x18.

UPDATE_RESP 0x18 · payload 7 bytes

Reply

Every refusal reaches the library as Error::Update.

READY for a device-chip BEGIN, credit 16:

RollbackReverts an image that won't run

A freshly booted image is on probation until it confirms itself. The bootloader reverts an image that never does. QUERY(FIRMWARE) reports each chip's booted slot and image state.

  boot new slot --> pending-verify --> chip confirms itself --> valid
                          |
                          +-- panics, or never confirms --> bootloader picks the old slot

The host chip's image arrives over the link, its only way back. A host image that runs but can't use the link must therefore revert by itself.

Measured on hardware: an image that panics in its entry point is back on the old slot in 0.8 s. An image built to ignore the link reverted and restored the link unaided.

Stable update pathFixed from protocol 5 on

A client that can update one box can update every later one. From protocol 5 (v3.2.0) on, no protocol changes these:

A status may be added. A client reads an unknown status as a refusal. The dashboard connects to any box on protocol 5 or later, and can update but not control a box on another protocol.