Files
tthandClaude Opus 5.5 3293254443
build / ci-image (push) Successful in 10s
build / build (push) Successful in 26m44s
OTA: a Check button tells whether the node is up to date, without sending anything
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>
2026-11-19 12:09:56 +01:00

82 lines
4.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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).