pub-release / release (push) Successful in 32m57s
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
520 lines
20 KiB
Python
Executable File
520 lines
20 KiB
Python
Executable File
#!/usr/bin/env python3
|
|
# SPDX-License-Identifier: MIT
|
|
"""Push an OTA package (tools/ota_pack.py) to a node OVER THE MESH, as admin.
|
|
|
|
tools/ota_mesh_push.py <companion> <dest> <package> [--apply] [--duty 1]
|
|
|
|
<companion> how to reach the companion that talks for us:
|
|
tcp://127.0.0.1:7003 (serial_tcp_proxy.py + ssh -L) or a
|
|
serial port path
|
|
<dest> the target node's public key prefix (>= 8 hex), as in its
|
|
`get public.key`
|
|
<package> a DELTA package only (ota_pack.py diff / fetch --base): a
|
|
full image is refused here and by the node itself
|
|
--apply after a good `fw verify`, `fw apply` and wait for the node to
|
|
come back with the new image (ver + fw status over the mesh)
|
|
--duty P airtime budget in percent per hour (default 1: the
|
|
865-868 MHz bench band). Token bucket of P% x 3600 s. It
|
|
counts what the transfer puts on the CHANNEL, not just our
|
|
radio: request and the expected reply, each times
|
|
(hops + 1), because every repeater on the path sends both
|
|
again.
|
|
--gap S pause after every reply before the next command (default 5).
|
|
Without it a small delta goes out as fast as the round trip
|
|
(~2 s per chunk at SF8) and holds the channel for that time.
|
|
--via HEX force a direct path through these repeater hashes (2 bytes
|
|
each, e.g. c327 or c327a1b2) -- also the login goes along
|
|
it, so the node answers back the same way. For testing
|
|
multi-hop on the bench.
|
|
--text send chunks as text CLI (`fw w <off> <base64>`, 96 B, each
|
|
answered) instead of the default binary requests (128 B,
|
|
unanswered, missing ones found by a bitmap query). Falls
|
|
back to text by itself when the node does not answer the
|
|
binary query (older firmware, or the sensor build).
|
|
--wait S how long to wait for the dest's advert if the companion
|
|
does not know it yet (default 120 s); send `advert.zerohop`
|
|
on the dest meanwhile
|
|
|
|
The same `fw` commands as tools/ota_push.py (USB), carried as remote admin CLI.
|
|
Every `fw w` is idempotent on the node, so a lost reply is simply resent; the
|
|
node checks the manifest as soon as its chunks arrive and answers ERR for a
|
|
wrong board or base -- that stops the transfer.
|
|
|
|
The admin password comes from platformio.local.ini ([secrets] admin_pw), or is
|
|
asked for on the terminal; it is never printed. CHECK `get radio` on both ends first: this transmits.
|
|
"""
|
|
|
|
import argparse
|
|
import asyncio
|
|
import base64
|
|
import configparser
|
|
import math
|
|
import random
|
|
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)
|
|
|
|
from meshcore import EventType, MeshCore
|
|
|
|
CHUNK = 96 # FW_OTA_CHUNK (text)
|
|
BCHUNK = 128 # FW_OTA_BCHUNK (binary)
|
|
# The companion takes host frames of at most MAX_FRAME_SIZE 176 B, and a binary
|
|
# request frame is 1 (cmd) + 32 (pubkey) + payload. 160 B chunks made 199 B
|
|
# frames that the companion dropped -- every one of them (13. 11. 2026).
|
|
MAX_FRAME = 176
|
|
UNIT = 32 # FW_OTA_UNIT
|
|
MANIFEST = 256 # FW_OTA_MANIFEST_SIZE
|
|
REQ_FW = 0xF0 # REQ_TYPE_FW_OTA
|
|
INI = Path(__file__).resolve().parent.parent / "platformio.local.ini"
|
|
|
|
|
|
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 admin_pw() -> str:
|
|
"""[secrets] admin_pw of platformio.local.ini, else asked on the terminal
|
|
(never an argument: it would show in the process list and the history)."""
|
|
cp = configparser.ConfigParser(interpolation=None, strict=False)
|
|
cp.read(INI)
|
|
pw = cp.get("secrets", "admin_pw", fallback="").strip()
|
|
if not pw and sys.stdin.isatty():
|
|
import getpass
|
|
|
|
pw = getpass.getpass("admin password of the node: ").strip()
|
|
if not pw:
|
|
sys.exit(f"no admin password: [secrets] admin_pw in {INI}, or run it on a terminal")
|
|
return pw
|
|
|
|
|
|
def lora_airtime(n: int, sf: int, bw_khz: float, cr: int, preamble: int = 16) -> float:
|
|
"""Seconds on air for an n-byte LoRa frame (explicit header, CRC on)."""
|
|
tsym = (2**sf) / (bw_khz * 1000)
|
|
de = 1 if tsym > 0.016 else 0
|
|
payload = 8 + max(
|
|
math.ceil((8 * n - 4 * sf + 28 + 16) / (4 * (sf - 2 * de))) * cr, 0
|
|
)
|
|
return (preamble + 4.25) * tsym + payload * tsym
|
|
|
|
|
|
def frame_len(text: str) -> int:
|
|
"""MeshCore direct text frame: header+path_len, dest/src hash, MAC, and
|
|
timestamp+flags+text padded to the AES block."""
|
|
body = 5 + len(text.encode())
|
|
return 2 + 2 + 2 + 16 * math.ceil(body / 16)
|
|
|
|
|
|
class Bucket:
|
|
def __init__(self, duty: float):
|
|
self.rate = duty / 100.0
|
|
self.cap = self.rate * 3600
|
|
self.level = self.cap
|
|
self.t = time.monotonic()
|
|
self.used = 0.0
|
|
|
|
async def spend(self, secs: float) -> None:
|
|
while True:
|
|
now = time.monotonic()
|
|
self.level = min(self.cap, self.level + (now - self.t) * self.rate)
|
|
self.t = now
|
|
if self.level >= secs:
|
|
self.level -= secs
|
|
self.used += secs
|
|
return
|
|
await asyncio.sleep((secs - self.level) / self.rate)
|
|
|
|
|
|
REPLY_TEXT = 40 # typical reply ("ok", status lines are longer but rare)
|
|
|
|
|
|
def hops_of(contact: dict) -> int:
|
|
"""out_path_len: low 6 bits = hops, top 2 = hash size - 1; -1 = flood."""
|
|
v = int(contact.get("out_path_len", -1))
|
|
return -1 if v < 0 else v & 0x3F
|
|
|
|
|
|
class Link:
|
|
def __init__(
|
|
self,
|
|
mc: MeshCore,
|
|
contact: dict,
|
|
bucket: Bucket,
|
|
radio: tuple,
|
|
gap: float = 0.0,
|
|
):
|
|
self.mc, self.c, self.bucket, self.radio, self.gap = (
|
|
mc,
|
|
contact,
|
|
bucket,
|
|
radio,
|
|
gap,
|
|
)
|
|
self.prefix = contact["public_key"][:12]
|
|
self.retries = 0
|
|
|
|
def cost(self, text: str) -> float:
|
|
hops = max(hops_of(self.c), 0)
|
|
one = lora_airtime(frame_len(text), *self.radio) + lora_airtime(
|
|
frame_len("x" * REPLY_TEXT), *self.radio
|
|
)
|
|
return one * (hops + 1)
|
|
|
|
async def cmd(self, text: str, timeout: float = 20.0, tries: int = 4) -> str:
|
|
for attempt in range(tries):
|
|
await self.bucket.spend(self.cost(text))
|
|
await self.mc.commands.send_cmd(self.c, text)
|
|
ev = await self.mc.wait_for_event(
|
|
EventType.CONTACT_MSG_RECV,
|
|
attribute_filters={"pubkey_prefix": self.prefix},
|
|
timeout=timeout,
|
|
)
|
|
if ev is not None:
|
|
if self.gap:
|
|
await asyncio.sleep(self.gap)
|
|
return str(ev.payload.get("text", "")).strip()
|
|
self.retries += 1
|
|
print(
|
|
f" ({text[:12]}...: no reply, try {attempt + 2}/{tries})", flush=True
|
|
)
|
|
raise TimeoutError(f"no reply to {text[:30]!r}")
|
|
|
|
|
|
def req_frame_len(payload_len: int) -> int:
|
|
"""Direct REQ: header+path_len, dest/src hash, MAC, timestamp+payload padded."""
|
|
return 2 + 2 + 2 + 16 * math.ceil((4 + payload_len) / 16)
|
|
|
|
|
|
class Binary:
|
|
"""Firmware chunks as binary requests (REQ_TYPE_FW_OTA)."""
|
|
|
|
def __init__(self, link: "Link"):
|
|
self.link = link
|
|
self.pub = bytes.fromhex(link.c["public_key"])
|
|
self.sid = 0
|
|
|
|
def cost(self, payload_len: int, reply_len: int = 0) -> float:
|
|
hops = max(hops_of(self.link.c), 0)
|
|
t = lora_airtime(req_frame_len(payload_len), *self.link.radio)
|
|
if reply_len:
|
|
t += lora_airtime(req_frame_len(reply_len), *self.link.radio)
|
|
return t * (hops + 1)
|
|
|
|
async def send(self, payload: bytes) -> str | None:
|
|
if 1 + 32 + len(payload) > MAX_FRAME:
|
|
raise ValueError(
|
|
f"binary request of {len(payload)} B exceeds the companion frame"
|
|
)
|
|
ev = await self.link.mc.commands.send(
|
|
b"\x32" + self.pub + payload, [EventType.MSG_SENT, EventType.ERROR]
|
|
)
|
|
if ev.type != EventType.MSG_SENT:
|
|
return None
|
|
tag = ev.payload.get("expected_ack")
|
|
return tag.hex() if isinstance(tag, bytes | bytearray) else str(tag)
|
|
|
|
async def write(self, off: int, chunk: bytes) -> None:
|
|
payload = w_payload(self.sid, off, chunk)
|
|
c = self.cost(len(payload))
|
|
await self.link.bucket.spend(c)
|
|
await self.send(payload)
|
|
# no reply comes: give the packet time to go out along the whole path
|
|
await asyncio.sleep(max(self.link.gap, c + 1.0))
|
|
|
|
async def missing(self, timeout: float = 20.0) -> tuple[int, list[int]] | None:
|
|
"""(state, missing unit indices) or None when the node does not answer."""
|
|
for _ in range(2):
|
|
await self.link.bucket.spend(self.cost(2, 160))
|
|
fut: asyncio.Future = asyncio.get_running_loop().create_future()
|
|
|
|
def got(ev, fut=fut):
|
|
if not fut.done():
|
|
fut.set_result(ev)
|
|
|
|
sub = self.link.mc.subscribe(EventType.BINARY_RESPONSE, got)
|
|
try:
|
|
tag = await self.send(bytes([REQ_FW, ord("m")]))
|
|
ev = await asyncio.wait_for(fut, timeout)
|
|
except TimeoutError:
|
|
ev = None
|
|
finally:
|
|
self.link.mc.unsubscribe(sub)
|
|
if ev is None or (tag and ev.payload.get("tag") != tag):
|
|
continue
|
|
d = bytes.fromhex(ev.payload["data"])
|
|
if len(d) < 5:
|
|
continue
|
|
cnt = int.from_bytes(d[3:5], "little")
|
|
miss = [
|
|
int.from_bytes(d[5 + 2 * i : 7 + 2 * i], "little") for i in range(cnt)
|
|
]
|
|
await asyncio.sleep(self.link.gap)
|
|
return d[0], miss
|
|
return None
|
|
|
|
|
|
async def login(mc: MeshCore, contact: dict) -> str:
|
|
"""Admin login; returns the event type name."""
|
|
fut: asyncio.Future = asyncio.get_running_loop().create_future()
|
|
|
|
def done(ev):
|
|
if not fut.done():
|
|
fut.set_result(ev.type.name)
|
|
|
|
subs = [
|
|
mc.subscribe(t, done) for t in (EventType.LOGIN_SUCCESS, EventType.LOGIN_FAILED)
|
|
]
|
|
try:
|
|
await mc.commands.send_login(contact, admin_pw())
|
|
return await asyncio.wait_for(fut, 30)
|
|
except TimeoutError:
|
|
return "timeout"
|
|
finally:
|
|
for sub in subs:
|
|
mc.unsubscribe(sub)
|
|
|
|
|
|
async def find_contact(mc: MeshCore, prefix: str, wait: float) -> dict:
|
|
added: list[dict] = []
|
|
|
|
async def on_new(ev):
|
|
added.append(ev.payload)
|
|
|
|
sub = mc.subscribe(EventType.NEW_CONTACT, on_new)
|
|
t0 = time.time()
|
|
try:
|
|
while True:
|
|
await mc.ensure_contacts(follow=True)
|
|
for c in mc.contacts.values():
|
|
if c["public_key"].lower().startswith(prefix):
|
|
return c
|
|
for p in added:
|
|
if p.get("public_key", "").lower().startswith(prefix):
|
|
await mc.commands.add_contact(p)
|
|
if time.time() - t0 > wait:
|
|
sys.exit(
|
|
f"{prefix}: not among the companion's contacts after {wait:.0f} s (advert.zerohop on the node?)"
|
|
)
|
|
await asyncio.sleep(3)
|
|
finally:
|
|
mc.unsubscribe(sub)
|
|
|
|
|
|
async def run(args: argparse.Namespace) -> int:
|
|
data = Path(args.package).read_bytes()
|
|
# Only deltas go over the mesh -- the node refuses anything else too
|
|
# (FwUpdate: `fw begin` over 64 kB, a format 1 manifest). A full image is
|
|
# ~300 kB, hours of a shared channel: USB (ota_push.py) or the BLE console.
|
|
if data[:4] != b"MCFW" or data[4] != 2:
|
|
sys.exit(
|
|
f"{args.package}: not a delta package (format {data[4] if len(data) > 4 else '?'}) -- "
|
|
"over the mesh only deltas; a full image goes over USB (tools/ota_push.py) or BLE"
|
|
)
|
|
if args.companion.startswith("tcp://"):
|
|
host, port = args.companion[6:].rsplit(":", 1)
|
|
mc = await MeshCore.create_tcp(host, int(port))
|
|
else:
|
|
mc = await MeshCore.create_serial(args.companion)
|
|
if mc is None:
|
|
sys.exit("companion does not answer")
|
|
try:
|
|
si = mc.self_info
|
|
cr = int(si["radio_cr"]) - 4
|
|
radio = (int(si["radio_sf"]), float(si["radio_bw"]), cr)
|
|
print(
|
|
f"companion {si['name']}: {si['radio_freq']} MHz, SF{radio[0]}, BW{radio[1]}, CR4/{si['radio_cr']}"
|
|
)
|
|
await mc.start_auto_message_fetching()
|
|
contact = await find_contact(mc, args.dest.lower(), args.wait)
|
|
if args.via:
|
|
path = bytes.fromhex(args.via)
|
|
if len(path) % 2:
|
|
sys.exit("--via: whole 2-byte hashes")
|
|
await mc.commands.update_contact(contact, path=path.hex(), path_hash_mode=1)
|
|
contact = await find_contact(mc, args.dest.lower(), 5)
|
|
print(
|
|
f"dest {contact['adv_name']} {contact['public_key'][:8]}, out_path_len {contact.get('out_path_len')}"
|
|
)
|
|
|
|
bucket = Bucket(args.duty)
|
|
await bucket.spend(lora_airtime(48, *radio))
|
|
r = await login(mc, contact)
|
|
if r != "LOGIN_SUCCESS":
|
|
sys.exit(f"login: {r}")
|
|
print("login: ok (admin)")
|
|
await mc.ensure_contacts(follow=True) # login may have taught it a path
|
|
contact = await find_contact(mc, args.dest.lower(), 5)
|
|
print(
|
|
f"path: {hops_of(contact)} hops (out_path_len {contact.get('out_path_len')})"
|
|
)
|
|
link = Link(mc, contact, bucket, radio, args.gap)
|
|
t0 = time.time()
|
|
|
|
print("status:", await link.cmd("fw status"))
|
|
sid = random.randint(1, 0xFFFF) # chunks of an earlier transfer are dropped
|
|
r = await link.cmd(f"fw begin {len(data)} {sid}")
|
|
print("begin:", r)
|
|
if not r.startswith("OK"):
|
|
return 1
|
|
binary = None if args.text else Binary(link)
|
|
if binary:
|
|
binary.sid = sid
|
|
text_todo: list[int] | None = None
|
|
if binary:
|
|
st = await binary.missing()
|
|
if st is None:
|
|
print("node does not answer binary requests: text chunks")
|
|
binary = None
|
|
if binary:
|
|
nb = (len(data) + BCHUNK - 1) // BCHUNK
|
|
todo = list(range(nb))
|
|
last_miss = 1 << 30
|
|
|
|
async def settled():
|
|
for _ in range(10):
|
|
st = await binary.missing()
|
|
if st is None or st[0] != 4: # 4 = busy (manifest check)
|
|
return st
|
|
await asyncio.sleep(3)
|
|
return st
|
|
|
|
manifest_checked = False
|
|
for rnd in range(6):
|
|
for k, i in enumerate(todo):
|
|
off = i * BCHUNK
|
|
await binary.write(off, data[off : off + BCHUNK])
|
|
print(
|
|
f"\r{k + 1}/{len(todo)} binary chunks (round {rnd + 1}), {time.time() - t0:.0f} s, "
|
|
f"airtime {bucket.used:.1f} s",
|
|
end="",
|
|
flush=True,
|
|
)
|
|
if not manifest_checked and off + BCHUNK >= MANIFEST and k + 1 < len(todo):
|
|
# The node checks the manifest as soon as it is in (signature,
|
|
# target, base, NOT OLDER): ask before the rest goes on air --
|
|
# a refused package otherwise costs the whole first round.
|
|
manifest_checked = True
|
|
st = await settled()
|
|
if st is not None and st[0] == 3:
|
|
print("\nnode:", await link.cmd("fw status"))
|
|
print(f"stopped after the manifest, airtime {bucket.used:.1f} s")
|
|
return 1
|
|
print()
|
|
st = await settled()
|
|
if st is None:
|
|
print("missing: no answer")
|
|
return 1
|
|
state, miss = st
|
|
print(f"missing: state {state}, {len(miss)} units")
|
|
if state == 3:
|
|
print("node:", await link.cmd("fw status"))
|
|
return 1
|
|
if not miss:
|
|
break
|
|
if rnd > 0 and len(miss) >= last_miss:
|
|
# a round that adds nothing will not be fixed by more rounds
|
|
print("binary chunks do not arrive: text chunks for the rest")
|
|
binary = None
|
|
text_todo = sorted({u * UNIT // CHUNK for u in miss})
|
|
break
|
|
last_miss = len(miss)
|
|
todo = sorted({u * UNIT // BCHUNK for u in miss})
|
|
if binary:
|
|
todo = []
|
|
elif text_todo is not None:
|
|
todo = text_todo # only what the binary rounds did not deliver
|
|
else:
|
|
todo = list(range((len(data) + CHUNK - 1) // CHUNK))
|
|
for rnd in range(4 if todo else 0):
|
|
for k, i in enumerate(todo):
|
|
off = i * CHUNK
|
|
r = await link.cmd(
|
|
f"fw w {off} {base64.b64encode(data[off : off + CHUNK]).decode()}"
|
|
)
|
|
if r != "ok":
|
|
print(f"\nchunk {off}: {r}")
|
|
return 1
|
|
print(
|
|
f"\r{k + 1}/{len(todo)} chunks (round {rnd + 1}), {time.time() - t0:.0f} s, "
|
|
f"airtime {bucket.used:.1f} s",
|
|
end="",
|
|
flush=True,
|
|
)
|
|
print()
|
|
r = await link.cmd("fw missing")
|
|
print("missing:", r)
|
|
if r.endswith("none"):
|
|
break
|
|
todo = [int(x) // CHUNK for x in r.lstrip(">").split()]
|
|
r = await link.cmd("fw verify", timeout=40)
|
|
for _ in range(20): # the node runs it in loop(), not in the handler
|
|
if "verifying" not in r:
|
|
break
|
|
await asyncio.sleep(3)
|
|
r = await link.cmd("fw status")
|
|
print("verify:", r)
|
|
if not r.startswith(">") or "ready" not in r:
|
|
return 1
|
|
print("bootloader:", await link.cmd("fw bl"))
|
|
if args.apply:
|
|
r = await link.cmd("fw apply", timeout=30, tries=1)
|
|
print("apply:", r)
|
|
if not r.startswith("OK"):
|
|
return 1
|
|
print("waiting 60 s for the node to rewrite itself and boot ...")
|
|
await asyncio.sleep(60)
|
|
print("login after apply:", await login(mc, contact))
|
|
print("ver:", await link.cmd("ver"))
|
|
print("status:", await link.cmd("fw status"))
|
|
print("bootloader:", await link.cmd("fw bl"))
|
|
print(
|
|
f"done in {time.time() - t0:.0f} s, channel airtime {bucket.used:.1f} s, retries {link.retries}"
|
|
)
|
|
return 0
|
|
finally:
|
|
await mc.disconnect()
|
|
|
|
|
|
def main() -> None:
|
|
ap = argparse.ArgumentParser(
|
|
description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
|
|
)
|
|
ap.add_argument("companion")
|
|
ap.add_argument("dest")
|
|
ap.add_argument("package")
|
|
ap.add_argument("--apply", action="store_true")
|
|
ap.add_argument("--duty", type=float, default=1.0)
|
|
ap.add_argument("--wait", type=float, default=120.0)
|
|
ap.add_argument("--gap", type=float, default=5.0)
|
|
ap.add_argument("--via")
|
|
ap.add_argument("--text", action="store_true")
|
|
sys.exit(asyncio.run(run(ap.parse_args())))
|
|
|
|
|
|
if __name__ == "__main__":
|
|
main()
|