diff --git a/.gitignore b/.gitignore index 961dd4ac..e9e57d4b 100644 --- a/.gitignore +++ b/.gitignore @@ -29,5 +29,5 @@ __pycache__/ # PID soubor lokálního helperu (běhový balast, ne konfigurace) ether.pid -# data z pochůzkových testů (tools/walk.sh fetch) — polohy, necommitovat +# data z pochůzkových testů (.tth/tools/walk.sh fetch) — polohy, necommitovat walk-data/ diff --git a/docs/budka-sensor.md b/docs/budka-sensor.md index fd3bac1c..b61f07cd 100644 --- a/docs/budka-sensor.md +++ b/docs/budka-sensor.md @@ -40,7 +40,7 @@ Budka `mc_tx` pad → XIAO **D0**, GND ↔ GND, each board on its own USB. A A line with a bad checksum is dropped whole; a value not refreshed for 2 min is left out. Meter channels stay reserved while a meter is missing. -Read it with `tools/budka_telem.py `. The sensor +Read it with `.tth/tools/budka_telem.py `. The sensor answers only clients in its ACL — a request from anyone else is dropped (`recv matches no peers` in a `MESH_DEBUG` build). Add the companion from the sensor's USB console with `setperm 1`, or log in as admin. diff --git a/docs/power.md b/docs/power.md index 5b885bad..428c4c37 100644 --- a/docs/power.md +++ b/docs/power.md @@ -137,7 +137,7 @@ live mesh. On a mast, where 2 mA of ~24 is not the problem, leave it off. `powersaving on` makes the nRF52 wait in WFE between events (it wakes on any interrupt, including LoRa DIO1). Upstream ships it **off**, and it was missing from our provisioning, so every node built from that file ran the core at 64 MHz -around the clock. It is now in `tools/provision/repeater-cz-silent.txt`. +around the clock. It is now in our provisioning file. **But it buys about 1 mA, not the 3-4 that seemed obvious.** Measured with GPS held off so its sync windows could not pollute the cells: paired estimate @@ -171,5 +171,5 @@ drain directly costs collected frames. 40.9 mA against 24.1-24.5 in its neighbours). Put `gps off` in every cell of such a run and restore `gps duty` afterwards. -See `tools/README.md` (`power_ab.py`) for the alternating-cell design that makes +See `tools/power_ab.py --help` for the alternating-cell design that makes these deltas trustworthy in the first place. diff --git a/tools/README.md b/tools/README.md new file mode 100644 index 00000000..d3e893b6 --- /dev/null +++ b/tools/README.md @@ -0,0 +1,61 @@ + +# tools/ + +Host-side tools for MeshCore nodes of this fork: consoles, flashing, bench +tests and diagnostics. Every script answers `--help` without touching a port, +a node or the network. + +## Your boards: the local config + +The tools carry no board serial, MAC or host of anyone's bench. Names like +`b1` resolve through one file outside the repo: + + ~/.config/meshcore-tools/config.ini (or $MESHCORE_TOOLS_CONFIG) + +Start from [`config.example.ini`](config.example.ini); the format and the shell +interface are in `mctools_config.py --help`. Without a config everything still +works with full USB serial numbers, BLE MACs and port paths. Two fields matter +for safety: `protect` (flashing tools refuse the board unless told to) and +`refuse` (console tools do not open it at all, e.g. the radio of an observer +running other firmware). No secrets go in there. + +Serial ports are always matched in `/dev/serial/by-id` by the USB serial +number: a `ttyACM` number changes with every replug and would point a tool at +a different board. + +## Consoles + +| tool | what | +|---|---| +| `serial_cli.py` | text console over USB: send commands, print the replies | +| `ble_cli.py` | the same console over BLE (Nordic UART); needs a bonded node | +| `ble_pair.py` | non-interactive BLE pairing by PIN (bluetoothctl over a pty) | +| `serial_tcp_proxy.py` | a board's USB console on a localhost TCP port, for a board on another host (SSH tunnel) | + +## Flashing + +| tool | what | +|---|---| +| `flash_node.sh` | flash any board: picks USB DFU, UF2 or BLE from what the board is doing, refuses `protect`ed boards | +| `xiao_uf2_flash.sh` | XIAO nRF52840 through its UF2 drive, to a named board, verified by reading the version back | +| `xiao_serial_dfu.sh` | XIAO with a text console over USB serial DFU: no drive, no mount, no root | +| `ble_flash_node.sh` | BLE OTA of a node out of reach of a cable, with the checks around it (silence, services, version) | +| `ble_dfu.py` | legacy Nordic DFU over BLE for the Adafruit nRF52 bootloader (buttonless, both phases) | +| `build_version.py` | PlatformIO pre-script: real version and build time for `ver` | + +## Bench and diagnostics + +| tool | what | +|---|---| +| `board_probe.py` | what runs on each board on USB, and whether that changed | +| `fleet_test.py` | regression smoke test of the bench boards after a firmware change | +| `bench_soak.py` | long run: who hears whom over time, when a board reboots or goes deaf | +| `radio_stall_watch.py` | watch a `RADIO_DIAG` node until its receiver stalls | +| `mesh_sniffer.py` | passive sniffer: every frame the radio hears, decoded on the host | +| `preset_trace.py` | TRACE along a fixed path on a chosen radio preset | +| `fw_room_smoke.py` | smoke test of a firmware room server over the air | +| `power_ab.py` | A/B current measurement with a UC96 meter (alternating cells) | +| `companion_backup.py` | back up a companion (contacts, channels, settings) before flashing, diff and restore after | +| `gen_node_id.py` | a node identity whose path hash collides with no known repeater | + +`fleet.py` and `mctools_config.py` are the shared board lookup. diff --git a/tools/bench_soak.py b/tools/bench_soak.py new file mode 100755 index 00000000..272bdacb --- /dev/null +++ b/tools/bench_soak.py @@ -0,0 +1,247 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Dlouhý běh lavice: kdo koho slyší, v čase, a kdy deska rebootuje nebo ohluchne. + +Vzniklo 23. 9. 2026 kvůli second-mast: po OTA na nový firmware přestala přijímat +(`recv 0`) a na zerohop hlásila `sent 0` + `tx_timeout 4`, přestože ob2 vedle ní +slyšel všechny čtyři adverty. Rádio vysílalo, ale IRQ se nedostalo do MCU. +`fleet_test.py` je jednorázový snímek za pár sekund -- tohle je stejná otázka +položená stokrát za sebou, protože chyba přišla až po minutách běhu. + + tools/bench_soak.py --boards b1,b2 --hours 8 + tools/bench_soak.py --period 30 --out /tmp/soak # all bench boards of the config + +Co dělá, v kolech (každých --period s, vysílá jedna deska, dokola): + 1. snímek `stats-packets` a `stats-core` na všech deskách, + 2. vysílající pošle `advert.zerohop` (nikdo ho nerebroadcastuje, takže + „B slyšel A" nejde splnit přes třetí desku a netřeba sahat na `repeat`), + 3. po --settle s druhý snímek. + +Orákulum je vždy JINÁ deska: slyšel = `recv` příjemce vzrostl. Vlastní `sent` +vysílajícího se jen zapisuje vedle -- u second-mast lhal (0, zatímco vysílala). + +Konzole se drží otevřené celou dobu a KAŽDÝ řádek jde s časem do logu, takže se +zachytí i to, co deska vypíše sama (boot `RESETREAS`, `!!! HARDFAULT`). Když +deska zmizí z USB, nástroj to zapíše a čeká, až se vrátí -- nic nerestartuje. + +Nic nemění: žádné `set`, žádné `reboot`. Prefs pro test nastav předem ručně. +PAST (z fleet_test.py): na testované desce nesmí viset BLE klient -- USB a BLE +konzole dělí jeden buffer a prokládají znaky. +""" +import argparse +import glob +import json +import os +import re +import signal +import sys +import threading +import time +from datetime import datetime, timezone + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +from board_probe import _open as open_port +from fleet import serial_for + +FLAG_RE = re.compile(r"boot:|RESETREAS|HARDFAULT|LOCKUP|WATCHDOG", re.IGNORECASE) + + +def now(): + return datetime.now(timezone.utc).isoformat(timespec="seconds") + + +class Board: + """Jedna konzole: čtecí vlákno loguje vše, `cmd()` sbírá odpověď z okna.""" + + def __init__(self, name, log_fh, events): + self.name = name + self.sn = serial_for(name) + self.log = log_fh + self.events = events + self.s = None + self.lines = [] # řádky od posledního cmd() + self.lock = threading.Lock() + self.stop = False + self.up = False + threading.Thread(target=self._reader, daemon=True).start() + + def _path(self): + hits = [p for p in glob.glob("/dev/serial/by-id/*") if self.sn in p] + return hits[0] if len(hits) == 1 else None + + def _event(self, kind, **kw): + ev = {"t": now(), "board": self.name, "event": kind, **kw} + self.events.append(ev) + self.log.write(json.dumps(ev, ensure_ascii=False) + "\n") + self.log.flush() + print(f"[{ev['t']}] {self.name}: {kind} {kw if kw else ''}", flush=True) + + def _reader(self): + buf = b"" + while not self.stop: + if self.s is None: + p = self._path() + if p: + try: + self.s = open_port(p) + if self.up is False and self.events is not None: + self._event("usb_up", port=os.path.basename(p)) + self.up = True + except Exception: + self.s = None + time.sleep(1) + continue + try: + d = self.s.read(4096) + except Exception as e: + self._event("usb_gone", err=str(e)[:80]) + self.up = False + try: + self.s.close() + except Exception: + pass + self.s = None + continue + if not d: + time.sleep(0.02) + continue + buf += d + while b"\n" in buf: + raw, buf = buf.split(b"\n", 1) + line = raw.decode("utf-8", "replace").rstrip("\r") + if not line.strip(): + continue + self.log.write(f"{now()} {self.name} | {line}\n") + if FLAG_RE.search(line): + self._event("flagged_line", line=line[:200]) + with self.lock: + self.lines.append(line) + self.log.flush() + + def cmd(self, text, window=1.5): + if self.s is None: + return None + with self.lock: + self.lines = [] + try: + self.s.write((text + "\r").encode()) + except Exception: + return None + time.sleep(window) + with self.lock: + return "\n".join(self.lines) + + def stats(self): + out = {} + for c in ("stats-packets", "stats-core"): + r = self.cmd(c) + m = re.search(r"\{.*\}", r or "") + if not m: + return None + try: + out.update(json.loads(m.group(0))) + except ValueError: + return None + return out + + +def main(): + ap = argparse.ArgumentParser(description=__doc__, + formatter_class=argparse.RawDescriptionHelpFormatter) + ap.add_argument("--boards", default=None, + help="desky z lokalniho configu, čárkou (default: všechny role=bench bez refuse)") + ap.add_argument("--hours", type=float, default=8.0) + ap.add_argument("--period", type=float, default=60.0, help="s mezi koly") + ap.add_argument("--settle", type=float, default=4.0, help="s po advertu") + ap.add_argument("--out", default=".", help="adresář na log + JSONL") + a = ap.parse_args() + if a.boards is None: + from mctools_config import by_role + + a.boards = ",".join(n for n, b in by_role("bench").items() if b.get("serial") and not b.get("refuse")) + if not a.boards: + ap.error("no --boards and no role=bench board in the local config (tools/mctools_config.py)") + + os.makedirs(a.out, exist_ok=True) + stamp = datetime.now().strftime("%Y%m%d-%H%M%S") + log = open(os.path.join(a.out, f"soak-{stamp}.log"), "a") + rounds_fh = open(os.path.join(a.out, f"soak-{stamp}.jsonl"), "a") + events = [] + boards = [Board(n.strip(), log, events) for n in a.boards.split(",")] + if len(boards) < 2: + sys.exit("potřeba aspoň dvě desky -- svědkem musí být JINÁ deska") + + stop = {"v": False} + signal.signal(signal.SIGINT, lambda *_: stop.update(v=True)) + signal.signal(signal.SIGTERM, lambda *_: stop.update(v=True)) + + time.sleep(3) + last_up = {} + pairs = {} # (tx, rx) -> [heard, tried] + miss_streak = {} # (tx, rx) -> po sobě jdoucí neslyšení + reboots = {b.name: 0 for b in boards} + txto = {b.name: 0 for b in boards} + t_end = time.time() + a.hours * 3600 + rnd = 0 + while not stop["v"] and time.time() < t_end: + t0 = time.time() + tx = boards[rnd % len(boards)] + before = {b.name: b.stats() for b in boards} + ok = tx.cmd("advert.zerohop", window=1.0) + time.sleep(a.settle) + after = {b.name: b.stats() for b in boards} + + rec = {"t": now(), "round": rnd, "tx": tx.name, + "tx_cmd_ok": bool(ok and "OK" in ok), "heard": {}, "boards": {}} + for b in boards: + s0, s1 = before[b.name], after[b.name] + rec["boards"][b.name] = s1 + if s1 and "uptime_secs" in s1: + u = s1["uptime_secs"] + if b.name in last_up and u < last_up[b.name]: + reboots[b.name] += 1 + b._event("reboot", uptime_before=last_up[b.name], uptime_now=u) + last_up[b.name] = u + if s0 and s1: + d_to = s1.get("tx_timeout", 0) - s0.get("tx_timeout", 0) + if d_to > 0: + txto[b.name] += d_to + b._event("tx_timeout", delta=d_to) + if b is tx or not (s0 and s1): + continue + heard = s1.get("recv", 0) - s0.get("recv", 0) >= 1 + rec["heard"][b.name] = heard + key = (tx.name, b.name) + h = pairs.setdefault(key, [0, 0]) + h[1] += 1 + h[0] += int(heard) + miss_streak[key] = 0 if heard else miss_streak.get(key, 0) + 1 + if miss_streak[key] == 3: + b._event("deaf?", tx=tx.name, streak=3, + note="3 kola po sobě neslyšel -- ověř svědkem") + tb, ta = before[tx.name], after[tx.name] + if tb and ta: + rec["tx_sent_delta"] = ta.get("sent", 0) - tb.get("sent", 0) + rounds_fh.write(json.dumps(rec, ensure_ascii=False) + "\n") + rounds_fh.flush() + rnd += 1 + time.sleep(max(0.0, a.period - (time.time() - t0))) + + for b in boards: + b.stop = True + summary = { + "rounds": rnd, + "pairs": {f"{k[0]}->{k[1]}": f"{v[0]}/{v[1]}" for k, v in sorted(pairs.items())}, + "reboots": reboots, + "tx_timeouts": txto, + "events": len(events), + } + print(json.dumps(summary, ensure_ascii=False, indent=1)) + rounds_fh.write(json.dumps({"summary": summary}, ensure_ascii=False) + "\n") + bad = any(v for v in reboots.values()) or any(v for v in txto.values()) or \ + any(v[0] < v[1] for v in pairs.values()) + sys.exit(1 if bad else 0) + + +if __name__ == "__main__": + main() diff --git a/tools/ble_cli.py b/tools/ble_cli.py new file mode 100755 index 00000000..b140f283 --- /dev/null +++ b/tools/ble_cli.py @@ -0,0 +1,184 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Text console of a MeshCore node over BLE (Nordic UART Service). + +The same console you get on USB serial, but wireless -- which is the only way +in once a node is mounted somewhere without a cable. Works against any build +that has `BLE_PIN_CODE` set (repeater, room server, companion_radio_ble). + +Why this exists as a tool rather than a snippet: the NUS write has a size limit +that is easy to miss and fails in a misleading way (see CHUNK below), and the +BlueZ/bleak connect path needs retries to be usable for anything longer than a +single command. Every ad-hoc script re-learned both the hard way. + + # single command (a MAC, or a board name from the local config) + ble_cli.py AA:BB:CC:DD:EE:10 ver + ble_cli.py hill-rpt ver + + # several, one connection + ble_cli.py AA:BB:CC:DD:EE:10 "get radio" "get name" stats-radio + + # from a file, one command per line, '#' comments ignored + ble_cli.py AA:BB:CC:DD:EE:10 -f provision.txt + + # {epoch} expands to the host's current unix time -- the point being that a + # provisioning FILE can carry `time {epoch}`, which a shell cannot reach + ble_cli.py AA:BB:CC:DD:EE:10 "time {epoch}" + + # keep reconnecting per command (slow, but survives a flaky link) + ble_cli.py AA:BB:CC:DD:EE:10 --per-command "gps on" "set af 9" + +PAIRING: the console characteristics are SECMODE_ENC_WITH_MITM, so the node +must be bonded first or the connect pops a passkey dialog on the desktop: + + bluetoothctl --agent KeyboardOnly # then: pair , enter the BLE PIN + +`erase` on the node wipes the bond too (bonds live in InternalFS), so re-pair +after one. + +CAUTION: one console at a time. USB and BLE read into the same command buffer +in the firmware (`simple_repeater/main.cpp`, "commands share the buffer"), so +two consoles at once interleave into one line and can crash the node. +""" +import argparse +import asyncio +import sys +import time + +from bleak import BleakClient, BleakScanner + +NUS_RX = "6e400002-b5a3-f393-e0a9-e50e24dcca9e" # write (host -> node) +NUS_TX = "6e400003-b5a3-f393-e0a9-e50e24dcca9e" # notify (node -> host) + +# A NUS write carries at most ATT_MTU-3 bytes, and BlueZ will not split it for +# you. At the default MTU of 23 that is 20 bytes -- and MeshCore nodes are +# routinely left at 23. A longer write is rejected with +# "[org.bluez.Error.Failed] Failed to initiate write", which reads like a +# dropped link rather than "your command was too long": commands up to 18 +# characters work and everything longer fails, deterministically. Hence chunking +# every write, always. +CHUNK = 20 + + +def log(*a): + print(*a, file=sys.stderr, flush=True) + + +async def send(client, buf, cmd, wait): + buf.clear() + # {epoch} -> host unix time, expanded HERE rather than at parse time so that + # it is the time the command is actually sent: --per-command reconnects cost + # seconds each, and a whole -f file can take minutes. + # + # It exists for `time {epoch}` in a provisioning file. -f reads lines verbatim, + # so a `$(date +%s)` in one is sent as literal text and the node answers + # "Unknown command" -- which is why the clock line in a provisioning file + # was a commented-out note telling you to substitute the epoch by hand. Every + # clock in this firmware is volatile without GPS or an I2C RTC, and a node + # whose RTC still says May 2024 has its adverts dropped as replays. + cmd = cmd.replace("{epoch}", str(int(time.time()))) + data = (cmd + "\r\n").encode() + for i in range(0, len(data), CHUNK): + await client.write_gatt_char(NUS_RX, data[i:i + CHUNK], response=False) + await asyncio.sleep(0.15) + await asyncio.sleep(wait) + out = bytes(buf).decode("utf-8", "replace").strip() + # the node echoes nothing, but replies are prefixed "-> " or "> " + for p in ("-> ", "> "): + if out.startswith(p): + out = out[len(p):] + # the EXPANDED command goes back too, so the printout says what was really + # sent rather than the `{epoch}` template + return cmd, out.strip() + + +async def run(mac, cmds, wait, per_command, tries): + async def connect(): + last = None + for attempt in range(tries): + try: + dev = await BleakScanner.find_device_by_address(mac, timeout=20) + if dev is None: + # a connected peripheral stops advertising; a stale link on + # the adapter is the usual reason it cannot be found + raise RuntimeError(f"{mac} not advertising (already connected?)") + c = BleakClient(dev, timeout=30) + await c.connect() + return c + except Exception as e: # noqa: BLE001 + last = e + log(f" [connect {attempt + 1}/{tries}] {type(e).__name__}: {e}") + await asyncio.sleep(4) + raise SystemExit(f"cannot connect to {mac}: {last}") + + results = [] + if per_command: + for cmd in cmds: + c = await connect() + try: + buf = bytearray() + await c.start_notify(NUS_TX, lambda _h, d: buf.extend(d)) + results.append(await send(c, buf, cmd, wait)) + finally: + await c.disconnect() + await asyncio.sleep(2) + else: + c = await connect() + try: + buf = bytearray() + await c.start_notify(NUS_TX, lambda _h, d: buf.extend(d)) + for cmd in cmds: + results.append(await send(c, buf, cmd, wait)) + finally: + await c.disconnect() + return results + + + +def _mac(key): + """A board name from the local config (tools/mctools_config.py) -> its MAC. + Optional on purpose: ble_flash_node.sh --via copies this file ALONE to a + remote host, where there is no config and a MAC is given anyway.""" + try: + from mctools_config import mac_for + except ImportError: + return key + return mac_for(key) or key + +def main(): + ap = argparse.ArgumentParser(description=__doc__, + formatter_class=argparse.RawDescriptionHelpFormatter) + ap.add_argument("mac", help="BLE address of the node, or its name in the local config") + ap.add_argument("cmds", nargs="*", help="console commands") + ap.add_argument("-f", "--file", help="read commands from a file, one per line") + ap.add_argument("-w", "--wait", type=float, default=3.0, + help="seconds to collect the reply (default 3; raise for " + "paged output like rxlog/nodes)") + ap.add_argument("--per-command", action="store_true", + help="reconnect for every command -- slower, but survives a " + "link that drops mid-sequence") + ap.add_argument("--tries", type=int, default=5, help="connect attempts") + # intermixed, not plain parse_args: with a trailing `cmds` of nargs="*", an + # option BETWEEN the MAC and the commands (` -w 8 rxlog`, the form this + # tool's own help suggests) makes argparse on Python <= 3.12 drop the + # commands with "unrecognized arguments". 3.13 fixed it, so it works on an + # Arch workstation and fails on the Debian hosts (bridge-host, cabin-host) that are + # the only way to reach a mast node -- exactly where you cannot debug it. + a = ap.parse_intermixed_args() + + a.mac = _mac(a.mac) + cmds = list(a.cmds) + if a.file: + with open(a.file) as fh: + cmds += [ln.strip() for ln in fh + if ln.strip() and not ln.lstrip().startswith("#")] + if not cmds: + ap.error("no commands given") + + + for cmd, out in asyncio.run(run(a.mac, cmds, a.wait, a.per_command, a.tries)): + print(f"{cmd}\t{out}") + + +if __name__ == "__main__": + main() diff --git a/tools/ble_dfu.py b/tools/ble_dfu.py new file mode 100644 index 00000000..a536aaeb --- /dev/null +++ b/tools/ble_dfu.py @@ -0,0 +1,363 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Legacy Nordic DFU (SDK ~11, dfu_version 0.5) over BLE pro Adafruit nRF52 bootloader. +Generický BlueZ adaptér přes bleak (bez Nordic donglu). + +Fáze 1: připoj běžící APP, enable notify na 1531, zapiš 0x01 (buttonless) → reboot do bootloaderu. +Fáze 2: reconnect na bootloader (advertuje 1530 DFU svc), proveď START/INIT/IMAGE(PRN)/VALIDATE/ACTIVATE. + BLE DFU je flaky (dropnutá receipt notif → přenos spadne). Fáze 2 se proto + auto-retryuje: po pádu pošle RESET (bootloader → čistý IDLE) a zkusí znovu. + +Použití: ble_dfu.py [phase1|phase2] + phase1 JEN buttonless reboot do bootloaderu, pak skončí (flash si dodělá + volající — po USB je to ~20 s místo minut po BLE) + phase2 přeskočí fázi 1 (buttonless) — použij když uzel UŽ visí v bootloaderu + (advertuje SCAP_DFU), např. po přerušeném DFU. Zotavení bez power-cycle. +""" +import asyncio +import os +import re +import struct +import sys +import zipfile +from bleak import BleakClient, BleakScanner + +DFU_SVC = "00001530-1212-efde-1523-785feabcd123" +CP_UUID = "00001531-1212-efde-1523-785feabcd123" # control point (write+notify) +PKT_UUID = "00001532-1212-efde-1523-785feabcd123" # packet (write-no-resp) + +# opcody +START_DFU, INIT_DFU, RECEIVE_FW, VALIDATE, ACTIVATE_RESET, RESET, REPORT, PKT_RCPT_REQ = 1,2,3,4,5,6,7,8 +RESP, PKT_RCPT = 0x10, 0x11 + +class Notif: + def __init__(self): self.q = asyncio.Queue() + def cb(self, _h, data): self.q.put_nowait(bytes(data)) + async def wait(self, timeout=30): + return await asyncio.wait_for(self.q.get(), timeout) + +def log(*a): print(*a, flush=True) + +async def expect_resp(nf, opcode, timeout=30): + while True: + d = await nf.wait(timeout) + if d and d[0] == RESP and d[1] == opcode: + if d[2] != 1: + raise RuntimeError(f"DFU resp opcode {opcode} status {d[2]} (fail)") + return d + if d and d[0] == PKT_RCPT: + continue # receipt, ignoruj tady + log(" (neočekávaná notif:", d.hex(), ")") + +def mac_plus_one(mac): + p = mac.upper().split(":") + p[-1] = "%02X" % ((int(p[-1], 16) + 1) & 0xFF) + return ":".join(p) + +async def find(mac, want_dfu=False, timeout=30): + """Najdi zařízení. POZOR: běžící APP inzeruje DFU službu taky (kvůli + buttonless), takže 'want_dfu' NESMÍ matchovat jen podle DFU svc -> spletl by + si app s bootloaderem. Bootloader advertuje SCAP_DFU na MAC+1 (SenseCap na + stožáru) NEBO AdaDFU na TÉŽE MAC (XIAO, novější SenseCap Solar). + + ADRESA JE POVINNÁ. Dřív stačil název obsahující "DFU" bez ohledu na adresu a + bralo se prostě první zařízení ze skenu -- s víc deskami v bootloaderu + najednou to sáhne na cizí. Stalo se: cíl CE:72:…:02, připojilo se + FE:11:…:C4. Zachytilo se to jen proto, že se log četl ručně; o pár sekund + později by START_DFU přepsal jinou desku.""" + boot_mac = mac_plus_one(mac) + log(f" scan (want_dfu={want_dfu}, mac={mac}, boot={boot_mac})...") + devs = await BleakScanner.discover(timeout=timeout, return_adv=True) + cand, rejected = [], [] + for d, adv in devs.values(): + addr = d.address.upper() + has_dfu = DFU_SVC in [u.lower() for u in (adv.service_uuids or [])] + name = (d.name or adv.local_name or "") + if want_dfu: + if not has_dfu: + continue + looks_like_dfu = "DFU" in name.upper() + right_addr = addr in (boot_mac, mac.upper()) + if looks_like_dfu and right_addr: + cand.append((d, adv, 0)) + elif looks_like_dfu: + rejected.append(f"{addr} {name!r}") + elif addr == mac.upper(): + cand.append((d, adv, 1)) + cand.sort(key=lambda x: x[2]) + for d, adv, _ in cand: + log(f" kandidát: {d.address} {d.name!r} dfu={DFU_SVC in [u.lower() for u in (adv.service_uuids or [])]}") + if rejected: + log(f" (v bootloaderu i CIZÍ desky, ignoruji: {', '.join(rejected)})") + return cand[0][0] if cand else None + +async def connect_app(mac, tries=5): + """Scan + connect s opakováním, jako to dělá ble_cli.py. + + Jediný pokus NESTAČÍ a stálo to 22. 8. 2026 hodinu na second-mast: BLE konzole + (`ble_cli.py ver`) na tomtéž uzlu a z téhož hostu prošla bez zaváhání, kdežto + DFU umřelo na `TimeoutError` z `local_disconnect_monitor_event.wait()`. Rozdíl + NEBYL v uzlu, v bondu ani ve vzdálenosti (−64 dBm) — jen v tom, že ble_cli + connect opakuje a tady se zkoušel jednou. Vypadá to jako mrtvá deska, a není. + """ + last = None + for attempt in range(tries): + try: + dev = await BleakScanner.find_device_by_address(mac, timeout=25) + if dev is None: + # připojený peripheral přestane advertovat -- obvyklý důvod je + # viset spojení na adaptéru + raise RuntimeError("APP nenalezen ve scanu (už připojený?)") + c = BleakClient(dev, timeout=30) + await c.connect() + return c + except Exception as e: # noqa: BLE001 + last = e + log(f" [connect {attempt + 1}/{tries}] {type(e).__name__}: {str(e)[:60]}") + await asyncio.sleep(4) + raise RuntimeError(f"APP nenalezen ve scanu / connect selhal: {last}") + +async def phase1_buttonless(mac): + log("== FÁZE 1: buttonless reboot do bootloaderu ==") + c = await connect_app(mac) + try: + log(" připojen k APP, is_connected:", c.is_connected) + svcs = [s.uuid.lower() for s in c.services] + if DFU_SVC not in svcs: + raise RuntimeError("APP nemá DFU službu 1530") + nf = Notif() + await c.start_notify(CP_UUID, nf.cb) # write-authorize vyžaduje notify enabled + try: + await c.write_gatt_char(CP_UUID, bytes([START_DFU]), response=True) + except Exception as e: + log(" (write 0x01 → disconnect, očekávané):", type(e).__name__) + finally: + # write 0x01 uzel odpojí sám, takže disconnect() tu obvykle jen uklízí + try: + await c.disconnect() + except Exception: # noqa: BLE001 + pass + log(" APP odpojen, čekám na reboot bootloaderu...") + await asyncio.sleep(4) + +class ImageDone(Exception): + """Bootloader potvrdil celý image dřív, než smyčka došla na PRN práh.""" + +class ChunkTooBig(Exception): + """Bootloader neodpověděl na první receipt -> nezvládá velké pakety.""" + +async def send_image(c, nf, pkt_char, data, prn=8, chunk=None): + if chunk is None: + mtu = getattr(c, "mtu_size", 23) or 23 + chunk = max(20, mtu - 3) + log(f" posílám image {len(data)} B, chunk {chunk} B, PRN {prn}") + sent = 0 + since_rcpt = 0 + total = len(data) + for off in range(0, total, chunk): + piece = data[off:off+chunk] + await c.write_gatt_char(pkt_char, piece, response=False) + sent += len(piece) + since_rcpt += 1 + if prn and since_rcpt >= prn: + since_rcpt = 0 + # počkej na receipt [0x11, <4B received>] + while True: + try: + d = await nf.wait(60) + except asyncio.TimeoutError: + # Ticho po PRVNÍ skupině = bootloader ty pakety vůbec + # nepobral. Není to congestion, ale velikost: legacy DFU + # (SDK 11) na některých bootloaderech bere jen 20 B, a když + # BlueZ vyjedná MTU 247, posíláme 244 B a přenos umře pod + # 48 kB. Pozorováno: XIAO nRF52840 (AdaDFU, MTU 247) padá, + # SenseCap Solar (AdaDFU, MTU zůstane 23) i mast-three + # (SCAP_DFU na MAC+1, MTU 247) jedou. Volající to zkusí + # znovu s 20 B. + if sent <= prn * chunk and chunk > 20: + raise ChunkTooBig() + raise + if d and d[0] == PKT_RCPT: + got = struct.unpack(" 3 else "" + skip_phase1 = mode == "phase2" + + # `phase1` = jen prepni uzel do bootloaderu a skonci. Ma to smysl u desky, + # ktera je zaroven na USB: BLE OTA trva jednotky az patnact minut podle MTU, + # kdezto po USB je to ~20 s. BLE se tedy pouzije jen na to, na co USB nestaci + # -- companion build nema textovou konzoli, takze `dfu` prikazem ho tam + # neposles. Tuhle kombinaci pouziva tools/flash_node.sh. + if mode == "phase1": + await phase1_buttonless(mac) + log("== uzel je v bootloaderu; flash dokonci volajici (napr. po USB) ==") + return + z = zipfile.ZipFile(zippath) + fw_bin = z.read("firmware.bin") + fw_dat = z.read("firmware.dat") + log(f"firmware.bin {len(fw_bin)} B, firmware.dat {len(fw_dat)} B, cíl {mac}") + + # STALENESS GUARD. `pio run` builds firmware.zip, `pio run -t create_uf2` + # builds firmware.uf2, and NEITHER refreshes the other. Flashing one board + # from the .zip and another from the .uf2 then silently gives them different + # firmware -- that is how x3 ended up 50 min behind the rest of the fleet, + # missing a command the others had. firmware.elf is relinked by every build, + # so it is the reference. + elf = os.path.join(os.path.dirname(os.path.abspath(zippath)), "firmware.elf") + if os.path.exists(elf) and os.path.getmtime(elf) > os.path.getmtime(zippath): + sys.exit(f"CHYBA: {os.path.basename(zippath)} je STARŠÍ než firmware.elf — " + f"nalil bys starý obraz.\n" + f" Sprav: pio run -e && pio run -e -t create_uf2") + # Put the version on the record BEFORE it lands on the board, not after. + m = re.search(rb"v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]+\+?", fw_bin) + if m: + log(f" verze v obrazu: {m.group(0).decode()}") + if skip_phase1: + log("== FÁZE 1 přeskočena (uzel už v bootloaderu) ==") + else: + await phase1_buttonless(mac) + # BLE DFU je flaky — přenos občas spadne uprostřed (dropnutá receipt notif). + # Auto-retry: po pádu vyresetuj bootloader do IDLE a zkus phase2 znovu. + ATTEMPTS = 6 + chunk = None # None = mtu-3; prepne se na 20 po ChunkTooBig + for i in range(ATTEMPTS): + try: + await phase2_dfu(mac, fw_bin, fw_dat, chunk=chunk) + return # hotovo + except ChunkTooBig: + # Tenhle bootloader nebere mtu-3 velke pakety. Nejde to zachranit + # v behu -- START_DFU podruhe vrati status 2 (INVALID_STATE) -- + # takze RESET, nove spojeni a znovu, natvrdo po 20 B. + log("!! bootloader nezvlada velke pakety -> opakuji s 20 B") + chunk = 20 + await recover_to_bootloader(mac) + except Exception as e: + log(f"!! DFU pokus {i+1}/{ATTEMPTS} selhal: {type(e).__name__}: {str(e)[:80]}") + if i == ATTEMPTS - 1: + raise + await recover_to_bootloader(mac) + +if {"-h", "--help"} & set(sys.argv[1:]): + print(__doc__.strip()) + sys.exit(0) +asyncio.run(main()) diff --git a/tools/ble_flash_node.sh b/tools/ble_flash_node.sh new file mode 100755 index 00000000..dd5772d2 --- /dev/null +++ b/tools/ble_flash_node.sh @@ -0,0 +1,259 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MIT +# Ostrý flash MeshCore uzlu přes BLE OTA, celý postup na jeden příkaz. +# +# Existuje proto, že samotné `ble_dfu.py` je jen přenos obrazu. Kolem něj je +# pokaždé stejných šest věcí, a každá z nich už jednou něco stála: +# +# 1. ČISTÝ STROM. Verze ze špinavého stromu má `+` a na stožáru pak nepoznáš, +# co na uzlu je. Skript odmítne pokračovat. +# 2. PŘEDLETOVÁ KONTROLA prefs. Prefs v InternalFS přebíjejí build flagy a +# flash je NEPŘEPÍŠE — takže se musí přečíst PŘED i PO a porovnat. +# 3. TICHO u uzlu s odpojenou antenou (`--require-silence`). Vysílání do +# odpojené antény poškozuje PA; build je mlčící z konstrukce, ale prefs to +# přebijou, takže se ticho ověřuje na uzlu, ne v ini. +# 4. UVOLNĚNÍ LINKU. Zastavit službu (most) NESTAČÍ, spojení drží BlueZ. +# 5. OVĚŘENÍ VERZE proti obrazu, ne "vypadá to dobře". +# 6. VRÁCENÍ SLUŽBY do provozu a kontrola, že zase teče. +# +# Použití: +# tools/ble_flash_node.sh --env SenseCap_Solar_repeater --mac AA:BB:CC:DD:EE:10 \ +# --require-silence +# +# tools/ble_flash_node.sh --env SenseCap_Solar_repeater \ +# --mac AA:BB:CC:DD:EE:11 --via gateway-host \ +# --python /opt/ble-bridge/venv/bin/python \ +# --stop-service ble-bridge.service +# +# --check-only jen přečte stav uzlu a skončí (nic nemění, nic neflashuje) +# +# `--via` flashuje ze vzdáleného hostu, protože BLE má metry: mast-three je +# v dosahu bridge-host, ne pracovní stanice. Nic se tam neinstaluje — použije se +# python, který na hostu už je (`--python`). +set -euo pipefail + +ENV_NAME="" +MAC="" +VIA="" +PY="python3" +STOP_SVC="" +REQUIRE_SILENCE=0 +CHECK_ONLY=0 +REPO="$(cd "$(dirname "$(readlink -f "$0")")/.." && pwd)" + +while [ $# -gt 0 ]; do + case "$1" in + --env) + ENV_NAME="$2" + shift 2 + ;; + --mac) + MAC="$2" + shift 2 + ;; + --via) + VIA="$2" + shift 2 + ;; + --python) + PY="$2" + shift 2 + ;; + --stop-service) + STOP_SVC="$2" + shift 2 + ;; + --require-silence) + REQUIRE_SILENCE=1 + shift + ;; + --check-only) + CHECK_ONLY=1 + shift + ;; + -h | --help) + sed -n '3,33p' "$0" + exit 0 + ;; + *) + echo "neznámý argument: $1" >&2 + exit 2 + ;; + esac +done +[ -n "$MAC" ] || { + echo "chybí --mac" >&2 + exit 2 +} +[ -n "$ENV_NAME" ] || [ "$CHECK_ONLY" = 1 ] || { + echo "chybí --env" >&2 + exit 2 +} + +PIO="${PIO:-$HOME/.platformio/penv/bin/pio}" +CLI_CMDS=(ver "get name" "get repeat" "get advert.interval" "get flood.advert.interval" "get freq") + +# Konzole uzlu: buď lokálně, nebo na hostu z --via (tam se nahrají nástroje). +# timeout: ble_cli.py sám žádný nemá. 27. 9. 2026 na mast-three visel připojený +# a hluchý 35 minut, most celou dobu stál a flash se k DFU vůbec nedostal. +NODE_CLI_TIMEOUT=${NODE_CLI_TIMEOUT:-180} +node_cli() { + if [ -n "$VIA" ]; then + # shellcheck disable=SC2029 + ssh "$VIA" "timeout $NODE_CLI_TIMEOUT $PY /tmp/ble_cli.py $MAC $(printf '%q ' "$@")" 2>/dev/null + else + timeout "$NODE_CLI_TIMEOUT" "$PY" "$REPO/tools/ble_cli.py" "$MAC" "$@" 2>/dev/null + fi +} + +pref() { grep -E "^$1[[:space:]]" <<<"$2" | cut -f2- | tr -d '\r'; } + +if [ -n "$VIA" ]; then + scp -q -p "$REPO/tools/ble_cli.py" "$VIA:/tmp/" || { + echo "scp ble_cli.py selhalo" >&2 + exit 1 + } +fi + +# Uvolnit link MUSÍ být PŘED předletovou kontrolou: když linku drží most, na +# konzoli se nedostaneš ani ty. A když cokoli dál selže, služba se musí vrátit +# do provozu — proto trap, ne "restart na konci". +SVC_STOPPED=0 +restore_svc() { + [ "$SVC_STOPPED" = 1 ] || return 0 + echo "== vracím $STOP_SVC ==" >&2 + ssh "$VIA" "systemctl start $STOP_SVC" >/dev/null 2>&1 || true + SVC_STOPPED=0 +} +trap restore_svc EXIT + +if [ -n "$STOP_SVC" ] && [ "$CHECK_ONLY" = 0 ]; then + echo "== uvolnění linku ($STOP_SVC) ==" + # Zastavit službu NESTAČÍ — spojení drží BlueZ, další připojení pak selže. + ssh "$VIA" "systemctl stop $STOP_SVC; bluetoothctl disconnect $MAC >/dev/null 2>&1 || true; sleep 3" + SVC_STOPPED=1 +fi + +echo "== stav uzlu $MAC ==" +BEFORE="$(node_cli "${CLI_CMDS[@]}")" || { + echo "uzel neodpovídá na BLE konzoli" >&2 + exit 1 +} +echo "$BEFORE" | sed 's/^/ /' + +V_BEFORE="$(pref ver "$BEFORE")" +REPEAT_BEFORE="$(pref 'get repeat' "$BEFORE")" +ADV_BEFORE="$(pref 'get advert.interval' "$BEFORE")" +FADV_BEFORE="$(pref 'get flood.advert.interval' "$BEFORE")" + +if [ "$REQUIRE_SILENCE" = 1 ]; then + if [ "$ADV_BEFORE" != "0" ] || [ "$FADV_BEFORE" != "0" ] || [ "$REPEAT_BEFORE" != "off" ]; then + cat >&2 <&2 + echo " by pak nešlo poznat, co na něm je. Commitni, nebo stashni." >&2 + exit 1 +fi +(cd "$REPO" && "$PIO" run -e "$ENV_NAME" >/dev/null) || { + echo "build selhal" >&2 + exit 1 +} +ZIP="$REPO/.pio/build/$ENV_NAME/firmware.zip" +ELF="$REPO/.pio/build/$ENV_NAME/firmware.elf" +# Bez roury schválně. `strings "$ELF" | grep -m1 ...` tady padalo na SIGPIPE +# (exit 141): grep po prvním nálezu rouru zavře, `strings` ji dostane a +# `set -o pipefail` z toho udělá pád celého skriptu -- uprostřed flashe, se +# zastaveným mostem. Je to race, takže to roky procházelo; spuštěné hned po +# `pio run` ale selhalo 3/3 (21. 9. 2026, mast-three, dvakrát v ostrém běhu). +# `grep -a` čte ELF přímo, žádná roura = není co zavřít. +# `|| true`, protože skript běží pod `set -e`: bez toho by neúspěšný grep +# skript ukončil rovnou na tomhle přiřazení a STOP hláška o dva řádky níž by +# se nikdy nevypsala — operátor by dostal holý nenulový exit uprostřed flashe, +# klidně už se zastaveným mostem. +V_EXPECT="$(grep -m1 -aoE 'v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]*\+?' "$ELF" || true)" +# `grep -m1 -o` zastaví po prvním ŘÁDKU, ale vypíše z něj VŠECHNY shody. ELF +# má .rodata oddělenou nulami bez newline, takže dvakrát vražený literál verze +# dá dvouřádkový V_EXPECT, porovnání s `ver` z uzlu pak nesedí a povedený OTA +# se ohlásí jako chyba. Necháváme první řádek. +V_EXPECT="${V_EXPECT%%$'\n'*}" +[ -n "$V_EXPECT" ] || { + echo "STOP: v obrazu není stampovaná verze (env bez stampingu?)" >&2 + exit 1 +} +echo " obraz: $V_EXPECT ($(stat -c%s "$ZIP") B)" +echo " na uzlu teď: $V_BEFORE" + +echo "== DFU ==" +if [ -n "$VIA" ]; then + scp -q -p "$ZIP" "$REPO/tools/ble_dfu.py" "$VIA:/tmp/" + ssh "$VIA" "cd /tmp && nohup timeout 1500 $PY /tmp/ble_dfu.py /tmp/firmware.zip $MAC > /tmp/dfu_$MAC.log 2>&1 &" || true + until ssh "$VIA" "grep -qE 'HOTOVO|SELHALO|Traceback' /tmp/dfu_$MAC.log" 2>/dev/null; do sleep 20; done + ssh "$VIA" "tail -4 /tmp/dfu_$MAC.log" | sed 's/^/ /' + ssh "$VIA" "grep -q HOTOVO /tmp/dfu_$MAC.log" || { + echo "DFU SELHALO — zotavení: ble_dfu.py … phase2" >&2 + exit 1 + } +else + "$PY" "$REPO/tools/ble_dfu.py" "$ZIP" "$MAC" | tail -4 | sed 's/^/ /' +fi + +echo "== ověření po flashi ==" +for _ in $(seq 1 30); do + sleep 10 + AFTER="$(node_cli "${CLI_CMDS[@]}" || true)" + [ -n "$(pref ver "$AFTER")" ] && break +done +echo "$AFTER" | sed 's/^/ /' + +V_AFTER="$(pref ver "$AFTER")" +FAIL=0 +case "$V_AFTER" in +"$V_EXPECT"*) echo " verze OK" ;; +*) + echo " CHYBA: uzel hlásí '$V_AFTER', čekáno '$V_EXPECT'" >&2 + FAIL=1 + ;; +esac +# Prefs flash nepřepisuje, takže rozdíl = něco je špatně (nebo si je uzel resetoval). +for p in repeat:REPEAT advert.interval:ADV flood.advert.interval:FADV; do + key="${p%%:*}" + var="${p##*:}" + b_var="${var}_BEFORE" + before="${!b_var}" + after="$(pref "get $key" "$AFTER")" + if [ "$before" != "$after" ]; then + echo " CHYBA: $key se změnil: '$before' -> '$after'" >&2 + FAIL=1 + fi +done +[ "$FAIL" = 0 ] && echo " prefs beze změny" + +if [ "$SVC_STOPPED" = 1 ]; then + echo "== vrácení služby ==" + restore_svc + sleep 15 + ssh "$VIA" "systemctl is-active $STOP_SVC" | sed 's/^/ /' + echo " a ověř DATA, ne jen službu:" + echo " ssh $VIA \"journalctl -u $STOP_SVC --since -5min | grep 'full scrape'\"" +fi + +[ "$FAIL" = 0 ] || exit 1 +echo "== HOTOVO: $MAC na $V_AFTER ==" diff --git a/tools/ble_pair.py b/tools/ble_pair.py new file mode 100755 index 00000000..6812ede0 --- /dev/null +++ b/tools/ble_pair.py @@ -0,0 +1,200 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Non-interactive BLE pairing by PIN, driving bluetoothctl over a pty. + +A MeshCore node's console characteristics are SECMODE_ENC_WITH_MITM, so the +first connection to an unpaired node raises a passkey dialog on the desktop -- +useless from a script. This registers its own KeyboardOnly agent and answers +the prompt. + + ble_pair.py AA:BB:CC:DD:EE:10 # one node + ble_pair.py AA:BB:CC:DD:EE:10 hill-rpt # MACs or config board names + +The PIN comes from platformio.local.ini ([secrets] ble_pin) and is never +printed. That is the same value the firmware was built with, so a node whose +PIN does not match here was built from a different tree. + +WHY A SCRIPT, AND WHY STATE-DRIVEN: the first version marched through +bluetoothctl on a fixed schedule and sent `pair` before the agent was +registered. The passkey prompt then went to the default agent and the node +stayed unpaired -- with no error anywhere. Every step here waits for the +output that proves the previous one landed. + +BONDING IS NOT ONLY FOR THE CONSOLE. The buttonless-DFU control point is +declared with the same SECMODE_ENC_WITH_MITM +(`helpers/nrf52/SerialBLEInterface.cpp`), so `ble_dfu.py` phase 1 cannot write +its trigger to an unpaired node either. It fails as a plain write error, which +does not look like "you are not bonded". + +AFTERWARDS, DISCONNECT BEFORE FLASHING. bluetoothctl leaves the node +*connected* once pairing succeeds, and a connected peripheral stops +advertising -- so `ble_dfu.py` immediately fails its scan with "APP nenalezen +ve scanu". Run `bluetoothctl disconnect ` first. + + ble_pair.py && bluetoothctl disconnect && ble_dfu.py fw.zip + +DOCK-QUIET NODES ADVERTISE ONLY WHEN UNDOCKED. On dual USB/BLE companion +builds (T1000-E, Wio L1), BLE advertising is suppressed while a USB host holds +DTR high. Unplug USB, or hold the port open with DTR deasserted, or nothing on +this page will find the node. +""" +import atexit +import os +import pty +import re +import select +import signal +import sys +import time + +INI = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), + "platformio.local.ini") + + +def read_pin(): + # A node built from an env that does not take [secrets] (e.g. a companion env + # that keeps the variant's default BLE_PIN_CODE) needs a different PIN. Give + # it as a FILE, not a value, so it stays out of argv, env dumps and history. + pin_file = os.environ.get("BLE_PIN_FILE") + if pin_file: + with open(pin_file) as fh: + pin = fh.read().strip() + if not pin.isdigit(): + sys.exit(f"BLE_PIN_FILE {pin_file} does not hold a numeric PIN") + return pin + try: + with open(INI) as fh: + lines = fh.readlines() + except FileNotFoundError: + sys.exit(f"{INI} not found -- it holds the real PIN and is git-ignored") + pin = None + for line in lines: # last one wins, same as PlatformIO + m = re.match(r"\s*ble_pin\s*=\s*(\d+)", line) + if m: + pin = m.group(1) + if not pin: + sys.exit(f"no [secrets] ble_pin in {INI}") + return pin + + + +def _mac(key): + """A board name from the local config (tools/mctools_config.py) -> its MAC. + Optional on purpose: ble_flash_node.sh --via copies this file ALONE to a + remote host, where there is no config and a MAC is given anyway.""" + try: + from mctools_config import mac_for + except ImportError: + return key + return mac_for(key) or key + +def main(): + macs = [_mac(m) for m in sys.argv[1:]] + if not macs: + sys.exit(f"usage: {os.path.basename(sys.argv[0])} [MAC...]") + pin = read_pin() + + pid, fd = pty.fork() + if pid == 0: + os.execvp("bluetoothctl", ["bluetoothctl"]) + + def drain(seconds, want=None, mac=None): + """Read for `seconds` (or until `want` matches), answering prompts.""" + end = time.time() + seconds + hit = None + while time.time() < end: + r, _, _ = select.select([fd], [], [], 0.4) + if not r: + continue + try: + chunk = os.read(fd, 4096).decode("utf-8", "replace") + except OSError: + break + clean = re.sub(r"\x1b\[[0-9;?]*[a-zA-Z]", "", chunk) + for ln in clean.splitlines(): + t = ln.strip() + if not t or "RSSI" in t or t.startswith("[NEW] Device"): + continue # scan noise + if pin and pin in t: # bluetoothctl echoes the typed passkey + t = t.replace(pin, "******") + print(" bt|", t[:110], flush=True) + low = clean.lower() + if "passkey" in low or "enter pin" in low or "pin code" in low: + os.write(fd, (pin + "\n").encode()) + print(" -> PIN sent", flush=True) + elif "(yes/no)" in low: + os.write(fd, b"yes\n") + print(" -> confirmed", flush=True) + if want and mac and re.search(want, clean, re.I) and mac in clean: + hit = True + break + if "failed" in low and mac and mac.lower() in low: + hit = False + break + return hit + + def send(cmd, wait=1.5, want=None, mac=None): + os.write(fd, (cmd + "\n").encode()) + print(f"$ {cmd}", flush=True) + return drain(wait, want, mac) + + # ÚKLID MUSÍ PROBĚHNOUT I PŘI ZABITÍ. Registrovaný `default-agent` odpovídá + # na CIZÍ párovací požadavky a `scan on` drží discovery -- když se skript + # zabije uprostřed (stalo se 22. 8. 2026 vlastním `timeout 60`), zůstane + # hostitel v tomhle stavu a začne se chovat jako párovatelné zařízení pro + # okolí. Na notebooku na vzdálené stanoviště z toho vyskočil párovací požadavek na televizi. + def cleanup(*_a): + try: + for c in ("scan off", "pairable off", "discoverable off", + "agent off", "quit"): + os.write(fd, (c + "\n").encode()) + time.sleep(0.4) + except OSError: + pass + + atexit.register(cleanup) + for _sig in (signal.SIGTERM, signal.SIGINT, signal.SIGHUP): + signal.signal(_sig, lambda *_a: sys.exit(130)) + + send("agent KeyboardOnly", 2) + send("default-agent", 2) + failed = [] + for mac in macs: + print(f"===== {mac} =====", flush=True) + send(f"remove {mac}", 3) # a stale bond makes `pair` a no-op + send("scan on", 1) + # ČEKEJ, DOKUD HO SKEN NEUVIDÍ, ne pevných pár sekund. `remove` smaže + # i objevené zařízení, takže `pair` hned poté řekne "Device not + # available" — a to vypadá úplně stejně jako špatný PIN. Repeater navíc + # po 30 s přepne z rychlého advertisingu na pomalý, takže se do krátkého + # okna netrefí. Stálo to 22. 8. 2026 dvě hodiny hledání na dvou hostech. + if drain(45, want=r"Device", mac=mac): + print(" (uzel ve skenu, páruju)", flush=True) + else: + print(f" POZOR: {mac} se za 45 s ve skenu neobjevil — `pair` nejspíš " + f"skončí na 'not available'. Uzel neadvertuje?", flush=True) + ok = send(f"pair {mac}", 45, want=r"Bonded: yes|Pairing successful", mac=mac) + print(f" paired: {ok}", flush=True) + if not ok: + failed.append(mac) + send("scan off", 1) + send(f"trust {mac}", 3) + # `agent off` odregistruje KeyboardOnly agenta -- bez toho by host dál + # odpovídal na cizí párovací požadavky, dokud bluetoothctl neskončí + send("agent off", 1) + send("quit", 1) + os.close(fd) + + if failed: + print("NOT PAIRED: " + ", ".join(failed)) + print("A wrong PIN and a node that stopped advertising look the same " + "here -- check both.") + sys.exit(1) + print("done -- disconnect before running ble_dfu.py") + + +if __name__ == "__main__": + if {"-h", "--help"} & set(sys.argv[1:]): + print(__doc__.strip()) + sys.exit(0) + main() diff --git a/tools/board_probe.py b/tools/board_probe.py new file mode 100755 index 00000000..8926f488 --- /dev/null +++ b/tools/board_probe.py @@ -0,0 +1,433 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Otisk XIAO desek na USB: co na které z nich BĚŽÍ, a jestli se to změnilo. + + tools/board_probe.py --all + tools/board_probe.py --all --compare + tools/board_probe.py --all --compare --expect-changed + +Vzniklo 1. 9. 2026 poté, co `pio run -t upload --upload-port ` ohlásil +FAILED a obraz přistál na **x2**, desce, která na té příkazové řádce nebyla. +Poznat to šlo až po hodině: x2 přestal odpovídat konzoli i companion protokolu +a vypadal jako zaseklý, přitom na něm normálně běžel KISS modem, který ani +jedno z toho nemá. Tři replugy nepomohly a pomoct nemohly. + +Otisk je proto přes VŠECHNY protokoly, které na těch deskách jezdí, ne jen přes +ten, který zrovna čekáme: + + text MeshCore repeater/analyzer `ver` -> v1.17.1-tth... + companion MeshCore companion_radio CMD_DEVICE_QUERY (bez textové konzole) + kiss examples/kiss_modem SetHardware GetVersion (0x11 -> 0x91) + modem openhop_modem port `XIAO-Wio-SX1262`, mlčí na vše + bootloader UF2 port bez "Studio" / se "Sense" + +`modem` a `bootloader` se poznají podle JMÉNA portu, ne podle idProduct: obojí +drží 0044 a AGENTS.md čte 0044 jako bootloader, což pro openhop_modem neplatí. +""" +import argparse +import glob +import multiprocessing +import os +import re +import struct +import sys +import time + +try: + import serial +except ImportError: + sys.exit("chybi pyserial") + +# Kolik sekund nejvys smi trvat otisk CELE sbernice. +# Musi pokryt PLNY cyklus jedne desky: settle 0,9 + text 1,2 + companion 1,5 + +# KISS 1,2 + GetDeviceName 1,2 = ~6 s (zmereno 2. 9. 2026 na x4: 6,4 s, tri behy +# za sebou stejne). S kratsim deadlinem se posledni protokol nestihne a deska se +# oznaci jako "visi", i kdyz normalne odpovida -- presne to se stalo KISS modemu +# na x4 pri BOARD_PROBE_DEADLINE=6. +PROBE_DEADLINE = float(os.environ.get("BOARD_PROBE_DEADLINE", "12")) + + +def usb_boards(): + """[(serial, port, board, state_hint)] pro kazdou desku flotily na USB. + + Typ desky i rezim se poznaji z JMENA portu, protoze idProduct lze -- 0044 + drzi jak UF2 bootloader XIAO, tak openhop_modem, coz je aplikace. A na + T1000-E je to jmeno primo obracene, nez by clovek cekal: + + Seeed_Studio_XIAO_nRF52840_ XIAO, aplikace (MeshCore build) + Seeed_XIAO_nRF52840_Sense_ XIAO, bootloader + Seeed_XIAO-Wio-SX1262_ XIAO, openhop_modem (APLIKACE, ne boot) + Seeed_Studio_T1000-E-BOOT_ T1000-E, APLIKACE <- "-BOOT" ma aplikace! + Seeed_Studio_T1000-E_ T1000-E, bootloader (+ UF2 disk T1000-E) + """ + pats = [ + # (regex na jmeno portu, deska, stav) + (r"Seeed_Studio_T1000-E-BOOT_", "t1000e", "app"), + (r"Seeed_Studio_T1000-E_", "t1000e", "boot"), + (r"Seeed_XIAO-Wio-SX1262_", "xiao", "modem"), + (r"Seeed_Studio_XIAO_nRF52840_", "xiao", "app"), + (r"Seeed_XIAO_nRF52840", "xiao", "boot"), + (r"Wio|TRACKER", "wio-l1", "app"), + ] + out = [] + for port in sorted(glob.glob("/dev/serial/by-id/*")): + name = os.path.basename(port) + m = re.search(r"_([0-9A-F]{16})-if00", name) + if not m: + continue # ESP32 a spol. -- neni to nase nRF52 flotila + for rx, board, state in pats: + if re.search(rx, name): + out.append((m.group(1), port, board, state)) + break + return out + + +def port_busy(dev): + """Drzi ten port jiny proces? Vrati jeho pid, nebo None. + + Sahat na port, ktery uz nekdo ma otevreny, neni jen zbytecne -- je to + SKODLIVE. 2. 9. 2026 tenhle probe otevrel port, na kterem openHop drzel KISS + spojeni; demon zahlasil "multiple access on port", oznacil link za degradovany + a nakonec si RADIO VYPNUL (`Radio is disabled`) a nesl si to v repeater.db, + takze to neresil ani restart kontejneru. Kontrola stavu nesmi rozbit to, co + kontroluje. + + Ctou se /proc/*/fd, takze to nepotrebuje root ani lsof; cizi procesy pod jinym + UID neuvidime, ale docker tady bezi pod nasim (--user $(id -u)), takze ten ano. + """ + try: + real = os.path.realpath(dev) + except OSError: + return None + me = os.getpid() + for pid in os.listdir("/proc"): + if not pid.isdigit() or int(pid) == me: + continue + d = f"/proc/{pid}/fd" + try: + entries = os.listdir(d) + except OSError: + continue + for fd in entries: + try: + if os.path.realpath(f"{d}/{fd}") == real: + return pid + except OSError: + continue + return None + + +def _open(port): + s = serial.Serial(port, 115200, timeout=0) + s.dtr = True + s.rts = True + time.sleep(0.9) + s.reset_input_buffer() + return s + + +def _drain(s, w): + buf, t = b"", time.time() + while time.time() - t < w: + try: + d = s.read(8192) + except Exception: + # "device reports readiness to read but returned no data" -- deska + # se odpojila uprostred cteni. Vracime, co uz mame; neni to duvod + # shodit cely otisk. + break + if d: + buf += d + else: + time.sleep(0.02) + return buf + + +def _kiss_frame(raw, resp_code): + """Vrat KISS ramec zacinajici 0xC0, jehoz treti bajt je `resp_code`. + + Bez tohohle se raw[1]/raw[2] cetly z offsetu 0, tedy z toho, co v bufferu + zbylo po predchozim protokolu -- a odpoved se dala minout i kdyz prisla. + """ + i = -1 + while True: + i = raw.find(bytes([0xC0]), i + 1) + if i < 0: + return raw + fr = raw[i:] + if len(fr) > 4 and fr[1] == 0x06 and fr[2] == resp_code: + return fr + + +def probe(port): + """('text'|'companion'|'kiss'|'nic', verze) -- zkusí protokoly po řadě.""" + try: + s = _open(port) + except Exception as e: + return ("nedostupny", type(e).__name__) + try: + # Prvni prikaz po otevreni portu se casto ztrati, proto to prazdne CRLF. + s.write(b"\r\n") + time.sleep(0.4) + s.reset_input_buffer() + + s.write(b"ver\r\n") + txt = _drain(s, 1.2).decode(errors="replace") + m = re.search(r"(v\d+\.\d+\.\d+-tth[0-9a-f]+\+?)", txt) + if m: + return ("text", m.group(1)) + + s.reset_input_buffer() + s.write(b"<" + struct.pack("' v bufferu. + # Driv stacilo, aby za '>' byly dva bajty a neprazdny zbytek, a vratilo se + # ("companion", "?") -- takze opozdena radka textove konzole nebo + # MESH_DEBUG_PRINTLN se ctla jako companion ramec. flash_node.sh pak + # porovnal "?" s ocekavanou verzi a oznamil "FLASH SE NEAPLIKOVAL" na + # desce, na ktere bezel spravny firmware -- presne ta trida falesne + # diagnozy, kvuli ktere tenhle nastroj vznikl. + # + # Prohledavaji se VSECHNY vyskyty '>' a uzna se jen plnohodnotny + # RESP_DEVICE_INFO (kod 13, aspon 80 B, delka souhlasi s tim, co dorazilo). + i = -1 + while True: + i = raw.find(b">", i + 1) + if i < 0: + break + if len(raw) < i + 3: + continue + ln = struct.unpack("= 80 and fr[0] == 13: # RESP_DEVICE_INFO + return ("companion", fr[60:80].split(b"\0")[0].decode(errors="replace")) + + s.reset_input_buffer() + s.write(bytes([0xC0, 0x06, 0x11, 0xC0])) # KISS GetVersion + raw = _drain(s, 1.2) + # Kotvit na ZACATEK KISS ramce (0xC0), ne na offset 0: pred odpovedi muze + # lezet zbytek predchoziho vystupu a raw[1]/raw[2] by pak cetly cizi bajty. + raw = _kiss_frame(raw, 0x91) + if len(raw) > 4 and raw[1] == 0x06 and raw[2] == 0x91: + # GetVersion (0x11) vrací verzi KISS PROTOKOLU, ne našeho buildu -- + # ta je k nerozeznání mezi dvěma různými firmwary. Stampovaná verze + # jede v GetDeviceName (0x16), viz KissModem::handleGetDeviceName. + s.reset_input_buffer() + s.write(bytes([0xC0, 0x06, 0x16, 0xC0])) # KISS GetDeviceName + nm = _kiss_frame(_drain(s, 1.2), 0x96) + if len(nm) > 4 and nm[1] == 0x06 and nm[2] == 0x96: + txt = nm[3:-1].decode(errors="replace") + m = re.search(r"(v\d+\.\d+\.\d+-tth[0-9a-f]+\+?)", txt) + if m: + return ("kiss", m.group(1)) + return ("kiss", txt.strip() or "?") + # Starší KISS build bez stampované verze v GetDeviceName. + return ("kiss", "proto" + ".".join(str(b) for b in raw[3:-1])) + + return ("nic", "-") + finally: + try: + s.close() + except Exception: + pass + + +def _probe_one(sn, port, board, state): + """Otisk jedne desky. Bezi ve VLASTNIM PROCESU (viz fingerprint).""" + if state in ("boot", "modem"): + # Bootloader nemluvi nasim protokolem a openhop_modem nemluvi vubec; + # ptat se jich je jen ztrata casu (a u boot i riziko, ze to vypada + # jako zaseknuta deska). + return (sn, f"{board}/{state}", "-") + busy = port_busy(port) + if busy: + return (sn, f"{board}/obsazeny", f"drzi pid {busy} -- nesaham") + kind, ver = probe(port) + return (sn, f"{board}/{kind}", ver) + + +def _worker(i, sn, port, board, state, q): + try: + q.put((i,) + _probe_one(sn, port, board, state)) + except Exception as e: # nikdy nenech potomka umrit potichu + q.put((i, sn, f"{board}/chyba", type(e).__name__)) + + +def fingerprint(): + """Otisk cele sbernice. Paralelne -- porty jsou nezavisle a serazovat je za + sebe se necetlo: pet desek po ~9 s (settle + tri protokoly, u mlcicich desek + plny timeout) delalo pres dve minuty, coz je na kontrolu spoustenou PRED a PO + kazdym flashem moc. Poradi vysledku je dane vstupem, ne dobehem. + + KAZDA DESKA VE VLASTNIM PROCESU, ne ve vlakne. Puvodni verze mela daemon + vlakna a tvrdy deadline, jenze `serial.Serial()` umi na nereagujici desce + viset v open(2) UVNITR C kodu, ktery NEPOUSTI GIL -- takze jedna zaseklá + deska zmrazila i vsechny ostatni probe vlakna a ta pak deadline nestihla. + Projev: 2. 9. 2026 hlasil x4 (zdravy KISS modem, sam o sobe 6,4 s) + "visi neodpovida v case" pri deadline 12 s, zatimco cely beh trval 42 s. + Diagnoza "deska neodpovida" na desce, ktera odpovida, je horsi nez zadna. + + Proces se da terminate() i uprostred blokujiciho open(2), takze deadline + plati doopravdy a zbytek flotily se otiskne v normalnim case. + + "visi" u T1000-E NENI diagnoza desky. Obe karty (B3F160.., B612AE..) visi + v serial.Serial() open(2) i pres 60 s, kazda samostatne ve vlastnim procesu + (zmereno 2. 9. 2026) -- pyserial se z nich otisk proste nedozvi a zvysovani + deadlinu s tim nic neudela. Deska pritom muze byt uplne v poradku; na + T1000-E se pta textova konzole primo, ne tenhle nastroj.""" + boards = usb_boards() + rows = [None] * len(boards) + if not boards: + return [] + + ctx = multiprocessing.get_context("fork") # fork: potomek zdedi uz nactene moduly + q = ctx.Queue() + procs = [] + for i, (sn, port, b, st) in enumerate(boards): + p = ctx.Process(target=_worker, args=(i, sn, port, b, st, q), daemon=True) + p.start() + procs.append(p) + + deadline = time.time() + PROBE_DEADLINE + got = 0 + while got < len(boards) and time.time() < deadline: + try: + i, sn, kind, ver = q.get(timeout=max(0.05, deadline - time.time())) + except Exception: + break + rows[i] = (sn, kind, ver) + got += 1 + + for p in procs: + if p.is_alive(): + p.terminate() # utne i blokujici open(2) + for p in procs: + p.join(timeout=1.0) + # SIGKILL na to, co terminate() neslozilo. main() konci `os._exit`, ktery + # obchazi atexit handler multiprocessingu -- prezivsi potomek by tedy zustal + # bezet A DRZET SERIOVY PORT, takze dalsi beh (flash_node.sh pousti probe + # tretkrat za flash) by tu desku ohlasil jako `obsazeny drzi pid `: + # nastroj obvinujici vlastni pozustatky. + for p in procs: + if p.is_alive(): + p.kill() + for p in procs: + p.join(timeout=0.5) + + for i, (sn, _, board, _) in enumerate(boards): + if rows[i] is None: + rows[i] = (sn, f"{board}/visi", "neodpovida v case") + return [r for r in rows if r] + + +def _parse_pairs(path): + """[(serial, (kind, verze))] z otisku. Verze muze obsahovat mezery (starsi + KISS build vraci "Seeed Xiao-nrf52"), takze split(None, 2) -- split() na tri + pole by zbytek utnul a porovnani by hlasilo ZMENU tam, kde se nic nezmenilo. + + Radek s PRAZDNOU verzi se NEZAHAZUJE. Driv to filtroval `len(p) >= 3`, takze + deska, u ktere probe verzi nevyplnil, z predchoziho otisku zmizela a pak se + ohlasila jako "ZMIZELA z USB" -- falesny poplach o desce, ktera tam celou dobu + byla. + """ + out = [] + for line in open(path): + if not line.strip(): + continue + p = line.split(None, 2) + if len(p) < 2: + continue + out.append((p[0], (p[1], p[2].strip() if len(p) > 2 else ""))) + return out + + +def _parse(path): + return [(sn, k, v) for sn, (k, v) in _parse_pairs(path)] + + +def fmt(rows): + return "\n".join(f"{sn} {kind} {str(ver).strip()}" for sn, kind, ver in rows) + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--all", action="store_true") + ap.add_argument("--compare", help="soubor s predchozim otiskem") + ap.add_argument("--now", help="soubor s AKTUALNIM otiskem (jinak se sbernice" + " otiskne znovu)") + ap.add_argument("--expect-changed", help="seriak, ktery se zmenit MA") + a = ap.parse_args() + + # --now existuje proto, aby volajici, ktery uz otisk ma, nemusel platit dalsi + # probe (az PROBE_DEADLINE) -- a hlavne aby verdikt o zmenach a jeho vlastni + # kontrola verze vychazely z TEHOZ vzorku sbernice, ne ze dvou ruznych. + rows = _parse(a.now) if a.now else fingerprint() + now = {sn: (k, v) for sn, k, v in rows} + + if not a.compare: + print(fmt(rows)) + return 0 + + prev = dict(_parse_pairs(a.compare)) + + bad = False + for sn in sorted(set(prev) | set(now)): + was, is_ = prev.get(sn), now.get(sn) + tag = "" + if was != is_: + # Poradi je zamerne: deska, ktera ZMIZELA, neni uspech ani kdyz je to + # cil. Po flashi se to na tehle lavici stava bezne a hlaska "zmeneno + # (cil)" by to zakryla -- pritom se z desky nedá precist, co na ni je, + # takze flash NENI overeny. Chce to replug a spustit znovu. + if is_ is None: + tag = " <- ZMIZELA z USB (po flashi bezne) -- replug a spust znovu" + bad = True + elif was is None: + tag = " <- NOVA deska na sbernici" + elif (a.expect_changed + and sn.endswith(a.expect_changed.upper()) + and len([x for x in set(prev) | set(now) + if x.endswith(a.expect_changed.upper())]) == 1): + tag = " <- zmeneno (cil)" + else: + tag = " <- !!! ZMENENO, PRESTOZE TO NEBYL CIL !!!" + bad = True + print(f" {sn} {was[0] if was else '-':10s} {was[1] if was else '-':22s}" + f" -> {is_[0] if is_ else '-':10s} {is_[1] if is_ else '-':22s}{tag}") + + if a.expect_changed: + want = a.expect_changed.upper() + hits = [x for x in sorted(set(prev) | set(now)) if x.endswith(want)] + if len(hits) > 1: + # Kratky suffix umi sednout na vic seriaku; driv se vzal jeden podle + # poradi ve slovniku, takze "zmeneno (cil)" mohlo omluvit ZMENU NA JINE + # DESCE. + print(f"\n{a.expect_changed} sedi na {len(hits)} desky ({', '.join(hits)})" + f" -- upresni seriove cislo, jinak nejde rict, ktera se zmenit mela.") + bad = True + elif not hits: + # Driv: cil chybel v obou otiscich -> smycka ho nikdy nenavstivila, + # `bad` zustalo False a beh skoncil "ok, zmenil se jen cil". Otisk, + # ve kterem cil nikdy nikdo nevidel, neni uspech. + print(f"\nCIL {a.expect_changed} NENI V ZADNEM z otisku -- neni z ceho" + f" rict, ze se zmenil. Sedi to seriove cislo?") + bad = True + elif prev.get(hits[0]) == now.get(hits[0]): + print(f"\nCIL {a.expect_changed} SE NEZMENIL -- flash se neaplikoval," + f" i kdyby nastroj hlasil uspech.") + bad = True + + print("\nVERDIKT:", "PROBLEM (viz vys)" if bad else "ok, zmenil se jen cil") + return 1 if bad else 0 + + +if __name__ == "__main__": + rc = main() + # os._exit misto sys.exit: vlakno, ktere visi v serial.Serial() open(2), + # drzi otevreny file descriptor a interpret na nej pri uklidu ceka -- otisk + # se vypsal za par sekund, ale proces dobihal jeste ~30 s (a pod `timeout` + # se tvaril jako zaseknuty). Vysledek uz je venku, uklizet nemame co. + sys.stdout.flush() + sys.stderr.flush() + os._exit(rc) diff --git a/tools/build_version.py b/tools/build_version.py index 5b80deea..3b3e54f6 100644 --- a/tools/build_version.py +++ b/tools/build_version.py @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MIT # CUSTOM (TeTeHacko): real version and build timestamp for the `ver` command. # # WIRE THIS INTO EVERY ENV WE FLASH. Without it the node reports the fallback @@ -18,6 +19,15 @@ # Import("env") has to come first, hence the file-wide ruff exemption. # ruff: noqa: F821, E402 # mypy: disable-error-code="name-defined" +if __name__ == "__main__": # run by hand (--help): the header above, nothing else + with open(__file__) as _f: + for _ln in _f: + if not _ln.startswith("#"): + break + if "SPDX-License-Identifier" not in _ln: + print(_ln[2:].rstrip() if _ln.startswith("# ") else "") + raise SystemExit(0) + Import("env") import re import subprocess diff --git a/tools/companion_backup.py b/tools/companion_backup.py new file mode 100755 index 00000000..c72bdd4e --- /dev/null +++ b/tools/companion_backup.py @@ -0,0 +1,260 @@ +#!/usr/bin/python +# SPDX-License-Identifier: MIT +"""Záloha companionu (L1, karta) přes companion protokol PŘED flashem. + + tools/companion_backup.py /dev/serial/by-id/usb-...L1... L1-pre-flash + tools/companion_backup.py --diff ~/.local/share/meshcore-backups/.json + tools/companion_backup.py # místo portu MAC = přes BLE (bond nutný) + +Uloží self_info (jméno, rádio, poloha, path hash…), device query, custom vars, +kontakty a kanály do ~/.local/share/meshcore-backups/-.json (0600 — +jsou v tom klíče kanálů). Na stdout nic tajného, jen souhrn; `--diff` porovná se +starší zálohou (po flashi), klíče kanálů porovnává jen jako shodu. + +Solo navíc vystavuje nastavení přes companion CLI (`keys`, `get`, `set`; +ui-core/SettingsCli.h): záloha je uloží všechna do sekce `cli` a `--restore` +je vrátí. Live Share cíl/zapnutí/scope (`share.to`, `share.on`, `share.scope`) +umí CLI až od solo-tth s tímhle doplňkem — 16. 10. 2026 po v2.0 skončil Live +Share na kanálu Public a nebylo jak to zjistit. Co CLI nezná (bot, část UI), +musí po flashi zkontrolovat člověk na zařízení. + +Hodiny flash nepřežijí (L1 22. 10. 2026 po v2.0.1 o 10 h pozadu), proto +`--diff` (= běh po flashi) a samostatné `--sync-time` nastaví čas hostu +(CMD_SET_DEVICE_TIME — lokální příkaz po USB, nic nevysílá). Firmware čas +dozadu odmítne; uzel napřed se jen ohlásí. + + tools/companion_backup.py L1-post --restore .json # jen ukáže + tools/companion_backup.py L1-post --restore .json --apply # zapíše + +`--restore` Live Share nikdy NEZAPNE (to je vysílání do meshe) — jen vypne, +když bylo v záloze vypnuté; zapnout ho je na člověku. Privátní klíč přes USB náš firmware nevydá +(`private_key_export_disabled`), záloha identity je ve vaultu (keys.yml). + +Spouští se interpretem meshcli (#!/usr/bin/python), tam je knihovna meshcore. +Knihovna shazuje DTR a L1 bez DTR na USB mlčí ⇒ _dtr_on() + cx_dly=1,5 s. +Když je k L1 připojený telefon přes BLE, USB mlčí — vypni na telefonu BT. +""" +import argparse +import asyncio +import datetime as dt +import json +import os +import re +import sys +import time + +if {"-h", "--help"} & set(sys.argv[1:]): + print(__doc__.strip()) + sys.exit(0) + +from meshcore import EventType, MeshCore # noqa: E402 + +DIR = os.path.expanduser("~/.local/share/meshcore-backups") + + +def plain(x): + if isinstance(x, (bytes, bytearray)): + return x.hex() + if isinstance(x, dict): + return {str(k): plain(v) for k, v in x.items()} + if isinstance(x, (list, tuple)): + return [plain(v) for v in x] + return x + + +def _dtr_on(): + """Knihovna meshcore po otevření portu SHAZUJE DTR (serial_cx.connection_made: + `dtr = False`, kvůli deskám, které DTR resetuje). Solo DualSerialInterface ale + bez DTR na USB neposlouchá — odtud „No response … serial companion?“ u + meshcli na L1. Proto DTR po otevření zase nahodit.""" + from meshcore import serial_cx + proto = serial_cx.SerialConnection.MCSerialClientProtocol + orig = proto.connection_made + + def connection_made(self, transport): + orig(self, transport) + if getattr(transport, "serial", None): + transport.serial.dtr = True + proto.connection_made = connection_made + + +async def connect(port): + # a BLE MAC instead of a port: a companion that is not on USB here (the + # probe card sits on another host, reachable over BLE only) + ble = re.fullmatch(r"([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}", port) is not None + if not ble: + _dtr_on() + for attempt in range(4): + try: + if ble: + mc = await MeshCore.create_ble(port, default_timeout=8) + else: + mc = await MeshCore.create_serial(port, 115200, default_timeout=8, cx_dly=1.5) + if mc and mc.self_info: + return mc + if mc: + await mc.disconnect() + except (OSError, asyncio.TimeoutError, ConnectionError) as e: + print(f"pokus {attempt + 1}: {e}", file=sys.stderr) + await asyncio.sleep(2 + attempt * 2) + sys.exit("companion neodpovídá (připojený telefon přes BLE? po flashi chvíli počkej)") + + +async def cli(mc, cmd): + ev = await mc.commands.run_cli_command(cmd) + return ev.payload.get("text", "").strip() if ev.type == EventType.CLI_REPLY else None + + +async def cli_settings(mc): + """Všechny klíče z `keys` (po stránkách) a jejich hodnoty z `get`; None, když + firmware Solo CLI nemá (upstream companion: „Unknown command“).""" + keys, page = [], 1 + while page < 20: + r = await cli(mc, "keys" if page == 1 else f"keys {page}") + if not r or r.startswith(("Unknown", "Error", "No more")): + break + more = "(more: keys" in r + keys += r.split(" (more:")[0].split() + if not more: + break + page += 1 + if not keys: + return None + out = {} + for k in keys: + r = await cli(mc, f"get {k}") + out[k] = r[2:] if r and r.startswith("> ") else r + return out + + +RESTORE_FIRST = ["share.to", "share.scope"] # cíl dřív než cokoli, co by vysílalo + + +async def restore(mc, saved, apply): + cur = await cli_settings(mc) or {} + order = [k for k in RESTORE_FIRST if k in saved] + [k for k in saved if k not in RESTORE_FIRST] + plan = [] + for k in order: + v = saved[k] + if v is None or cur.get(k) == v or k not in cur: + continue + if k == "share.on" and v == "on": + plan.append((k, v, "PŘESKOČENO — zapnutí Live Share vysílá, zapni ho na zařízení")) + continue + plan.append((k, v, (await cli(mc, f"set {k} {v}")) if apply else "(--apply zapíše)")) + return plan + + +async def node_offset(mc): + ev = await mc.commands.get_time() + return ev.payload["time"] - int(time.time()) if ev.type == EventType.CURRENT_TIME else None + + +async def sync_clock(mc): + before = await node_offset(mc) + ev = await mc.commands.set_time(int(time.time())) + return {"before_s": before, "set": ev.type == EventType.OK, "after_s": await node_offset(mc)} + + +async def backup(port, restore_from=None, apply=False, sync=False): + mc = await connect(port) + out = {"taken_at": dt.datetime.now().astimezone().isoformat(timespec="seconds"), "port": port, + "self_info": plain(mc.self_info)} + ev = await mc.commands.send_device_query() + out["device"] = plain(ev.payload) if ev.type != EventType.ERROR else None + ev = await mc.commands.get_custom_vars() + out["custom_vars"] = plain(ev.payload) if ev.type != EventType.ERROR else None + ev = await mc.commands.get_contacts() + out["contacts"] = plain(ev.payload) if ev.type != EventType.ERROR else None + chans = [] + for i in range(40): + ev = await mc.commands.get_channel(i) + if ev.type == EventType.ERROR: + break + chans.append(plain(ev.payload)) + out["channels"] = chans + out["cli"] = await cli_settings(mc) + plan = await restore(mc, restore_from, apply) if restore_from else None + if plan and apply: + out["cli"] = await cli_settings(mc) + out["clock"] = await sync_clock(mc) if sync else {"before_s": await node_offset(mc)} + await mc.disconnect() + return out, plan + + +def summary(b): + si = b["self_info"] + used = [c for c in b["channels"] if c.get("channel_name")] + return (f"{si.get('name')} pubkey {str(si.get('public_key'))[:8]} · {si.get('radio_freq')}/{si.get('radio_bw')}/" + f"SF{si.get('radio_sf')}/CR{si.get('radio_cr')} · fw {(b.get('device') or {}).get('ver')} · " + f"{len(b.get('contacts') or {})} kontaktů · kanály: " + + ", ".join(f"{c.get('channel_idx')}={c.get('channel_name')}" for c in used)) + + +def diff(old, new): + keys = sorted(set(old["self_info"]) | set(new["self_info"])) + d = [f"self_info.{k}: {old['self_info'].get(k)} → {new['self_info'].get(k)}" + for k in keys if old["self_info"].get(k) != new["self_info"].get(k)] + if old.get("custom_vars") != new.get("custom_vars"): + d.append(f"custom_vars: {old.get('custom_vars')} → {new.get('custom_vars')}") + oc = {c["channel_idx"]: c for c in old["channels"]} + for c in new["channels"]: + o = oc.get(c["channel_idx"], {}) + if o.get("channel_name") != c.get("channel_name") or o.get("channel_secret") != c.get("channel_secret"): + d.append(f"kanál {c['channel_idx']}: {o.get('channel_name')} → {c.get('channel_name')}" + + (" (jiný klíč)" if o.get("channel_secret") != c.get("channel_secret") else "")) + oc, nc = old.get("cli") or {}, new.get("cli") or {} + for k in sorted(set(oc) | set(nc)): + if oc.get(k) != nc.get(k): + d.append(f"cli {k}: {oc.get(k)} → {nc.get(k)}") + ok, nk = set(old.get("contacts") or {}), set(new.get("contacts") or {}) + if ok != nk: + d.append(f"kontakty: −{len(ok - nk)} +{len(nk - ok)}") + return d + + +def main(): + ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + ap.add_argument("port", help="/dev/serial/by-id/... nebo BLE MAC") + ap.add_argument("name", help="jméno zálohy, např. L1-pre-flash") + ap.add_argument("--diff", metavar="JSON", help="porovnat se starší zálohou") + ap.add_argument("--restore", metavar="JSON", help="vrátit nastavení z CLI sekce zálohy (bez --apply jen ukáže)") + ap.add_argument("--apply", action="store_true", help="s --restore opravdu zapsat") + ap.add_argument("--sync-time", action="store_true", help="nastavit čas hostu (s --diff automaticky)") + a = ap.parse_args() + saved = None + if a.restore: + with open(os.path.expanduser(a.restore)) as f: + saved = json.load(f).get("cli") + if not saved: + sys.exit(f"{a.restore}: záloha nemá sekci cli (starší skript nebo firmware bez Solo CLI)") + b, plan = asyncio.run(backup(a.port, saved, a.apply, a.sync_time or bool(a.diff))) + os.makedirs(DIR, mode=0o700, exist_ok=True) + path = os.path.join(DIR, f"{a.name}-{dt.datetime.now().astimezone().date()}.json") + fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600) + with os.fdopen(fd, "w") as f: + json.dump(b, f, ensure_ascii=False, indent=1) + print(f"záloha: {path}\n{summary(b)}") + if b["cli"] is not None: + sh = {k: v for k, v in b["cli"].items() if k.startswith("share.")} + print(f"CLI: {len(b['cli'])} klíčů; Live Share: " + ", ".join(f"{k}={v}" for k, v in sh.items())) + else: + print("CLI: firmware Solo CLI nemá — Solo prefs zkontroluj na zařízení") + c = b["clock"] + if "set" not in c: + print(f"hodiny: odchylka {c['before_s']:+} s" if c["before_s"] is not None else "hodiny: nepřečteny") + elif c["set"]: + print(f"hodiny: odchylka {c['before_s']:+} s → srovnáno ({c['after_s']:+} s)") + else: + print(f"hodiny: odchylka {c['before_s']:+} s → firmware nastavení odmítl (čas dozadu?)") + if plan is not None: + print("\nobnova z " + a.restore + ":\n" + ("\n".join(f"- set {k} {v} → {r}" for k, v, r in plan) + if plan else "- nic, vše sedí")) + if a.diff: + with open(os.path.expanduser(a.diff)) as f: + d = diff(json.load(f), b) + print("\nrozdíly proti " + a.diff + ":\n" + ("\n".join("- " + x for x in d) if d else "- žádné")) + + +if __name__ == "__main__": + main() diff --git a/tools/config.example.ini b/tools/config.example.ini new file mode 100644 index 00000000..15688a34 --- /dev/null +++ b/tools/config.example.ini @@ -0,0 +1,32 @@ +; SPDX-License-Identifier: MIT +; Config of the MeshCore tools -- copy to ~/.config/meshcore-tools/config.ini +; (or point $MESHCORE_TOOLS_CONFIG at it) and describe YOUR boards. +; Format and the shell interface: tools/mctools_config.py --help. +; No secrets here: admin passwords stay in platformio.local.ini. + +; A bench board on USB: tools take `b1` (or `1`) instead of the serial number. +[board.b1] +serial = 0123456789ABCDEF +mac = AA:BB:CC:DD:EE:01 +aliases = 1 +role = bench + +; A board that keeps an identity you do not want overwritten by accident: +; flash_node.sh refuses it unless told to. +[board.home-card] +serial = FEDCBA9876543210 +mac = AA:BB:CC:DD:EE:02 +role = probe +protect = keeps its identity and a client database + +; A radio that runs other firmware (e.g. a KISS modem of an observer): console +; tools refuse to open its port at all. +[board.modem] +serial = 00112233445566AA +role = bench +refuse = observer radio, not a MeshCore console + +; A deployed node, reached over BLE only (no USB serial). +[board.hill-rpt] +mac = AA:BB:CC:DD:EE:10 +role = live diff --git a/tools/flash_node.sh b/tools/flash_node.sh new file mode 100755 index 00000000..05fc4687 --- /dev/null +++ b/tools/flash_node.sh @@ -0,0 +1,484 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MIT +# Flash any board of the fleet -- pick the route from what the board is doing, +# and prove where the image landed. +# +# tools/flash_node.sh [target] [--force-protected] +# +# target USB serial (full or unique suffix), a BLE MAC, or a board name/alias +# from the local config (tools/mctools_config.py). +# Omit only when exactly one board of the fleet is plugged in. +# +# WHY A DISPATCHER. Which route works depends on the board AND on what it is +# doing right now. The rules are written out in .claude/skills/flash-node +# and AGENTS.md -- prose, i.e. the kind of thing that gets skipped mid-task. On +# 2026-09-01 three of them were skipped in one session: `pio -t upload` went to a +# board already in DFU (it touches unconditionally, kicking it back out), a +# hand-rolled nrfutil went to a board in the application (it does NOT touch, so +# nothing was listening), and a failed upload was retried instead of asking for a +# replug -- which is how an image ended up on a board nobody named. The rules +# therefore live here, where the board's state is actually known: +# +# board state route +# ------ ---------------- ------------------------------------------------ +# xiao application pio -t upload (env has upload_protocol=nrfutil, +# so PlatformIO touches; ~35 s, no buttons) +# xiao bootloader + disk hand off to xiao_uf2_flash.sh +# xiao bootloader, no hand-rolled nrfutil (does not touch; the board is +# disk (serial-only) already where it needs to be) +# t1000e application with `dfu uf2` on the console -> wait for the port to +# a text console rename -> hand-rolled nrfutil on the CDC port +# t1000e bootloader hand-rolled nrfutil straight away +# wio-l1 application 1200-baud touch -> UF2 drive "TRACKER L1" +# sensecap anywhere not over USB: BLE OTA, tools/ble_dfu.py +# +# CDC is preferred over the UF2 drive wherever both work: mounting the drive +# needs root, and `sudo` over SSH without a terminal has nobody to ask for a +# password. Writing to a CDC port works as the ordinary user. +# +# Whatever the route: the whole bus is fingerprinted before and after, the target +# must come back with the new version READ OFF THE BOARD, and every other board +# must be untouched. "Device programmed" is not evidence -- both flashes that went +# wrong that day printed it. +set -uo pipefail +case "${1:-}" in -h | --help) + sed -n '3,/^[^#]/{/^#/s/^# \{0,1\}//p}' "$0" + exit 0 + ;; +esac + +HERE="$(cd "$(dirname "$0")" && pwd)" +ROOT="$(cd "$HERE/.." && pwd)" +die() { + echo "CHYBA: $*" >&2 + exit 1 +} + +# JEN JEDEN FLASH NAJEDNOU. Dva soubezne behy si lezou do cesty na sdilenych +# zdrojich -- jeden BLE adapter, jedna USB sbernice, jeden .pio/build adresar. +# 2. 9. 2026 se kvuli tomu spustily TRI instance zaraz (spousteny na pozadi, bez +# kontroly, jestli predchozi dobehla): kazda si zvlast retryovala BLE connect, +# takze se karta porad dokola pripojovala a odpojovala a zaplavila plochu +# notifikacemi. Nebyla to chyba retry logiky, ale toho, ze bezely tri. +exec 9>"${TMPDIR:-/tmp}/.meshcore-flash-node.lock" +if ! flock -n 9; then + die "uz bezi jiny flash (zamek ${TMPDIR:-/tmp}/.meshcore-flash-node.lock). + Pockej, az dobehne -- soubezne flashovani si leze do cesty na BLE i na USB." +fi + +# Desky, na ktere se podle AGENTS.md nesaha bez vyslovneho zadani. Drzi identitu, +# historii nebo produkcni roli, a prepsat je omylem je draha chyba. +# Ktere to jsou, rika lokalni config (pole `protect`, tools/mctools_config.py). +cfg() { python3 "$HERE/mctools_config.py" "$@" 2>/dev/null; } +PROTECTED="$(cfg list --has protect --field serial || true)" + +# Cil se da zadat i jako BLE MAC, takze gate musi znat OBOJI. Do 2. 9. 2026 se +# kontrola delala az po dispatchi a obe BLE cesty (`flash_over_ble` a vetev pro +# MAC) z ni utekly `exit`em driv, nez na ni dosla rada -- chranenou domaci +# T1000-E slo pres BLE prepsat bez --force-protected. Ta karta uz o identitu +# jednou nenavratne prisla. +is_protected() { + local t="$1" sn mac + for sn in $PROTECTED; do + case "$t" in *"$sn"*) return 0 ;; esac + mac="$(ble_mac_for "$sn")" + [ -n "$mac" ] && [ "$(printf %s "$t" | tr a-f A-F)" = "$mac" ] && return 0 + done + return 1 +} + +guard_protected() { + is_protected "$1" || return 0 + [ "$FORCE" = "1" ] || die "$1 je CHRANENA deska (AGENTS.md: bez vyslovneho + zadani na ni nesahat). Kdyz to fakt chces: --force-protected" +} + +# BLE adresy desek, ktere nemaji textovou konzoli. Companion build se do +# bootloaderu neda poslat prikazem `dfu` (zadna konzole neni), takze jediny zpusob +# je buttonless DFU pres BLE. Kdyz je pak deska ZAROVEN na USB, samotny prenos jde +# po USB: ~20 s misto 3-15 min po BLE (podle vyjednaneho MTU). +ble_mac_for() { + cfg mac "$1" || true # pole `mac` v lokalnim configu +} + +# Deska, ktera po flashi "spadla z USB", NENI mrtva -- 2. 9. 2026 x1 i x4 v tom +# stavu normalne advertovaly na BLE. Softwarovy replug pritom neni z ceho udelat: +# vsechny desky visi primo na root hubu (xhci), a ten neumi prepinat napajeni +# portu, takze ani uhubctl by nepomohl. BLE OTA je proto jedina cesta, jak takovou +# desku doflashovat BEZ RUKOU -- a nepotrebuje USB touch, takze ji ani nema jak +# shodit znovu. +# +# Pozor na dock-quiet: deska, ktera JE na USB, drzi DTR a proto neadvertuje +# (potvrzeno tyz den na x2). BLE zachrana tedy funguje prave pro ty desky, ktere +# z USB vypadly -- coz je presne kdyz je potreba. +# Vraci: 0 = MAC videna, 1 = scan bezel a MAC tam nebyla, 2 = ADAPTER NEVIDEL NIC. +# Ten treti stav je potreba rozlisit, protoze scanner na tehle pracovni stanici je +# HLUCHY (MediaTek; `Discovering: yes` a presto nulovy vystup -- viz pamet +# "BLE jen z desktop"). Bez toho rozliseni skript hlasil "deska neadvertuje" i +# tehdy, kdyz neslysi adapter, tedy obvinoval desku z vady hostitele. +ble_reachable() { + local mac="$1" out + out="$(timeout 20 bash -c "bluetoothctl --timeout 12 scan on 2>/dev/null" || true)" + printf %s "$out" | grep -q "$mac" && return 0 + printf %s "$out" | grep -qE "^\s*\[NEW\] Device |Device [0-9A-F]{2}:" || return 2 + return 1 +} + +flash_over_ble() { + local mac="$1" + echo "== cesta: BLE OTA na $mac (bez USB, tedy bez rizika replugu)" + "$PIO" run -e "$ENV_NAME" >/dev/null 2>&1 || die "build selhal" + bluetoothctl disconnect "$mac" >/dev/null 2>&1 || true + sleep 2 + python3 "$HERE/ble_dfu.py" ".pio/build/$ENV_NAME/firmware.zip" "$mac" +} + +ENV_NAME="" +TARGET="" +FORCE=0 +PASSTHRU=() +for arg in "$@"; do + case "$arg" in + --force-protected) FORCE=1 ;; + # Vse ostatni s -- se predava ble_flash_node.sh (--require-silence, --via, + # --stop-service, --check-only); tady by to nemelo co delat. + --*) PASSTHRU+=("$arg") ;; + *) if [ -z "$ENV_NAME" ]; then ENV_NAME="$arg"; else TARGET="$arg"; fi ;; + esac +done +[ -n "$ENV_NAME" ] || { + echo "usage: $(basename "$0") [serial|board|mac] [--force-protected]" >&2 + exit 1 +} + +# Nastroje a pracovni adresar PRED jakoukoli cestou. Do 2. 9. 2026 se PIO +# prirazovalo AZ ZA vetvi pro BLE MAC, ktera ho pouzivala -- se `set -u` to +# znamenalo "PIO: unbound variable" a cela dokumentovana cesta na stozar/vzdálené stanoviště +# byla mrtva. `cd "$ROOT"` bylo taky pozdeji, takze build i relativni cesta do +# .pio/build mirily do cwd volajiciho. +PIO="$HOME/.platformio/penv/bin/pio" +[ -x "$PIO" ] || PIO="$(command -v pio)" || die "pio nenalezeno" +NRF="$HOME/.platformio/packages/tool-adafruit-nrfutil" +cd "$ROOT" || die "nelze do $ROOT" + +# Jmeno nebo alias desky z lokalniho configu -> seriove cislo. Serial, jeho +# unikatni suffix i BLE MAC projdou beze zmeny. +case "$TARGET" in +"" | *:*:*:*:*:*) ;; +*) SN="$(cfg serial "$TARGET")" && TARGET="$SN" ;; +esac + +# Cil zadany jako BLE MAC = deska na USB vubec neni (stozar, vzdálené stanoviště). Predava se +# ble_flash_node.sh, ktery kolem prenosu dela sest veci, jez tady chybely: +# odmitnuti spinaveho stromu, prefs PRED i PO (prefs v InternalFS prebijeji build +# flagy a flash je nepresipe), --require-silence u uzlu s odpojenou antenou, +# uvolneni linku v BlueZ, overeni verze proti obrazu a vraceni sluzby. Presne +# u mastovych/chatovych uzlu, kam tahle vetev miri, je ticho ochrana PA. +case "$TARGET" in +*:*:*:*:*:*) + guard_protected "$TARGET" + BFN="$HERE/ble_flash_node.sh" + [ -x "$BFN" ] || die "$BFN nenalezen" + echo "== cil je BLE MAC $TARGET -- deska neni na USB, predavam ble_flash_node.sh" + echo " (pokud ma uzel odpojenou antenu, pridej --require-silence)" + exec "$BFN" --env "$ENV_NAME" --mac "$TARGET" "${PASSTHRU[@]}" + ;; +esac + +# Spinavy strom da verzi s '+', a na uzlu pak nepoznas, co na nem je (AGENTS.md). +if [ -n "$(git status --porcelain 2>/dev/null)" ]; then + echo "VAROVANI: strom neni cisty -- obraz dostane verzi s '+'." >&2 +fi + +echo "== env: $ENV_NAME${TARGET:+ cil: $TARGET}" +echo "== otisk desek PRED flashem" +BEFORE="$("$HERE/board_probe.py" --all)" || die "otisk se nezdaril" +echo "$BEFORE" | sed 's/^/ /' + +if [ -n "$TARGET" ]; then + hits="$(echo "$BEFORE" | grep -c -- "$TARGET" || true)" + if [ "$hits" = "0" ]; then + # Neni na USB. Drive to znamenalo "rekni si o replug"; kdyz ale deska + # advertuje, da se doflashovat pres BLE a ruce nejsou potreba. + guard_protected "$TARGET" + MAC="$(ble_mac_for "$TARGET")" + if [ -n "$MAC" ]; then + echo "== $TARGET neni na USB; zkousim, jestli je na BLE ($MAC)" + ble_reachable "$MAC" + BR=$? + if [ "$BR" = "0" ]; then + flash_over_ble "$MAC" + exit $? + fi + [ "$BR" = "2" ] && die "$TARGET neni na USB a BLE scan na tomhle hostu NEVIDEL + ANI JEDNO zarizeni -- to neni vypoved o desce, ale o adapteru. Na tehle + pracovni stanici je scanner hluchy (MediaTek): $(bluetoothctl) hlasi + Discovering: yes a presto nic. Bud replug po USB, nebo BLE cestu spust + z hostu, ktery ji slysi, nebo pres ble_flash_node.sh --via." + die "$TARGET neni na USB ani neadvertuje na BLE -- replug. + POZOR, nez z toho udelas diagnozu: BLE zachrana funguje jen tehdy, kdyz + ten build BLE vubec MA. USB-only companion (env *_companion_radio_usb, + napr. Xiao_x4_cmp_usb) ho nema, takze tam neadvertuje ani zdrava deska -- + overeno 2. 9. 2026 na x2, ktera tehdy jela USB build. Dnesni Xiao_x2_cmp + je naopak BLE companion: na USB mlci a advertuje (11. 10. 2026). BLE MAC + v tabulce vyse muze byt z doby, kdy na desce jel jiny build." + fi + die "cil $TARGET neni na sbernici a neznam k nemu BLE adresu." + fi + [ "$hits" = "1" ] || die "cil $TARGET je na sbernici ${hits}x -- upresni seriove cislo" +else + n="$(echo "$BEFORE" | grep -c . || true)" + [ "$n" = "1" ] || die "na sbernici je $n desek -- rekni ktera: $(basename "$0") $ENV_NAME " + TARGET="$(echo "$BEFORE" | awk '{print $1}')" +fi + +guard_protected "$TARGET" + +FULL="$(echo "$BEFORE" | awk -v t="$TARGET" '$1 ~ t {print $2}')" +BOARD="${FULL%%/*}" +STATE="${FULL##*/}" +# shellcheck disable=SC2010 # by-id names are [A-Za-z0-9_:.-]; $TARGET is a regex +PORT="/dev/serial/by-id/$(ls /dev/serial/by-id/ | grep -- "$TARGET" | head -1)" +echo "== cil: $BOARD, stav: $STATE" + +# Stav, ktery NENI zjisteny protokol, znamena "nevim, co na desce bezi" -- a do +# `xiao/*` propadal na `pio -t upload`, tedy 1200baudovy touch naslepo. U stavu +# `obsazeny` je to nejhorsi: board_probe.py se portu, ktery drzi nekdo jiny, +# schvalne NESAHA, protoze 2. 9. 2026 dotek portu, ktery drzel openHop, oznacil +# link za degradovany a vypnul radio natrvalo do repeater.db. Ta pojistka byla +# v probe a do dispatcheru se nepropsala. +case "$STATE" in +obsazeny) + die "port desky $TARGET drzi jiny proces ($(echo "$BEFORE" | grep -- "$TARGET" | cut -d' ' -f3-)). + Nesaham na nej: dotek zive linky umi protistrane vypnout radio natrvalo. + Zastav toho, kdo port drzi, a spust znovu." + ;; +visi | nic | nedostupny | chyba) + die "stav desky $TARGET se nepodarilo zjistit (probe hlasi '$STATE'), takze + nevim, kterou cestou flashovat -- a hadat znamena touch naslepo. + U T1000-E je 'visi' bezne (pyserial ji neotiskne): + dostan ji do bootloaderu rucne (dlouhy stisk do 8 s od startu) a spust + znovu, pak to pujde vetvi t1000e/boot." + ;; +esac + +# OCEKAVANA VERZE. Bez ni umi otisk rict jen "neco se zmenilo", coz je slabe: +# 2. 9. 2026 pio dvakrat ohlasilo SUCCESS a na desce zustal STARY firmware +# (bootloader nestihl novy obraz aktivovat, protoze deska spadla z USB), a +# jindy naopak flash "selhal" a firmware se pritom nalil. Jedine, cemu se da +# verit, je verze PRECTENA Z DESKY -- a porovnat se musi proti tomu, co je +# v obrazu, ne proti predchozimu stavu. +"$PIO" run -e "$ENV_NAME" >/dev/null 2>&1 || die "build selhal" +WANT_VER="$(strings ".pio/build/$ENV_NAME/firmware.elf" 2>/dev/null | + grep -oE "v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]+\+?" | head -1)" +[ -n "$WANT_VER" ] || die "obraz nema stampovanou verzi -- po flashi by neslo + overit, co na desce doopravdy je. Zapoj do envu: extra_scripts = \${stamped.extra_scripts}" +echo "== ocekavana verze: $WANT_VER" + +has_uf2_drive() { + local d s blk + for d in /sys/bus/usb/devices/*/; do + s="$(cat "$d/serial" 2>/dev/null)" || continue + case "$s" in *"$TARGET"*) ;; *) continue ;; esac + blk="$(ls -d "$d"*/host*/target*/*/block/* 2>/dev/null | head -1)" || true + [ -n "$blk" ] && return 0 + done + return 1 +} + +# nrfutil umi skoncit tracebackem a PRESTO vratit 0 -- videno 1. 9. 2026 na +# "No data received on serial port". Cte se tedy i vystup, ne jen navratovy kod. +run_nrfutil() { + local port="$1" out + # ZADNY dalsi `pio run`: build je jednou nahore, u cteni WANT_VER. Stamping meni + # FIRMWARE_BUILD_DATE pri kazdem behu, takze kazde volani znamenalo PLNY rebuild + # (10-30 s) -- a hlavne se pak flashoval jiny artefakt, nez ze ktereho se + # WANT_VER precetla, cimz ta kontrola prestavala overovat odeslany obraz. + out="$(PYTHONPATH="$NRF/site-packages" "$HOME/.platformio/penv/bin/python" \ + "$NRF/adafruit-nrfutil.py" dfu serial \ + -pkg ".pio/build/$ENV_NAME/firmware.zip" -p "$port" -b 115200 --singlebank 2>&1)" || + { + echo "$out" | tail -4 + return 1 + } + echo "$out" | tail -3 + case "$out" in *NordicSemiException* | *"Not able to proceed"* | *Traceback*) return 1 ;; esac + return 0 +} + +# T1000-E: aplikace s textovou konzoli se do bootloaderu posle sama prikazem +# `dfu uf2`. Port se pritom PREJMENUJE z "...T1000-E-BOOT..." na "...T1000-E..." +# (ano, "-BOOT" ma aplikace) a pyserial hodi OSError: [Errno 5] -- to je reboot, +# ne chyba. +t1000e_to_bootloader() { + echo "== posilam 'dfu uf2' na konzoli, deska se rebootne do bootloaderu" + python3 - "$PORT" <<'PY' || true +import serial, sys, time +try: + s = serial.Serial(sys.argv[1], 115200, timeout=0) + s.dtr = True; s.rts = True + time.sleep(1.5) + s.write(b"dfu uf2\r\n"); s.flush() + time.sleep(2) + s.close() +except Exception as e: + print(f" ({type(e).__name__} pri odesilani -- deska se rebootuje)") +PY + for _ in $(seq 30); do + local p + # shellcheck disable=SC2010 # by-id names are [A-Za-z0-9_:.-]; $TARGET is a regex + p="$(ls /dev/serial/by-id/ 2>/dev/null | grep -- "$TARGET" | grep -v -- "-BOOT" | head -1)" + [ -n "$p" ] && { + PORT="/dev/serial/by-id/$p" + echo " bootloader port: $PORT" + return 0 + } + sleep 1 + done + return 1 +} + +RC=0 +case "$BOARD/$STATE" in +xiao/boot) + if has_uf2_drive; then + echo "== cesta: UF2 disk -> predavam xiao_uf2_flash.sh" + "$PIO" run -e "$ENV_NAME" -t create_uf2 >/dev/null 2>&1 || die "create_uf2 selhal" + # NE `exec`: tim by se predalo rizeni a preskocila zaverecna kontrola, ze + # se nezmenila zadna JINA deska -- tedy presne ta pojistka, kvuli ktere + # tenhle skript vznikl. xiao_uf2_flash.sh si overi svuj cil, my overime zbytek. + "$HERE/xiao_uf2_flash.sh" ".pio/build/$ENV_NAME/firmware.uf2" "$TARGET" || RC=$? + # `else` tady CHYBELO, takze po uspesnem UF2 flashi beh propadl do nrfutil na + # $PORT zachyceny PRED flashem -- ten uz neexistuje, protoze se deska + # rebootla do aplikace. Kazdy uspesny UF2 flash se tim ohlasil jako selhany, + # vcetne rady "dvojklikni RESET a spust znovu" pro flash, ktery prosel. + else + echo "== cesta: rucni nrfutil (bootloader bez UF2 disku = serial-only rezim)" + if ! run_nrfutil "$PORT"; then + # Videno 1. 9. 2026 na x2: bootloader vystavuje CDC (USB tridy 02+0a, zadne + # mass storage), ale na DFU protokol neodpovida -- nrfutil skonci na "No + # data received", se `--singlebank` i bez nej. Deska neni mrtva a replug + # s tim nehne, protoze v bootloaderu zustane; chce to DVOJKLIK na RESET, + # kterym se bootloader prepne do UF2 rezimu a VYSTAVI DISK. Pak uz tenhle + # skript sam zvoli druhou cestu (xiao_uf2_flash.sh). + echo >&2 + echo "Bootloader neodpovida na serial DFU, a UF2 disk nevystavuje." >&2 + echo "DVOJKLIKNI na male tlacitko RESET -- tim se prepne do UF2 rezimu" >&2 + echo "a objevi se disk. Pak spust tenhle skript znovu, uz pujde diskem." >&2 + RC=1 + fi + fi + ;; +xiao/*) + echo "== cesta: pio -t upload (deska je v APLIKACI, touch si udela sam)" + "$PIO" run -e "$ENV_NAME" -t upload --upload-port "$PORT" || RC=$? + ;; +t1000e/boot) + echo "== cesta: rucni nrfutil (T1000-E uz je v bootloaderu)" + run_nrfutil "$PORT" || RC=1 + ;; +t1000e/text) + t1000e_to_bootloader || die "deska se do 30 s neprepnula do bootloaderu" + run_nrfutil "$PORT" || RC=1 + ;; +t1000e/*) + # Companion build nema textovou konzoli, takze `dfu uf2` nema kam poslat. + # Buttonless DFU pres BLE ho tam dostane -- a protoze deska JE na USB, + # samotny prenos pak jde po kabelu (~20 s misto minut po BLE). + MAC="$(ble_mac_for "$TARGET")" + [ -n "$MAC" ] || die "T1000-E ve stavu '$STATE' nema textovou konzoli a k seriaku + $TARGET neznam BLE adresu. Doplň pole mac do configu ($(cfg path || echo "$HOME/.config/meshcore-tools/config.ini")), nebo desku dostan + do bootloaderu rucne (dlouhy stisk do 8 s od startu)." + echo "== cesta: BLE buttonless -> bootloader, pak flash po USB" + echo " BLE $MAC (jen prepnuti; prenos pojede po kabelu)" + "$PIO" run -e "$ENV_NAME" >/dev/null 2>&1 || die "build selhal" + # Pripojeny BLE klient by uzel drzel a buttonless zapis by nemel kam -- + # zastavit sluzbu NESTACI, spojeni drzi BlueZ (skill flash-node). + bluetoothctl disconnect "$MAC" >/dev/null 2>&1 || true + sleep 2 + if ! python3 "$HERE/ble_dfu.py" ".pio/build/$ENV_NAME/firmware.zip" "$MAC" phase1; then + die "buttonless pres BLE se nepovedl. BLE DFU je flaky a jeden pokus o connect + nestaci -- ale NESPOUSTEJ to opakovane, RESET po kazdem padu umi desku + uštvat doopravdy (skill flash-node)." + fi + # Bootloader se na USB hlasi BEZ "-BOOT" v nazvu portu -- ano, obracene. + echo "== cekam na bootloader port" + BOOTPORT="" + for _ in $(seq 30); do + # shellcheck disable=SC2010 # by-id names are [A-Za-z0-9_:.-]; $TARGET is a regex + p="$(ls /dev/serial/by-id/ 2>/dev/null | grep -- "$TARGET" | grep -v -- "-BOOT" | head -1)" + [ -n "$p" ] && { + BOOTPORT="/dev/serial/by-id/$p" + break + } + sleep 1 + done + [ -n "$BOOTPORT" ] || die "deska se do 30 s neobjevila v bootloaderu na USB" + echo " bootloader port: $BOOTPORT" + run_nrfutil "$BOOTPORT" || RC=1 + ;; +wio-l1/*) + echo "== cesta: Wio L1 -> predavam MeshCore-solo/flash-l1.sh (touch + disk TRACKER L1)" + L1="$HOME/projects/MeshCore-solo/flash-l1.sh" + [ -x "$L1" ] || die "$L1 nenalezen" + "$PIO" run -e "$ENV_NAME" -t create_uf2 >/dev/null 2>&1 || die "create_uf2 selhal" + "$L1" "$ROOT/.pio/build/$ENV_NAME/firmware.uf2" || RC=$? + ;; +*) + die "kombinaci '$BOARD/$STATE' neumim. Deska neodpovida zadnemu protokolu -- + vytahni ji z USB, zapoj zpatky a spust znovu." + ;; +esac + +if [ "$RC" != "0" ]; then + echo >&2 + echo "FLASH SELHAL. NEOPAKUJ ho -- jeden 1200baudovy touch na power session." >&2 + echo "Vytahni desku z USB, zapoj zpatky, a spust tenhle skript znovu." >&2 + echo >&2 + echo "Kontroluji, jestli to nezapsalo jinam:" >&2 + "$HERE/board_probe.py" --all --compare <(echo "$BEFORE") >&2 + exit 1 +fi + +echo "== otisk desek PO flashi (necham CDC nabehnout)" +sleep 8 +AFTER="$("$HERE/board_probe.py" --all)" +# JEDEN otisk pro obe kontrole. Driv se sbernice otiskovala dvakrat za sebou +# (kazdy az PROBE_DEADLINE dlouhy) a verdikt o zmenach se pocital z jineho +# vzorku, nez overeni verze. +# +# A `|| true` tady BYT NESMI. Do 2. 9. 2026 tam bylo, takze verdikt "zmenila se +# i jina deska" se jen vypsal a skript skoncil nulou -- tedy presne ten nalez, +# pro ktery tenhle nastroj vznikl (obraz mel jit na x4 a pristal na x2), se dal +# prehlednout a kazdy volajici, ktery se ridi exit kodem, videl uspech. +if ! "$HERE/board_probe.py" --all --compare <(echo "$BEFORE") \ + --expect-changed "$TARGET" --now <(echo "$AFTER"); then + echo >&2 + die "otisk sbernice nesouhlasi (viz vys). Bud se zmenila i JINA deska, nebo se + cil nezmenil -- obojim smerem to znamena, ze obraz sel jinam, nez mel." +fi + +GOT_VER="$(echo "$AFTER" | awk -v t="$TARGET" '$1 ~ t {print $3}')" +# Rozlisuj NEOVERITELNE od OVERENE SPATNE. board_probe umi vratit stavovy text +# misto verze (napr. T1000-E, kterou pyserial neotiskne), a +# ten se drive porovnal s WANT_VER a vypsal "FLASH SE NEAPLIKOVAL" po flashi, +# ktery klidne prosel. Dokumentovana cesta `flash_node.sh t1000e_repeater B3F160` +# tak koncila chybou vzdycky. +case "$GOT_VER" in +"" | "-" | neodpovida | drzi | nenalezen) + echo >&2 + echo "NEOVERENO: flash probehl bez chyby, ale verzi z $TARGET nejde precist" >&2 + echo "(probe hlasi '$STATE'). NEZNAMENA to, ze flash selhal -- u T1000-E je to" >&2 + echo "bezny stav. Over rucne z konzole: 'ver' ma dat $WANT_VER." >&2 + exit 2 + ;; +esac +if [ "$GOT_VER" != "$WANT_VER" ]; then + echo >&2 + die "FLASH SE NEAPLIKOVAL. Deska hlasi '$GOT_VER', obraz ma '$WANT_VER'. + Nastroj pred tim mohl hlasit uspech -- 'Device programmed' i 'SUCCESS' + umi vypsat i beh, po kterem na desce zustal stary firmware (bootloader + nestihl novy obraz aktivovat). Spust znovu; pokud to vytrva, chce to + replug." +fi +echo "== OVERENO NA DESCE: $TARGET bezi $GOT_VER" diff --git a/tools/fleet.py b/tools/fleet.py new file mode 100755 index 00000000..9eda1863 --- /dev/null +++ b/tools/fleet.py @@ -0,0 +1,26 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Board names -> USB serial numbers, for the Python tools. + +A thin view of the local config (tools/mctools_config.py, +~/.config/meshcore-tools/config.ini): the tools refer to boards by name, and +`/dev/serial/by-id` is matched on the serial number -- a ttyACM number +changes with every replug and would point a console at a DIFFERENT board. + +There used to be a table here, and a copy of it in five other places (the +shell flashers, the sniffer, the console and a hook). One board reflashed, +the copies drifted, and a stale entry aimed a console at the wrong board. +Now there is one file, outside the repo. +""" + +from mctools_config import boards, serial_for # noqa: F401 (re-exported) + +# name -> serial, only boards that have one (a BLE-only node has none) +FLEET = {n: b["serial"] for n, b in boards().items() if b.get("serial")} + +# the same keyed by each alias too (mesh_sniffer takes `--board 0`) +FLEET_BARE = dict(FLEET) +for _b in boards().values(): + for _a in (x.strip() for x in _b.get("aliases", "").split(",")): + if _a and _b.get("serial"): + FLEET_BARE[_a] = _b["serial"] diff --git a/tools/fleet_test.py b/tools/fleet_test.py new file mode 100755 index 00000000..a767a162 --- /dev/null +++ b/tools/fleet_test.py @@ -0,0 +1,569 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Regression smoke test for the bench fleet -- run it after every firmware change. + + tools/fleet_test.py [--boards 0,1,2,4] [--rounds 1] [--json out.json] + +Grew out of a one-off hw_check.py written to tell a dead radio from a dead IRQ +line. The lesson that made it worth keeping: **a node's own counters cannot +certify the node**. `sent` only says the firmware believes it transmitted, which +is exactly what a dead DIO1 line breaks -- bench-board reported `sent 0` for a week +while a second board heard every frame it sent. So every RF claim here is made by +a DIFFERENT board than the one under test. + +What it does, in order: + + 1. identity version/build per board; flags unstamped ("v1.16.0" with no -tth, + identical in every build ever made) and dirty ("+") images, and + boards that are not on the same build as the rest. + 2. config freq/bw/sf/cr must agree across the fleet, names must be unique. + Without this the matrix below measures nothing -- two boards on + different spreading factors simply cannot hear each other, which + looks exactly like broken hardware. + 3. matrix N x N. Each board sends a ZERO-HOP advert in turn; every other + board must count it. Zero-hop is deliberate: nobody rebroadcasts + it, so "B heard A" cannot be satisfied by C's relay of A -- and + it means the test never has to touch `repeat` prefs. + 4. hygiene tx_timeout / tx_start_fail / recv_errors must not move during the + run, on any board. + 5. commands console builds only: the command surface answers (informational, + plus a hard fail on the handful every repeater build must have). + +Nothing here writes prefs, changes radio settings or reboots anything. + +Handles both build flavours on the bench: the text console (repeater/analyzer) +and the binary companion protocol (companion_radio, which has no text console). +Detection is automatic. + +TRAP: do not leave a BLE client connected to a board under test. The USB and BLE +consoles share one command[160] buffer (simple_repeater/main.cpp), so two live +consoles interleave characters into one line and the node ends up executing +garbage. An earlier A/B run was invalidated exactly that way. +""" +import argparse +import glob +import json +import os +import re +import struct +import subprocess +import sys +import time +from datetime import datetime, timezone + +import serial + +HERE = os.path.dirname(os.path.abspath(__file__)) +FLASH_SH = os.path.join(HERE, "xiao_uf2_flash.sh") + +# Companion protocol (examples/companion_radio/MyMesh.cpp) +CMD_APP_START, CMD_SEND_SELF_ADVERT = 1, 7 +CMD_DEVICE_QUERY, CMD_GET_STATS = 22, 56 +STATS_TYPE_PACKETS = 2 +RESP_SELF_INFO, RESP_DEVICE_INFO, RESP_STATS = 5, 13, 24 + + +def fleet_table(): + """Fleet number -> USB serial, read out of xiao_uf2_flash.sh. + + Parsed rather than duplicated on purpose: two copies of this table would + drift, and mixing up which board is which is the single most expensive + mistake on this bench (a flash went to x4 while the log said x3). + """ + try: + src = open(FLASH_SH).read() + except OSError as e: + sys.exit(f"nelze precist {FLASH_SH}: {e}") + tbl = dict(re.findall(r"^\s*([0-9])\)\s*TARGET=([0-9A-F]{16})\s*;;", src, re.M)) + if not tbl: + sys.exit(f"v {FLASH_SH} nenalezena tabulka desek -- zmenil se format?") + return tbl + + +def discover(wanted): + """[(fleet_no, serial, port)] for XIAO boards actually on USB. + + Always through /dev/serial/by-id and matched on the SERIAL NUMBER: ttyACM* + renumbers on every replug, so a positional guess talks to another board. + """ + tbl = fleet_table() + found, modems = [], [] + # Hledaji se OBA product stringy, ale znamenaji ruzne desky: + # + # usb-Seeed_Studio_XIAO_nRF52840_ MeshCore build (PID 8044) + # usb-Seeed_XIAO-Wio-SX1262_ openhop_modem firmware (PID 0044) + # + # Prejmenovani dela openhop_modem, ne bootloader -- je to hloupe SX1262 PHY + # pro openHop demona, takze na MeshCore konzoli ani companion protokol + # neodpovi a zadnou UF2 mechaniku nevystavi (openHop config: + # radio_type: pymc_usb). + # + # Hlasi se zvlast, protoze obe chybne odpovedi na tohle stoji cas: pri globu + # jen na "XIAO_nRF52840" se 1. 9. 2026 matice smrskla na jednu desku bez + # vysvetleni, a pri globu na oboji to vypadalo jako dve zaseknute desky + # (nasledoval replug a pokus o nrfutil, oboje zbytecne -- deska byla v poradku). + for port in sorted(glob.glob("/dev/serial/by-id/*XIAO-Wio-SX1262*")): + m = re.search(r"_([0-9A-F]{16})-if00", port) + if m: + sn = m.group(1) + modems.append((next((n for n, s in tbl.items() if s == sn), "?"), sn)) + if modems: + for no, sn in modems: + print(f" x{no} ({sn}): openhop_modem firmware, ne MeshCore uzel -- vynechavam") + + for port in sorted(glob.glob("/dev/serial/by-id/*XIAO_nRF52840*")): + m = re.search(r"_([0-9A-F]{16})-if00", port) + if not m: + continue + sn = m.group(1) + no = next((n for n, s in tbl.items() if s == sn), "?") + if wanted and no not in wanted: + continue + found.append((no, sn, port)) + return found + + +# ---------------------------------------------------------------- transports + +class Node: + """Common bits. Ports are opened once and held: reopening costs ~1.3 s of + settle time per command (CDC on nRF52 is deaf until DTR is raised), which + turns an N x N matrix into minutes of dead waiting.""" + + def __init__(self, no, sn, port): + self.no, self.sn, self.port = no, sn, port + self.name = f"x{no}" + # serial_for_url: a /dev path, or socket://host:port for a board on + # another host (--remote; DTR/RTS are then held by the far end). + self.s = serial.serial_for_url(port, 115200, timeout=0) + self.s.dtr = True + self.s.rts = True + time.sleep(1.3) + self.s.reset_input_buffer() + self.info = {} + + def close(self): + try: + self.s.close() + except Exception: + pass + + +class ConsoleNode(Node): + """Repeater / analyzer build: line-oriented text console.""" + + kind = "console" + + def cmd(self, c, timeout=3.0, quiet=0.25): + """Send and read until the reply has stopped arriving. + + Idle-based rather than a fixed sleep: paged analyzer replies (rxlog) are + kilobytes and a fixed wait either truncates them or wastes seconds on + every one-line answer. + """ + self.s.reset_input_buffer() + self.s.write((c + "\r\n").encode()) + buf, deadline, last = b"", time.time() + timeout, None + while time.time() < deadline: + chunk = self.s.read(8192) + if chunk: + buf += chunk + last = time.time() + elif last and time.time() - last > quiet: + break + else: + time.sleep(0.02) + return buf.decode(errors="replace") + + def stats(self): + m = re.search(r"\{.*\}", self.cmd("stats-packets")) + return json.loads(m.group(0)) if m else {} + + def radio_stats(self): + m = re.search(r"\{.*\}", self.cmd("stats-radio")) + return json.loads(m.group(0)) if m else {} + + def identify(self): + ver = self.cmd("ver") + m = re.search(r"->\s*(\S+)\s*\(Build:\s*([^)]*)\)", ver) + self.info["version"] = m.group(1) if m else "?" + self.info["build"] = m.group(2).strip() if m else "?" + r = re.search(r"->\s*>?\s*([\d.]+),([\d.]+),(\d+),(\d+)", self.cmd("get radio")) + self.info["radio"] = (f"{float(r.group(1)):.3f}/{float(r.group(2))}/" + f"{r.group(3)}/{r.group(4)}") if r else "?" + n = re.search(r"->\s*>?\s*(.+)", self.cmd("get name")) + self.info["node"] = n.group(1).strip() if n else "?" + + def advert(self): + return "OK" in self.cmd("advert.zerohop", timeout=4.0) + + +class CompanionNode(Node): + """companion_radio build: binary frames, no text console at all. + + Framing is '<' + uint16 LE length + payload outbound, '>' + length + payload + inbound (src/helpers/ArduinoSerialInterface.cpp). + """ + + kind = "companion" + + def send(self, payload): + self.s.write(b"<" + struct.pack("") + if i < 0 or len(buf) < i + 3: + break + ln = struct.unpack("= 80: + self.info["build"] = d[8:20].split(b"\0")[0].decode(errors="replace") + self.info["version"] = d[60:80].split(b"\0")[0].decode(errors="replace") + # RESP_CODE_SELF_INFO: code, adv_type, tx_power, max_tx_power, + # pub_key[32], lat[4], lon[4], multi_acks, + # loc_policy, telemetry, manual_contacts, + # freq[4], bw[4], sf, cr, name[...] + self.send(bytes([CMD_APP_START, 1, 0, 0, 0, 0, 0, 0]) + b"fleet") + s = self.recv(RESP_SELF_INFO) + if s and len(s) >= 58: + freq, bw = struct.unpack("" in n.cmd("ver", timeout=2.0): + return n + n.close() + c = CompanionNode(no, sn, port) + if c.handshake(): + return c + c.close() + return None + + +# -------------------------------------------------------------------- checks + +class Report: + def __init__(self): + self.rows = [] + + def add(self, section, name, ok, detail): + self.rows.append((section, name, bool(ok), detail)) + mark = "OK " if ok else "FAIL" + print(f" [{mark}] {name}: {detail}", flush=True) + + def note(self, text): + print(f" {text}", flush=True) + + @property + def failed(self): + return [r for r in self.rows if not r[2]] + + +def check_identity(nodes, rep): + print("\n== 1. identita a verze", flush=True) + for n in nodes: + v, b = n.info.get("version", "?"), n.info.get("build", "?") + rep.note(f"x{n.no} {n.info.get('node','?'):<14} {v} ({b}) [{n.kind}]") + vers = {n.info.get("version", "?") for n in nodes} + stale = [n for n in nodes if not re.search(r"-tth[0-9a-f]+", n.info.get("version", ""))] + dirty = [n for n in nodes if n.info.get("version", "").endswith("+")] + rep.add("identity", "vsechny obrazy jsou stampovane", not stale, + "ok" if not stale else + f"bez -tth: {[n.name for n in stale]} -- env nema ${{stamped.extra_scripts}}, " + "verze je literal shodny ve vsech buildech") + rep.add("identity", "zadny obraz z spinaveho stromu", not dirty, + "ok" if not dirty else f"konci na '+': {[n.name for n in dirty]}") + # Deliberately a note, not a check. The bench legitimately runs several envs + # at once (repeater, bot, companion), so "all on one version" is not a + # property this fleet has -- asserting it would cry wolf on every run and + # train you to ignore the summary. What matters is that you can SEE what is + # where, and the two things above, which are rule violations in any env. + if len(vers) > 1: + by_ver = {} + for n in nodes: + by_ver.setdefault(n.info.get("version", "?"), []).append(n.name) + rep.note("ruzne buildy na lavici: " + + " | ".join(f"{v}: {' '.join(b)}" for v, b in sorted(by_ver.items()))) + + +def check_config(nodes, rep): + print("\n== 2. konfigurace radia", flush=True) + radios = {} + for n in nodes: + radios.setdefault(n.info.get("radio", "?"), []).append(n.name) + rep.add("config", "shodne parametry radia", len(radios) == 1, + " | ".join(f"{r}: {v}" for r, v in radios.items())) + names = [n.info.get("node", "?") for n in nodes] + dupes = {x for x in names if names.count(x) > 1} + rep.add("config", "jmena uzlu jsou unikatni", not dupes, + "ok" if not dupes else f"duplicity: {sorted(dupes)}") + return len(radios) == 1 + + +def check_matrix(nodes, rep, rounds): + print(f"\n== 3. krizova matice ({len(nodes)} desek, {rounds}x)", flush=True) + if len(nodes) < 2: + rep.add("matrix", "matice potrebuje aspon 2 desky", False, + f"pripojena je {len(nodes)}") + return {} + + heard = {t.name: {r.name: 0 for r in nodes if r is not t} for t in nodes} + rssi = {t.name: {} for t in nodes} + for rnd in range(rounds): + for tx in nodes: + others = [n for n in nodes if n is not tx] + before = {n.name: n.stats() for n in nodes} + tx.advert() + time.sleep(3.0) + after = {n.name: n.stats() for n in nodes} + + d_sent = after[tx.name].get("sent", 0) - before[tx.name].get("sent", 0) + d_to = after[tx.name].get("tx_timeout", 0) - before[tx.name].get("tx_timeout", 0) + got = [] + for rx in others: + d = after[rx.name].get("recv", 0) - before[rx.name].get("recv", 0) + if d >= 1: + heard[tx.name][rx.name] += 1 + rs = rx.radio_stats() + if rs: + rssi[tx.name][rx.name] = (rs.get("last_rssi"), rs.get("last_snr")) + got.append(f"{rx.name}{'+' if d >= 1 else '-'}") + rep.note(f"kolo {rnd+1}: {tx.name} vysila -> sent +{d_sent} " + f"timeout +{d_to} | slyseli: {' '.join(got)}") + + for tx in nodes: + misses = [r for r, c in heard[tx.name].items() if c < rounds] + rep.add("matrix", f"{tx.name} slyseli vsichni ({rounds}/{rounds})", not misses, + "ok" if not misses else + f"neslyseli/ne vzdy: {', '.join(f'{r} {heard[tx.name][r]}/{rounds}' for r in misses)}") + for tx in nodes: + for rx, v in rssi[tx.name].items(): + if v[0] is not None: + rep.note(f"{tx.name} -> {rx}: RSSI {v[0]} dBm, SNR {v[1]} dB") + return heard + + +def check_hygiene(nodes, base, rep): + print("\n== 4. countery chyb behem behu", flush=True) + for n in nodes: + a, b = n.stats(), base[n.name] + bad = {k: a.get(k, 0) - b.get(k, 0) + for k in ("tx_timeout", "tx_start_fail", "recv_errors") + if a.get(k, 0) - b.get(k, 0) > 0} + rep.add("hygiene", f"{n.name} bez chybovych counteru", not bad, + "ok" if not bad else str(bad)) + + +# Rok, pod kterym je jasne, ze hodinam nikdo cas nenastavil: VolatileRTCClock +# startuje v kvetnu 2024 a jinak jen tika z millis(). +CLOCK_FLOOR = 1735689600 # 2025-01-01 UTC + + +def check_clock(nodes, rep): + print("\n== 6. hodiny desek", flush=True) + for n in nodes: + if n.kind != "console": + rep.note(f"{n.name}: companion build, `clock` neexistuje -- preskoceno") + continue + out = n.cmd("clock") + m = re.search(r"epoch\s+(\d+)", out) + if m: + node_epoch = int(m.group(1)) + else: + m = re.search(r"\b(\d{1,2}):(\d{2})\s*-\s*(\d{1,2})/(\d{1,2})/(\d{4})", out) + if not m: + rep.add("clock", f"{n.name} odpovida na clock", False, out.strip()[:60]) + continue + hh, mm, day, mon, year = (int(g) for g in m.groups()) + try: + node_epoch = int(datetime(year, mon, day, hh, mm, + tzinfo=timezone.utc).timestamp()) + except ValueError: + rep.add("clock", f"{n.name} odpovida na clock", False, out.strip()[:60]) + continue + skew = int(time.time()) - node_epoch + # Deska, ktere nikdo cas nenastavil, je vada konfigurace, ne vada desky -- + # ale prave proto se to musi hlasit. Na x3 to uniklo 811 dni a na teto + # lavici to 7. 8. 2026 platilo pro KAZDOU desku. Spatny cas neni kosmetika: + # RTC stampuje kazdy vyslany advert a prijemce stary timestamp zahodi jako + # replay. Srovnat: `tools/ble_cli.py "time {epoch}"` nebo pres USB. + rep.add("clock", f"{n.name} ma nastavene hodiny", node_epoch > CLOCK_FLOOR, + f"{datetime.fromtimestamp(node_epoch, timezone.utc).isoformat()}" + f" (skew {skew:+d} s = {skew / 86400:.1f} dni)") + + +# Commands every repeater/analyzer build must answer. `dfu` is deliberately NOT +# probed -- it reboots into the bootloader. +MUST_HAVE = ["ver", "advert.zerohop", "stats-packets", "blink", "txpwr"] +OPTIONAL = ["nodes", "rxlog 999999", "pktlog 999999", "bot", "dio1", "bleconn"] + + +def check_commands(nodes, rep): + print("\n== 5. povrch prikazu (jen console buildy)", flush=True) + for n in nodes: + if n.kind != "console": + rep.note(f"{n.name}: companion build, textova konzole neexistuje -- preskoceno") + continue + missing = [c for c in MUST_HAVE if "Unknown command" in n.cmd(c)] + rep.add("commands", f"{n.name} ma zakladni prikazy", not missing, + "ok" if not missing else f"chybi: {missing}") + have = [c.split()[0] for c in OPTIONAL if "Unknown command" not in n.cmd(c)] + rep.note(f"{n.name} volitelne: {' '.join(have) if have else '(zadne)'}") + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--boards", help="cisla desek, napr. 0,1,2,4 (vychozi: vse na USB)") + ap.add_argument("--rounds", type=int, default=1, help="kol matice (vychozi 1)") + ap.add_argument("--json", help="ulozit vysledek jako JSON") + ap.add_argument("--remote", action="append", default=[], metavar="N=URL", + help="deska na jinem hostu, napr. 1=socket://127.0.0.1:7001 " + "(TCP<->serial proxy na tom hostu + ssh -L); opakovatelne") + a = ap.parse_args() + + wanted = set(a.boards.split(",")) if a.boards else None + found = discover(wanted) + tbl = fleet_table() + for r in a.remote: + no, _, url = r.partition("=") + if not url: + sys.exit(f"--remote {r}: cekam N=URL") + found.append((no, tbl.get(no, "?"), url)) + if not found: + sys.exit("na USB nenalezena zadna XIAO deska") + + print(f"== nalezeno {len(found)} desek", flush=True) + nodes = [] + for no, sn, port in found: + n = open_node(no, sn, port) + if n is None: + # "Neodpovida" je spatna diagnoza, kdyz na desce bezi neco, co ani + # odpovidat nema. 1. 9. 2026 to stalo hodinu a tri zbytecne replugy: + # na x2 skoncil omylem KISS modem (nema textovou konzoli ANI companion + # protokol) a hlaska vypadala jako zaseknuta deska. Doptame se tedy + # jeste KISS ramcem, at je videt, CO tam bezi. + what = "neodpovida ani konzoli, ani companion protokolu" + try: + out = subprocess.run( + [os.path.join(HERE, "board_probe.py"), "--all"], + capture_output=True, text=True, timeout=90).stdout + # Stav, ktery probe NEZJISTIL, se nesmi vydavat za zjistenou + # identitu firmwaru. `visi` znamena, ze deska visela v open(2), + # `obsazeny` ze port drzi nekdo jiny (casto tenhle beh sam), + # `chyba` ze probe spadl -- z zadneho z nich neplyne "neni to + # MeshCore uzel". Takhle to hlasilo presne tu diagnozu, kterou + # nastroj nemel cim podepřít. + for line in out.splitlines(): + f = line.split(None, 2) + if len(f) < 2 or f[0] != sn: + continue + kind = f[1].split("/")[-1] + ver = f[2].strip() if len(f) > 2 else "" + if kind in ("nic", "nedostupny", "modem", "boot"): + what = f"{f[1]} {ver} -- neni to MeshCore uzel, vynechavam" + elif kind in ("visi", "obsazeny", "chyba"): + what = (f"{f[1]} {ver} -- stav se NEPODARILO zjistit," + f" vynechavam (o firmwaru to nic nerika)") + else: + what = f"{f[1]} {ver} -- jiny protokol, vynechavam" + except Exception: + pass + print(f" x{no} ({sn}): {what}", flush=True) + continue + n.identify() + nodes.append(n) + if not nodes: + sys.exit("zadna deska neodpovedela") + + rep = Report() + try: + check_identity(nodes, rep) + same_radio = check_config(nodes, rep) + if not same_radio: + rep.note("POZOR: desky nejsou na stejnem radiu, matice nize je tim padem " + "test konfigurace, ne hardwaru") + base = {n.name: n.stats() for n in nodes} + check_matrix(nodes, rep, a.rounds) + check_hygiene(nodes, base, rep) + check_commands(nodes, rep) + check_clock(nodes, rep) + finally: + for n in nodes: + n.close() + + print("\n===== SOUHRN =====") + for _sec, name, ok, _detail in rep.rows: + print(f" {'OK ' if ok else 'FAIL'} {name}") + n_bad = len(rep.failed) + print(f"\n{len(rep.rows) - n_bad}/{len(rep.rows)} proslo") + + if a.json: + with open(a.json, "w") as f: + json.dump({"boards": [{"no": n.no, "sn": n.sn, "kind": n.kind, **n.info} + for n in nodes], + "checks": [{"section": s, "name": nm, "ok": ok, "detail": d} + for s, nm, ok, d in rep.rows]}, f, indent=2) + print(f"JSON: {a.json}") + return 1 if n_bad else 0 + + +# The guard is not decoration: this module TRANSMITS. check_matrix() and the +# `advert.zerohop` probe in check_commands() key the radio on every console board +# found on USB, whatever band each one is tuned to. Without the guard, so much as +# `import fleet_test` to reuse discover() ran the whole suite -- which on +# 7. 8. 2026 put two zero-hop adverts on 869.432 out of a bench board configured +# for the live CZ mesh, before the importing script's own first line had run. +if __name__ == "__main__": + sys.exit(main()) diff --git a/tools/fw_room_smoke.py b/tools/fw_room_smoke.py new file mode 100755 index 00000000..ff0e8c8f --- /dev/null +++ b/tools/fw_room_smoke.py @@ -0,0 +1,119 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Smoke test of a FIRMWARE room server (simple_room_server) over the air. + +Two MeshCore companions log in as guests; each posts once and the room must +push that post to the OTHER one (signed message from the room, author prefix +in the signature), never back to its author. That is the room's whole job -- +login, store, push -- end to end, on real radios. + + tools/fw_room_smoke.py --room --password \\ + --a 127.0.0.1:47001 --b 127.0.0.1:47003 + +--a/--b are companions reachable as meshcore TCP (a companion on USB elsewhere +can be exposed with a TCP<->serial bridge; the frames are the same). The room +is added to both as a contact with a flood path, so no advert is needed. + +Run it on the bench preset only (all three on 866.5): it transmits logins and +posts. Exit 0 = every step passed. + +Not the openHop room (tth-room): that one has its own bench, +openhop-repeater/tools/bench/room_delivery.py. +""" + +import argparse +import asyncio +import sys +import time + +if __name__ == "__main__" and any(a in ("-h", "--help") for a in sys.argv[1:]): + print(__doc__) + sys.exit(0) + +from meshcore import EventType, MeshCore # noqa: E402 + +ROOM_TYPE = 3 + + +def room_contact(pubkey, name="room-under-test"): + return { + "public_key": pubkey, "type": ROOM_TYPE, "flags": 0, + "out_path_len": -1, "out_path": "", "out_path_hash_mode": 0, + "adv_name": name, "last_advert": 0, "adv_lat": 0.0, "adv_lon": 0.0, + } + + +async def connect(hostport): + host, port = hostport.rsplit(":", 1) + mc = await MeshCore.create_tcp(host, int(port)) + return mc + + +async def wait_push(mc, room_prefix, needle, timeout): + """Wait for a message from the room whose text contains `needle`.""" + deadline = time.monotonic() + timeout + while time.monotonic() < deadline: + ev = await mc.dispatcher.wait_for_event(EventType.CONTACT_MSG_RECV, + timeout=max(0.1, deadline - time.monotonic())) + if ev is None: + break + p = ev.payload + if p.get("pubkey_prefix", "").lower() == room_prefix and needle in p.get("text", ""): + return p + return None + + +async def main(): + ap = argparse.ArgumentParser(description="firmware room server smoke test") + ap.add_argument("--room", required=True, help="room server public key (64 hex)") + ap.add_argument("--password", required=True, help="guest password") + ap.add_argument("--a", required=True, help="companion A host:port") + ap.add_argument("--b", required=True, help="companion B host:port") + ap.add_argument("--push-timeout", type=float, default=120) + args = ap.parse_args() + + room = args.room.lower() + prefix = room[:12] + ok = True + a, b = await connect(args.a), await connect(args.b) + names = {id(a): a.self_info.get("name"), id(b): b.self_info.get("name")} + for mc in (a, b): + await mc.commands.add_contact(room_contact(room)) + await mc.ensure_contacts() + await mc.start_auto_message_fetching() + + for mc in (a, b): + t0 = time.monotonic() + ev = await mc.commands.send_login_sync(room, args.password, min_timeout=20) + good = ev is not None and ev.type == EventType.LOGIN_SUCCESS + print(f"login {names[id(mc)]}: {'OK' if good else 'FAIL'} ({time.monotonic() - t0:.1f} s)") + ok &= good + if not good: + break + + if ok: + for src, dst in ((a, b), (b, a)): + tag = f"smoke-{int(time.time())}-{names[id(src)]}" + res = await src.commands.send_msg_with_retry(room, tag, max_attempts=3) + sent = res is not None and res.type != EventType.ERROR + print(f"post by {names[id(src)]}: {'acked' if sent else 'NOT acked'}") + t0 = time.monotonic() + got = await wait_push(dst, prefix, tag, args.push_timeout) + if got: + print(f"push to {names[id(dst)]}: OK after {time.monotonic() - t0:.1f} s " + f"(author sig {got.get('signature')}, path_len {got.get('path_len')})") + else: + print(f"push to {names[id(dst)]}: FAIL (nothing in {args.push_timeout:.0f} s)") + echo = await wait_push(src, prefix, tag, 5) + if echo: + print(f"author {names[id(src)]} got its own post back: FAIL") + ok &= sent and got is not None and echo is None + + for mc in (a, b): + await mc.disconnect() + print("RESULT:", "PASS" if ok else "FAIL") + return 0 if ok else 1 + + +if __name__ == "__main__": + sys.exit(asyncio.run(main())) diff --git a/tools/gen_node_id.py b/tools/gen_node_id.py new file mode 100755 index 00000000..4abd3629 --- /dev/null +++ b/tools/gen_node_id.py @@ -0,0 +1,177 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Vygeneruje identitu uzlu s NEKOLIZNIM path hashem. + +Proc to nejde nechat na nahode +------------------------------- +Path hash je prosty prefix verejneho klice (`Identity.h:20`) a jeho sirku urcuje +ODESILATEL paketu, ne forwarder -- `Mesh.cpp:346` pripoji `packet->getPathHashSize()` +bajtu, takze do jednobajtoveho paketu pripise jeden bajt i repeater nastaveny na dva. +Kandidatem na hop je proto VZDY cela populace repeateru, ne jen ti nastaveni na tutez +sirku. Zmereno na CZ meshi 5. 8. 2026 (669 repeateru): + + 1 bajt -> 620 repeateru sedi na sdilenem prefixu (253 z 256 hodnot obsazeno) + 2 bajty -> 6 (obsazenost 1,25 %) + 3 bajty -> 0 + +Jednobajtova unikatnost je tedy neziskatelna (pigeonhole: 669 > 256), zato dvoubajtova +je skoro zadarmo. Kolize neni kosmetika: `isHashMatch` porovna prave tyhle bajty, takze +na kolidujici hop reaguje VIC repeateru -- rozbiji to routovani i atribuci v analyzeru. + +Pouziti +------- + tools/gen_node_id.py # 2B prefix volny proti CoreScope + tools/gen_node_id.py --bytes 3 # prisnejsi + tools/gen_node_id.py --first-byte 5f # k tomu konkretni prvni bajt + tools/gen_node_id.py --known klice.txt # offline, misto CoreScope + +Nahrani do uzlu (klic je 64 B = seed32 || pubkey32, viz PRV_KEY_SIZE v MeshCore.h): + meshcore-cli -a set private_key <128 hex znaku> +""" +import argparse +import hashlib +import json +import os +import secrets +import sys +import urllib.request +from cryptography.hazmat.primitives import serialization as ser +from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey + + +def keypair(seed: bytes): + """Vrati (pub32, prv64) ve formatu, ktery ceka MeshCore. + + POZOR: prv NENI seed||pub (konvence libsodium), ale **clampnuty SHA-512(seed)** + -- viz lib/ed25519/keypair.c: + + sha512(seed, 32, private_key); + private_key[0] &= 248; private_key[31] &= 63; private_key[31] |= 64; + ge_scalarmult_base(&A, private_key); + + `set prv.key` jinak odpovi "Error, bad key", protoze validatePrivateKey() + si pubkey odvodi pres ed25519_derive_pub() z prvnich 32 bajtu jako ze skalaru. + Pub pocitame pres standardni Ed25519 ze seedu -- RFC 8032 dela presne tohle. + """ + h = bytearray(hashlib.sha512(seed).digest()) + h[0] &= 248 + h[31] &= 63 + h[31] |= 64 + pub = Ed25519PrivateKey.from_private_bytes(seed).public_key().public_bytes( + ser.Encoding.Raw, ser.PublicFormat.Raw) + return pub, bytes(h) + +# Verejny komunitni analyzer: vidi cely mesh (50 observeru), ne jen to, co slysi +# nase dve. Kolize se musi hledat proti nejuplnejsi populaci, jakou sezeneme. +DEFAULT_SRC = "https://analyzer.meshcore.cz/api/analytics/hash-sizes" + + +def load_known(src): + """Vrati (vsechny_pubkey, pubkey_repeateru) jako lowercase hex.""" + if src.startswith("http"): + with urllib.request.urlopen(src, timeout=20) as r: + d = json.load(r) + # Zdroje se lisi tvarem a API se meni pod rukama (23. 8. 2026 zmizel + # "multiByteCapability" z CoreScope): zkus zname obalky, pak fallback + # na prvni list dictu v odpovedi. Klic pubkeye taky pluje. + nodes = None + for k in ("multiByteCapability", "nodes", "data"): + if isinstance(d, dict) and isinstance(d.get(k), list): + nodes = d[k] + break + if nodes is None: + if isinstance(d, list): + nodes = d + else: + nodes = next((v for v in d.values() if isinstance(v, list)), None) + if not nodes: + sys.exit(f"zdroj {src} nevratil zadny seznam uzlu") + def pk(n): + return (n.get("pubkey") or n.get("public_key") or n.get("publicKey") or "").lower() + rep_types = {"repeater", 2, "2"} + return ([pk(n) for n in nodes if pk(n)], + [pk(n) for n in nodes if pk(n) and ( + n.get("role") in rep_types or n.get("type") in rep_types + or n.get("node_type") in rep_types)]) + keys = [ln.strip().lower() for ln in open(src) if ln.strip()] + return keys, keys + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--bytes", type=int, default=2, + help="kolik bajtu prefixu musi byt volnych (default 2)") + ap.add_argument("--first-byte", metavar="HEX", + help="vynutit konkretni prvni bajt, napr. 5f") + ap.add_argument("--known", default=DEFAULT_SRC, + help="zdroj znamych klicu: URL CoreScope nebo soubor") + ap.add_argument("--max-tries", type=int, default=5_000_000) + ap.add_argument("--derive", metavar="HEX128", + help="jen odvodit pubkey z existujiciho 64B prv.key a skoncit. " + "PAST: prv[32:64] NENI pubkey (je to druha pulka SHA-512) " + "-- pub = ge_scalarmult_base(prv[0:32]). Chce PyNaCl.") + ap.add_argument("--out", metavar="SOUBOR", + help="kam zapsat privatni klic (0600). Bez toho se NEVYPISUJE " + "-- klic nema co delat v scrollbacku terminalu.") + a = ap.parse_args() + + if a.derive: + import nacl.bindings as nb # jen tady, jinak staci `cryptography` + prv = bytes.fromhex(a.derive.strip()) + if len(prv) != 64: + sys.exit(f"prv.key ma mit 64 bajtu (128 hex), ma {len(prv)}") + print(nb.crypto_scalarmult_ed25519_base_noclamp(prv[:32]).hex()) + return + + try: + allk, repk = load_known(a.known) + except Exception as e: + sys.exit(f"nelze nacist zname klice z {a.known}: {e}") + + n = a.bytes * 2 + taken_all = {k[:n] for k in allk} + bucket1 = {} + for k in repk: + bucket1[k[:2]] = bucket1.get(k[:2], 0) + 1 + print(f"znamych uzlu {len(allk)} (z toho repeateru {len(repk)}); " + f"obsazenych {a.bytes}B prefixu: {len(taken_all)}", file=sys.stderr) + + want = a.first_byte.lower() if a.first_byte else None + if want and len(want) != 2: + sys.exit("--first-byte chce prave dva hex znaky") + + if want in ("00", "ff"): + sys.exit("00 a ff nejsou volne, ale ZAKAZANE -- Identity.cpp:56 odmita " + "klic s pub[0] == 0x00 nebo 0xFF jako neplatny") + + for i in range(a.max_tries): + seed = secrets.token_bytes(32) + pub, prv64 = keypair(seed) + h = pub.hex() + if h[:2] in ("00", "ff"): # firmware by takovy klic odmitl + continue + if want and h[:2] != want: + continue + if h[:n] in taken_all: + continue + crowd = bucket1.get(h[:2], 0) + print(f"nalezeno po {i + 1} pokusech", file=sys.stderr) + print(f"pub_key {h}") + print(f"path hash 1B={h[:2]} 2B={h[:4]} 3B={h[:6]}") + print(f"prvni bajt {h[:2]} sdili {crowd} repeateru" + + (" <-- unikatni i na 1 bajt!" if crowd == 0 else "")) + if a.out: + fd = os.open(a.out, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600) + with os.fdopen(fd, "w") as f: + f.write(prv64.hex() + "\n") + print(f"\nprivatni klic zapsan do {a.out} (0600). Nahrani do uzlu:") + print(f" repeater po seriove konzoli: set prv.key $(cat {a.out})") + print(f" companion pres meshcore-cli: set private_key $(cat {a.out})") + else: + print("\n(privatni klic se nevypisuje; pouzij --out SOUBOR)") + return + sys.exit("nenalezeno, zvys --max-tries nebo uvolni podminky") + + +if __name__ == "__main__": + main() diff --git a/tools/mctools_config.py b/tools/mctools_config.py new file mode 100755 index 00000000..b246aa31 --- /dev/null +++ b/tools/mctools_config.py @@ -0,0 +1,173 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Local config of the MeshCore tools: which boards and nodes you have. + +The tools in this directory carry no board serial, MAC or host of anyone's +bench. They take them from ONE file beside the repo: + + ~/.config/meshcore-tools/config.ini (or $MESHCORE_TOOLS_CONFIG) + +Copy tools/config.example.ini there and describe your boards. Without the +file every tool still works with full serial numbers, MACs and port paths -- +only names like `b1` need it. No secrets go in here: admin passwords stay in +platformio.local.ini. + +From Python: + + from mctools_config import serial_for, mac_for, boards + serial_for("b1") # -> "0123456789ABCDEF", or the input unchanged + +From shell (the same answers, one per line, exit 1 when there is none): + + tools/mctools_config.py path + tools/mctools_config.py serial b1 # alias, number or serial + tools/mctools_config.py mac b1 # BLE MAC of that board + tools/mctools_config.py get b1 protect # any field of the board + tools/mctools_config.py list [--role bench] [--has protect] [--field serial] + tools/mctools_config.py name 0123456789ABCDEF # board name for a serial or MAC + +Board section, every field optional: + + [board.b1] + serial = 0123456789ABCDEF ; USB serial number (/dev/serial/by-id) + mac = AA:BB:CC:DD:EE:01 ; BLE MAC of the application + aliases = 1 ; other names that mean this board + role = bench ; bench | live | probe -- tools and hooks decide by it + protect = keeps an identity ; flashing tools refuse it unless told to + refuse = an observer radio ; console tools refuse to open it at all + host = lab-pc ; where it is plugged in (informative) +""" + +from __future__ import annotations + +import argparse +import configparser +import os +import re +import shlex +import sys +from pathlib import Path + +ENV = "MESHCORE_TOOLS_CONFIG" +DEFAULT = Path.home() / ".config/meshcore-tools/config.ini" +EXAMPLE = Path(__file__).resolve().parent / "config.example.ini" +FIELDS = ("serial", "mac", "aliases", "role", "protect", "refuse", "host") + + +def path() -> Path: + return Path(os.environ.get(ENV) or DEFAULT) + + +def boards() -> dict[str, dict[str, str]]: + """{name: {field: value}} from the config; empty without a config.""" + cp = configparser.ConfigParser(interpolation=None, inline_comment_prefixes=(";", "#")) + cp.read(path()) + out = {} + for sec in cp.sections(): + if sec.startswith("board."): + out[sec[6:]] = {k: v.strip() for k, v in cp[sec].items()} + return out + + +def find(key: str) -> tuple[str, dict[str, str]] | None: + """The board a name, alias, serial number or MAC belongs to.""" + k = key.strip() + for name, b in boards().items(): + aliases = [a.strip() for a in b.get("aliases", "").split(",") if a.strip()] + if k == name or k in aliases: + return name, b + if b.get("serial") and k.upper() == b["serial"].upper(): + return name, b + if b.get("mac") and k.upper() == b["mac"].upper(): + return name, b + return None + + +def serial_for(key: str) -> str: + """USB serial of a board name/alias, or the input unchanged (a serial or a + port path passes straight through).""" + hit = find(key) + return hit[1].get("serial", key) if hit else key + + +def mac_for(key: str) -> str | None: + hit = find(key) + return hit[1].get("mac") if hit else None + + +def field(key: str, name: str) -> str | None: + hit = find(key) + return hit[1].get(name) if hit else None + + +def by_role(role: str | None = None) -> dict[str, dict[str, str]]: + return {n: b for n, b in boards().items() if role is None or b.get("role") == role} + + +def unknown_alias_hint(key: str) -> str: + return f"{key!r} is no board in {path()} (template: {EXAMPLE})" + + +def main() -> int: + ap = argparse.ArgumentParser( + description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter + ) + sub = ap.add_subparsers(dest="cmd", required=True) + sub.add_parser("path", help="the config file in use") + sub.add_parser("hook-vars", help="shell assignments LIVE_IDS / BENCH_IDS (regexes) for a guard hook") + for c in ("serial", "mac", "name"): + sub.add_parser(c).add_argument("key") + g = sub.add_parser("get") + g.add_argument("key") + g.add_argument("field", choices=FIELDS) + lst = sub.add_parser("list") + lst.add_argument("--role") + lst.add_argument("--has", choices=FIELDS, help="only boards that set this field") + lst.add_argument("--field", choices=FIELDS, help="print only this field (skip boards without it)") + a = ap.parse_args() + + if a.cmd == "path": + print(path()) + return 0 if path().exists() else 1 + if a.cmd == "hook-vars": + # live: MACs and names; bench: serials, MACs and names as whole words + def ere(text: str) -> str: # POSIX ERE (grep -E), not Python re + return re.sub(r"([.^$*+?()\[\]{}|\\])", r"\\\1", text) + + def ids(role: str) -> str: + out = [] + for n, b in by_role(role).items(): + out += [ere(b[k]) for k in ("serial", "mac") if b.get(k)] + out.append(f"(^| ){ere(n)}( |$)") + return "|".join(out) + + print(f"LIVE_IDS={shlex.quote(ids('live'))}") + print(f"BENCH_IDS={shlex.quote(ids('bench'))}") + return 0 + if a.cmd == "list": + for n, b in by_role(a.role).items(): + if a.has and not b.get(a.has): + continue + if a.field: + if b.get(a.field): + print(b[a.field]) + else: + print(n) + return 0 + hit = find(a.key) + if a.cmd == "serial": + val = hit[1].get("serial") if hit else None + elif a.cmd == "mac": + val = hit[1].get("mac") if hit else None + elif a.cmd == "name": + val = hit[0] if hit else None + else: + val = hit[1].get(a.field) if hit else None + if not val: + return 1 + print(val) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tools/mesh_sniffer.py b/tools/mesh_sniffer.py new file mode 100755 index 00000000..520215db --- /dev/null +++ b/tools/mesh_sniffer.py @@ -0,0 +1,445 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Passive MeshCore sniffer -- every frame the radio hears, decoded on the host. + + tools/mesh_sniffer.py --board 0 --preset cz [--jsonl cap.jsonl] [--pcap cap.pcap] + [--psk ] [--seconds 600] + +Needs a board running the openHop modem firmware (openhop-dev/openhop_modem) and +`pip install openhop-core` -- the Python reimplementation of the MeshCore stack. +The board is a dumb SX1262 PHY: it hands up EVERY frame that passes CRC, tagged +with RSSI/SNR, and all decoding happens here. + +Why this exists, when we already have a node + BLE bridge feeding the analyzer: + + * A companion node only ever surfaces what ITS firmware decided to process -- + its own channels and DMs, adverts, packets addressed to it. Foreign-PSK + channel traffic and DIRECT packets for other destinations are dropped before + the companion protocol ever sees them. The modem has no such opinion, so + "SDR sees twice what the observer decodes" (docs, measured) becomes a + testable claim instead of a mystery: the modem's own rx_count is printed + next to the number of frames we managed to parse. + * No BLE anywhere on the path -- no dock-quiet interaction, no BlueZ holding + the link, no MC_BLE_OFF_INTERVAL windows costing 42 % of the capture. + +RECEIVE ONLY, by construction. There is no call to radio.send() in this file and +no dispatcher/handler is registered, so nothing can answer, ACK or forward. That +matters on 869.432: an unannounced node that starts answering confuses routing. +The modem is left with tx_power at its floor as a second line of defence. + +Two traps that shaped the code, both worth keeping in mind if you extend it: + + * openhop_core's own Dispatcher runs a PacketFilter that swallows byte-identical + frames for 30 s. That is right for a repeater and wrong for a sniffer -- two + neighbours relaying the same flood is exactly the observation we are after. + So this script parses packets itself instead of going through the dispatcher, + and counts duplicates instead of hiding them. + * USBLoRaRadio's rx_callback is handed only the payload; RSSI/SNR live in + radio.last_rssi/last_snr, which the NEXT packet overwrites before a queued + callback runs. So we override _dispatch_frame and take the metadata straight + out of the CMD_RX_PACKET frame, where it is atomic with the bytes. +""" + +from __future__ import annotations + +import argparse +import glob +import hashlib +import hmac +import json +import os +import socket +import struct +import sys +import threading +import time +from collections import Counter + +try: + from openhop_core.hardware.usb_radio import CMD_RX_PACKET, USBLoRaRadio + from openhop_core.protocol import decode_appdata, parse_advert_payload + from openhop_core.protocol.packet import Packet +except ImportError: + # --help má jít i bez závislostí: aspoň hlavička (plné volby až s openhop-core). + if {"-h", "--help"} & set(sys.argv[1:]): + print(__doc__.strip()) + sys.exit(0) + sys.exit( + "chybi openhop-core: python3 -m venv .venv && .venv/bin/pip install openhop-core pyserial" + ) + +# Fleet shorthand, same numbering as tools/xiao_uf2_flash.sh. Keyed on serial +# number because the by-id NAME changes with the firmware: the modem build +# renames the port from usb-Seeed_Studio_XIAO_nRF52840_ to +# usb-Seeed_XIAO-Wio-SX1262_, so anything matching on the name breaks the +# moment the board becomes a modem. +# Tabulka žije v fleet.py, ať se pátá kopie nerozejde s deskami. +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +from fleet import FLEET_BARE as FLEET + +# freq_hz, bandwidth_hz, sf, cr -- mirrored from platformio.ini / .local.ini so a +# capture cannot silently run on the wrong parameters. Two boards on different +# spreading factors simply cannot hear each other. +PRESETS = { + "cz": (869_432_000, 62_500, 7, 5), # live CZ mesh, [cz_radio] + "bench": (866_500_000, 62_500, 8, 5), # test band, [test_radio] + committed defaults + "prod": (869_618_000, 62_500, 8, 5), # committed platformio.ini default +} + +ROUTE_TYPES = {0: "TRANSPORT_FLOOD", 1: "FLOOD", 2: "DIRECT", 3: "TRANSPORT_DIRECT"} +PAYLOAD_TYPES = { + 0x00: "REQ", + 0x01: "RESPONSE", + 0x02: "TXT_MSG", + 0x03: "ACK", + 0x04: "ADVERT", + 0x05: "GRP_TXT", + 0x06: "GRP_DATA", + 0x07: "ANON_REQ", + 0x08: "PATH", + 0x09: "TRACE", + 0x0A: "MULTIPART", + 0x0B: "CONTROL", + 0x0F: "RAW_CUSTOM", +} +ADVERT_ROLES = {0x01: "chat", 0x02: "repeater", 0x03: "room", 0x04: "sensor"} + +LINKTYPE_USER0 = 147 # what openhop_core's own wireshark example uses + + +def resolve_port(board: str, port: str | None) -> str: + """Map a fleet number or serial number to a /dev/serial/by-id path.""" + if port: + return port + serial_no = FLEET.get(board, board) + matches = [p for p in glob.glob("/dev/serial/by-id/*") if serial_no in p] + if not matches: + sys.exit(f"zadny port pro sn {serial_no} -- pripojena deska? (ls /dev/serial/by-id/)") + if len(matches) > 1: + sys.exit(f"vic portu pro sn {serial_no}: {matches}") + return matches[0] + + +class SnifferRadio(USBLoRaRadio): + """USBLoRaRadio that hands RX frames straight to a callback, metadata included. + + See the module docstring: the stock rx_callback loses the RSSI/SNR pairing + under load, and it is scheduled onto an asyncio loop we do not want to run. + """ + + def __init__(self, *args, on_frame=None, **kwargs): + super().__init__(*args, **kwargs) + self._on_frame = on_frame + + def _dispatch_frame(self, cmd: int, payload: bytes): + if cmd == CMD_RX_PACKET and len(payload) >= 6: + # Keep the driver's own bookkeeping up to date -- get_status() is our + # honest denominator -- but do NOT delegate to super() here: with no + # rx_callback set it logs "RX packet but no callback registered" for + # every single frame, which is noise in a capture. + rssi, snr_x10, signal_rssi = struct.unpack(" tuple[int, bytes]: + """(channel hash, 32B secret) from a hex PSK, matching the firmware. + + The firmware hashes only the first 16 bytes when the second 16 are zero, so a + 128-bit key written out as 32 hex bytes still derives the right hash. + """ + secret = bytes.fromhex(psk_hex) + if len(secret) >= 32 and secret[16:32] == b"\x00" * 16: + hashed = secret[:16] + else: + hashed = secret[:32] + master = hashlib.sha256(hashed).digest() + secret32 = (secret + b"\x00" * 32)[:32] + return master[0], secret32 + + +def try_decrypt_channel(payload: bytes, keys: dict[int, list[bytes]]) -> dict | None: + """MeshCore group text: hash(1) | mac(2) | AES-128-ECB ciphertext.""" + if len(payload) < 4: + return None + chan_hash, mac, ciphertext = payload[0], payload[1:3], payload[3:] + for secret32 in keys.get(chan_hash, []): + if hmac.new(secret32, ciphertext, hashlib.sha256).digest()[:2] != mac: + continue # 1-byte hash collides; the HMAC is the real test + from Crypto.Cipher import AES # pycryptodome, pulled in by openhop-core + + padded = ciphertext + b"\x00" * (-len(ciphertext) % 16) + plain = AES.new(secret32[:16], AES.MODE_ECB).decrypt(padded)[: len(ciphertext)] + if len(plain) < 5: + return None + return { + "timestamp": int.from_bytes(plain[:4], "little"), + "flags": plain[4], + "text": plain[5:].decode("utf-8", errors="replace").rstrip("\x00"), + } + return None + + +def decode(data: bytes, keys: dict[int, list[bytes]]) -> dict: + """Parse one raw frame into a flat dict. Never raises.""" + out: dict = {"len": len(data), "raw": data.hex()} + pkt = Packet() + try: + pkt.read_from(data) + except Exception as exc: # truncated, bad version, bogus path_len + out["error"] = str(exc) + return out + + hash_size = pkt.get_path_hash_size() + hash_count = pkt.get_path_hash_count() + payload_type = pkt.get_payload_type() + path = bytes(pkt.path) + out.update( + { + "route": ROUTE_TYPES.get(pkt.get_route_type(), "?"), + "type": PAYLOAD_TYPES.get(payload_type, f"0x{payload_type:02X}"), + "ver": pkt.get_payload_ver(), + # Hash width is chosen by the SENDER and carried in bits 6-7 of + # path_len, so a 2B/3B-path-hash node decodes here without a rebuild. + "hash_size": hash_size, + "hops": hash_count, + "path": ":".join( + path[i : i + hash_size].hex() for i in range(0, hash_size * hash_count, hash_size) + ), + } + ) + if pkt.has_transport_codes(): + out["transport_codes"] = list(pkt.transport_codes) + + payload = bytes(pkt.payload) + name = out["type"] + try: + if name == "ADVERT": + adv = parse_advert_payload(payload) + app = decode_appdata(adv["appdata"]) if adv["appdata"] else {} + out["advert"] = { + "pubkey": adv["pubkey"], + "path_hash": adv["pubkey"][: hash_size * 2], + "timestamp": adv["timestamp"], + "name": app.get("node_name"), + "role": ADVERT_ROLES.get(app.get("flags", 0) & 0x0F), + "lat": app.get("latitude"), + "lon": app.get("longitude"), + } + elif name in ("GRP_TXT", "GRP_DATA"): + out["channel_hash"] = f"{payload[0]:02x}" + decrypted = try_decrypt_channel(payload, keys) + if decrypted: + out["channel_msg"] = decrypted + elif name == "ACK": + out["ack_crc"] = payload[:4].hex() + elif name in ("TXT_MSG", "RESPONSE", "REQ"): + # dest hash | src hash | mac | ciphertext, hashes as wide as the sender chose + out["dest"] = payload[:hash_size].hex() + out["src"] = payload[hash_size : hash_size * 2].hex() + elif name == "PATH": + out["dest"] = payload[:hash_size].hex() + elif name == "TRACE": + tag, auth, flags = struct.unpack(" str: + """One packet, one terminal line, most-identifying field last.""" + head = ( + f"{time.strftime('%H:%M:%S', time.localtime(rec['ts']))} " + f"{rec['rssi']:>4}dBm {rec['snr']:>5.1f}dB {rec['len']:>3}B " + f"{rec.get('route', '?'):<15} {rec.get('type', '?'):<9} " + f"{rec.get('hops', 0)}hop/{rec.get('hash_size', 0)}B" + ) + if rec.get("dup"): + head += f" dup#{rec['dup']}" + if "error" in rec: + return f"{head} UNPARSED: {rec['error']} {rec['raw'][:48]}" + tail = [] + if rec.get("path"): + tail.append(f"path={rec['path']}") + adv = rec.get("advert") + if adv: + tail.append(f"{adv.get('role') or 'node'} {adv.get('name') or '?'} [{adv['path_hash']}]") + if adv.get("lat"): + tail.append(f"{adv['lat']:.4f},{adv['lon']:.4f}") + if rec.get("channel_hash"): + tail.append(f"chan={rec['channel_hash']}") + if rec.get("channel_msg"): + tail.append(f"msg={rec['channel_msg']['text']!r}") + for key in ("dest", "src", "ack_crc"): + if rec.get(key): + tail.append(f"{key}={rec[key]}") + if rec.get("trace"): + tail.append(f"trace tag={rec['trace']['tag']}") + return f"{head} " + " ".join(tail) + + +def main() -> int: + ap = argparse.ArgumentParser(description=(__doc__ or "").split("\n")[0]) + ap.add_argument("--board", default="0", help="fleet number or serial number (default 0)") + ap.add_argument("--port", help="explicit /dev/serial/by-id path, overrides --board") + ap.add_argument("--preset", choices=sorted(PRESETS), default="cz") + ap.add_argument("--freq", type=float, help="MHz, overrides preset") + ap.add_argument("--bw", type=float, help="kHz, overrides preset") + ap.add_argument("--sf", type=int, help="overrides preset") + ap.add_argument("--cr", type=int, help="overrides preset") + ap.add_argument("--psk", action="append", default=[], help="channel PSK hex, repeatable") + ap.add_argument("--jsonl", help="append decoded packets here, one JSON per line") + ap.add_argument("--pcap", help="write raw frames as pcap (LINKTYPE_USER0)") + ap.add_argument("--wireshark", help="also stream pcap over UDP, host:port") + ap.add_argument("--seconds", type=float, help="stop after N seconds") + ap.add_argument("--status-interval", type=float, default=60.0, help="0 disables") + ap.add_argument("--quiet", action="store_true", help="no per-packet stdout") + args = ap.parse_args() + + freq, bw, sf, cr = PRESETS[args.preset] + if args.freq: + freq = int(args.freq * 1e6) + if args.bw: + bw = int(args.bw * 1000) + sf, cr = args.sf or sf, args.cr or cr + port = resolve_port(args.board, args.port) + + keys: dict[int, list[bytes]] = {} + for psk in args.psk: + chan_hash, secret32 = channel_keys(psk) + keys.setdefault(chan_hash, []).append(secret32) + + stats: Counter[str] = Counter() + seen: dict[str, int] = {} + lock = threading.Lock() + jsonl = open(args.jsonl, "a") if args.jsonl else None + pcap = PcapWriter(args.pcap, args.wireshark) + + def on_frame(data: bytes, rssi: int, snr: float, signal_rssi: int): + ts = time.time() + with lock: + stats["heard"] += 1 + rec = decode(data, keys) + rec.update({"ts": ts, "rssi": rssi, "snr": snr, "signal_rssi": signal_rssi}) + digest = hashlib.sha256(data).hexdigest()[:16] + seen[digest] = seen.get(digest, 0) + 1 + if seen[digest] > 1: + rec["dup"] = seen[digest] + stats["dup"] += 1 + stats["parsed" if "error" not in rec else "unparsed"] += 1 + stats[f"type:{rec.get('type', 'BAD')}"] += 1 + pcap.write(data, ts) + if jsonl: + jsonl.write(json.dumps(rec, default=str) + "\n") + jsonl.flush() + if not args.quiet: + print(format_line(rec), flush=True) + + print( + f"== port {os.path.basename(port)}\n" + f"== {freq / 1e6:.3f} MHz BW {bw / 1000:g} kHz SF{sf} CR{cr}" + f" ({args.preset}){' +' + str(len(args.psk)) + ' PSK' if args.psk else ''}", + flush=True, + ) + radio = SnifferRadio( + port=port, + frequency=freq, + bandwidth=bw, + spreading_factor=sf, + coding_rate=cr, + tx_power=2, # receive-only tool; keep the floor as a second safety net + lbt_enabled=False, + on_frame=on_frame, + ) + if not radio.begin(): + sys.exit(f"modem na {port} neodpovedel -- bezi na desce openHop modem firmware?") + print("== RX only, nic nevysilam. Ctrl-C ukonci a vypise souhrn.\n", flush=True) + + t0 = time.time() + next_status = t0 + args.status_interval if args.status_interval else None + try: + while True: + time.sleep(0.25) + now = time.time() + if args.seconds and now - t0 >= args.seconds: + break + if next_status and now >= next_status: + next_status = now + args.status_interval + # The modem's own counter is the honest denominator: it counted a + # CRC-clean frame even when nothing here could parse it. + modem = radio.get_status() + with lock: + print( + f"-- {now - t0:6.0f}s modem rx={modem.get('rx_count')} " + f"crc_err={modem.get('crc_errors')} heard={stats['heard']} " + f"parsed={stats['parsed']} unparsed={stats['unparsed']} " + f"dup={stats['dup']}", + flush=True, + ) + except KeyboardInterrupt: + pass + finally: + radio.cleanup() + pcap.close() + if jsonl: + jsonl.close() + + elapsed = time.time() - t0 + print(f"\n== {elapsed:.0f}s, {stats['heard']} frames heard, {stats['dup']} duplicates") + print(f"== parsed {stats['parsed']}, unparsed {stats['unparsed']}") + for key, count in sorted(stats.items()): + if key.startswith("type:"): + print(f" {key[5:]:<10} {count}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tools/power_ab.py b/tools/power_ab.py new file mode 100755 index 00000000..8cf0ee0e --- /dev/null +++ b/tools/power_ab.py @@ -0,0 +1,461 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""A/B current measurement on a bench node, via the UC96 meter's own exporter. + + tools/power_ab.py --serial 0123456789ABCDEF --minutes 30 \ + --cell "baseline=" --cell "ps=powersaving on" --cell "duty=gps duty" + +Why the exporter and not the meter: `uc96-exporter.service` owns the BLE link to +the UC96. A second central connecting to it takes the link away and the service +reconnect-loops, so this reads http://localhost:9877/metrics instead. Same data, +no contention. (It also lands in Mimir via alloy, so a run stays inspectable +afterwards -- but the exporter is scraped live, which is tighter for timing.) + +**The instantaneous current field is useless here.** The UC96 reports current in +10 mA steps (`meter_current_amps` 0.02 for a node drawing anywhere from 15 to +24 mA), and the deltas worth chasing on a repeater are 1-4 mA. The accumulating +`meter_capacity_ah` counter has 1 mAh resolution, so this integrates that over a +window instead: avg mA = 60 * delta_mAh / minutes. The +-1 mAh quantisation is +printed with every cell as an explicit error bar -- at 20 minutes that is ++-3 mA, which would swallow the whole effect, so short windows are a trap and +the tool says so rather than letting you read noise as a result. + +Two estimators are reported per cell, because the endpoint one alone wastes the +window: `fit` is a least-squares slope through the whole sampled staircase, and +it beats the endpoint difference by using WHEN each 1 mAh step landed instead of +only how many landed. Its residual spread is printed too -- a cell that drifted +(traffic burst, charging, a hand near the antenna) shows up there rather than +quietly biasing the number. When the two estimators disagree by more than the +error bar, do not average them: the cell was not stationary, so re-run it. + +Airtime counters are recorded per cell as CONTEXT, not as the claim: a cell that +happened to relay a flood burns more than an idle one, and without that column a +polluted cell looks like a real regression. +""" + +import argparse +import glob +import json +import re +import sys +import time +import urllib.request + +import serial + +EXPORTER = "http://localhost:9877/metrics" +SETTLE_DEFAULT = 60 + + +def meter_sample(url, meter=None): + """One reading of the exporter: (capacity_mAh, volts, amps, unix_ts).""" + with urllib.request.urlopen(url, timeout=10) as r: + body = r.read().decode() + out = {} + for name in ("meter_capacity_ah", "meter_voltage_volts", "meter_current_amps", + "meter_last_seen_timestamp_seconds", "meter_up"): + for line in body.splitlines(): + if not line.startswith(name + "{"): + continue + if meter and f'meter="{meter}"' not in line: + continue + out[name] = float(line.rsplit(" ", 1)[1]) + break + missing = [k for k in ("meter_capacity_ah", "meter_up") if k not in out] + if missing: + raise SystemExit(f"exporter neposkytl {missing} (jiny meter? --meter )") + if out["meter_up"] != 1.0: + raise SystemExit("meter_up=0 -- exporter nema spojeni s meraakem, meritko by lhalo") + # Frames must be arriving, not just the link be up: a stale series is a + # straight line, and a straight line reads like a perfectly stable load. + age = time.time() - out.get("meter_last_seen_timestamp_seconds", 0.0) + if age > 30: + raise SystemExit(f"posledni ramec pred {age:.0f} s -- serie je zamrzla, ne stabilni") + return (out["meter_capacity_ah"] * 1000.0, out.get("meter_voltage_volts", 0.0), + out.get("meter_current_amps", 0.0), out.get("meter_last_seen_timestamp_seconds", 0.0)) + + +def fit_slope_ma(series): + """Least-squares mA through (seconds, mAh) samples: (mA, residual, std err). + + The counter is a 1 mAh staircase, so the slope carries the timing of every + step, not just the count at the ends. Residuals are returned in mAh: on a + stationary cell they stay under ~0.6 (half a step); much more than that means + the load moved during the window and the average is hiding something. + + CAVEAT on the standard error: it assumes independent residuals, and a + quantised staircase violates that (consecutive samples sit on the same step), + so it reads optimistic. It is still the right order of magnitude, and it is + the honest one to compare deltas against -- unlike the endpoint quantisation, + which the fit is specifically there to beat. Run one cell twice to get the + empirical repeatability; that number outranks this estimate. + """ + n = len(series) + if n < 4: + return None, None, None + tx = sum(t for t, _ in series) / n + ty = sum(c for _, c in series) / n + sxx = sum((t - tx) ** 2 for t, _ in series) + if sxx == 0: + return None, None, None + sxy = sum((t - tx) * (c - ty) for t, c in series) + slope = sxy / sxx # mAh per second + sse = sum((c - (ty + slope * (t - tx))) ** 2 for t, c in series) + resid = (sse / n) ** 0.5 + se = ((sse / (n - 2)) / sxx) ** 0.5 # mAh/s + return slope * 3600.0, resid, se * 3600.0 + + +class Console: + """Text console of a repeater/analyzer build over USB CDC. + + dtr/rts + the settle delay are not optional: nRF52 TinyUSB keeps the CDC + mute until DTR is asserted, and a board opened without it looks dead. + """ + + LOST = "" + + def __init__(self, port_glob): + self.port_glob = port_glob + self.s = None + self._open() + + def _open(self): + path = glob.glob(self.port_glob) + if not path: + raise SystemExit(f"port {self.port_glob} nenalezen") + self.s = serial.Serial(path[0], 115200, timeout=0) + self.s.dtr = True + self.s.rts = True + time.sleep(1.3) + self.s.reset_input_buffer() + + def reopen(self, wait=90.0): + """Wait for the board to come back on USB and re-open it. + + These boards drop off USB on their own (documented flakiness) and return + seconds to minutes later. Losing the console mid-run must not force a + rerun of an hour-long matrix. + """ + try: + if self.s: + self.s.close() + except Exception: + pass + self.s = None + t0 = time.time() + while time.time() - t0 < wait: + if glob.glob(self.port_glob): + try: + self._open() + return True + except (OSError, serial.SerialException, SystemExit): + pass + time.sleep(3) + return False + + def cmd(self, c, timeout=4.0, quiet=0.3): + """Send a command. On a console drop, re-open once and retry. + + Returns LOST if the console could not be recovered. Callers that are + APPLYING a cell setting must treat that as a failed cell — measuring a + treatment that was never applied is worse than no measurement, and it + happened: `gps off` was lost on the wire, the run carried on, and two + cells silently measured `gps on` again. + """ + try: + return self._cmd(c, timeout, quiet) + except (OSError, serial.SerialException): + pass + if self.reopen(): + try: + return self._cmd(c, timeout, quiet) + except (OSError, serial.SerialException): + pass + return self.LOST + + def _cmd(self, c, timeout, quiet): + if self.s is None: + raise serial.SerialException("console not open") + self.s.write((c + "\r").encode()) + buf, last, t0 = b"", time.time(), time.time() + while time.time() - t0 < timeout: + d = self.s.read(256) + if d: + buf += d + last = time.time() + elif buf and time.time() - last > quiet: + break + else: + time.sleep(0.02) + txt = buf.decode(errors="replace") + # echo of the command comes back first; keep the answer only + lines = [ln.strip() for ln in txt.replace("\r", "\n").split("\n") if ln.strip()] + lines = [ln for ln in lines if ln != c] + return " | ".join(ln.lstrip("> ").strip() for ln in lines) + + def air(self): + m = re.search(r'"tx_air_secs":(\d+).*?"rx_air_secs":(\d+)', self.cmd("stats-radio")) + return (int(m.group(1)), int(m.group(2))) if m else (None, None) + + def close(self): + try: + if self.s: + self.s.close() + except Exception: + pass + + +# What a cell's setting command must end up reporting, so "applied" is verified +# on the node rather than assumed from a write that returned no error. Key is the +# command prefix, value is (query, expected substring in the answer). +VERIFY = { + "gps off": ("gps", "off"), + "gps on": ("gps", "on,"), + "gps duty": ("gps", "duty"), + "powersaving on": ("powersaving", "on"), + "powersaving off": ("powersaving", "off"), + "ble on": ("ble", "on"), + "ble off": ("ble", "off"), +} + +# Queried at the start of every cell: the record of what the node actually was, +# and the raw material for VERIFY above. +STATE_QUERIES = ("powersaving", "gps", "ble", "get repeat") + + +def port_glob_for(serial_no): + g = glob.glob(f"/dev/serial/by-id/*{serial_no}*") + if not g: + raise SystemExit(f"port pro seriak {serial_no} nenalezen v /dev/serial/by-id/") + return f"/dev/serial/by-id/*{serial_no}*" + + +def main(): + ap = argparse.ArgumentParser(description="A/B mereni proudu pres UC96 exporter") + ap.add_argument("--serial", help="seriove cislo desky (matchuje se v /dev/serial/by-id/)") + ap.add_argument("--port", help="misto --serial: pevna cesta k portu") + ap.add_argument("--cell", action="append", default=[], metavar="NAME=CMD[;CMD]", + help="jedna bunka: jmeno a prikazy, ktere ji nastavi (prazdne = jen mer)") + ap.add_argument("--minutes", type=float, default=30.0, help="delka okna bunky (vychozi 30)") + ap.add_argument("--settle", type=float, default=SETTLE_DEFAULT, + help="prodleva po aplikaci prikazu pred zacatkem okna (s, vychozi 60)") + ap.add_argument("--poll", type=float, default=10.0, + help="jak casto vzorkovat citac kapacity v okne (s, vychozi 10)") + ap.add_argument("--meter", help="MAC merace bez dvojtecek, kdyz exporter vidi vic meraku") + ap.add_argument("--url", default=EXPORTER) + ap.add_argument("--json", help="ulozit vysledek jako JSON") + args = ap.parse_args() + + if not args.cell: + raise SystemExit("aspon jedna --cell") + + err_ma = 60.0 / args.minutes # +-1 mAh quantisation over the window + print(f"okno {args.minutes:g} min => kvantizace merice je +-{err_ma:.2f} mA na bunku") + if err_ma > 1.5: + print(" POZOR: to je vic, nez kolik ceka vetsina uspor. Delsi --minutes, nebo " + "cti vysledek jako 'nezmereno'.") + + con = None + if args.serial or args.port: + con = Console(args.port or port_glob_for(args.serial)) + print(f"deska: {con.cmd('ver')} / {con.cmd('get name')}") + + results = [] + try: + for spec in args.cell: + name, _, cmds = spec.partition("=") + name = name.strip() or "cell" + cmds = [c.strip() for c in cmds.split(";") if c.strip()] + print(f"\n=== bunka {name}") + + applied = True + for c in cmds: + if not con: + raise SystemExit("bunka ma prikazy, ale neni zadana deska (--serial)") + reply = con.cmd(c) + print(f" {c} -> {reply}") + if reply == Console.LOST or "Unknown command" in reply or "rror" in reply: + applied = False + if cmds: + print(f" usazovani {args.settle:g} s") + time.sleep(args.settle) + + state = {} + tx0 = rx0 = None + if con: + for q in STATE_QUERIES: + state[q] = con.cmd(q) + tx0, rx0 = con.air() + + # Verify on the node that the setting took, then refuse to measure a + # treatment that is not actually in place. The alternative -- what + # this tool did before -- is a plausible-looking number for a state + # the node was never in. + for c in cmds: + for prefix, (query, expect) in VERIFY.items(): + if c.startswith(prefix): + answer = state.get(query, "") + if expect not in answer: + print(f" NEOVERENO: po '{c}' hlasi '{query}' -> " + f"'{answer}' (cekano '{expect}')") + applied = False + if not applied: + print(" CHYBA: zasah se neaplikoval/neoveril -- bunka se NEMERI " + "(merit neaplikovany zasah je horsi nez nemerit)") + results.append({"cell": name, "cmds": cmds, "avg_ma": None, "fit_ma": None, + "resid_mah": None, "se_ma": None, "delta_mah": None, + "minutes": 0.0, "err_ma": err_ma, "volts": None, + "state": state, "tx_air_delta": None, "rx_air_delta": None, + "samples": 0, "invalid": "neaplikovano"}) + continue + cap0, v0, _, _ = meter_sample(args.url, args.meter) + t0 = time.time() + print(f" start: cap={cap0:.0f} mAh, U={v0:.2f} V, stav={state}") + + series = [(0.0, cap0)] + deadline = t0 + args.minutes * 60 + # Heartbeat once a minute. Without it a healthy cell and a hung + # process look identical for ten minutes at a stretch -- which is + # exactly how a good run got killed two minutes before it finished. + next_beat = t0 + 60 + while time.time() < deadline: + time.sleep(min(args.poll, max(0.0, deadline - time.time()))) + cap, v1, i1, _ = meter_sample(args.url, args.meter) + now = time.time() + series.append((now - t0, cap)) + if now >= next_beat: + next_beat += 60 + el = (now - t0) / 60.0 + print(f" ... {el:.0f}/{args.minutes:g} min, +{cap-cap0:.0f} mAh, " + f"zatim {(cap-cap0)/((now-t0)/3600.0):.1f} mA", flush=True) + + cap1, v1, i1, _ = meter_sample(args.url, args.meter) + series.append((time.time() - t0, cap1)) + dt_h = (time.time() - t0) / 3600.0 + tx1, rx1 = con.air() if con else (None, None) + dcap = cap1 - cap0 + fit_ma = resid = se_ma = None + if dcap < 0: + print(" CHYBA: citac kapacity klesl (reset merice) -- bunka je neplatna") + avg = None + elif dcap == 0: + # An instrument reporting a perfectly flat counter is not + # measuring a small load, it is not measuring. Reporting + # "0.00 +-0.00 mA" as a result once sent a whole session chasing + # the wrong thing: the same board read 22 mA on another meter + # while this one sat at zero for 15 minutes. Refuse the cell. + print(f" CHYBA: citac kapacity se za {dt_h*60:.0f} min NEHNUL " + f"(instant {i1*1000:.0f} mA). Merak tuhle zatez nemeri -- " + f"nula NENI vysledek. Zkus jiny merak nebo vetsi zatez.") + avg = None + else: + avg = dcap / dt_h + fit_ma, resid, se_ma = fit_slope_ma(series) + print(f" konec: cap={cap1:.0f} mAh, delta={dcap:.0f} mAh za {dt_h*60:.1f} min, " + f"{len(series)} vzorku") + print(f" ==> endpoint {avg:.2f} +-{err_ma:.2f} mA | fit {fit_ma:.2f} " + f"+-{se_ma:.2f} mA (rezidua {resid:.2f} mAh) @ {v1:.2f} V " + f"(instant {i1*1000:.0f} mA, 10mA krok)") + if abs(fit_ma - avg) > err_ma: + print(" POZOR: estimatory se rozchazi vic nez chyba -- bunka nebyla " + "stacionarni, zopakuj ji") + # stats-radio can fail to parse on either end (busy console); keep the + # cell valid and just report the airtime column as unknown. + d_tx = tx1 - tx0 if (tx0 is not None and tx1 is not None) else None + d_rx = rx1 - rx0 if (rx0 is not None and rx1 is not None) else None + if d_tx is not None: + print(f" airtime v okne: tx +{d_tx} s, rx +{d_rx} s") + results.append({"cell": name, "cmds": cmds, "avg_ma": avg, "fit_ma": fit_ma, + "resid_mah": resid, "se_ma": se_ma, "delta_mah": dcap, + "minutes": dt_h * 60, "err_ma": err_ma, "volts": v1, + "state": state, "tx_air_delta": d_tx, "rx_air_delta": d_rx, + "samples": len(series)}) + finally: + if con: + con.close() + + summarize(results) + + if args.json: + with open(args.json, "w") as f: + json.dump(results, f, indent=2) + print(f"\nJSON -> {args.json}") + return 0 + + +def summarize(results): + """Print the summary. Separate from main() so a finished run's JSON can be + re-analysed (and the analysis tested) without touching hardware.""" + print("\n===== SOUHRN ===== (fit je presnejsi estimator, endpoint v zavorce)") + valid = [r for r in results if r["fit_ma"] is not None] + base = valid[0] if valid else None + + # Spread across repeats of the same cell is repeatability ONLY if the rig is + # stationary. It is not, when something drifts underneath (a charging cell + # tapering: `gps on` cells went 107 -> 92 -> 88 -> 84 mA across one hour). + # Using that spread as a noise floor then buries the very effect being + # measured -- it flagged a real 46 mA GPS delta as "v sumu". + floor = None + groups = {} + for r in valid: + groups.setdefault(tuple(r["cmds"]), []).append(r["fit_ma"]) + for cmds, vals in groups.items(): + if len(vals) > 1: + spread = max(vals) - min(vals) + trend = abs(vals[-1] - vals[0]) + drifting = trend > 0.6 * spread # monotone-ish: most of the spread is trend + label = "drift, NE sum" if drifting else "opakovatelnost" + print(f" {label} ({'+'.join(cmds) or 'bez prikazu'}): rozptyl {spread:.2f} mA " + f"pres {len(vals)} bunky (kraje se lisi o {trend:.2f})") + if not drifting: + floor = spread if floor is None else max(floor, spread) + + # Alternating designs (A B A B ...) are the answer to a drifting rig, so + # analyse them as such: each B against the MEAN OF ITS TWO NEIGHBOURING A + # cells, which cancels a linear trend. This is the number to quote. + sigs = [tuple(r["cmds"]) for r in valid] + distinct = list(dict.fromkeys(sigs)) + if len(distinct) == 2 and len(valid) >= 3: + a_sig, b_sig = distinct + deltas = [] + for i, r in enumerate(valid): + if tuple(r["cmds"]) != b_sig: + continue + before = next((v["fit_ma"] for v in reversed(valid[:i]) + if tuple(v["cmds"]) == a_sig), None) + after = next((v["fit_ma"] for v in valid[i + 1:] + if tuple(v["cmds"]) == a_sig), None) + flank = [x for x in (before, after) if x is not None] + if flank: + deltas.append(sum(flank) / len(flank) - r["fit_ma"]) + if deltas: + mean = sum(deltas) / len(deltas) + print(f"\n PAROVY ODHAD ({'+'.join(a_sig) or 'bez prikazu'} minus " + f"{'+'.join(b_sig) or 'bez prikazu'}): {mean:.2f} mA " + f"(z {len(deltas)} paru, rozptyl {min(deltas):.2f}-{max(deltas):.2f}) " + f"-- drift vykracen, tohle je cislo k citovani") + + for r in valid: + d = "" + if base and r is not base: + diff = r["fit_ma"] - base["fit_ma"] + # Significance against the measured repeatability when we have it, + # otherwise against twice the fit's own standard error. + lim = floor if floor is not None else 2 * (r["se_ma"] or 0) + sig = "" if abs(diff) > lim else " (v sumu!)" + d = f" delta vs {base['cell']}: {diff:+.2f} mA{sig}" + print(f" {r['cell']:12s} {r['fit_ma']:6.2f} +-{r['se_ma']:.2f} mA " + f"(endpoint {r['avg_ma']:.2f} +-{r['err_ma']:.2f}){d}") + for r in results: + if r["fit_ma"] is None: + print(f" {r['cell']:12s} neplatna ({r.get('invalid', 'merak nemeril')})") + + +if __name__ == "__main__": + # Re-analyse a finished run: power_ab.py --reanalyse run.json + if len(sys.argv) == 3 and sys.argv[1] == "--reanalyse": + with open(sys.argv[2]) as f: + summarize(json.load(f)) + sys.exit(0) + sys.exit(main()) diff --git a/tools/preset_trace.py b/tools/preset_trace.py new file mode 100644 index 00000000..7c77f0b3 --- /dev/null +++ b/tools/preset_trace.py @@ -0,0 +1,85 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""TRACE po pevné cestě na zvoleném presetu přes USB companion — měření přímého hopu. + +Companion přepne rádio na preset, pošle N× TRACE po cestě (2B hashe) a vypíše +SNR, které na trase připsal každý hop, a SNR, se kterým odpověď slyšel on sám. +Slouží k měření spoje mezi dvěma repeatery, které jsou mezitím přes `tempradio` +na stejném presetu (sám je nepřelaďuje). + + preset_trace.py /dev/serial/by-id/... 869.525 62.5 12 8 --path 025c,5f14,025c -n 8 + preset_trace.py /dev/serial/by-id/... 866.5 62.5 8 5 --tx 2 --restore # zpět, bez TRACE + +Nastavení rádia companion ukládá do prefs — po měření ho vrať (--restore). +Výstup: jedna JSON řádka na pokus (ok/timeout, hopy se SNR, rtt). +""" +import argparse +import asyncio +import json +import random +import time + + +def parse(): + ap = argparse.ArgumentParser(description=__doc__, + formatter_class=argparse.RawDescriptionHelpFormatter) + ap.add_argument("port", help="sériový port companionu (/dev/serial/by-id/...)") + ap.add_argument("freq", type=float, help="MHz") + ap.add_argument("bw", type=float, help="kHz") + ap.add_argument("sf", type=int) + ap.add_argument("cr", type=int, help="5..8 (4/5..4/8)") + ap.add_argument("--tx", type=int, default=22, help="TX výkon dBm (default 22)") + ap.add_argument("--path", default="025c,5f14,025c", help="hopy TRACE, 2B hex, čárkou") + ap.add_argument("-n", type=int, default=8, help="počet TRACE (default 8)") + ap.add_argument("--gap", type=float, default=3.0, help="pauza mezi pokusy, s") + ap.add_argument("--timeout", type=float, default=0, + help="čekání na odpověď, s (0 = odhad firmwaru + 50 %%)") + ap.add_argument("--restore", action="store_true", help="jen nastavit rádio, žádný TRACE") + return ap.parse_args() + + +async def main(a): + from meshcore import EventType, MeshCore + + mc = await MeshCore.create_serial(a.port, 115200) + if mc is None: + raise SystemExit("companion neodpovídá") + r = await mc.commands.set_radio(a.freq, a.bw, a.sf, a.cr) + if r.type == EventType.ERROR: + raise SystemExit("set_radio: %s" % r.payload) + r = await mc.commands.set_tx_power(a.tx) + if r.type == EventType.ERROR: # build caps TX (MAX_LORA_TX_POWER): keep its current power + print(json.dumps({"warn": "set_tx_power %d refused" % a.tx}), flush=True) + await mc.commands.send_appstart() + si = mc.self_info + print(json.dumps({"radio": [si.get("radio_freq"), si.get("radio_bw"), si.get("radio_sf"), + si.get("radio_cr")], "tx": si.get("tx_power")}), flush=True) + if a.restore: + await mc.disconnect() + return + + for i in range(a.n): + tag = random.randint(1, 0xFFFFFFFF) + t0 = time.monotonic() + sent = await mc.commands.send_trace(auth_code=0, tag=tag, flags=1, path=a.path) + if sent.type == EventType.ERROR: + print(json.dumps({"i": i, "error": str(sent.payload)}), flush=True) + await asyncio.sleep(a.gap) + continue + est = (sent.payload or {}).get("suggested_timeout", 0) / 1000 + wait = a.timeout or max(10.0, est * 1.5) + ev = await mc.wait_for_event(EventType.TRACE_DATA, attribute_filters={"tag": tag}, + timeout=wait) + rec = {"i": i, "t": time.strftime("%H:%M:%S"), "wait": round(wait, 1)} + if ev is None: + rec["ok"] = False + else: + rec.update(ok=True, rtt=round(time.monotonic() - t0, 1), + hops=[[h.get("hash", "me"), h["snr"]] for h in ev.payload.get("path", [])]) + print(json.dumps(rec), flush=True) + await asyncio.sleep(a.gap) + await mc.disconnect() + + +if __name__ == "__main__": + asyncio.run(main(parse())) diff --git a/tools/radio_stall_watch.py b/tools/radio_stall_watch.py new file mode 100755 index 00000000..d7f10b1a --- /dev/null +++ b/tools/radio_stall_watch.py @@ -0,0 +1,129 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Watch a RADIO_DIAG node on its USB console until its receiver goes deaf. + +usage: radio_stall_watch.py [--stall-min N] [--log FILE] + +Born 31. 10. 2026: bench-sensor stopped receiving (recv frozen, noise_floor +-120, last_rssi 0) and a reboot revived it. A reboot fixes nothing, it only +destroys the evidence -- so this sits on the console and waits for the next one: + + * every line the node prints (MESH_DEBUG) goes to the log with a UTC stamp + * every 60 s: `radiostat` + `stats-packets` + * no packet read for --stall-min minutes (default 15; the live CZ mesh + normally delivers a flood every 30-60 s) = STALL: + - three `radiostat` snapshots, 10 s apart (is anything still moving?) + - then the recovery ladder, gentlest first, one step at a time: + clrirq -> rx -> standby -> agc. After each step it waits 3 min for a + packet; the FIRST step that brings recv back names the broken layer + (lost DIO1 edge / RX not re-armed / chip out of RX / AGC-analog). + - if nothing helps, it says so and leaves the node deaf for a human. + It does not reboot the node, ever. + +Needs firmware built with -D RADIO_DIAG (radiostat/radiokick). Holds the port +open for as long as it runs, so the node's BLE (dock-quiet) and other console +users are off meanwhile. Nothing is transmitted. +""" + +import re +import sys +import time + +if {"-h", "--help"} & set(sys.argv[1:]): + print(__doc__.strip()) + sys.exit(0) + +import serial # noqa: E402 + +LADDER = ["clrirq", "rx", "standby", "agc"] +RX_RE = re.compile(r"\brx=(\d+)/(\d+)s") + + +def utc(): + return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()) + + +class Node: + def __init__(self, port, log): + self.s = serial.Serial(port, 115200, timeout=0.2) + self.log = log + self.buf = b"" + + def write_log(self, line): + self.log.write(f"{utc()} {line}\n") + self.log.flush() + + def pump(self, secs): + """Log everything the node prints for `secs`; return the lines.""" + out, end = [], time.time() + secs + while time.time() < end: + self.buf += self.s.read(4096) + while b"\n" in self.buf: + raw, self.buf = self.buf.split(b"\n", 1) + line = raw.decode(errors="replace").rstrip("\r") + if line: + self.write_log(line) + out.append(line) + return out + + def cmd(self, c): + self.write_log(f">>> {c}") + self.s.write((c + "\r").encode()) + for line in self.pump(1.0): + if line.startswith(c) and "->" in line: + return line.split("->", 1)[1].strip() + return "" + + def rx_age(self): + m = RX_RE.search(self.cmd("radiostat")) + return (int(m.group(1)), int(m.group(2))) if m else (None, None) + + +def main(port, stall_s, logpath): + with open(logpath, "a") as log: + n = Node(port, log) + n.write_log(f"=== watch start, stall after {stall_s} s, port {port}") + n.cmd("ver") + while True: + n.pump(59) + n.cmd("stats-packets") + rx, age = n.rx_age() + if age is None or age < stall_s: + continue + n.write_log(f"!!! STALL: no packet read for {age} s (rx={rx})") + for _ in range(3): + n.cmd("radiostat") + n.pump(10) + for step in LADDER: + n.cmd(f"radiokick {step}") + end = time.time() + 180 + while time.time() < end: + n.pump(30) + rx2, _ = n.rx_age() + if rx2 is not None and rx2 > rx: + n.write_log(f"!!! RECOVERED by '{step}' (rx {rx} -> {rx2})") + break + else: + n.write_log(f"... '{step}' did not bring RX back") + continue + break + else: + n.write_log("!!! NOTHING on the ladder revived RX -- left deaf for inspection") + n.pump(10**9) + + +stall_min, logfile = 15, "radio_stall_watch.log" +it = iter(sys.argv[1:]) +args = [] +for a in it: + if a == "--stall-min": + stall_min = int(next(it)) + elif a == "--log": + logfile = next(it) + elif a.startswith("--"): + sys.exit(__doc__.strip().splitlines()[2]) + else: + args.append(a) +if len(args) != 1: + sys.exit(__doc__.strip().splitlines()[2]) +main(args[0], stall_min * 60, logfile) diff --git a/tools/serial_cli.py b/tools/serial_cli.py new file mode 100755 index 00000000..c60a4ebf --- /dev/null +++ b/tools/serial_cli.py @@ -0,0 +1,116 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Textova konzole uzlu na USB -- posli prikazy, vypis odpovedi. + + tools/serial_cli.py x4 ver + tools/serial_cli.py x4 "get freq" "get name" "get batt.icon" + tools/serial_cli.py /dev/serial/by-id/usb-Seeed_Studio_XIAO_... ver + tools/serial_cli.py --list + +USB protejsek `ble_cli.py`. Vzniklo 21. 9. 2026: `board_probe.py` umi jen +otisk (posle `ver` a skonci), `fleet_test.py` konzoli pouziva, ale jen na svuj +scenar -- a na kazdy dotaz typu "co ma ta deska ve `get freq`" se pokazde psal +jednorazovy skript znovu. + +Parametry portu jsou prevzate z `board_probe.py::_open()` vcetne dvou veci, +ktere vypadaji jako zbytecnost a nejsou: + + * DTR+RTS nahoru a 0,9 s cekani -- bez toho deska jeste neni pripravena + a prvni prikaz spolkne. + * prazdne CRLF pred prvnim prikazem -- prvni radek po otevreni portu se + casto ztrati uplne. + +PAST (z hlavicky fleet_test.py): nenechavej pripojeneho BLE klienta na desce, +se kterou tady mluvis. USB a BLE konzole sdileji jeden buffer command[160] +(simple_repeater/main.cpp), takze dve zive konzole si michaji znaky do jedne +radky a uzel pak vykona nesmysl. + +Companion buildy textovou konzoli NEMAJI a na vsechno tady odpovi tichem -- +neni to zaseklá deska. Co na ktere desce bezi rekne `board_probe.py --all`. +""" +import argparse +import glob +import os +import sys +import time + +# FLEET ani otevírání portu se tu NEDUPLIKUJE -- viz fleet.py (tabulka) a +# board_probe.py::_open (sekvence dtr/rts + settle + prime, kterou by druhá +# kopie dřív nebo později rozešla). AGENTS.md: "nevymýšlej kolo". +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +from board_probe import _open as open_port +from fleet import FLEET, serial_for +from mctools_config import field, unknown_alias_hint + + +def ports(): + return sorted(glob.glob("/dev/serial/by-id/*")) + + +def resolve(target): + """Jmeno z flotily, holé seriove cislo, nebo rovnou cesta k portu.""" + if target.startswith("/"): + return target + sn = serial_for(target) + why = field(sn, "refuse") + if why: + sys.exit(f"{target}: odmitnuto -- {why}") + hits = [p for p in ports() if sn in p] + if not hits: + hint = f"; {unknown_alias_hint(target)}" if sn == target else "" + sys.exit(f"port pro {target!r} (sn {sn}) nenalezen -- viz --list{hint}") + if len(hits) > 1: + sys.exit(f"{target!r} odpovida vic portum: {hits}") + return hits[0] + + +def drain(s, window): + buf, t = b"", time.time() + while time.time() - t < window: + d = s.read(8192) + if d: + buf += d + else: + time.sleep(0.02) + return buf + + +def main(): + ap = argparse.ArgumentParser(description=__doc__, + formatter_class=argparse.RawDescriptionHelpFormatter) + ap.add_argument("board", nargs="?", help="jmeno desky z configu (tools/mctools_config.py), seriove cislo, nebo cesta k portu") + ap.add_argument("cmd", nargs="*", help="prikazy konzole") + ap.add_argument("--list", action="store_true", help="vypis porty a konci") + ap.add_argument("--wait", type=float, default=1.5, + help="kolik sekund cekat na odpoved (default 1.5; `nodes` a " + "`rxlog` na plnem uzlu chtou vic)") + ap.add_argument("--raw", action="store_true", help="bez hlavicek, jen odpovedi") + args = ap.parse_args() + + if args.list: + for p in ports(): + tag = next((n for n, sn in FLEET.items() if sn in p), "") + print(f"{tag:4} {p}") + return + if not args.board or not args.cmd: + ap.error("chybi deska nebo prikaz (viz --list)") + + port = resolve(args.board) + s = open_port(port) # dtr/rts + 0,9 s settle + reset_input_buffer + try: + s.write(b"\r\n") + time.sleep(0.4) + s.reset_input_buffer() + + for c in args.cmd: + s.write(c.encode() + b"\r\n") + out = drain(s, args.wait).decode(errors="replace").strip() + if args.raw: + print(out) + else: + print(f"[{args.board}] {c}\n{out}\n") + finally: + s.close() + + +main() diff --git a/tools/serial_tcp_proxy.py b/tools/serial_tcp_proxy.py new file mode 100755 index 00000000..69690515 --- /dev/null +++ b/tools/serial_tcp_proxy.py @@ -0,0 +1,86 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Bridge a bench XIAO's USB console to a localhost TCP port. + + tools/serial_tcp_proxy.py + +Holds the console open with DTR/RTS up (as fleet_test.py does) and serves it +on 127.0.0.1:, one client at a time, so a board on another host +joins a test run here through an SSH tunnel: + + ssh -L 7001:127.0.0.1:7001 lab-pc \\ + 'python3 MeshCore/tools/serial_tcp_proxy.py b1 7001' + tools/fleet_test.py --boards 4 --remote 1=socket://127.0.0.1:7001 + +Localhost only. Matches the board by its USB serial number, never ttyACM*; +a board name/alias is looked up in the local config (tools/mctools_config.py) +of the host it runs on. Refuses a board whose config entry sets `refuse` +(e.g. the radio of an observer, which runs other firmware). +""" + +import glob +import socket +import sys +import threading + +from mctools_config import field, serial_for + + +def serve(ser, srv: socket.socket) -> None: + while True: + conn, _ = srv.accept() + conn.settimeout(0.05) + alive = [True] + + def to_client() -> None: + while alive[0]: + try: + data = ser.read(4096) + if data: + conn.sendall(data) + except OSError: + alive[0] = False + + t = threading.Thread(target=to_client, daemon=True) + t.start() + while alive[0]: + try: + data = conn.recv(4096) + if not data: + break + ser.write(data) + except socket.timeout: + continue + except OSError: + break + alive[0] = False + t.join(1) + conn.close() + + +def main() -> None: + if len(sys.argv) != 3 or sys.argv[1] in ("-h", "--help"): + print(__doc__) + sys.exit(0) + sn, tport = serial_for(sys.argv[1]), int(sys.argv[2]) + why = field(sn, "refuse") + if why: + sys.exit(f"refused: {why}") + ports = [p for p in glob.glob("/dev/serial/by-id/*Seeed_Studio_XIAO*") if sn in p] + if not ports: + sys.exit(f"{sn}: no MeshCore XIAO port") + import serial # after --help: the help works without pyserial + + ser = serial.Serial(ports[0], 115200, timeout=0.05) + ser.dtr = True + ser.rts = True + srv = socket.socket() + srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) + srv.bind(("127.0.0.1", tport)) + srv.listen(1) + print(f"{ports[0]} <-> 127.0.0.1:{tport}", flush=True) + serve(ser, srv) + + +if __name__ == "__main__": + main() diff --git a/tools/xiao_serial_dfu.sh b/tools/xiao_serial_dfu.sh new file mode 100755 index 00000000..3d526646 --- /dev/null +++ b/tools/xiao_serial_dfu.sh @@ -0,0 +1,75 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MIT +# Flash a XIAO nRF52840 with a text console (repeater, room server, sensor) +# over USB serial DFU -- no UF2 drive, no mount, no root, no 1200-baud touch. +# +# tools/xiao_serial_dfu.sh +# +# firmware.zip the DFU package (.pio/build//firmware.zip, or a release +# asset *.zip) +# usb-serial the board's USB serial number (matched in /dev/serial/by-id) +# board its name for serial_cli.py (local config, tools/mctools_config.py) +# +# NRF= directory holding tool-adafruit-nrfutil +# (default ~/.platformio/packages) +# PY= interpreter (default python3) +# CLI= serial_cli.py (default: next to this script) +# +# Sends `dfu serial` on the console, waits for the bootloader port +# (XIAO_nRF52840_Sense_) and runs adafruit-nrfutil on it; a board already +# in the bootloader is flashed as it is. Reports success only when the app is +# back on USB -- check `ver` yourself. Companion builds have no console: use +# `pio run -e -t upload` there (touch). Refuses a board whose config +# entry has `refuse` set (e.g. the radio of an observer). Runs on any host that +# has the board on USB and a checkout of this repo -- no PlatformIO project +# build needed there, only the nrfutil package. +set -euo pipefail +case "${1:-}" in -h | --help | "") + sed -n '3,/^[^#]/{/^#/s/^# \{0,1\}//p}' "$0" + exit 0 + ;; +esac +[ $# -eq 3 ] || { + echo "usage: $0 " >&2 + exit 2 +} +ZIP=$1 SN=$2 BOARD=$3 +WHY="$(python3 "$(dirname "$0")/mctools_config.py" get "$SN" refuse 2>/dev/null || true)" +[ -z "$WHY" ] || { + echo "refused: $WHY" >&2 + exit 1 +} +[ -f "$ZIP" ] || { + echo "$ZIP: no such file" >&2 + exit 1 +} +NRF=${NRF:-$HOME/.platformio/packages} +PY=${PY:-python3} +CLI=${CLI:-$(dirname "$(readlink -f "$0")")/serial_cli.py} +port() { compgen -G "/dev/serial/by-id/*$1$SN*" | head -1; } + +if [ -n "$(port Seeed_Studio_XIAO_nRF52840_)" ]; then + timeout 20 "$PY" "$CLI" "$BOARD" "dfu serial" >/dev/null 2>&1 || true +fi +B="" +for _ in $(seq 1 25); do + B=$(port XIAO_nRF52840_Sense_ || true) + [ -n "$B" ] && break + sleep 1 +done +[ -n "$B" ] || { + echo "$BOARD: bootloader port did not appear" >&2 + exit 1 +} +PYTHONPATH="$NRF/tool-adafruit-nrfutil/site-packages" timeout 120 "$PY" \ + "$NRF/tool-adafruit-nrfutil/adafruit-nrfutil.py" dfu serial -pkg "$ZIP" \ + -p "$B" -b 115200 --singlebank 2>&1 | tail -1 +for _ in $(seq 1 30); do + if [ -n "$(port Seeed_Studio_XIAO_nRF52840_)" ]; then + echo "$BOARD: app back on USB" + exit 0 + fi + sleep 2 +done +echo "$BOARD: app did not come back on USB" >&2 +exit 1 diff --git a/tools/xiao_uf2_flash.sh b/tools/xiao_uf2_flash.sh new file mode 100755 index 00000000..b47f49cd --- /dev/null +++ b/tools/xiao_uf2_flash.sh @@ -0,0 +1,314 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MIT +# Flash a XIAO nRF52840 through its UF2 drive -- to a named board, and verified. +# +# tools/xiao_uf2_flash.sh [target] +# +# target USB serial (full or unique suffix), or a board name/alias from the +# local config (tools/mctools_config.py). +# Omit only when exactly one board is plugged in. +# +# XIAO_UF2_WAIT=300 seconds to wait for UF2 mode (default 90). Worth raising +# when the board has to be double-tapped by hand. +# +# Get the board into UF2 mode with 'dfu' on its console (deterministic), or by +# double-tapping its small RESET button. +# +# What it refuses to do, because each of these has actually gone wrong here: +# - flash an image older than the build that produced it (pio run and +# pio run -t create_uf2 refresh different artifacts; x3 silently ended up +# two commits behind the rest of the fleet that way) +# - guess which board to write to when several are in UF2 mode (every drive +# is labelled XIAO-SENSE, in plug order, so the label proves nothing) +# - write to a board other than the one you named +# - report success without reading the version back off the board (the first +# version of this script printed x4's port after flashing x3) +# +# NEVER uses the 1200-baud touch: it only requests the bootloader's SERIAL_ONLY +# mode, so no drive ever appears, and a second touch in one power session wedges +# the board out of USB and BLE with no self-recovery. +set -uo pipefail +case "${1:-}" in -h | --help) + sed -n '3,/^[^#]/{/^#/s/^# \{0,1\}//p}' "$0" + exit 0 + ;; +esac + +die() { + echo "CHYBA: $*" >&2 + exit 1 +} + +UF2="${1:-}" +TARGET="${2:-}" +[ -n "$UF2" ] && [ -f "$UF2" ] || { + echo "usage: $(basename "$0") [serial|board]" >&2 + exit 1 +} + +# Board names/aliases come from the local config (tools/mctools_config.py); +# a serial or its unique suffix passes through. +if [ -n "$TARGET" ] && SN="$(python3 "$(dirname "$0")/mctools_config.py" serial "$TARGET" 2>/dev/null)"; then + TARGET="$SN" +fi + +# A .hex or .zip dropped on a UF2 drive is silently ignored by the bootloader and +# looks like a successful flash, so check the container before trusting it. +# UF2 blocks start with the magic 0x0A324655 ("UF2\n"). +head -c4 "$UF2" | grep -q 'UF2' || die "$UF2 neni UF2 obraz (chybi magic 'UF2\\n')" +echo "== image: $UF2 ($(stat -c%s "$UF2") B)" + +ELF="$(dirname "$UF2")/firmware.elf" +if [ -f "$ELF" ] && [ "$ELF" -nt "$UF2" ]; then + die "$(basename "$UF2") je STARSI nez firmware.elf -- nalil bys stary obraz. + Sprav: pio run -e && pio run -e -t create_uf2" +fi + +# Read the version out of the UF2 PAYLOAD, not the raw file. A UF2 is 512-byte +# blocks of 32 B header + 256 B data, so any string in the image can be cut in +# half by a block boundary -- and then a plain grep over the file finds nothing +# and this script refuses a perfectly good build. That is not hypothetical: it +# happened to SenseCap_mast_rpt on 15. 8. 2026 (the version was in the ELF the +# whole time), and it cost a hand-copied flash and a board that had to be +# replugged. Stitching the payload back together makes the check depend on the +# image rather than on where the linker happened to put the string. +WANT_VER="$( + python3 - "$UF2" <<'PY' 2>/dev/null || true +import re, sys +raw = open(sys.argv[1], "rb").read() +payload = b"".join(raw[i+32:i+288] for i in range(0, len(raw), 512)) +m = re.search(rb"v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]+\+?", payload) +if m: print(m.group(0).decode()) +PY +)" +if [ -z "$WANT_VER" ]; then + die "obraz nema verzi od tools/build_version.py -- po flashi by neslo overit, + co na desce doopravdy je. Zapoj do envu: extra_scripts = \${stamped.extra_scripts}" +fi +echo "== verze v obrazu: $WANT_VER" +[ -n "$TARGET" ] && echo "== cil: $TARGET" + +# Resolve UF2 drives THROUGH SYSFS, never by label: every XIAO drive is called +# XIAO-SENSE (then XIAO-SENSE1, ...) assigned in plug order, so with several +# boards on the bus the label says nothing about which board you are writing to. +find_uf2_boards() { + local d s blk + for d in /sys/bus/usb/devices/*/; do + s="$(cat "$d/serial" 2>/dev/null)" || continue + [ "$(cat "$d/idVendor" 2>/dev/null)" = "2886" ] || continue + blk="$(ls -d "$d"*/host*/target*/*/block/* 2>/dev/null | head -1)" || true + [ -n "$blk" ] && echo "$s /dev/$(basename "$blk")" + done +} + +# Companion builds have no text console, so no `dfu` command: those boards can +# only be double-tapped by hand, and 90 s turned out to be shorter than the round +# trip of asking someone to do it. Overridable rather than just longer, so an +# unattended flash still fails fast. +WAIT="${XIAO_UF2_WAIT:-90}" +echo -n "== cekam na UF2 rezim, ${WAIT}s (\"dfu\" na konzoli, nebo dvojklik RESET) " +SERIAL="" +DISK="" +for _ in $(seq 1 "$WAIT"); do + mapfile -t found < <(find_uf2_boards) + if [ -n "$TARGET" ]; then # keep only the board asked for + mapfile -t found < <(printf '%s\n' "${found[@]:-}" | grep -F "$TARGET" || true) + fi + if [ "${#found[@]}" -gt 1 ]; then + echo + { + echo "${#found[@]} desek v UF2 rezimu -- nevim, ktera je ta tva:" + printf ' %s\n' "${found[@]}" + echo "Zadej cil: $(basename "$0") $UF2 " + } >&2 + exit 1 + fi + if [ "${#found[@]}" -eq 1 ] && [ -n "${found[0]}" ]; then + SERIAL="${found[0]%% *}" + DISK="${found[0]##* }" + break + fi + echo -n "." + sleep 1 +done +echo +[ -n "$DISK" ] || die "do ${WAIT} s se v UF2 rezimu neobjevila${TARGET:+ deska $TARGET}" +echo "== deska: $SERIAL disk: $DISK" + +# Mount with retries: the drive appears a moment before the desktop automounter +# gets to it, and udisksctl can lose that race, so a single attempt fails on a +# board that is perfectly fine. Observed on the very first `dfu`-driven flash. +MNT="" +for _ in $(seq 1 12); do + MNT="$(lsblk -no MOUNTPOINT "$DISK" | head -1)" + [ -n "$MNT" ] && break + udisksctl mount -b "$DISK" >/dev/null 2>&1 || true + sleep 1 +done +[ -n "$MNT" ] || die "disk $DISK se nepodarilo namountovat ani na 12 pokusu + Zkus rucne: udisksctl mount -b $DISK" + +echo "== mount: $MNT -- kopiruju" +# The board resets itself the moment it has all the blocks, so cp/sync failing +# at the very end is normal, not an error. +cp "$UF2" "$MNT/" 2>/dev/null || true +sync 2>/dev/null || true + +echo -n "== cekam, az disk zmizi (= bootloader obraz prevzal) " +GONE=0 +for _ in $(seq 1 30); do + find_uf2_boards | grep -q "^$SERIAL " || { + GONE=1 + break + } + echo -n "." + sleep 1 +done +echo +[ "$GONE" -eq 1 ] || die "disk nezmizel -- flash nejspis neprobehl" + +# Wait for THIS board, matched on its serial. "Some XIAO came back on USB" is +# worthless with four of them plugged in. +echo -n "== cekam na navrat desky $SERIAL " +PORT="" +for _ in $(seq 1 45); do + for d in /sys/bus/usb/devices/*/; do + [ "$(cat "$d/serial" 2>/dev/null)" = "$SERIAL" ] || continue + [ "$(cat "$d/idProduct" 2>/dev/null)" = "8044" ] || continue + PORT="$(ls /dev/serial/by-id/*"$SERIAL"*-if00 2>/dev/null | head -1)" || true + done + [ -n "$PORT" ] && break + echo -n "." + sleep 1 +done +echo +[ -n "$PORT" ] || die "$SERIAL se do 45 s neohlasila jako aplikace" + +# The actual proof: ask the board what it is running. Anything less and a flash +# that quietly did nothing still reports success. +# +# The same trip also SETS THE CLOCK, because this is the one moment when a host +# is provably talking to the board. Every clock in this firmware is volatile +# unless the board has GPS or an I2C RTC: `VolatileRTCClock` starts in May 2024 +# and only ticks from millis(). A node with a wrong clock is not a cosmetic +# problem -- the RTC stamps every advert it transmits, and receivers drop a stale +# timestamp as a replay. Measured 7. 8. 2026: bench-board had been running 811 days +# behind since deployment, and bench board x1 was 812 days behind, both simply +# because nobody ever typed `time `. +GOT="$( + python3 - "$PORT" <<'PY' 2>/dev/null || true +import re, struct, sys, time +try: + import serial +except ImportError: + sys.exit(0) +# Retry: the port enumerates a second or two before the firmware is answering on +# it, so a single attempt calls a perfectly good flash "unverified" -- which is +# worse than no check, because it teaches you to ignore the tool. +for attempt in range(5): + try: + s = serial.Serial(sys.argv[1], 115200, timeout=1); s.dtr = True; s.rts = True + time.sleep(2.5); s.reset_input_buffer() + # Throwaway newline first. The board's own line buffer can still hold a + # fragment from before the reset, and whatever is sent next gets appended + # to it -- so the first real command comes back "Unknown command" and the + # flash is declared unverified even though it landed. Cost this exactly + # one wrong conclusion about x4. + s.write(b"\r\n"); s.flush(); time.sleep(0.5); s.reset_input_buffer() + s.write(b"ver\r\n"); s.flush(); time.sleep(2.0) + out = s.read(s.in_waiting or 1).decode("utf-8", "replace") + m = re.search(r"v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]+\+?", out) + if m: + print("VER\t" + m.group(0)) + # Set the clock, then read it back. The read-back is what decides: + # `time` answers "(ERR: clock cannot go backwards)" when the board is + # already right -- which happens once the build epoch seeds the RTC, + # and is SUCCESS, not failure. Never trust the setter's own reply. + s.reset_input_buffer() + s.write(("time %d\r\n" % int(time.time())).encode()); s.flush() + time.sleep(1.5); s.reset_input_buffer() + s.write(b"clock\r\n"); s.flush(); time.sleep(1.5) + got = s.read(s.in_waiting or 1).decode("utf-8", "replace") + c = re.search(r"\d{1,2}:\d{2} - \d{1,2}/\d{1,2}/\d{4} UTC(?: \(epoch \d+\))?", got) + print("CLOCK\t" + (c.group(0) if c else "?")) + s.close(); break + # No text console means this is a companion_radio build, which has no + # `ver` command at all -- ask in its own language rather than calling a + # perfectly good flash unverified (it did exactly that on x2). + # CMD_DEVICE_QUERY(22) -> RESP_CODE_DEVICE_INFO(13); firmware_version is + # the 20-byte field at offset 60. Framing: '<' + uint16 LE len + payload + # outbound, '>' + len + payload back. + s.reset_input_buffer() + s.write(b"<" + struct.pack("") + if i >= 0 and len(buf) >= i + 3: + ln = struct.unpack("= 80 and f[0] == 13: + v = f[60:80].split(b"\0")[0].decode("utf-8", "replace") + if v: + print("VER\t" + v) + # Companion builds have no `time` command at all -- the app + # sets the clock with CMD_SET_DEVICE_TIME(6). Same guard as + # the console (`secs >= curr`), so an ERR frame here is not a + # failure either; CMD_GET_DEVICE_TIME(5) -> RESP(9) decides. + now = int(time.time()) + s.reset_input_buffer() + fr = bytes([6]) + struct.pack("") + if j >= 0 and len(rb) >= j + 3: + rl = struct.unpack("= 5 and rf[0] == 9: + t = struct.unpack("&2 + exit 2 +fi +if [ "$GOT_VER" != "$WANT_VER" ]; then + die "deska hlasi $GOT_VER, ale v obrazu bylo $WANT_VER -- flash NEPROSEL" +fi +echo "== OK: $SERIAL bezi $GOT_VER ($PORT)" + +# Warn rather than fail: a wrong clock does not mean the flash was bad, and this +# script's contract is "the image landed". But it must not pass silently -- an +# unset clock is exactly what went unnoticed on x3 for 811 days. +# Only the year is checked, because that is what a volatile RTC gets wrong: it +# comes up in 2024 and stays there. (Around midnight on 31 December this warns +# for one minute on a board that is actually right. Non-fatal, once a year.) +case "$GOT_CLOCK" in +"") echo "!! hodiny se necetly zpatky -- nastav je rucne: time \$(date +%s)" >&2 ;; +"?") echo "!! hodiny neodpovedely ve znamem formatu -- zkontroluj 'clock' rucne" >&2 ;; +*"/$(date -u +%Y)"*) + echo "== hodiny: $GOT_CLOCK" + ;; +*) echo "!! hodiny hlasi $GOT_CLOCK -- nesedi rok, nastav je rucne: time \$(date +%s)" >&2 ;; +esac