tools/ public with a local config, private tools to .tth/tools/

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
tthandClaude Opus 5.5 committed 2026-11-13 16:03:03 +01:00
1 parent b7b397b9b1
commit 845a228209
27 files changed
+5312 -4

No files matched your search

+1 -1
View File
@@ -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/
+1 -1
View File
@@ -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 <companion-port> <sensor-name>`. The sensor
Read it with `.tth/tools/budka_telem.py <companion-port> <sensor-name>`. 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 <companion-pubkey> 1`, or log in as admin.
+2 -2
View File
@@ -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.
+61
View File
@@ -0,0 +1,61 @@
<!-- SPDX-License-Identifier: MIT -->
# 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.
+247
View File
@@ -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()
+184
View File
@@ -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 <MAC>, 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 (`<MAC> -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()
+363
View File
@@ -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 <zip> <ble-mac> [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("<I", d[1:5])[0]
if got != sent:
raise RuntimeError(f"PRN mismatch: bootloader {got} vs poslal {sent}")
break
# Poslední skupina nemusí na PRN práh dosáhnout: bootloader pak
# místo receiptu pošle rovnou úspěšnou RESP(RECEIVE_FW). To je
# konec přenosu, ne chyba.
if d and d[0] == RESP and d[1] == RECEIVE_FW and d[2] == 1:
log(f" image potvrzen bootloaderem na {sent}/{total} B")
raise ImageDone()
if d and d[0] == RESP:
raise RuntimeError(f"nečekaná RESP během image: {d.hex()}")
if (sent // chunk) % 200 == 0:
log(f" {sent}/{total} B ({100*sent//total} %)")
log(f" image odesláno {sent}/{total} B")
async def phase2_dfu(mac, fw_bin, fw_dat, chunk=None):
log("== FÁZE 2: DFU na bootloaderu ==")
dev = None
for attempt in range(6):
dev = await find(mac, want_dfu=True, timeout=12)
if dev:
break
log(f" bootloader zatím nenalezen (pokus {attempt+1})...")
if not dev:
raise RuntimeError("bootloader (DFU svc) nenalezen ve scanu")
async with BleakClient(dev, timeout=30) as c:
log(" připojen k bootloaderu:", dev.address, "mtu:", getattr(c, "mtu_size", "?"))
try:
await c._backend._acquire_mtu() # BlueZ: vyjednej větší MTU
log(" MTU po acquire:", getattr(c, "mtu_size", "?"))
except Exception as e:
log(" (_acquire_mtu:", type(e).__name__, e, ")")
nf = Notif()
await c.start_notify(CP_UUID, nf.cb)
# START_DFU (application)
await c.write_gatt_char(CP_UUID, bytes([START_DFU, 0x04]), response=True)
await c.write_gatt_char(PKT_UUID, struct.pack("<III", 0, 0, len(fw_bin)), response=False)
await expect_resp(nf, START_DFU)
log(" START ok")
# INIT packet
await c.write_gatt_char(CP_UUID, bytes([INIT_DFU, 0x00]), response=True)
await c.write_gatt_char(PKT_UUID, fw_dat, response=False)
await c.write_gatt_char(CP_UUID, bytes([INIT_DFU, 0x01]), response=True)
await expect_resp(nf, INIT_DFU)
log(" INIT ok")
# PRN
prn = 8
await c.write_gatt_char(CP_UUID, bytes([PKT_RCPT_REQ]) + struct.pack("<H", prn), response=True)
# RECEIVE image
await c.write_gatt_char(CP_UUID, bytes([RECEIVE_FW]), response=True)
try:
await send_image(c, nf, PKT_UUID, fw_bin, prn=prn, chunk=chunk)
await expect_resp(nf, RECEIVE_FW, timeout=90)
except ImageDone:
pass # RESP(RECEIVE_FW) už dorazila uvnitř send_image
# ChunkTooBig se TADY neresi. Restart od START_DFU uvnitr tehoz spojeni
# bootloader odmitne se status 2 = INVALID_STATE -- stavovy automat uz je
# v "receiving" a dostat ho zpatky do IDLE umi jen RESET (opcode 6) plus
# nove spojeni. Vyhazuje se ven, main() to zopakuje s vynucenymi 20 B.
log(" IMAGE ok")
# VALIDATE
await c.write_gatt_char(CP_UUID, bytes([VALIDATE]), response=True)
await expect_resp(nf, VALIDATE)
log(" VALIDATE ok")
# ACTIVATE & reset
try:
await c.write_gatt_char(CP_UUID, bytes([ACTIVATE_RESET]), response=True)
except Exception as e:
log(" (ACTIVATE → disconnect, očekávané):", type(e).__name__)
log("== HOTOVO: bootloader aktivoval nový firmware a rebootuje ==")
async def reset_bootloader(mac):
"""Poke a stuck bootloader with RESET (opcode 6) so it reboots into a clean
DFU IDLE. After an interrupted image transfer the Adafruit bootloader keeps
its 'receiving image' state, so a fresh START_DFU returns INVALID_STATE;
this soft-reset clears the state machine (the GPREGRET flag survives, so it
re-enters DFU) and lets the next attempt start clean."""
log(" RESET bootloaderu (opcode 6) → čistý DFU IDLE...")
for att in range(4):
try:
dev = await find(mac, want_dfu=True, timeout=12)
if not dev:
await asyncio.sleep(2)
continue
async with BleakClient(dev, timeout=25) as c:
try:
await c.start_notify(CP_UUID, lambda _h, _d: None)
except Exception:
pass
try:
await c.write_gatt_char(CP_UUID, bytes([RESET]), response=True)
log(" RESET zapsán")
except Exception as e:
log(f" RESET write → {type(e).__name__} (reboot, očekávané)")
return True
except Exception as e:
log(f" RESET pokus {att+1}: {type(e).__name__} {str(e)[:50]}")
await asyncio.sleep(2)
return False
async def recover_to_bootloader(mac):
"""Get the node back into a clean DFU state, whichever way RESET left it.
reset_bootloader() on its own is not enough, and the two board families
differ: after RESET the SenseCap bootloader stays in DFU (the GPREGRET flag
survives), while the XIAO boots the APPLICATION instead. Assuming the
SenseCap behaviour made every XIAO retry scan forever for a bootloader that
was no longer there -- observed on bench-board, where the 20 B fallback could
never get started because the RESET that arms it also ended DFU mode.
So: reset, and if the bootloader is gone, ask the application to go back."""
await reset_bootloader(mac)
await asyncio.sleep(6)
dev = await find(mac, want_dfu=True, timeout=12)
if dev:
return
log(" po RESETu bootloader pryč (naběhla APP) → buttonless znovu")
await phase1_buttonless(mac)
async def main():
zippath, mac = sys.argv[1], sys.argv[2]
mode = sys.argv[3] if len(sys.argv) > 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 <env> && pio run -e <env> -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())
+259
View File
@@ -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 <<EOF
STOP: --require-silence, ale uzel není tichý
advert.interval=$ADV_BEFORE flood.advert.interval=$FADV_BEFORE repeat=$REPEAT_BEFORE
U uzlu s odpojenou antenou to znamená vysílání do odpojené antény po rebootu.
Umlč ho a spusť znovu:
set advert.interval 0 / set flood.advert.interval 0 / set repeat off
EOF
exit 1
fi
echo " ticho ověřeno (0/0/off)"
fi
[ "$CHECK_ONLY" = 1 ] && {
echo "== --check-only, končím =="
exit 0
}
echo "== build $ENV_NAME =="
DIRTY="$(cd "$REPO" && git status --porcelain | wc -l)"
if [ "$DIRTY" != "0" ]; then
echo "STOP: strom není čistý ($DIRTY změn) — verze by dostala '+' a na uzlu" >&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 =="
+200
View File
@@ -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 <MAC>` first.
ble_pair.py <MAC> && bluetoothctl disconnect <MAC> && ble_dfu.py fw.zip <MAC>
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> [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 <mac> 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()
+433
View File
@@ -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 <soubor s predchozim otiskem>
tools/board_probe.py --all --compare <soubor> --expect-changed <serial>
Vzniklo 1. 9. 2026 poté, co `pio run -t upload --upload-port <x4>` 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_<sn> XIAO, aplikace (MeshCore build)
Seeed_XIAO_nRF52840_Sense_<sn> XIAO, bootloader
Seeed_XIAO-Wio-SX1262_<sn> XIAO, openhop_modem (APLIKACE, ne boot)
Seeed_Studio_T1000-E-BOOT_<sn> T1000-E, APLIKACE <- "-BOOT" ma aplikace!
Seeed_Studio_T1000-E_<sn> 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("<H", 2) + bytes([22, 10])) # CMD_DEVICE_QUERY
s.flush()
raw = _drain(s, 1.5)
# Rámec se hleda podle CELE hlavicky, ne podle prvniho '>' 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("<H", raw[i + 1:i + 3])[0]
fr = raw[i + 3:i + 3 + ln]
if len(fr) == ln and ln >= 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 <n>`:
# 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)
+10
View File
@@ -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
+260
View File
@@ -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 <port> <jméno> --diff ~/.local/share/meshcore-backups/<starší>.json
tools/companion_backup.py <BLE MAC> <jméno> # 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/<jméno>-<datum>.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 <port> L1-post --restore <záloha>.json # jen ukáže
tools/companion_backup.py <port> L1-post --restore <záloha>.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()
+32
View File
@@ -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
+484
View File
@@ -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 <env> [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") <env> [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 <serial|board>"
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"
Executable
+26
View File
@@ -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"]
+569
View File
@@ -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_<sn> MeshCore build (PID 8044)
# usb-Seeed_XIAO-Wio-SX1262_<sn> 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("<H", len(payload)) + bytes(payload))
self.s.flush()
def recv(self, want, timeout=2.5):
"""Wait for a frame with response code `want`, skipping push frames.
A companion node emits unsolicited pushes (new message waiting, and so
on), so 'the next frame' is not necessarily the answer to the question.
"""
buf, deadline = b"", time.time() + timeout
while time.time() < deadline:
buf += self.s.read(4096) or b""
while True:
i = buf.find(b">")
if i < 0 or len(buf) < i + 3:
break
ln = struct.unpack("<H", buf[i + 1:i + 3])[0]
if len(buf) < i + 3 + ln:
break
frame, buf = buf[i + 3:i + 3 + ln], buf[i + 3 + ln:]
if frame and frame[0] == want:
return frame
time.sleep(0.02)
return None
def handshake(self):
# RESP_CODE_DEVICE_INFO: code, ver_code, max_contacts/2, max_channels,
# ble_pin[4], build_date[12], manufacturer[40],
# firmware_version[20], client_repeat, path_hash_mode
self.send(bytes([CMD_DEVICE_QUERY, 10]))
d = self.recv(RESP_DEVICE_INFO)
if d and len(d) >= 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("<II", s[48:56])
self.info["radio"] = f"{freq/1000:.3f}/{bw/1000}/{s[56]}/{s[57]}"
self.info["node"] = s[58:].decode(errors="replace").strip()
return bool(s)
def identify(self):
if not self.handshake():
self.info.setdefault("version", "?")
def stats(self):
self.send(bytes([CMD_GET_STATS, STATS_TYPE_PACKETS]))
f = self.recv(RESP_STATS)
if not f or len(f) < 30 or f[1] != STATS_TYPE_PACKETS:
return {}
v = struct.unpack("<7I", f[2:30])
return dict(zip(("recv", "sent", "flood_tx", "direct_tx",
"flood_rx", "direct_rx", "recv_errors"), v))
def radio_stats(self):
return {}
def advert(self):
self.send(bytes([CMD_SEND_SELF_ADVERT, 0])) # 0 = zero hop
return True
def open_node(no, sn, port):
"""Console or companion? Ask, do not assume.
A companion build ignores stray text and a console build ignores stray
frames, so probing either way is harmless.
"""
n = ConsoleNode(no, sn, port)
if "->" 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<sha>: {[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 <MAC> "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())
+119
View File
@@ -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 <pubkey64> --password <guest pw> \\
--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()))
+177
View File
@@ -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 <adresa> 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()
+173
View File
@@ -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())
+445
View File
@@ -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 <hex>] [--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_<sn> to
# usb-Seeed_XIAO-Wio-SX1262_<sn>, 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("<hhh", payload[0:6])
self.last_rssi, self.last_snr = rssi, snr_x10 / 10.0
self.last_signal_rssi = signal_rssi
self._rx_count += 1
if self._on_frame:
self._on_frame(payload[6:], rssi, snr_x10 / 10.0, signal_rssi)
return
super()._dispatch_frame(cmd, payload)
class PcapWriter:
"""Minimal pcap writer/streamer. Payload is the raw MeshCore frame.
LINKTYPE_USER0 means Wireshark shows the bytes but does not dissect them --
good enough for eyeballing lengths and repeats, and the decoded fields are in
the JSONL anyway. A Lua dissector for USER0 would be the next step.
"""
def __init__(self, path: str | None, udp: str | None):
self.fh = None
self.sock = None
self.dest = None
header = struct.pack("<IHHiIII", 0xA1B2C3D4, 2, 4, 0, 0, 65535, LINKTYPE_USER0)
if path:
self.fh = open(path, "wb")
self.fh.write(header)
if udp:
host, _, port = udp.partition(":")
self.dest = (host, int(port or 5555))
self.sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
self.sock.sendto(header, self.dest)
def write(self, data: bytes, ts: float):
if not (self.fh or self.sock):
return
rec = struct.pack("<IIII", int(ts), int((ts % 1) * 1e6), len(data), len(data)) + data
if self.fh:
self.fh.write(rec)
self.fh.flush()
if self.sock and self.dest:
self.sock.sendto(rec, self.dest)
def close(self):
if self.fh:
self.fh.close()
if self.sock:
self.sock.close()
def channel_keys(psk_hex: str) -> 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("<IIB", payload[:9])
out["trace"] = {"tag": f"{tag:08x}", "auth": f"{auth:08x}", "flags": flags}
elif name == "ANON_REQ":
out["dest"] = payload[:hash_size].hex()
out["src_pubkey"] = payload[hash_size : hash_size + 32].hex()
except Exception as exc:
out["decode_error"] = f"{name}: {exc}"
return out
def format_line(rec: dict) -> 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())
+461
View File
@@ -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 <mac bez dvojtecek>)")
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 = "<console 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())
+85
View File
@@ -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()))
+129
View File
@@ -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] <serial-port>
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)
+116
View File
@@ -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()
+86
View File
@@ -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 <usb-serial|board> <tcp-port>
Holds the console open with DTR/RTS up (as fleet_test.py does) and serves it
on 127.0.0.1:<tcp-port>, 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()
+75
View File
@@ -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> <usb-serial> <board>
#
# firmware.zip the DFU package (.pio/build/<env>/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=<dir> directory holding tool-adafruit-nrfutil
# (default ~/.platformio/packages)
# PY=<python> interpreter (default python3)
# CLI=<path> serial_cli.py (default: next to this script)
#
# Sends `dfu serial` on the console, waits for the bootloader port
# (XIAO_nRF52840_Sense_<sn>) 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 <env> -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 <firmware.zip> <usb-serial> <board>" >&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
+314
View File
@@ -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 <firmware.uf2> [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") <firmware.uf2> [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 <env> && pio run -e <env> -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 <serial|board>"
} >&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 <epoch>`.
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("<H", 2) + bytes([22, 10])); s.flush()
time.sleep(1.0)
buf = s.read(s.in_waiting or 1)
# The port stays OPEN here on purpose. It used to be closed on this line,
# before the reply was even parsed -- which was harmless while the only
# thing left to do was print, and became a PortNotOpenError the moment
# the clock was set afterwards (caught by the outer handler, so it looked
# like four silent retries printing VER over and over). Closed on both
# exits below instead.
i = buf.find(b">")
if i >= 0 and len(buf) >= i + 3:
ln = struct.unpack("<H", buf[i+1:i+3])[0]
f = buf[i+3:i+3+ln]
if len(f) >= 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("<I", now)
s.write(b"<" + struct.pack("<H", len(fr)) + fr); s.flush()
time.sleep(1.0); s.reset_input_buffer()
s.write(b"<" + struct.pack("<H", 1) + bytes([5])); s.flush()
time.sleep(1.0)
rb = s.read(s.in_waiting or 1)
shown = "?"
j = rb.find(b">")
if j >= 0 and len(rb) >= j + 3:
rl = struct.unpack("<H", rb[j+1:j+3])[0]
rf = rb[j+3:j+3+rl]
if len(rf) >= 5 and rf[0] == 9:
t = struct.unpack("<I", rf[1:5])[0]
shown = time.strftime("%H:%M - %-d/%-m/%Y UTC",
time.gmtime(t)) + " (epoch %d)" % t
print("CLOCK\t" + shown)
s.close(); break
s.close() # neither dialect answered -- close before the retry reopens
except Exception:
pass
time.sleep(3)
PY
)"
GOT_VER="$(printf '%s\n' "$GOT" | sed -n 's/^VER\t//p' | head -1)"
GOT_CLOCK="$(printf '%s\n' "$GOT" | sed -n 's/^CLOCK\t//p' | head -1)"
if [ -z "$GOT_VER" ]; then
echo "!! deska neodpovedela ani konzoli, ani companion protokolu -- flash NEOVERENY (drzi konzoli BLE klient?)" >&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