Files
meshcore-tth/tools/ota_push.py
T

253 lines
10 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)
tools/ota_push.py CE:72:14:CD:FD:02 <dir> --apply # the package for the node's image
The package may be a directory with one release's packages (full image and
deltas): the delta from the image `fw status` reports is taken, else the full
image. Exit 3 = nothing there starts from the node's image (or no `fw`).
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.
The transfer is the tth.meshcore Ansible collection's OTA engine
(module_utils/meshcore_ota_engine.py), the same code as ota_mesh_push.py and
the meshcore_fw_ota module; tools/ota_collection.py says where it is found.
--force apply below the battery gate (`fw apply force`, local
console only): a bench board without a cell reads its
floating battery pin
Bench tests of the MESH protocol without a radio (--binary): the chunks go
through `fw bin`, which feeds the very handler a binary request over the mesh
reaches, padded to the AES block as the node sees it after decryption. Then
the missing-units bitmap ('m') decides what to resend, as over the mesh.
--drop P lose P % of the chunks of the first round on purpose
--prime FILE first send the manifest of ANOTHER package and abort, so it
stays in the stage flash
--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 asyncio
import base64
import glob
import importlib
import random
import re
import sys
import time
from pathlib import Path
if __name__ == "__main__" and (any(a in ("-h", "--help") for a in sys.argv[1:]) or len(sys.argv) == 1):
print(__doc__)
sys.exit(0)
sys.path.insert(0, str(Path(__file__).resolve().parent))
from ota_collection import PKG, locate
locate()
engine = importlib.import_module(f"{PKG}.meshcore_ota_engine")
ota = importlib.import_module(f"{PKG}.meshcore_ota")
console = importlib.import_module(f"{PKG}.meshcore_console")
MAC_RE = re.compile(r"^[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){5}$")
BCHUNK = 96 # binary over USB: base64 of 7 + 96 B fits the 160 B console line
NO_PACKAGE = 3 # exit code: no package starts from the node's image
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]
class EchoLog(list):
def append(self, line):
print(line, flush=True)
super().append(line)
async def push(args: argparse.Namespace) -> int:
"""The ordinary transfer: the engine over the node's console."""
con = console.BleConsole(args.board) if MAC_RE.match(args.board) else console.SerialConsole(resolve(args.board))
io = engine.Console(con, log=EchoLog())
try:
out = await engine.update(io, args.package, apply=args.apply, force=args.force)
except (engine.OtaError, console.ConsoleError, ValueError, OSError) as e:
print(f"FAILED: {e}")
return 1
print(f"{out['state']}: {out.get('package', '-')} {out.get('version_after') or out.get('version') or ''}")
return NO_PACKAGE if out["no_package"] else 0
# ── bench harness: the mesh protocol through `fw bin` (USB only) ─────────────
def command(s, line: str, timeout: float = 5.0) -> str:
"""One console command, returns the reply after '-> '."""
s.reset_input_buffer()
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 = console.REPLY.search(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 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([ota.REQ_FW, ord("m")]))
st = ota.parse_missing(d or b"")
if st is None:
sys.exit(f"'m' reply: {d!r}")
have = (len(d or b"") - 5) // 2 # the console prints a shortened list
return st[0], st[1][:have]
def send_binary(s, data: bytes, drop: float, sid: int, stale: bytes | None = None) -> None:
def inject():
# chunks of ANOTHER session (as if a late packet of an earlier transfer):
# the node must drop them, or the manifest check sees the wrong package
for off in (0, BCHUNK, 2 * BCHUNK):
fw_bin(s, ota.w_payload(sid ^ 0x5A5A, off, stale[off : off + BCHUNK]))
if stale:
inject()
print("sent 3 stale chunks of another session")
todo = list(range((len(data) + BCHUNK - 1) // BCHUNK))
for rnd in range(10):
lost = 0
for i in todo:
if rnd == 0 and random.random() < drop / 100:
lost += 1
continue
off = i * BCHUNK
if fw_bin(s, ota.w_payload(sid, off, data[off : off + BCHUNK])):
sys.exit("a 'w' got a reply, it must not")
if stale and rnd == 0:
inject() # and again AFTER the real manifest chunks: the order seen on the bench
state, miss = bin_missing(s)
for _ in range(20):
if state != 4:
break
time.sleep(0.3)
state, miss = bin_missing(s)
print(f"round {rnd + 1}: sent {len(todo) - lost}, dropped {lost}, state {state}, missing {len(miss)}+")
if state == 3:
sys.exit(f"node: {command(s, 'fw status')}")
if not miss:
return
todo = sorted({u * ota.UNIT // BCHUNK for u in miss})
sys.exit("binary transfer did not converge")
def bench(args: argparse.Namespace) -> int:
from board_probe import _open as open_port
s = open_port(resolve(args.board))
try:
s.write(b"\r\n")
time.sleep(0.4)
st = command(s, "fw status")
print("status:", st)
base = ota.parse_status(st)
if base is None:
print("no base image in `fw status`: not an -ota build")
return NO_PACKAGE
kind, pkg = ota.pick(engine.load_packages(args.package), base[1], full_ok=True)
if kind == "current":
print(f"the node already runs the image of {pkg.name}")
return 0
if kind == "none":
print(f"no package in {args.package} starts from {base[1]}")
return NO_PACKAGE
print(f"package: {pkg.name} ({kind})")
data = pkg.data
if args.prime:
other = Path(args.prime).read_bytes()
command(s, f"fw begin {len(other)}")
for off in range(0, ota.MANIFEST, ota.CHUNK):
command(s, f"fw w {off} {base64.b64encode(other[off : off + ota.CHUNK]).decode()}")
time.sleep(1) # let loop() check and flush it
print("primed with", args.prime, "->", command(s, "fw status"), "/", command(s, "fw abort"))
sid = random.randint(1, 0xFFFF)
r = command(s, f"fw begin {len(data)} {sid}")
print("begin:", r)
if not r.startswith("OK"):
return 1
send_binary(s, data, args.drop, sid, Path(args.stale).read_bytes() if args.stale else None)
print("missing:", command(s, "fw missing"))
r = command(s, "fw verify", timeout=30)
t1 = time.time()
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:
return 1
print("bootloader:", command(s, "fw bl"))
if args.apply:
print("apply:", command(s, "fw apply force" if args.force else "fw apply", timeout=10))
return 0
finally:
s.close()
def main() -> None:
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("board", help="board name (local config), USB serial number, port path, or BLE MAC")
ap.add_argument("package")
ap.add_argument("--apply", action="store_true")
ap.add_argument("--force", action="store_true")
ap.add_argument("--binary", action="store_true")
ap.add_argument("--drop", type=float, default=0.0)
ap.add_argument("--prime")
ap.add_argument("--stale", help="package whose chunks are injected with a wrong session id")
args = ap.parse_args()
harness = args.binary or args.drop or args.prime or args.stale
if harness and MAC_RE.match(args.board):
sys.exit("--binary/--drop/--prime/--stale are a bench test of the mesh path: USB only")
if harness and not args.binary:
sys.exit("--drop/--prime/--stale go with --binary")
sys.exit(bench(args) if harness else asyncio.run(push(args)))
if __name__ == "__main__":
main()