From f6e792f1bb34881a027c1cb3d48fc1a08e968eeb Mon Sep 17 00:00:00 2001 From: TeTeHacko Date: Mon, 16 Nov 2026 22:23:27 +0100 Subject: [PATCH] ota_mesh_push.py: --side F,BW,SF,CR carries the transfer on a side channel Co-Authored-By: Claude Opus 5.5 --- docs/ota.md | 23 ++++++ tools/ota_mesh_push.py | 169 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 192 insertions(+) diff --git a/docs/ota.md b/docs/ota.md index ddd9a98f..f97fa8a9 100644 --- a/docs/ota.md +++ b/docs/ota.md @@ -101,6 +101,29 @@ tools/ota_mesh_push.py /dev/serial/by-id/ pkg.mc tools/ota_push.py /dev/serial/by-id/ pkg.mcfw --apply ``` +### Off the shared channel: `--side` + + tools/ota_mesh_push.py pkg.mcfw --apply \ + --side 869.525,62.5,7,5 --duty 10 --gap 1 + +Login, `fw status` and `get radio` still go over the mesh; then the node gets +`tempradio ,3`, the companion retunes to the same preset, logs in again +zero-hop, and the chunks go there. The window grows to `--window` (15 min) once +the link is proven and is renewed while the transfer runs. The node comes back +by itself when the window runs out, on `fw apply` (the reboot), or when the +tool sends it back with `tempradio ,1`. Nothing new in the firmware: +any node with `tempradio` takes it. + +- The companion must be in **direct** range of the node, and it must be a + companion **firmware** that retunes its own radio. An openHop virtual + companion answers `set_radio` with OK and stays put; the tool checks that + and stops, and the node returns within 3 minutes. +- The companion's preset is put back at the end -- unless the tool is killed + hard; then `set_radio` it back yourself. +- The example preset sits inside 869.4-869.65 MHz (10 % duty) between the CZ + mesh (869.432/62.5) and EU Narrow (869.618/62.5). The node keeps its TX + power on the side channel: pick a band where that power is allowed. + `ota_mesh_push.py` needs the `meshcore` Python library. It logs in as admin (password from `[secrets] admin_pw` of `platformio.local.ini`, or asked for), sends binary chunks with a pause between them, asks which are missing and diff --git a/tools/ota_mesh_push.py b/tools/ota_mesh_push.py index 614dfa47..41a47833 100755 --- a/tools/ota_mesh_push.py +++ b/tools/ota_mesh_push.py @@ -39,6 +39,26 @@ --wait S how long to wait for the dest's advert if the companion does not know it yet (default 120 s); send `advert.zerohop` on the dest meanwhile + --side F,BW,SF,CR + carry the transfer on a SIDE CHANNEL, off the shared mesh: + login, `fw status` and `get radio` go over the mesh, then the + node gets `tempradio F,BW,SF,CR,` and the companion is + retuned to the same preset; the chunks go there, ZERO-HOP -- + the companion must be in direct range of the node. E.g. + 869.525,62.5,7,5: inside 869.4-869.65 (10 % duty), between + the CZ mesh (869.432/62.5) and EU Narrow (869.618/62.5). + The node returns to its own preset by itself when the window + runs out (first 3 min, then --window, renewed while the + transfer runs), at `fw apply` (reboot), or when we are done. + The companion must be one that retunes its radio: a MeshCore + companion firmware, not an openHop virtual companion (that + acks set_radio and stays put -- checked, and refused). Its + own preset is put back at the end; killed hard (-9), it stays + on the side channel: put it back with set_radio. --duty and + --gap still apply: on a side channel of its own the transfer + can take e.g. --duty 10 --gap 1. + --window M side channel window in minutes (default 15), renewed while + the transfer runs The same `fw` commands as tools/ota_push.py (USB), carried as remote admin CLI. Every `fw w` is idempotent on the node, so a lost reply is simply resent; the @@ -54,6 +74,7 @@ import argparse import asyncio import base64 import configparser +import functools import math import random import re @@ -104,6 +125,7 @@ def w_payload(sid: int, off: int, chunk: bytes) -> bytes: ) +@functools.cache # asked once: the side channel and --apply log in again def admin_pw() -> str: """[secrets] admin_pw of platformio.local.ini, else asked on the terminal (never an argument: it would show in the process list and the history).""" @@ -225,6 +247,19 @@ class Link: ) self.prefix = contact["public_key"][:12] self.retries = 0 + # (preset, window min, monotonic deadline) while the node is on a side + # channel: renewed before the node's own timer would take it back + self.side: tuple[str, int, float] | None = None + + async def keep_side(self) -> None: + if self.side is None or time.monotonic() < self.side[2] - SIDE_MARGIN: + return + preset, win, _ = self.side + self.side = (preset, win, time.monotonic() + win * 60) # before cmd(): no recursion + r = await self.cmd(f"tempradio {preset},{win}") + if not r.startswith("OK"): + raise RuntimeError(f"tempradio renewal: {r}") + await asyncio.sleep(3) # the node re-applies the preset 2 s after its reply def cost(self, text: str) -> float: hops = max(hops_of(self.c), 0) @@ -234,6 +269,7 @@ class Link: return one * (hops + 1) async def cmd(self, text: str, timeout: float = 20.0, tries: int = 4) -> str: + await self.keep_side() for attempt in range(tries): await self.bucket.spend(self.cost(text)) await self.mc.commands.send_cmd(self.c, text) @@ -287,6 +323,7 @@ class Binary: return tag.hex() if isinstance(tag, bytes | bytearray) else str(tag) async def write(self, off: int, chunk: bytes) -> None: + await self.link.keep_side() payload = w_payload(self.sid, off, chunk) c = self.cost(len(payload)) await self.link.bucket.spend(c) @@ -297,6 +334,7 @@ class Binary: async def missing(self, timeout: float = 20.0) -> tuple[int, list[int]] | None: """(state, missing unit indices) or None when the node does not answer.""" for _ in range(2): + await self.link.keep_side() await self.link.bucket.spend(self.cost(2, 160)) fut: asyncio.Future = asyncio.get_running_loop().create_future() @@ -326,6 +364,121 @@ class Binary: return None +SIDE_FIRST = 3 # min: the node's first side window, until the link there is proven +SIDE_MARGIN = 150 # s before the window ends: renew (a text cmd retries up to 80 s) + + +def parse_preset(s: str) -> tuple[float, float, int, int]: + """freq MHz, bw kHz, sf, cr (5..8) -- the ranges tempradio takes.""" + try: + f, bw, sf, cr = s.split(",") + p = (float(f), float(bw), int(sf), int(cr)) + except ValueError: + sys.exit(f"--side {s!r}: freq,bw,sf,cr (e.g. 869.525,62.5,7,5)") + if not (150 <= p[0] <= 2500 and 7 <= p[1] <= 500 and 5 <= p[2] <= 12 and 5 <= p[3] <= 8): + sys.exit(f"--side {s!r}: out of range (freq MHz, bw kHz, sf 5-12, cr 5-8)") + return p + + +def fmt_preset(p: tuple) -> str: + return f"{p[0]:g},{p[1]:g},{p[2]},{p[3]}" + + +def same_preset(si: dict, p: tuple) -> bool: + return ( + abs(float(si["radio_freq"]) - p[0]) < 0.001 + and abs(float(si["radio_bw"]) - p[1]) < 0.01 + and int(si["radio_sf"]) == p[2] + and int(si["radio_cr"]) == p[3] + ) + + +class Side: + """The node and the companion on a side channel, and the way back.""" + + def __init__(self, mc: MeshCore, link: "Link", preset: tuple, window: int): + self.mc, self.link, self.preset, self.window = mc, link, preset, window + self.node_main = "" # the node's own preset (`get radio`) + self.comp_main: tuple | None = None # the companion's, set once it moved + self.comp_repeat: bool | None = None + c = link.c # its mesh path, put back at the end + self.path = c["out_path"], int(c["out_path_len"]), int(c.get("out_path_hash_mode", 0)) + self.node_on_side = False + + async def enter(self) -> dict: + r = await self.link.cmd("get radio") + m = re.fullmatch(r">\s*([\d.]+),([\d.]+),(\d+),(\d+)", r) + if not m: + sys.exit(f"get radio: {r!r}") + self.node_main = ",".join(m.groups()) + side = fmt_preset(self.preset) + print(f"node preset {self.node_main}, side channel {side}") + r = await self.link.cmd(f"tempradio {side},{SIDE_FIRST}") + print("tempradio:", r) + if not r.startswith("OK"): + sys.exit(1) + self.node_on_side = True + self.link.side = (side, SIDE_FIRST, time.monotonic() + SIDE_FIRST * 60) + await asyncio.sleep(3) # the node switches 2 s after its reply + + si = self.mc.self_info + self.comp_main = ( + float(si["radio_freq"]), float(si["radio_bw"]), int(si["radio_sf"]), int(si["radio_cr"]) + ) + di = await self.mc.commands.send_device_query() + self.comp_repeat = di.payload.get("repeat") if di.type == EventType.DEVICE_INFO else None + rep = None if self.comp_repeat is None else 0 # no client repeat on the side channel + await self.mc.commands.set_radio(*self.preset, repeat=rep) + ev = await self.mc.commands.send_appstart() + if ev.type != EventType.SELF_INFO or not same_preset(ev.payload, self.preset): + self.comp_main = None # nothing moved, and the node is out of reach + sys.exit( + "the companion did not retune (an openHop virtual companion acks set_radio " + "and keeps the host's radio): it needs a MeshCore companion firmware. " + f"The node returns to its preset within {SIDE_FIRST} min." + ) + print(f"companion on {side}") + + # Zero-hop from here: the mesh path means nothing on the side channel, + # and the node answers along the path of the last login -- log in again. + await self.mc.commands.reset_path(self.link.c) + r = await login(self.mc, self.link.c) + if r != "LOGIN_SUCCESS": + sys.exit(f"login on the side channel: {r} (out of direct range?)") + await self.mc.ensure_contacts(follow=True) + contact = await find_contact(self.mc, self.link.prefix, 5) + print(f"login on the side channel: ok, {hops_of(contact)} hops") + self.link.c = contact + self.link.radio = (self.preset[2], self.preset[1], self.preset[3] - 4) + self.link.side = (side, self.window, 0.0) # renew to the full window now + await self.link.keep_side() + return contact + + async def leave(self) -> None: + """Back: the node (unless `fw apply` rebooted it), the companion, the path.""" + if self.node_on_side and self.comp_main is not None: + self.link.side = None + try: + # tempradio with its own preset: back in 2 s, on any firmware + print("node back:", await self.link.cmd(f"tempradio {self.node_main},1", tries=2)) + except (TimeoutError, RuntimeError): + print("node does not answer: it returns by itself when its window runs out") + self.node_on_side = False + self.link.side = None + if self.comp_main is not None: + rep = None if self.comp_repeat is None else int(self.comp_repeat) + await self.mc.commands.set_radio(*self.comp_main, repeat=rep) + ev = await self.mc.commands.send_appstart() + ok = ev.type == EventType.SELF_INFO and same_preset(ev.payload, self.comp_main) + print(f"companion back on {fmt_preset(self.comp_main)}: {'ok' if ok else 'CHECK IT'}") + self.comp_main = None + out_path, out_len, mode = self.path + if out_len < 0: + await self.mc.commands.reset_path(self.link.c) + else: + await self.mc.commands.update_contact(self.link.c, path=out_path, path_hash_mode=mode) + + async def login(mc: MeshCore, contact: dict) -> str: """Admin login; returns the event type name.""" fut: asyncio.Future = asyncio.get_running_loop().create_future() @@ -395,6 +548,7 @@ async def run(args: argparse.Namespace) -> int: mc = await MeshCore.create_serial(args.companion) if mc is None: sys.exit("companion does not answer") + side: Side | None = None try: si = mc.self_info cr = int(si["radio_cr"]) - 4 @@ -432,6 +586,9 @@ async def run(args: argparse.Namespace) -> int: print("status:", status) if data is None: data = check_delta(pick_package(args.package, status, full_ok=False), args.package) + if args.side: + side = Side(mc, link, parse_preset(args.side), args.window) + contact = await side.enter() if args.resume: # `fw begin` would wipe what the node has; text chunks need no session r = await link.cmd("fw missing") @@ -574,6 +731,14 @@ async def run(args: argparse.Namespace) -> int: print("apply:", r) if not r.startswith("OK"): return 1 + if side: + # the reboot takes the node back to its own preset: follow it + side.node_on_side = False + await side.leave() + await mc.ensure_contacts(follow=True) + contact = link.c = await find_contact(mc, args.dest.lower(), 5) + link.radio = radio + side = None print("waiting 60 s for the node to rewrite itself and boot ...") await asyncio.sleep(60) print("login after apply:", await login(mc, contact)) @@ -585,6 +750,8 @@ async def run(args: argparse.Namespace) -> int: ) return 0 finally: + if side: + await side.leave() await mc.disconnect() @@ -602,6 +769,8 @@ def main() -> None: ap.add_argument("--via") ap.add_argument("--text", action="store_true") ap.add_argument("--resume", action="store_true") + ap.add_argument("--side") + ap.add_argument("--window", type=int, default=15) sys.exit(asyncio.run(run(ap.parse_args())))