From 233e6bb6d392af1c5100361a47d846d92c1ea055 Mon Sep 17 00:00:00 2001 From: TeTeHacko Date: Tue, 17 Nov 2026 00:18:35 +0100 Subject: [PATCH] Document the OTA firmware update (tth fork) documentation/ota-updates.md: how to, options, the side channel, what the node checks, and where the reference implementation lives. README: the fork's feature list and its fork-only files. Co-Authored-By: Claude Opus 5.5 --- README.md | 9 ++++- documentation/ota-updates.md | 70 ++++++++++++++++++++++++++++++++++++ 2 files changed, 78 insertions(+), 1 deletion(-) create mode 100644 documentation/ota-updates.md diff --git a/README.md b/README.md index 9b3d06ac..b6df6aaf 100644 --- a/README.md +++ b/README.md @@ -49,13 +49,20 @@ in this README describes upstream and still applies. The last line reads `cmp off` when the companion is disconnected and `app off` when the app is closed (on exit at once; if the system killed it, within about 15–45 minutes). Tap opens the app. +- **Firmware update over the mesh (OTA)** — repeater hub (admin) → + *Firmware update (OTA)*, for nodes on an `-ota` image of + [meshcore-tth](https://git.rfa.cz/tth-pub/meshcore-tth): the delta for the + node's image comes from the latest release by itself; optionally on a side + channel, off the shared mesh. See + [documentation/ota-updates.md](documentation/ota-updates.md). - **Fix:** `shared_preferences_android` pinned to 2.4.28 — 2.5.0 crashes on start under R8 (black screen). The fork-only code is kept in separate files where possible (`lib/tth_fork.dart`, `lib/theme/terminal_theme.dart`, `lib/widgets/terminal_message_line.dart`, -`lib/services/home_widget_bridge.dart`, `UnreadWidget.kt`) with one-line +`lib/services/home_widget_bridge.dart`, `UnreadWidget.kt`, +`lib/services/ota/`, `lib/screens/repeater_ota_screen.dart`) with one-line hooks into upstream files, so the nightly merge rarely conflicts. **Install with Obtainium** diff --git a/documentation/ota-updates.md b/documentation/ota-updates.md new file mode 100644 index 00000000..13da1026 --- /dev/null +++ b/documentation/ota-updates.md @@ -0,0 +1,70 @@ +# 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". + +## 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. **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 ,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 ,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).