OTA phase 5: tools and docs ready for the public export
pub-release / release (push) Successful in 32m57s
pub-release / release (push) Successful in 32m57s
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
97618f223f
commit
d22005a6fd
12 files changed
+704
-24
No files matched your search
+108
@@ -0,0 +1,108 @@
|
||||
# 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 `<board>_<role>-ota` / `-observer-ota` image:
|
||||
|
||||
| file | what |
|
||||
|---|---|
|
||||
| `<image>-<release>.zip` / `.uf2` | the image, flashed the usual way (first time) |
|
||||
| `<image>-<release>.mcfw` | full package: USB/BLE console only |
|
||||
| `<image>-<release>.from-<earlier>.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 <image> --base <sha8>` does both and picks the delta
|
||||
for the node's image (`--full` for the full package, `--release <tag>` 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 <bytes> [sid] start a transfer
|
||||
fw w <offset> <base64> 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 <sha8 from fw status>
|
||||
|
||||
# over the mesh, through a companion (USB port or tcp://host:port), as admin
|
||||
tools/ota_mesh_push.py /dev/serial/by-id/<companion> <node pubkey prefix> pkg.mcfw --apply
|
||||
|
||||
# over the node's own USB console
|
||||
tools/ota_push.py /dev/serial/by-id/<node> 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 = <tools/ota_pack.py pubkey --key your.key>
|
||||
```
|
||||
|
||||
and pack with `tools/ota_pack.py pack|diff <env> --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.
|
||||
Reference in new issue
Block a user