# Admin-pushed firmware update (experimental `-ota` images) The `*-ota` and `*-observer-ota` images of this fork's releases can take a new firmware from their admin -- over the USB or BLE console, or **over the mesh, as remote admin CLI**. Nothing changes in the bootloader and there is no second bank: the node stores the package in free flash, checks all of it, and only on an explicit `fw apply` rewrites itself from a routine running in RAM. The point is the **delta**: a package against the image the node runs is usually a few kB, so it goes through LoRa in minutes. A full image (~300 kB) goes only over USB or BLE. **Experimental.** Tried on XIAO nRF52840 boards over USB and over the mesh (one hop). A broken new firmware has nothing to fall back to: try every release on one node within reach before the ones you cannot reach. ## What a release carries For every `_-ota` / `-observer-ota` image: | file | what | |---|---| | `-.zip` / `.uf2` | the image, flashed the usual way (first time) | | `-.mcfw` | full package: USB/BLE console only | | `-.from-.mcfw` | delta from an earlier release's same image | | `manifest.json` | image sha256, target, build epoch, packages, deltas by base | | `SHA256SUMS`, `SHA256SUMS.sig` | checksums, signed by `meshcore-ota@tth-pub` | Check a download: ssh-keygen -Y verify -f tools/ota_allowed_signers -I meshcore-ota@tth-pub \ -n meshcore-ota -s SHA256SUMS.sig < SHA256SUMS sha256sum -c --ignore-missing SHA256SUMS `tools/ota_pack.py fetch --base ` does both and picks the delta for the node's image (`--full` for the full package, `--release ` for another than the latest). ## On the node ``` fw status state, battery, the running image's size and sha256 prefix fw ver target and build epoch a package for this image needs fw begin [sid] start a transfer fw w one 96 B chunk (text) fw missing what is still missing fw verify queue the full check, poll fw status fw apply battery gate, then rewrite and reboot fw apply downgrade local console only: an older (or the same) image fw abort ``` What the node checks before it touches its own image: 1. The **manifest**, as soon as it is in: an Ed25519 signature by the key the image was built with (`[ota] pubkey`), the target (board + variant: an `-observer-ota` node takes no `-ota` package), the size, for a delta the base (the sha256 of the image it runs), and the build epoch. 2. Over the mesh: **only a delta, and only a newer build.** An older or equal one is refused right after the manifest; a full image is refused when the transfer begins. Locally a full image is fine, and an older one takes `fw apply downgrade`. 3. `fw verify`: the payload hash, and a delta applied **dry** -- the same code the real run uses, with the flash untouched -- must produce the signed image hash. 4. `fw apply`: battery at 3.8 V or more unless the node runs on USB. The bootloader settings get the new image's CRC **first**, so a power cut during the rewrite leaves the node in the bootloader (back with USB/BLE DFU), not in half an image. ## Tools ```bash # a delta for the node's image, from the latest release tools/ota_pack.py fetch Xiao_nrf52_repeater-ota --base # over the mesh, through a companion (USB port or tcp://host:port), as admin tools/ota_mesh_push.py /dev/serial/by-id/ pkg.mcfw --apply # over the node's own USB console tools/ota_push.py /dev/serial/by-id/ pkg.mcfw --apply ``` `ota_mesh_push.py` needs the `meshcore` Python library. It logs in as admin (password from `[secrets] admin_pw` of `platformio.local.ini`, or asked for), sends binary chunks with a pause between them, asks which are missing and resends only those, and keeps an airtime budget (`--duty`, default 1 % per hour: the 865-868 MHz band). A refused package costs the two manifest chunks, not the whole transfer. Check `get radio` on both ends first: this transmits. ## Your own builds A build with `-D FW_OTA=1` trusts `[ota] pubkey` of `platformio.ini` -- the release key. To sign your own packages, set your key in the gitignored `platformio.local.ini`: ```ini [ota] pubkey = ``` and pack with `tools/ota_pack.py pack|diff --key your.key`. Target and build epoch come from the ELF, never from the command line. Keep every image you flash: a delta needs the exact bytes the node runs as its base. Cost: about 10 kB of RAM on a repeater, the applier code in RAM, a 32 kB buffer while a full package is verified or applied. Classic images (without `-ota`) have none of it.