Login, `ver`, `fw status` (and `fw ver` for the release lookup), then the outcome: "up to date: the node already runs <tag>, no update needed" or "update available: <tag>, delta N B", with the node's version on top. It stops before `fw begin` and before the side channel, so no chunks go on air. OtaTransfer.checkOnly, OtaState.available; OtaResult carries the release tag and the `ver` reply. Refs #28 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
82 lines
4.5 KiB
Markdown
82 lines
4.5 KiB
Markdown
# Firmware update over the mesh (OTA) — tth fork
|
||
|
||
Repeaters and room servers that run an **`-ota` image of meshcore-tth**
|
||
([releases](https://git.rfa.cz/tth-pub/meshcore-tth/releases)) take a new
|
||
firmware from their admin over the mesh: the app sends a **delta** of a few kB
|
||
against the image the node runs, the node checks it and rewrites itself.
|
||
Classic MeshCore firmware has no such command; the tile is there, but the
|
||
update stops with "not an -ota build".
|
||
|
||
> **Experimental, not meant for regular users.** meshcore-tth is a personal
|
||
> development fork, and its `-ota` images track MeshCore `dev`
|
||
> and a new release comes roughly twice a day; there is no stable channel, no
|
||
> second bank and no automatic rollback. A bad image that still boots runs
|
||
> until you push the next one; one that does not boot needs USB/BLE DFU in
|
||
> hand. Update only nodes you can reach, and try each release on one of them
|
||
> first. Details: [docs/ota.md](https://git.rfa.cz/tth-pub/meshcore-tth/src/branch/main/docs/ota.md).
|
||
|
||
## How to
|
||
|
||
1. Log in to the repeater as **admin** (Contacts → long-press → Manage).
|
||
2. Repeater hub → **Firmware update (OTA)**.
|
||
3. Leave the packages empty: the app asks the node for its target and image
|
||
(`fw ver`, `fw status`) and takes the matching delta from the **latest
|
||
release** on git.rfa.cz, checked against the release's `SHA256SUMS`.
|
||
*Choose .mcfw files* is for your own builds (signed with your own key).
|
||
4. **Check** (optional) only finds out: it shows the node's `ver` and either
|
||
"up to date … no update needed" or "update available" with the delta
|
||
size. A login and three or four CLI replies on air, no chunks.
|
||
5. **Update**. Keep the app open until the log ends with `applied`; about
|
||
2–3 minutes on a direct link, a minute of it waiting for the reboot.
|
||
|
||
A second run against an updated node ends with "the node already runs …".
|
||
A node that skipped more releases than the latest one has deltas for gets
|
||
"no delta fits" — that one needs a full image over USB or BLE.
|
||
|
||
## Options
|
||
|
||
| option | default | what it does |
|
||
|---|---|---|
|
||
| Apply after verify | on | `fw apply`: the node rewrites itself and reboots. Off = the package stays staged on the node. |
|
||
| Airtime budget % / h | 3 | Token bucket of the channel time the transfer may use: request and reply, times hops + 1. 869.4–869.65 MHz allows 10 %, other sub-bands 1 %. |
|
||
| Pause per reply (s) | 5 | Gap after each answer, so the transfer does not hold a shared channel. |
|
||
| Side channel | off | See below. |
|
||
|
||
## Side channel
|
||
|
||
With **Side channel** on, the chunks go on another preset, off the shared
|
||
mesh. Login and `fw status` go over the mesh first; then the node gets
|
||
`tempradio <preset>,3`, the companion is retuned to the same preset, a fresh
|
||
login goes zero-hop and the delta follows. Both come back at the end: the node
|
||
by its reboot after `fw apply`, by `tempradio <its preset>,1`, or — if the
|
||
phone goes away — by its own timer when the window (renewed while the transfer
|
||
runs) ends. The companion gets its preset and the contact's path override
|
||
back.
|
||
|
||
- The companion must be in **direct range** of the node and must be a
|
||
**MeshCore companion firmware** that retunes its own radio. A virtual
|
||
companion (openHop) accepts the change but keeps its radio; the app reads the
|
||
radio back, stops, and the node returns within 3 minutes.
|
||
- Default preset `869.525,62.5,7,5`: inside 869.4–869.65 MHz (10 % duty),
|
||
between the CZ mesh (869.432) and EU Narrow (869.618). The node keeps its TX
|
||
power there — pick a band where that power is allowed.
|
||
- On a channel of its own the pause can be short (the switch sets 1 s).
|
||
|
||
## What the node checks itself
|
||
|
||
The package's Ed25519 signature (the release key built into the image), the
|
||
target (board and variant), the base image of a delta, and that it is newer —
|
||
right after the first chunks, before the rest goes on air. Then the whole
|
||
payload and a dry run of the delta must produce the signed image hash. A power
|
||
cut during the rewrite leaves the node in its bootloader, not in half an image.
|
||
|
||
## For developers
|
||
|
||
`lib/services/ota/` is a Dart port of the OTA engine of the tth.meshcore
|
||
Ansible collection (`plugins/module_utils/meshcore_ota_engine.py` in
|
||
[meshcore-ansible](https://git.rfa.cz/tth-pub/meshcore-ansible)), which is
|
||
the reference — change the protocol there first. `test/services/ota/ota_vectors.json`
|
||
is a copy of the collection's `tests/vectors/ota_vectors.json`; copy it over
|
||
when it changes. Firmware side and the full protocol:
|
||
[docs/ota.md](https://git.rfa.cz/tth-pub/meshcore-tth/src/branch/main/docs/ota.md).
|