Files
meshcore-open/documentation/ota-updates.md
T
tthandClaude Opus 5.5 8939cef7c1
build / ci-image (push) Successful in 13s
build / build (push) Successful in 11m0s
OTA docs: meshcore-tth and its -ota images are experimental, not for regular users
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 01:56:56 +01:00

4.3 KiB
Raw Blame History

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 -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.

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 <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.