ota_mesh_push.py: --side F,BW,SF,CR carries the transfer on a side channel

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
tthandClaude Opus 5.5 committed 2026-11-16 22:23:27 +01:00
1 parent a80e68186d
commit f6e792f1bb
2 files changed
+192

No files matched your search

+23
View File
@@ -101,6 +101,29 @@ tools/ota_mesh_push.py /dev/serial/by-id/<companion> <node pubkey prefix> pkg.mc
tools/ota_push.py /dev/serial/by-id/<node> pkg.mcfw --apply
```
### Off the shared channel: `--side`
tools/ota_mesh_push.py <companion> <node> 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 <side>,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 <its preset>,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
+169
View File
@@ -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,<min>` 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())))