Over-the-Air Updates

Hanasu nodes update their firmware over the mesh. A release is wrapped in a signed OTA package (.mnpkg), sent to one node as a Type 6 extended transfer, checked and staged in the node’s spare flash slot, and then applied by an allow-listed admin with a signed command. The new image boots on trial and confirms itself only once the node is healthy. Otherwise it rolls back without outside help, and the node reports either outcome to the admin who asked.

All of this is implemented on both targets, the XIAO MG24 (Zephyr + MCUboot) and the XIAO ESP32C6 (ESP-IDF), and was validated on hardware in both directions on 2026-09-30. The normative sources are docs/OTA-PACKAGE.md (package format, rev 1.4) and MAGNet_Protocol_DESIGN_PROPOSAL.md §13 (remote apply, report and revocation, rev 2.4). For the step-by-step procedure, see the OTA Operator Guide.

Three steps, kept apart link

Staging is harmless by design. Applying reboots the node and changes what it runs, so that is the privileged step.

Why a package, not a raw image link

The first MG24 implementation shipped a bare MCUboot image and relied on MCUboot’s signature check. That does not carry over to the ESP32-C6: a C6 without ESP secure boot (an irreversible eFuse decision the project is not making) boots any well-formed app image. So the node itself must decide, before anything is staged, that an image:

1. was released by a trusted key (authenticity),
2. arrived intact (integrity),
3. is meant for this chip and board (targeting: an MG24 image in a C6 slot, or an image without the XIAO RF-switch bring-up on a XIAO, bricks the radio),
4. is an acceptable version (version policy).

A small signed header answers all four the same way on every platform, and the platform’s own image format rides inside it unchanged.

Package layout link

A package is a fixed 256-byte header followed by the platform image, byte for byte. There is no trailer. The header always fits whole in chunk 0 of a Type 6 transfer (336 bytes), and every payload byte lands at package offset − 256, which keeps flash writes 4-byte aligned. File extension .mnpkg, MIME application/vnd.magnet.ota-package.

All multi-byte integers are big-endian. Reserved bytes must be zero when written and are verified zero when read.

The signature covers every header byte before it, including image_sha256, so it covers the payload too. Ed25519 signs the 192 raw header bytes; P-256 signs SHA-256 of them (r ‖ s). Everywhere else (the apply command, !OTA events, tooling) a staged package is identified by sha128, the first 16 bytes of image_sha256.

Chip and board registry link

chip and board come from an append-only registry in docs/OTA-PACKAGE.md §3.1: a value is never reused or redefined, and a board ID’s high byte is its chip ID. It covers six chips (ESP32-C6 0x0001, EFR32MG24 0x0002, classic ESP32, ESP32-S3, ESP32-C3, nRF52840) and every board in use across the MagNET repos. The two that Hanasu OTA builds use today:

tools/mnpkg.py carries the same table and refuses a board that does not belong to the given chip.

The nine checks link

A receiving node runs these in order and stages nothing unless all pass. Checks 1–6 need only the header, so the node runs them the moment chunk 0 arrives and refuses a bad package before its payload crosses the air. Checks 7–9 run after the last chunk.

Check 7 hashes what was read back, not what arrived, so it also catches a bad flash write. The downgrade rule is deliberately not a staging check: it is enforced at apply time, so an admin can stage a known-good older build ahead of an emergency rollback.

The node answers the sender with XC_COMPLETE only if all nine passed, and XC_REFUSED otherwise, with the failing check number in the STATUS frame’s reason byte. So on the sender, !XFER_SENT means “staged and verified”, and a refusal reads !XFER_FAIL <xid> refused:<n>.

Release keys link

Each image carries a compiled-in store of up to two release keys, current and next. Rotating keys means shipping an image, signed by the current key, whose store holds the next one. Nodes must support Ed25519 and should support P-256; both Hanasu targets do. The release key is separate from the admin keys (who may apply), the MCUboot key (what may boot on the MG24) and bundle author keys (what Forth may run). Holding one grants none of the others.

The repo’s DEV release keys are public. A build that trusts them says so at boot with !WARN ota-dev-keys, and mnpkg.py build refuses a DEV key unless the variant name starts with dev. Release builds use keys generated offline; see the operator guide.

Staging on each platform link

The transfer is one Type 6 transfer, CON unicast, with meta mnpkg:1. A node with an OTA sink claims a transfer by that meta, keeps the header in RAM, and writes payload bytes to its update slot.

On success the node logs !OTA staged v<version> <sha128 prefix> … — FORTH: ota-apply. The Forth word ota-status prints the running image and what is staged.

The C6 partition table link

OTA on the C6 needs a dual-slot table, firmware-idf/partitions_ota.csv, which fits 4 MB parts:

The BLE+LED image is about 1.16 MB (65 % of a slot) and the Thread-only image about 852 KB. A partition table cannot change over the air, so moving a node onto this table is a one-time USB flash of the OTA env (esp32c6_xiao_ble_led_ota, which also enables CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE). A package whose build changes the partition table must set REQUIRES_REPARTITION, and nodes refuse such packages over the air.

The MG24 flash map link

The MG24 build uses MCUboot in swap-using-move mode with the map in firmware-zephyr/boards/mg24_partitions.dtsi: MCUboot 48 KB, slot0 712 KB, slot1 712 KB, and storage 64 KB at 0x170000, where the pre-MCUboot build put it, so identity and bonds survive. See XIAO MG24 on Zephyr.

Trial, confirm, rollback link

Both platforms apply the same health policy, with each platform’s own mechanism underneath:

A new image is healthy, and only then confirmed, when both hold:

1. the node reached READY (Thread attached), and
2. every persisted Forth role bundle re-applied without error at boot (or none was persisted).

The node polls every 2 seconds. If it is not healthy within 10 minutes it logs !WARN ota-unhealthy and reboots, and the bootloader reverts. The bundle half of the rule matters: a firmware update can remove an FFI word a saved bundle uses. The bundle then fails to re-apply (safely), but the node still reaches READY, so a READY-only rule would confirm an image that had silently lost the node’s role.

PERMANENT mode skips the trial. On the MG24 it is MCUboot’s permanent upgrade; on the C6 the new image marks itself valid at its first boot when the apply record says PERMANENT. TEST is the default; PERMANENT is used only when explicitly requested.

Admin-signed remote apply link

system/ota_apply (namespace 0x00, command 0x06) is a Type 1 M2M command on the existing admin plane: ENCRYPTED, SIGNED and ADMIN, signed by the sender’s identity key and verified against the receiver’s admin allow-list before dispatch. It is sent CON unicast to the target, never multicast.

The receiver checks, in this order; any failure answers with the code and changes nothing. The status byte is the check number.

Check 7 runs right after check 2, so a build without OTA answers 7 rather than 3. A build without an OTA sink links weak defaults that answer E_UNSUPPORTED.

On success the node records the apply in NVS (the admin’s device ID and address, the new and previous versions, the mode), notes the CLEARS_BUNDLES flag, arms the slot, and replies accepted. It reboots once the reply’s CoAP ACK arrives (+0.5 s), or at a 20-second cap if it never does. Earlier drafts used a fixed short delay, which lost the reply on the bench whenever the first transmissions were lost; the cap keeps a lost admin from stranding an armed node.

The reply is a Type 2 M2M Response, 74 bytes: status, the target’s running version, and its 65-byte identity public key. It is SIGNED (not ADMIN) with the target’s own key. The admin does not hold that key in advance, so it checks the signature and that SHA-256(pubkey)[0:4] equals the sender’s device ID. SIGNED-without-ADMIN frames are accepted only for this reply and the report; any other is dropped.

The post-reboot report link

The result of an apply is only visible after the reboot, so the target reports once its OTA state settles. system/ota_report (namespace 0x00, command 0x07) carries 83 bytes:

The outcome is decided by version, not by platform state: running equals the applied version → CONFIRMED; running equals the version before the apply → ROLLED_BACK; anything else (reflashed by hand since) → the record is dropped silently. A rollback is reported by the old image on the boot after the revert. The report waits for READY and goes CON unicast to the admin that issued the apply, falling back to channel multicast if that send fails. A local ota-apply leaves no apply record, so it produces no report.

On the admin’s host link the exchange reads:

  OTA APPLY <peer-id|ipv6> <sha128-hex> <maj.min.rev+build> [PERM] [DOWNGRADE]
+OK sent
!OTA_RESULT <id> accepted v<running>
!OTA_REPORT <id> confirmed v<new> (was v<old>) bundles=<n>
!OTA_REPORT <id> rolled-back v<old> (failed v<new>) bundles=<n>
  

sequenceDiagram
    participant H as Operator host
    participant A as Admin node
    participant T as Target node
    H->>A: XFER BEGIN / XFER DATA (meta mnpkg:1)
    A->>T: Type 6 chunk 0 (header)
    Note over T: checks 1-6
    A->>T: Type 6 chunks 1..n
    Note over T: checks 7-9, staged in spare slot
    T-->>A: XC_COMPLETE
    A-->>H: !XFER_SENT
    H->>A: OTA APPLY id sha128 version
    A->>T: system/ota_apply (ADMIN, SIGNED)
    Note over T: apply checks 2-7, record + arm slot
    T-->>A: reply accepted (SIGNED)
    A-->>H: !OTA_RESULT accepted
    Note over T: reboot on ACK, trial boot
    Note over T: READY + bundles re-applied within 10 min
    T->>A: system/ota_report confirmed (or rolled-back)
    A-->>H: !OTA_REPORT

CLEARS_BUNDLES link

Flag bit 1 is for firmware that breaks the Forth vocabulary on purpose. While such an image is on trial the node does not re-apply its saved bundles: health reduces to READY and the report says bundles=3. Once the image is confirmed, the node forgets the saved bundles, and the operator redeploys bundles written for the new vocabulary. If the image rolls back instead, the bundles were never touched and the old image re-applies them as usual.

Nodes record the flag whenever an image is armed, by local ota-apply or remote apply, keyed by the image’s version. Package format revisions 1.0–1.3 said “forget on first boot”, which lost the bundles on a rollback; rev 1.4 holds them back during the trial instead.

Admin keys and revocation link

Admin keys are named by fingerprint, SHA-256(65-byte pubkey)[0:8], which ADMIN LIST prints. Its first 4 bytes are the key owner’s device ID. A node allow-lists up to 4 admin keys.

system/admin_revoke (namespace 0x00, command 0x08) carries the 8-byte fingerprint, is ADMIN|SIGNED, and is verified against the receiver’s allow-list like any admin command. Unlike apply it is multicast NON: revocation must reach every node, and it is idempotent, so the operator repeats it to cover a lost frame. An admin may revoke its own key, because the frame is signed before the local removal. A node that does not hold the key logs # admin revoke: key not held.

Limits: revocation cannot stop a thief who still holds a valid admin key from revoking the others just as fast, and a node that was offline when the revoke went out keeps the key until it is revoked again. There is no revocation list.

Threats link

Fleet rollout is sequential with a canary: one node first, the next only after its CONFIRMED report, never a multicast apply.

Hardware validation link

Run 2026-09-30 between a XIAO MG24 (Zephyr, BLE-resident, MCUboot) and a XIAO ESP32C6 (esp32c6_xiao_ble_led_ota), each allow-listing the other’s key. Every row was observed on hardware:

Two Zephyr-port bugs surfaced during these runs. The accepted reply was lost on several MG24 applies because the compat layer allocated FreeRTOS timer control blocks from the kernel heap, which BLE exhausts at runtime, so the reboot timer could not be created. The NVS shim had the same root cause: its key-list snapshot came from the kernel heap, so at runtime every NVS enumeration silently returned nothing. Both now allocate from the libc arena. Not covered by this run: refusal of a privileged verb on an unbonded BLE link (that gate was validated earlier, in the BLE phase).

Staging speed is bound by the node and radio round trip: tools/ota_push.py moves about 90 ms per 336-byte chunk. C6 → MG24 with a 557 KB package took 137–169 s; MG24 → C6 with 1.17 MB took 385 s.