Files
meshcore-tth/tools/ota_push.py
T

355 lines
13 KiB
Python
Executable File

#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Push an OTA package (tools/ota_pack.py) to a node over its USB or BLE console.
tools/ota_push.py b1 Xiao_nrf52_repeater-ota.mcfw # transfer + verify
tools/ota_push.py b1 Xiao_nrf52_repeater-ota.mcfw --apply # ... and apply
tools/ota_push.py b1 pkg.mcfw --binary --drop 30 --prime old.mcfw
tools/ota_push.py CE:72:14:CD:FD:02 pkg.mcfw --apply # over BLE (NUS)
The board: a name from the local config (tools/mctools_config.py), a USB
serial number, a port path -- or a BLE MAC: the node's BLE console, bonded
beforehand (tools/ble_pair.py), from the host that holds the bond. Prefer it
to tools/ota_mesh_push.py wherever BLE reaches: no airtime on the mesh, and the
console is local, so a full image goes too. Needs bleak; --binary is USB only.
Bench tests of the MESH protocol without a radio (--binary): the chunks go
through `fw bin`, which feeds the very handler a binary request over the mesh
reaches, padded to the AES block as the node sees it after decryption. Then
the missing-units bitmap ('m') decides what to resend, as ota_mesh_push.py does.
--drop P lose P % of the chunks of the first round on purpose
--prime FILE first send the manifest of ANOTHER package and abort, so it
stays in the stage flash
--stale FILE inject the first chunks of ANOTHER package with a wrong
session id before the real ones -- late packets of an earlier
transfer, the cause of "wrong base image" on the bench
The bench path of src/helpers/FwUpdate: the same `fw` commands later travel
over the mesh as admin CLI. Nothing here is applied without --apply, and the
node itself refuses to apply below FW_OTA_MIN_MV (battery) or with a package
that failed `fw verify`.
"""
import argparse
import base64
import glob
import os
import random
import re
import sys
import time
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
MAC_RE = re.compile(r"^[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){5}$")
NUS_RX = "6e400002-b5a3-f393-e0a9-e50e24dcca9e" # write (host -> node)
NUS_TX = "6e400003-b5a3-f393-e0a9-e50e24dcca9e" # notify (node -> host)
CHUNK = 96 # FW_OTA_CHUNK
BCHUNK = 96 # binary over USB: base64 of 7 + 96 B fits the 160 B console line
UNIT = 32 # FW_OTA_UNIT
def crc16(data: bytes, crc: int = 0xFFFF) -> int:
"""Nordic crc16_compute (CCITT, init 0xFFFF) -- FwUpdate.cpp crc16_update."""
for b in data:
crc = ((crc >> 8) | (crc << 8)) & 0xFFFF
crc ^= b
crc ^= (crc & 0xFF) >> 4
crc ^= (crc << 12) & 0xFFFF
crc ^= ((crc & 0xFF) << 5) & 0xFFFF
return crc
def w_payload(sid: int, off: int, chunk: bytes) -> bytes:
"""REQ_TYPE_FW_OTA 'w': [F0]['w'][sid u16][off u32][len u8][crc16][data]."""
head = sid.to_bytes(2, "little") + off.to_bytes(4, "little") + bytes([len(chunk)])
# the crc binds the data to this session and offset (FwUpdate::handleBinary)
return (
bytes([0xF0, ord("w")])
+ head
+ crc16(chunk, crc16(head)).to_bytes(2, "little")
+ chunk
)
def fw_bin(s, payload: bytes) -> bytes | None:
r = command(s, "fw bin " + base64.b64encode(payload).decode())
if r.startswith("ERR"):
sys.exit(f"fw bin: {r}")
r = r.lstrip("> ").strip()
return None if r == "-" else bytes.fromhex(r)
def bin_missing(s) -> tuple[int, list[int]]:
d = fw_bin(s, bytes([0xF0, ord("m")]))
if not d or len(d) < 5:
sys.exit(f"'m' reply: {d!r}")
cnt = int.from_bytes(d[3:5], "little")
have = (len(d) - 5) // 2 # the console prints a shortened list
return d[0], [
int.from_bytes(d[5 + 2 * i : 7 + 2 * i], "little")
for i in range(min(cnt, have))
]
def send_binary(
s, data: bytes, drop: float, sid: int, stale: bytes | None = None
) -> None:
if stale:
# chunks of ANOTHER session (as if a late packet of an earlier transfer):
# the node must drop them, or the manifest check sees the wrong package
for off in (0, BCHUNK, 2 * BCHUNK):
c = stale[off : off + BCHUNK]
fw_bin(
s,
w_payload((sid ^ 0x5A5A), off, c),
)
print("sent 3 stale chunks of another session")
todo = list(range((len(data) + BCHUNK - 1) // BCHUNK))
for rnd in range(10):
lost = 0
for i in todo:
if rnd == 0 and random.random() < drop / 100:
lost += 1
continue
off = i * BCHUNK
chunk = data[off : off + BCHUNK]
if fw_bin(
s,
w_payload(sid, off, chunk),
):
sys.exit("a 'w' got a reply, it must not")
if stale and rnd == 0:
# and again AFTER the real manifest chunks: the order seen on the bench
for off in (0, BCHUNK, 2 * BCHUNK):
c = stale[off : off + BCHUNK]
fw_bin(
s,
w_payload((sid ^ 0x5A5A), off, c),
)
state, miss = bin_missing(s)
for _ in range(20):
if state != 4:
break
time.sleep(0.3)
state, miss = bin_missing(s)
print(
f"round {rnd + 1}: sent {len(todo) - lost}, dropped {lost}, state {state}, missing {len(miss)}+"
)
if state == 3:
sys.exit(f"node: {command(s, 'fw status')}")
if not miss:
return
todo = sorted({u * UNIT // BCHUNK for u in miss})
sys.exit("binary transfer did not converge")
class BleConsole:
"""The node's BLE console (NUS) behind the few serial calls this tool makes:
write, read, reset_input_buffer, close. bleak runs in its own thread."""
def __init__(self, mac: str):
import asyncio
import threading
from bleak import BleakClient, BleakScanner
self._asyncio = asyncio
self._buf = bytearray()
self._lock = threading.Lock()
self._loop = asyncio.new_event_loop()
threading.Thread(target=self._loop.run_forever, daemon=True).start()
async def connect():
last = None
for attempt in range(5): # BLE connects are flaky, as in ble_cli.py
try:
dev = await BleakScanner.find_device_by_address(mac, timeout=20)
if dev is None:
raise RuntimeError("not advertising (already connected?)")
c = BleakClient(dev, timeout=30)
await c.connect()
await c.start_notify(NUS_TX, self._rx)
return c
except Exception as e: # noqa: BLE001
last = e
print(f" [connect {attempt + 1}/5] {type(e).__name__}: {e}", flush=True)
await asyncio.sleep(4)
raise RuntimeError(f"cannot connect to {mac}: {last}")
try:
self._c = self._run(connect())
except RuntimeError as e:
sys.exit(str(e))
# A NUS write carries at most ATT_MTU-3 bytes and BlueZ does not split it
# (ble_cli.py); at the default MTU 23 a chunk line goes out in 8 writes.
self._chunk = max(20, int(getattr(self._c, "mtu_size", 23)) - 3)
def _run(self, coro):
return self._asyncio.run_coroutine_threadsafe(coro, self._loop).result()
def _rx(self, _handle, data: bytearray) -> None:
with self._lock:
self._buf.extend(data)
def reset_input_buffer(self) -> None:
with self._lock:
self._buf.clear()
def write(self, data: bytes) -> None:
async def w():
for i in range(0, len(data), self._chunk):
await self._c.write_gatt_char(NUS_RX, data[i : i + self._chunk], response=False)
await self._asyncio.sleep(0.05)
self._run(w())
def read(self, n: int) -> bytes:
time.sleep(0.01)
with self._lock:
d = bytes(self._buf[:n])
del self._buf[:n]
return d
def close(self) -> None:
try:
self._run(self._c.disconnect())
except Exception as e: # noqa: BLE001 -- after `fw apply` the node is gone already
print(f"(disconnect: {type(e).__name__})")
finally:
self._loop.call_soon_threadsafe(self._loop.stop)
def open_console(target: str):
if MAC_RE.match(target):
return BleConsole(target)
from board_probe import _open as open_port
return open_port(resolve(target))
def resolve(target: str) -> str:
"""Same rules as serial_cli.py: fleet name, bare serial number, or a path."""
if target.startswith("/"):
return target
from fleet import serial_for
sn = serial_for(target)
hits = [p for p in sorted(glob.glob("/dev/serial/by-id/*")) if sn in p]
if len(hits) != 1:
sys.exit(f"{target!r} (sn {sn}): ports {hits}")
return hits[0]
def command(s, line: str, timeout: float = 5.0) -> str:
"""One console command, returns the reply after '-> '."""
s.reset_input_buffer()
s.write(line.encode() + b"\r\n")
buf, t = b"", time.time()
while time.time() - t < timeout:
d = s.read(4096)
if d:
buf += d
m = re.search(rb"-> ?(.*?)\r?\n", buf)
if m:
return m.group(1).decode(errors="replace").strip()
else:
time.sleep(0.005)
raise TimeoutError(f"no reply to {line[:40]!r}: {buf[-200:]!r}")
def main() -> None:
ap = argparse.ArgumentParser(
description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
)
ap.add_argument("board", help="board name (local config), USB serial number, or port path")
ap.add_argument("package")
ap.add_argument("--apply", action="store_true")
ap.add_argument(
"--force",
action="store_true",
help="apply below the battery gate (`fw apply force`, local console only): "
"a bench board without a cell reads its floating battery pin",
)
ap.add_argument("--binary", action="store_true")
ap.add_argument("--drop", type=float, default=0.0)
ap.add_argument("--prime")
ap.add_argument(
"--stale", help="package whose chunks are injected with a wrong session id"
)
args = ap.parse_args()
with open(args.package, "rb") as f:
data = f.read()
if args.binary and MAC_RE.match(args.board):
sys.exit("--binary is a bench test of the mesh path: USB only")
s = open_console(args.board)
try:
if not isinstance(s, BleConsole): # over BLE its reply comes late, as the next one's
s.write(b"\r\n")
time.sleep(0.4)
print("status:", command(s, "fw status"))
if args.prime:
with open(args.prime, "rb") as f:
other = f.read()
command(s, f"fw begin {len(other)}")
for off in range(0, 256, CHUNK):
command(
s,
f"fw w {off} {base64.b64encode(other[off : off + CHUNK]).decode()}",
)
time.sleep(1) # let loop() check and flush it
print(
"primed with",
args.prime,
"->",
command(s, "fw status"),
"/",
command(s, "fw abort"),
)
sid = random.randint(1, 0xFFFF)
r = command(s, f"fw begin {len(data)} {sid}")
print("begin:", r)
if not r.startswith("OK"):
sys.exit(1)
t0 = time.time()
n = 0 if args.binary else (len(data) + CHUNK - 1) // CHUNK
if args.binary:
stale = None
if args.stale:
with open(args.stale, "rb") as f:
stale = f.read()
send_binary(s, data, args.drop, sid, stale)
for i in range(n):
off = i * CHUNK
b64 = base64.b64encode(data[off : off + CHUNK]).decode()
r = command(s, f"fw w {off} {b64}")
if r != "ok":
sys.exit(f"chunk {off}: {r}")
if i % 200 == 0 or i == n - 1:
print(
f"\r{i + 1}/{n} chunks, {time.time() - t0:.0f} s",
end="",
flush=True,
)
print()
print("missing:", command(s, "fw missing"))
r = command(s, "fw verify", timeout=30)
t1 = time.time()
while "verifying" in r and time.time() - t1 < 60: # loop() runs it
time.sleep(0.5)
r = command(s, "fw status")
print("verify:", r)
if "ready" not in r:
sys.exit(1)
print("bootloader:", command(s, "fw bl"))
if args.apply:
print("apply:", command(s, "fw apply force" if args.force else "fw apply", timeout=10))
finally:
s.close()
if __name__ == "__main__":
main()