4.3 KiB
Firmware update over the mesh (OTA) — tth fork
Repeaters and room servers that run an -ota image of 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
-otaimages track MeshCoredevand 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.
How to
- Log in to the repeater as admin (Contacts → long-press → Manage).
- Repeater hub → Firmware update (OTA).
- 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'sSHA256SUMS. Choose .mcfw files is for your own builds (signed with your own key). - 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), 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.