#!/usr/bin/env python3 # SPDX-License-Identifier: MIT """Push an OTA package (tools/ota_pack.py) to a node over its USB 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 The board: a name from the local config (tools/mctools_config.py), a USB serial number or a port path. 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__))) from board_probe import _open as open_port from fleet import serial_for 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") def resolve(target: str) -> str: """Same rules as serial_cli.py: fleet name, bare serial number, or a path.""" if target.startswith("/"): return target 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("--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() s = open_port(resolve(args.board)) try: 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", timeout=10)) finally: s.close() if __name__ == "__main__": main()