diff --git a/docs/ota.md b/docs/ota.md index f97fa8a9..a88152be 100644 --- a/docs/ota.md +++ b/docs/ota.md @@ -124,6 +124,15 @@ any node with `tempradio` takes it. 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. +The transfer in both tools is the OTA engine of the +[tth.meshcore Ansible collection](https://git.rfa.cz/tth-pub/meshcore-ansible) +(`plugins/module_utils/meshcore_ota_engine.py`) -- its `meshcore_fw_ota` module +runs the same code, so a fix lands everywhere at once. The tools need only its +files, not Ansible: an installed collection +(`ansible-galaxy collection install git+https://git.rfa.cz/tth-pub/meshcore-ansible.git`), +a checkout named by `MESHCORE_ANSIBLE`, or one next to this repository +(`tools/ota_collection.py` prints which one it uses). + `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/README.md b/tools/README.md index f2fee636..9c00bbaf 100644 --- a/tools/README.md +++ b/tools/README.md @@ -49,7 +49,8 @@ a different board. |---|---| | `ota_pack.py` | `fetch` a signed package of a release and check it; `info`; build and sign your own (`pack`, `diff`) | | `ota_push.py` | push a package over the USB console (text, or the mesh protocol via `fw bin`) | -| `ota_mesh_push.py` | push a delta over the mesh through a companion, as admin | +| `ota_mesh_push.py` | push a delta over the mesh through a companion, as admin (`--side`: on a side channel via `tempradio`) | +| `ota_collection.py` | finds the OTA engine both push tools run: the tth.meshcore Ansible collection's module_utils | | `ota_ramlib.py` | PlatformIO script: runs the delta applier from RAM (a build dependency) | | `ota_check_ramfunc.sh` | checks that an `-ota` build's RAM code never calls into flash | | `ota_allowed_signers` | the release signer (`ssh-keygen -Y verify`) | diff --git a/tools/ota_collection.py b/tools/ota_collection.py new file mode 100755 index 00000000..0b690440 --- /dev/null +++ b/tools/ota_collection.py @@ -0,0 +1,79 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Find the OTA engine: the tth.meshcore Ansible collection's module_utils. + + tools/ota_collection.py # where it is found (or how to get it) + +The transfer of an OTA package (src/helpers/FwUpdate) is implemented ONCE, in +module_utils/meshcore_ota_engine.py of https://git.rfa.cz/tth-pub/meshcore-ansible +-- the Ansible module and these tools wrap the same code. Its module_utils do not +import Ansible, so the tools need only the files: + + 1. $MESHCORE_ANSIBLE: a checkout of meshcore-ansible + 2. an installed collection (ansible-galaxy collection install + git+https://git.rfa.cz/tth-pub/meshcore-ansible.git), found on sys.path, + in ~/.ansible/collections or /usr/share/ansible/collections + 3. a checkout next to this repo: ../meshcore-ansible +""" + +import os +import sys +import types +from pathlib import Path + +if __name__ == "__main__" and any(a in ("-h", "--help") for a in sys.argv[1:]): + print(__doc__) + sys.exit(0) + +PKG = "ansible_collections.tth.meshcore.plugins.module_utils" +REPO = Path(__file__).resolve().parent.parent + + +def _mount(checkout: Path) -> None: + """Make a plain checkout importable under its collection name.""" + parts = PKG.split(".") + for i in range(1, len(parts) + 1): + name = ".".join(parts[:i]) + mod = sys.modules.get(name) + if mod is None: + mod = types.ModuleType(name) + mod.__path__ = [] + sys.modules[name] = mod + sys.modules[PKG].__path__ = [str(checkout / "plugins" / "module_utils")] + + +def _has(checkout: Path) -> bool: + return (checkout / "plugins" / "module_utils" / "meshcore_ota_engine.py").is_file() + + +def locate() -> str: + """Make the engine importable; returns where it came from, exits with a hint if nowhere.""" + env = os.environ.get("MESHCORE_ANSIBLE") + if env: + if not _has(Path(env)): + sys.exit(f"MESHCORE_ANSIBLE={env}: no plugins/module_utils/meshcore_ota_engine.py there") + _mount(Path(env)) + return env + roots = [Path(p) for p in sys.path if p] + [ + Path.home() / ".ansible" / "collections", + Path("/usr/share/ansible/collections"), + ] + for root in roots: + c = root / "ansible_collections" / "tth" / "meshcore" + if _has(c): + if str(root) not in sys.path: + sys.path.append(str(root)) + return str(c) + sibling = REPO.parent / "meshcore-ansible" + if _has(sibling): + _mount(sibling) + return str(sibling) + sys.exit( + "the OTA engine (tth.meshcore collection) is not here: " + "ansible-galaxy collection install git+https://git.rfa.cz/tth-pub/meshcore-ansible.git, " + "or MESHCORE_ANSIBLE= (tools/ota_collection.py --help)" + ) + + +if __name__ == "__main__": + print(locate()) diff --git a/tools/ota_mesh_push.py b/tools/ota_mesh_push.py index 41a47833..33babde0 100755 --- a/tools/ota_mesh_push.py +++ b/tools/ota_mesh_push.py @@ -7,10 +7,10 @@ how to reach the companion that talks for us: tcp://127.0.0.1:7003 (serial_tcp_proxy.py + ssh -L) or a serial port path - the target node's public key prefix (>= 8 hex), as in its - `get public.key` - a DELTA package only (ota_pack.py diff / fetch --base): a - full image is refused here and by the node itself. Or a + the target node's public key, or a prefix (>= 8 hex) of a + contact the companion knows, as in its `get public.key` + a DELTA package (ota_pack.py diff / fetch --base): a full + image does not go over the mesh, the node refuses it too. Or a directory with one release's packages: the delta from the image `fw status` reports is taken; exit 3 = none fits --apply after a good `fw verify`, `fw apply` and wait for the node to @@ -24,10 +24,6 @@ --gap S pause after every reply before the next command (default 5). Without it a small delta goes out as fast as the round trip (~2 s per chunk at SF8) and holds the channel for that time. - --via HEX force a direct path through these repeater hashes (2 bytes - each, e.g. c327 or c327a1b2) -- also the login goes along - it, so the node answers back the same way. For testing - multi-hop on the bench. --text send chunks as text CLI (`fw w `, 96 B, each answered) instead of the default binary requests (128 B, unanswered, missing ones found by a bitmap query). Falls @@ -36,9 +32,9 @@ --resume continue a transfer that stopped (the node keeps what it got until the next `fw begin` or a reboot): no begin, only the chunks `fw missing` lists, as text, then verify (and --apply) - --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 + --wait S how long to wait for the dest's advert when only a prefix is + given and 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 @@ -60,10 +56,9 @@ --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 -node checks the manifest as soon as its chunks arrive and answers ERR for a -wrong board or base -- that stops the transfer. +The transfer itself is the tth.meshcore Ansible collection's OTA engine +(module_utils/meshcore_ota_engine.py) -- the meshcore_fw_ota module runs the +very same code. tools/ota_collection.py says where it is looked for. The admin password comes from platformio.local.ini ([secrets] admin_pw), is asked for on the terminal, or read from stdin when that is no terminal; it is @@ -72,60 +67,40 @@ never printed. CHECK `get radio` on both ends first: this transmits. import argparse import asyncio -import base64 import configparser -import functools -import math -import random -import re +import importlib import sys import time from pathlib import Path -if __name__ == "__main__" and ( - any(a in ("-h", "--help") for a in sys.argv[1:]) or len(sys.argv) == 1 -): +if __name__ == "__main__" and (any(a in ("-h", "--help") for a in sys.argv[1:]) or len(sys.argv) == 1): print(__doc__) sys.exit(0) -from meshcore import EventType, MeshCore +sys.path.insert(0, str(Path(__file__).resolve().parent)) +from ota_collection import PKG, locate + +locate() +engine = importlib.import_module(f"{PKG}.meshcore_ota_engine") +ota = importlib.import_module(f"{PKG}.meshcore_ota") +link = importlib.import_module(f"{PKG}.meshcore_link") -CHUNK = 96 # FW_OTA_CHUNK (text) -BCHUNK = 128 # FW_OTA_BCHUNK (binary) -# The companion takes host frames of at most MAX_FRAME_SIZE 176 B, and a binary -# request frame is 1 (cmd) + 32 (pubkey) + payload. 160 B chunks made 199 B -# frames that the companion dropped -- every one of them (13. 11. 2026). -MAX_FRAME = 176 -UNIT = 32 # FW_OTA_UNIT -MANIFEST = 256 # FW_OTA_MANIFEST_SIZE -REQ_FW = 0xF0 # REQ_TYPE_FW_OTA INI = Path(__file__).resolve().parent.parent / "platformio.local.ini" +NO_PACKAGE = 3 # exit code: no package starts from the node's image -def crc16(data: bytes, crc: int = 0xFFFF) -> int: - """Nordic crc16_compute (CCITT, init 0xFFFF) -- FwUpdate.cpp crc16_update.""" - for b in data: - crc = ((crc >> 8) | (crc << 8)) & 0xFFFF - crc ^= b - crc ^= (crc & 0xFF) >> 4 - crc ^= (crc << 12) & 0xFFFF - crc ^= ((crc & 0xFF) << 5) & 0xFFFF - return crc +class EchoLog(list): + """The engine's trace, printed as it grows.""" + + def __init__(self): + super().__init__() + self.t0 = time.time() + + def append(self, line): + print(f"[{time.time() - self.t0:5.0f} s] {line}", flush=True) + super().append(line) -def w_payload(sid: int, off: int, chunk: bytes) -> bytes: - """REQ_TYPE_FW_OTA 'w': [F0]['w'][sid u16][off u32][len u8][crc16][data].""" - head = sid.to_bytes(2, "little") + off.to_bytes(4, "little") + bytes([len(chunk)]) - # the crc binds the data to this session and offset (FwUpdate::handleBinary) - return ( - bytes([0xF0, ord("w")]) - + head - + crc16(chunk, crc16(head)).to_bytes(2, "little") - + chunk - ) - - -@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).""" @@ -137,628 +112,73 @@ def admin_pw() -> str: pw = getpass.getpass("admin password of the node: ").strip() elif not pw: - pw = sys.stdin.readline().strip() # piped in (the firmware role) + pw = sys.stdin.readline().strip() # piped in if not pw: sys.exit(f"no admin password: [secrets] admin_pw in {INI}, a terminal, or stdin") return pw -NO_PACKAGE = 3 # exit code: no package starts from the node's image +def transport_of(companion: str) -> dict: + if companion.startswith("tcp://"): + host, port = companion[6:].rsplit(":", 1) + return {"type": "tcp", "host": host, "port": int(port)} + return {"type": "serial", "port": companion} -def pick_package(where: str, status: str, full_ok: bool) -> bytes: - """`package` may be a directory with one release's packages (the full image - and its deltas, as the firmware role fetches them): take the delta that - starts from the image `fw status` reports, else -- where a full image may - go -- the full one. Exits NO_PACKAGE when nothing fits: the node runs an - image no delta starts from, or has no `fw` at all (not an -ota build).""" - p = Path(where) - if not p.is_dir(): - return p.read_bytes() - m = re.search(r"\bbase \d+ ([0-9a-f]{8})", status) - if not m: - print(f"no base image in `fw status`: {status!r}") - sys.exit(NO_PACKAGE) - base = m.group(1) - full = None - for f in sorted(p.glob("*.mcfw")): - data = f.read_bytes() - if data[:4] != b"MCFW": - continue - if data[16:48].hex().startswith(base): # raw_sha256 = the image it installs - print(f"the node already runs the image of {f.name}") - sys.exit(0) - if data[4] == 2 and data[160:192].hex().startswith(base): - print(f"package: {f.name} (delta from {base})") - return data - if data[4] == 1: - full = (f, data) - if full and full_ok: - print(f"package: {full[0].name} (full image, no delta from {base})") - return full[1] - print(f"no package in {where} starts from {base}") - sys.exit(NO_PACKAGE) +async def full_key(transport: dict, prefix: str, wait: float) -> str: + """The node's full pubkey from a prefix, among the companion's contacts + (waiting for its advert). The engine addresses the node by the full key.""" + from meshcore import EventType, MeshCore - -def lora_airtime(n: int, sf: int, bw_khz: float, cr: int, preamble: int = 16) -> float: - """Seconds on air for an n-byte LoRa frame (explicit header, CRC on).""" - tsym = (2**sf) / (bw_khz * 1000) - de = 1 if tsym > 0.016 else 0 - # Semtech AN1200.13: ceil(...) * (CR + 4), CR = 1..4 for 4/5..4/8. Until - # 14. 11. 2026 this multiplied by CR alone: ~3x too little airtime at 4/5, - # so --duty 3 let about 9 % through. - payload = 8 + max( - math.ceil((8 * n - 4 * sf + 28 + 16) / (4 * (sf - 2 * de))) * (cr + 4), 0 - ) - return (preamble + 4.25) * tsym + payload * tsym - - -def frame_len(text: str) -> int: - """MeshCore direct text frame: header+path_len, dest/src hash, MAC, and - timestamp+flags+text padded to the AES block.""" - body = 5 + len(text.encode()) - return 2 + 2 + 2 + 16 * math.ceil(body / 16) - - -class Bucket: - def __init__(self, duty: float): - self.rate = duty / 100.0 - self.cap = self.rate * 3600 - self.level = self.cap - self.t = time.monotonic() - self.used = 0.0 - - async def spend(self, secs: float) -> None: - while True: - now = time.monotonic() - self.level = min(self.cap, self.level + (now - self.t) * self.rate) - self.t = now - if self.level >= secs: - self.level -= secs - self.used += secs - return - await asyncio.sleep((secs - self.level) / self.rate) - - -REPLY_TEXT = 40 # typical reply ("ok", status lines are longer but rare) - - -def hops_of(contact: dict) -> int: - """out_path_len: low 6 bits = hops, top 2 = hash size - 1; -1 = flood.""" - v = int(contact.get("out_path_len", -1)) - return -1 if v < 0 else v & 0x3F - - -class Link: - def __init__( - self, - mc: MeshCore, - contact: dict, - bucket: Bucket, - radio: tuple, - gap: float = 0.0, - ): - self.mc, self.c, self.bucket, self.radio, self.gap = ( - mc, - contact, - bucket, - radio, - gap, - ) - 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) - one = lora_airtime(frame_len(text), *self.radio) + lora_airtime( - frame_len("x" * REPLY_TEXT), *self.radio - ) - 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) - ev = await self.mc.wait_for_event( - EventType.CONTACT_MSG_RECV, - attribute_filters={"pubkey_prefix": self.prefix}, - timeout=timeout, - ) - if ev is not None: - if self.gap: - await asyncio.sleep(self.gap) - return str(ev.payload.get("text", "")).strip() - self.retries += 1 - print( - f" ({text[:12]}...: no reply, try {attempt + 2}/{tries})", flush=True - ) - raise TimeoutError(f"no reply to {text[:30]!r}") - - -def req_frame_len(payload_len: int) -> int: - """Direct REQ: header+path_len, dest/src hash, MAC, timestamp+payload padded.""" - return 2 + 2 + 2 + 16 * math.ceil((4 + payload_len) / 16) - - -class Binary: - """Firmware chunks as binary requests (REQ_TYPE_FW_OTA).""" - - def __init__(self, link: "Link"): - self.link = link - self.pub = bytes.fromhex(link.c["public_key"]) - self.sid = 0 - - def cost(self, payload_len: int, reply_len: int = 0) -> float: - hops = max(hops_of(self.link.c), 0) - t = lora_airtime(req_frame_len(payload_len), *self.link.radio) - if reply_len: - t += lora_airtime(req_frame_len(reply_len), *self.link.radio) - return t * (hops + 1) - - async def send(self, payload: bytes) -> str | None: - if 1 + 32 + len(payload) > MAX_FRAME: - raise ValueError( - f"binary request of {len(payload)} B exceeds the companion frame" - ) - ev = await self.link.mc.commands.send( - b"\x32" + self.pub + payload, [EventType.MSG_SENT, EventType.ERROR] - ) - if ev.type != EventType.MSG_SENT: - return None - tag = ev.payload.get("expected_ack") - 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) - await self.send(payload) - # no reply comes: give the packet time to go out along the whole path - await asyncio.sleep(max(self.link.gap, c + 1.0)) - - 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() - - def got(ev, fut=fut): - if not fut.done(): - fut.set_result(ev) - - sub = self.link.mc.subscribe(EventType.BINARY_RESPONSE, got) - try: - tag = await self.send(bytes([REQ_FW, ord("m")])) - ev = await asyncio.wait_for(fut, timeout) - except TimeoutError: - ev = None - finally: - self.link.mc.unsubscribe(sub) - if ev is None or (tag and ev.payload.get("tag") != tag): - continue - d = bytes.fromhex(ev.payload["data"]) - if len(d) < 5: - continue - cnt = int.from_bytes(d[3:5], "little") - miss = [ - int.from_bytes(d[5 + 2 * i : 7 + 2 * i], "little") for i in range(cnt) - ] - await asyncio.sleep(self.link.gap) - return d[0], miss - 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() - - def done(ev): - if not fut.done(): - fut.set_result(ev.type.name) - - subs = [ - mc.subscribe(t, done) for t in (EventType.LOGIN_SUCCESS, EventType.LOGIN_FAILED) - ] - try: - await mc.commands.send_login(contact, admin_pw()) - return await asyncio.wait_for(fut, 30) - except TimeoutError: - return "timeout" - finally: - for sub in subs: - mc.unsubscribe(sub) - - -async def find_contact(mc: MeshCore, prefix: str, wait: float) -> dict: + if transport["type"] == "tcp": + mc = await MeshCore.create_tcp(transport["host"], transport["port"], auto_reconnect=False) + else: + mc = await MeshCore.create_serial(transport["port"]) + if mc is None: + sys.exit("companion does not answer") added: list[dict] = [] - - async def on_new(ev): - added.append(ev.payload) - - sub = mc.subscribe(EventType.NEW_CONTACT, on_new) + sub = mc.subscribe(EventType.NEW_CONTACT, lambda ev: added.append(ev.payload)) t0 = time.time() try: while True: await mc.ensure_contacts(follow=True) - for c in mc.contacts.values(): - if c["public_key"].lower().startswith(prefix): - return c - for p in added: - if p.get("public_key", "").lower().startswith(prefix): - await mc.commands.add_contact(p) + for c in list(mc.contacts.values()) + added: + if c.get("public_key", "").lower().startswith(prefix): + if c in added: + await mc.commands.add_contact(c) + return c["public_key"].lower() if time.time() - t0 > wait: - sys.exit( - f"{prefix}: not among the companion's contacts after {wait:.0f} s (advert.zerohop on the node?)" - ) + sys.exit(f"{prefix}: not among the companion's contacts after {wait:.0f} s (advert.zerohop on the node?)") await asyncio.sleep(3) finally: mc.unsubscribe(sub) - - -def check_delta(data: bytes, name: str) -> bytes: - # Only deltas go over the mesh -- the node refuses anything else too - # (FwUpdate: `fw begin` over 64 kB, a format 1 manifest). A full image is - # ~300 kB, hours of a shared channel: USB (ota_push.py) or the BLE console. - if data[:4] != b"MCFW" or data[4] != 2: - sys.exit( - f"{name}: not a delta package (format {data[4] if len(data) > 4 else '?'}) -- " - "over the mesh only deltas; a full image goes over USB (tools/ota_push.py) or BLE" - ) - return data - - -async def run(args: argparse.Namespace) -> int: - pkg = Path(args.package) - data = None if pkg.is_dir() else check_delta(pkg.read_bytes(), args.package) - if args.companion.startswith("tcp://"): - host, port = args.companion[6:].rsplit(":", 1) - mc = await MeshCore.create_tcp(host, int(port)) - else: - 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 - radio = (int(si["radio_sf"]), float(si["radio_bw"]), cr) - print( - f"companion {si['name']}: {si['radio_freq']} MHz, SF{radio[0]}, BW{radio[1]}, CR4/{si['radio_cr']}" - ) - await mc.start_auto_message_fetching() - contact = await find_contact(mc, args.dest.lower(), args.wait) - if args.via: - path = bytes.fromhex(args.via) - if len(path) % 2: - sys.exit("--via: whole 2-byte hashes") - await mc.commands.update_contact(contact, path=path.hex(), path_hash_mode=1) - contact = await find_contact(mc, args.dest.lower(), 5) - print( - f"dest {contact['adv_name']} {contact['public_key'][:8]}, out_path_len {contact.get('out_path_len')}" - ) - - bucket = Bucket(args.duty) - await bucket.spend(lora_airtime(48, *radio)) - r = await login(mc, contact) - if r != "LOGIN_SUCCESS": - sys.exit(f"login: {r}") - print("login: ok (admin)") - await mc.ensure_contacts(follow=True) # login may have taught it a path - contact = await find_contact(mc, args.dest.lower(), 5) - print( - f"path: {hops_of(contact)} hops (out_path_len {contact.get('out_path_len')})" - ) - link = Link(mc, contact, bucket, radio, args.gap) - t0 = time.time() - - status = await link.cmd("fw status") - 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") - print("missing:", r) - if not r.startswith(">"): - return 1 - sid = 0 - else: - sid = random.randint(1, 0xFFFF) # chunks of an earlier transfer are dropped - r = await link.cmd(f"fw begin {len(data)} {sid}") - print("begin:", r) - if not r.startswith("OK"): - return 1 - binary = None if (args.text or args.resume) else Binary(link) - if binary: - binary.sid = sid - text_todo: list[int] | None = None - if binary: - st = await binary.missing() - if st is None: - print("node does not answer binary requests: text chunks") - binary = None - if binary: - nb = (len(data) + BCHUNK - 1) // BCHUNK - todo = list(range(nb)) - last_miss = 1 << 30 - - async def settled(): - lost = 0 - for _ in range(10): - st = await binary.missing() - if st is None and lost < 4: - # a lost query or reply after a 40-minute round must not - # throw the round away (14. 11. 2026, mast-three: it did) - lost += 1 - await asyncio.sleep(10) - continue - if st is None or st[0] != 4: # 4 = busy (manifest check) - return st - await asyncio.sleep(3) - return st - - manifest_checked = False - for rnd in range(6): - for k, i in enumerate(todo): - off = i * BCHUNK - await binary.write(off, data[off : off + BCHUNK]) - print( - f"\r{k + 1}/{len(todo)} binary chunks (round {rnd + 1}), {time.time() - t0:.0f} s, " - f"airtime {bucket.used:.1f} s", - end="", - flush=True, - ) - if not manifest_checked and off + BCHUNK >= MANIFEST and k + 1 < len(todo): - # The node checks the manifest as soon as it is in (signature, - # target, base, NOT OLDER): ask before the rest goes on air -- - # a refused package otherwise costs the whole first round. - manifest_checked = True - st = await settled() - if st is not None and st[0] == 3: - print("\nnode:", await link.cmd("fw status")) - print(f"stopped after the manifest, airtime {bucket.used:.1f} s") - return 1 - print() - st = await settled() - if st is None: - print("missing: no answer (the node keeps what it has: --resume)") - return 1 - state, miss = st - print(f"missing: state {state}, {len(miss)} units") - if state == 3: - print("node:", await link.cmd("fw status")) - return 1 - if not miss: - break - if rnd > 0 and len(miss) >= last_miss: - # a round that adds nothing will not be fixed by more rounds - print("binary chunks do not arrive: text chunks for the rest") - binary = None - text_todo = sorted({u * UNIT // CHUNK for u in miss}) - break - last_miss = len(miss) - todo = sorted({u * UNIT // BCHUNK for u in miss}) - if binary: - todo = [] - elif text_todo is not None: - todo = text_todo # only what the binary rounds did not deliver - elif args.resume: - # `fw missing` lists ~23 offsets per reply: rounds go on while they help - todo = [] - if not r.endswith("none"): - todo = [int(x) // CHUNK for x in r.lstrip(">").split()] - else: - todo = list(range((len(data) + CHUNK - 1) // CHUNK)) - stuck = 0 - for rnd in range(40 if todo else 0): - for k, i in enumerate(todo): - off = i * CHUNK - r = await link.cmd( - f"fw w {off} {base64.b64encode(data[off : off + CHUNK]).decode()}" - ) - if r != "ok": - print(f"\nchunk {off}: {r}") - return 1 - print( - f"\r{k + 1}/{len(todo)} chunks (round {rnd + 1}), {time.time() - t0:.0f} s, " - f"airtime {bucket.used:.1f} s", - end="", - flush=True, - ) - print() - r = await link.cmd("fw missing") - print("missing:", r) - if r.endswith("none"): - break - if not r.startswith(">"): - stuck += 1 # a lost reply: ask again next round - if stuck > 3: - print("fw missing does not answer, giving up (--resume continues)") - return 1 - continue - new = [int(x) // CHUNK for x in r.lstrip(">").split()] - stuck = stuck + 1 if new == todo else 0 - if stuck > 3: - print("the same chunks keep missing, giving up") - return 1 - todo = new - r = await link.cmd("fw verify", timeout=40) - for _ in range(20): # the node runs it in loop(), not in the handler - if "verifying" not in r: - break - await asyncio.sleep(3) - r = await link.cmd("fw status") - print("verify:", r) - if not r.startswith(">") or "ready" not in r: - return 1 - print("bootloader:", await link.cmd("fw bl")) - if args.apply: - r = await link.cmd("fw apply", timeout=30, tries=1) - 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)) - print("ver:", await link.cmd("ver")) - print("status:", await link.cmd("fw status")) - print("bootloader:", await link.cmd("fw bl")) - print( - f"done in {time.time() - t0:.0f} s, channel airtime {bucket.used:.1f} s, retries {link.retries}" - ) - return 0 - finally: - if side: - await side.leave() await mc.disconnect() -def main() -> None: - ap = argparse.ArgumentParser( - description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter +async def run(args: argparse.Namespace) -> int: + transport = transport_of(args.companion) + target = args.dest.lower() + if len(target) != 64: + target = await full_key(transport, target, args.wait) + side = ota.parse_preset(args.side) if args.side else None + log = EchoLog() + io = engine.Radio( + transport, target, admin_pw(), duty=args.duty, gap=args.gap, side=side, window=args.window, log=log ) + try: + out = await engine.update(io, args.package, apply=args.apply, resume=args.resume, text=args.text) + except (engine.OtaError, link.LinkError, ValueError, OSError) as e: + print(f"FAILED: {e} (airtime {io.airtime} s)") + return 1 + print( + f"{out['state']}: {out.get('package', '-')} {out.get('version_after') or out.get('version') or ''}" + f" -- {time.time() - log.t0:.0f} s, channel airtime {out.get('airtime', 0)} s" + ) + return NO_PACKAGE if out["no_package"] else 0 + + +def main() -> None: + ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) ap.add_argument("companion") ap.add_argument("dest") ap.add_argument("package") @@ -766,7 +186,6 @@ def main() -> None: ap.add_argument("--duty", type=float, default=1.0) ap.add_argument("--wait", type=float, default=120.0) ap.add_argument("--gap", type=float, default=5.0) - ap.add_argument("--via") ap.add_argument("--text", action="store_true") ap.add_argument("--resume", action="store_true") ap.add_argument("--side") diff --git a/tools/ota_push.py b/tools/ota_push.py index cf9b79f0..6e952644 100755 --- a/tools/ota_push.py +++ b/tools/ota_push.py @@ -18,10 +18,18 @@ beforehand (tools/ble_pair.py), from the host that holds the bond. Prefer it to tools/ota_mesh_push.py wherever BLE reaches: no airtime on the mesh, and the console is local, so a full image goes too. Needs bleak; --binary is USB only. +The transfer is the tth.meshcore Ansible collection's OTA engine +(module_utils/meshcore_ota_engine.py), the same code as ota_mesh_push.py and +the meshcore_fw_ota module; tools/ota_collection.py says where it is found. + + --force apply below the battery gate (`fw apply force`, local + console only): a bench board without a cell reads its + floating battery pin + Bench tests of the MESH protocol without a radio (--binary): the chunks go through `fw bin`, which feeds the very handler a binary request over the mesh reaches, padded to the AES block as the node sees it after decryption. Then -the missing-units bitmap ('m') decides what to resend, as ota_mesh_push.py does. +the missing-units bitmap ('m') decides what to resend, as over the mesh. --drop P lose P % of the chunks of the first round on purpose --prime FILE first send the manifest of ANOTHER package and abort, so it stays in the stage flash @@ -36,242 +44,33 @@ that failed `fw verify`. """ import argparse +import asyncio import base64 import glob -import os +import importlib import random import re import sys import time from pathlib import Path -sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +if __name__ == "__main__" and (any(a in ("-h", "--help") for a in sys.argv[1:]) or len(sys.argv) == 1): + print(__doc__) + sys.exit(0) + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +from ota_collection import PKG, locate + +locate() +engine = importlib.import_module(f"{PKG}.meshcore_ota_engine") +ota = importlib.import_module(f"{PKG}.meshcore_ota") +console = importlib.import_module(f"{PKG}.meshcore_console") MAC_RE = re.compile(r"^[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){5}$") -NUS_RX = "6e400002-b5a3-f393-e0a9-e50e24dcca9e" # write (host -> node) -NUS_TX = "6e400003-b5a3-f393-e0a9-e50e24dcca9e" # notify (node -> host) - -CHUNK = 96 # FW_OTA_CHUNK BCHUNK = 96 # binary over USB: base64 of 7 + 96 B fits the 160 B console line -UNIT = 32 # FW_OTA_UNIT - - -def crc16(data: bytes, crc: int = 0xFFFF) -> int: - """Nordic crc16_compute (CCITT, init 0xFFFF) -- FwUpdate.cpp crc16_update.""" - for b in data: - crc = ((crc >> 8) | (crc << 8)) & 0xFFFF - crc ^= b - crc ^= (crc & 0xFF) >> 4 - crc ^= (crc << 12) & 0xFFFF - crc ^= ((crc & 0xFF) << 5) & 0xFFFF - return crc - - -def w_payload(sid: int, off: int, chunk: bytes) -> bytes: - """REQ_TYPE_FW_OTA 'w': [F0]['w'][sid u16][off u32][len u8][crc16][data].""" - head = sid.to_bytes(2, "little") + off.to_bytes(4, "little") + bytes([len(chunk)]) - # the crc binds the data to this session and offset (FwUpdate::handleBinary) - return ( - bytes([0xF0, ord("w")]) - + head - + crc16(chunk, crc16(head)).to_bytes(2, "little") - + chunk - ) - - -def fw_bin(s, payload: bytes) -> bytes | None: - r = command(s, "fw bin " + base64.b64encode(payload).decode()) - if r.startswith("ERR"): - sys.exit(f"fw bin: {r}") - r = r.lstrip("> ").strip() - return None if r == "-" else bytes.fromhex(r) - - -def bin_missing(s) -> tuple[int, list[int]]: - d = fw_bin(s, bytes([0xF0, ord("m")])) - if not d or len(d) < 5: - sys.exit(f"'m' reply: {d!r}") - cnt = int.from_bytes(d[3:5], "little") - have = (len(d) - 5) // 2 # the console prints a shortened list - return d[0], [ - int.from_bytes(d[5 + 2 * i : 7 + 2 * i], "little") - for i in range(min(cnt, have)) - ] - - -def send_binary( - s, data: bytes, drop: float, sid: int, stale: bytes | None = None -) -> None: - if stale: - # chunks of ANOTHER session (as if a late packet of an earlier transfer): - # the node must drop them, or the manifest check sees the wrong package - for off in (0, BCHUNK, 2 * BCHUNK): - c = stale[off : off + BCHUNK] - fw_bin( - s, - w_payload((sid ^ 0x5A5A), off, c), - ) - print("sent 3 stale chunks of another session") - todo = list(range((len(data) + BCHUNK - 1) // BCHUNK)) - for rnd in range(10): - lost = 0 - for i in todo: - if rnd == 0 and random.random() < drop / 100: - lost += 1 - continue - off = i * BCHUNK - chunk = data[off : off + BCHUNK] - if fw_bin( - s, - w_payload(sid, off, chunk), - ): - sys.exit("a 'w' got a reply, it must not") - if stale and rnd == 0: - # and again AFTER the real manifest chunks: the order seen on the bench - for off in (0, BCHUNK, 2 * BCHUNK): - c = stale[off : off + BCHUNK] - fw_bin( - s, - w_payload((sid ^ 0x5A5A), off, c), - ) - state, miss = bin_missing(s) - for _ in range(20): - if state != 4: - break - time.sleep(0.3) - state, miss = bin_missing(s) - print( - f"round {rnd + 1}: sent {len(todo) - lost}, dropped {lost}, state {state}, missing {len(miss)}+" - ) - if state == 3: - sys.exit(f"node: {command(s, 'fw status')}") - if not miss: - return - todo = sorted({u * UNIT // BCHUNK for u in miss}) - sys.exit("binary transfer did not converge") - - -class BleConsole: - """The node's BLE console (NUS) behind the few serial calls this tool makes: - write, read, reset_input_buffer, close. bleak runs in its own thread.""" - - def __init__(self, mac: str): - import asyncio - import threading - - from bleak import BleakClient, BleakScanner - - self._asyncio = asyncio - self._buf = bytearray() - self._lock = threading.Lock() - self._loop = asyncio.new_event_loop() - threading.Thread(target=self._loop.run_forever, daemon=True).start() - - async def connect(): - last = None - for attempt in range(5): # BLE connects are flaky, as in ble_cli.py - try: - dev = await BleakScanner.find_device_by_address(mac, timeout=20) - if dev is None: - raise RuntimeError("not advertising (already connected?)") - c = BleakClient(dev, timeout=30) - await c.connect() - await c.start_notify(NUS_TX, self._rx) - return c - except Exception as e: # noqa: BLE001 - last = e - print(f" [connect {attempt + 1}/5] {type(e).__name__}: {e}", flush=True) - await asyncio.sleep(4) - raise RuntimeError(f"cannot connect to {mac}: {last}") - - try: - self._c = self._run(connect()) - except RuntimeError as e: - sys.exit(str(e)) - # A NUS write carries at most ATT_MTU-3 bytes and BlueZ does not split it - # (ble_cli.py); at the default MTU 23 a chunk line goes out in 8 writes. - self._chunk = max(20, int(getattr(self._c, "mtu_size", 23)) - 3) - - def _run(self, coro): - return self._asyncio.run_coroutine_threadsafe(coro, self._loop).result() - - def _rx(self, _handle, data: bytearray) -> None: - with self._lock: - self._buf.extend(data) - - def reset_input_buffer(self) -> None: - with self._lock: - self._buf.clear() - - def write(self, data: bytes) -> None: - async def w(): - for i in range(0, len(data), self._chunk): - await self._c.write_gatt_char(NUS_RX, data[i : i + self._chunk], response=False) - await self._asyncio.sleep(0.05) - - self._run(w()) - - def read(self, n: int) -> bytes: - time.sleep(0.01) - with self._lock: - d = bytes(self._buf[:n]) - del self._buf[:n] - return d - - def close(self) -> None: - try: - self._run(self._c.disconnect()) - except Exception as e: # noqa: BLE001 -- after `fw apply` the node is gone already - print(f"(disconnect: {type(e).__name__})") - finally: - self._loop.call_soon_threadsafe(self._loop.stop) - - NO_PACKAGE = 3 # exit code: no package starts from the node's image -def pick_package(where: str, status: str, full_ok: bool) -> bytes: - """`package` may be a directory with one release's packages (the full image - and its deltas, as the firmware role fetches them): take the delta that - starts from the image `fw status` reports, else -- where a full image may - go -- the full one. Exits NO_PACKAGE when nothing fits: the node runs an - image no delta starts from, or has no `fw` at all (not an -ota build).""" - p = Path(where) - if not p.is_dir(): - return p.read_bytes() - m = re.search(r"\bbase \d+ ([0-9a-f]{8})", status) - if not m: - print(f"no base image in `fw status`: {status!r}") - sys.exit(NO_PACKAGE) - base = m.group(1) - full = None - for f in sorted(p.glob("*.mcfw")): - data = f.read_bytes() - if data[:4] != b"MCFW": - continue - if data[16:48].hex().startswith(base): # raw_sha256 = the image it installs - print(f"the node already runs the image of {f.name}") - sys.exit(0) - if data[4] == 2 and data[160:192].hex().startswith(base): - print(f"package: {f.name} (delta from {base})") - return data - if data[4] == 1: - full = (f, data) - if full and full_ok: - print(f"package: {full[0].name} (full image, no delta from {base})") - return full[1] - print(f"no package in {where} starts from {base}") - sys.exit(NO_PACKAGE) - - -def open_console(target: str): - if MAC_RE.match(target): - return BleConsole(target) - from board_probe import _open as open_port - - return open_port(resolve(target)) - - def resolve(target: str) -> str: """Same rules as serial_cli.py: fleet name, bare serial number, or a path.""" if target.startswith("/"): @@ -285,6 +84,28 @@ def resolve(target: str) -> str: return hits[0] +class EchoLog(list): + def append(self, line): + print(line, flush=True) + super().append(line) + + +async def push(args: argparse.Namespace) -> int: + """The ordinary transfer: the engine over the node's console.""" + con = console.BleConsole(args.board) if MAC_RE.match(args.board) else console.SerialConsole(resolve(args.board)) + io = engine.Console(con, log=EchoLog()) + try: + out = await engine.update(io, args.package, apply=args.apply, force=args.force) + except (engine.OtaError, console.ConsoleError, ValueError, OSError) as e: + print(f"FAILED: {e}") + return 1 + print(f"{out['state']}: {out.get('package', '-')} {out.get('version_after') or out.get('version') or ''}") + return NO_PACKAGE if out["no_package"] else 0 + + +# ── bench harness: the mesh protocol through `fw bin` (USB only) ───────────── + + def command(s, line: str, timeout: float = 5.0) -> str: """One console command, returns the reply after '-> '.""" s.reset_input_buffer() @@ -294,7 +115,7 @@ def command(s, line: str, timeout: float = 5.0) -> str: d = s.read(4096) if d: buf += d - m = re.search(rb"-> ?(.*?)\r?\n", buf) + m = console.REPLY.search(buf) if m: return m.group(1).decode(errors="replace").strip() else: @@ -302,81 +123,95 @@ def command(s, line: str, timeout: float = 5.0) -> str: raise TimeoutError(f"no reply to {line[:40]!r}: {buf[-200:]!r}") -def main() -> None: - ap = argparse.ArgumentParser( - description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter - ) - ap.add_argument("board", help="board name (local config), USB serial number, or port path") - ap.add_argument("package") - ap.add_argument("--apply", action="store_true") - ap.add_argument( - "--force", - action="store_true", - help="apply below the battery gate (`fw apply force`, local console only): " - "a bench board without a cell reads its floating battery pin", - ) - ap.add_argument("--binary", action="store_true") - ap.add_argument("--drop", type=float, default=0.0) - ap.add_argument("--prime") - ap.add_argument( - "--stale", help="package whose chunks are injected with a wrong session id" - ) - args = ap.parse_args() +def fw_bin(s, payload: bytes) -> bytes | None: + r = command(s, "fw bin " + base64.b64encode(payload).decode()) + if r.startswith("ERR"): + sys.exit(f"fw bin: {r}") + r = r.lstrip("> ").strip() + return None if r == "-" else bytes.fromhex(r) - if args.binary and MAC_RE.match(args.board): - sys.exit("--binary is a bench test of the mesh path: USB only") - s = open_console(args.board) + +def bin_missing(s) -> tuple[int, list[int]]: + d = fw_bin(s, bytes([ota.REQ_FW, ord("m")])) + st = ota.parse_missing(d or b"") + if st is None: + sys.exit(f"'m' reply: {d!r}") + have = (len(d or b"") - 5) // 2 # the console prints a shortened list + return st[0], st[1][:have] + + +def send_binary(s, data: bytes, drop: float, sid: int, stale: bytes | None = None) -> None: + def inject(): + # chunks of ANOTHER session (as if a late packet of an earlier transfer): + # the node must drop them, or the manifest check sees the wrong package + for off in (0, BCHUNK, 2 * BCHUNK): + fw_bin(s, ota.w_payload(sid ^ 0x5A5A, off, stale[off : off + BCHUNK])) + + if stale: + inject() + print("sent 3 stale chunks of another session") + todo = list(range((len(data) + BCHUNK - 1) // BCHUNK)) + for rnd in range(10): + lost = 0 + for i in todo: + if rnd == 0 and random.random() < drop / 100: + lost += 1 + continue + off = i * BCHUNK + if fw_bin(s, ota.w_payload(sid, off, data[off : off + BCHUNK])): + sys.exit("a 'w' got a reply, it must not") + if stale and rnd == 0: + inject() # and again AFTER the real manifest chunks: the order seen on the bench + state, miss = bin_missing(s) + for _ in range(20): + if state != 4: + break + time.sleep(0.3) + state, miss = bin_missing(s) + print(f"round {rnd + 1}: sent {len(todo) - lost}, dropped {lost}, state {state}, missing {len(miss)}+") + if state == 3: + sys.exit(f"node: {command(s, 'fw status')}") + if not miss: + return + todo = sorted({u * ota.UNIT // BCHUNK for u in miss}) + sys.exit("binary transfer did not converge") + + +def bench(args: argparse.Namespace) -> int: + from board_probe import _open as open_port + + s = open_port(resolve(args.board)) try: - if not isinstance(s, BleConsole): # over BLE its reply comes late, as the next one's - s.write(b"\r\n") - time.sleep(0.4) + s.write(b"\r\n") + time.sleep(0.4) st = command(s, "fw status") print("status:", st) - data = pick_package(args.package, st, full_ok=True) + base = ota.parse_status(st) + if base is None: + print("no base image in `fw status`: not an -ota build") + return NO_PACKAGE + kind, pkg = ota.pick(engine.load_packages(args.package), base[1], full_ok=True) + if kind == "current": + print(f"the node already runs the image of {pkg.name}") + return 0 + if kind == "none": + print(f"no package in {args.package} starts from {base[1]}") + return NO_PACKAGE + print(f"package: {pkg.name} ({kind})") + data = pkg.data if args.prime: - with open(args.prime, "rb") as f: - other = f.read() + other = Path(args.prime).read_bytes() command(s, f"fw begin {len(other)}") - for off in range(0, 256, CHUNK): - command( - s, - f"fw w {off} {base64.b64encode(other[off : off + CHUNK]).decode()}", - ) + for off in range(0, ota.MANIFEST, ota.CHUNK): + command(s, f"fw w {off} {base64.b64encode(other[off : off + ota.CHUNK]).decode()}") time.sleep(1) # let loop() check and flush it - print( - "primed with", - args.prime, - "->", - command(s, "fw status"), - "/", - command(s, "fw abort"), - ) + print("primed with", args.prime, "->", command(s, "fw status"), "/", command(s, "fw abort")) sid = random.randint(1, 0xFFFF) r = command(s, f"fw begin {len(data)} {sid}") print("begin:", r) if not r.startswith("OK"): - sys.exit(1) - t0 = time.time() - n = 0 if args.binary else (len(data) + CHUNK - 1) // CHUNK - if args.binary: - stale = None - if args.stale: - with open(args.stale, "rb") as f: - stale = f.read() - send_binary(s, data, args.drop, sid, stale) - for i in range(n): - off = i * CHUNK - b64 = base64.b64encode(data[off : off + CHUNK]).decode() - r = command(s, f"fw w {off} {b64}") - if r != "ok": - sys.exit(f"chunk {off}: {r}") - if i % 200 == 0 or i == n - 1: - print( - f"\r{i + 1}/{n} chunks, {time.time() - t0:.0f} s", - end="", - flush=True, - ) - print() + return 1 + send_binary(s, data, args.drop, sid, Path(args.stale).read_bytes() if args.stale else None) print("missing:", command(s, "fw missing")) r = command(s, "fw verify", timeout=30) t1 = time.time() @@ -385,13 +220,33 @@ def main() -> None: r = command(s, "fw status") print("verify:", r) if "ready" not in r: - sys.exit(1) + return 1 print("bootloader:", command(s, "fw bl")) if args.apply: print("apply:", command(s, "fw apply force" if args.force else "fw apply", timeout=10)) + return 0 finally: s.close() +def main() -> None: + ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + ap.add_argument("board", help="board name (local config), USB serial number, port path, or BLE MAC") + ap.add_argument("package") + ap.add_argument("--apply", action="store_true") + ap.add_argument("--force", action="store_true") + ap.add_argument("--binary", action="store_true") + ap.add_argument("--drop", type=float, default=0.0) + ap.add_argument("--prime") + ap.add_argument("--stale", help="package whose chunks are injected with a wrong session id") + args = ap.parse_args() + harness = args.binary or args.drop or args.prime or args.stale + if harness and MAC_RE.match(args.board): + sys.exit("--binary/--drop/--prime/--stale are a bench test of the mesh path: USB only") + if harness and not args.binary: + sys.exit("--drop/--prime/--stale go with --binary") + sys.exit(bench(args) if harness else asyncio.run(push(args))) + + if __name__ == "__main__": main()