feat: update led-driver app files over ESP-NOW

tools/driver_ota.py (make ota-drivers) pushes the driver's .py files
through the controller, one file per POST /drivers/ota/file. Drivers
skip files they already have, and the rest are committed together.

- one target: acked unicast, two chunks in flight
- several targets: each file is broadcast once, then each driver is
  asked for its missing chunks and repaired by unicast
- rel: rel_send_seq, rel_wait and rel_send_wait, plus a callback for
  the drivers' 0x26 status replies
- commands are retried, because status replies are not acked
- broadcast chunks are paced 50 ms apart: faster broadcast left C3
  drivers unable to receive until reset
- bench results in docs/BENCH_TEST.md, endpoints in docs/API.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
jimmyandClaude Opus 5.5 committed 2026-11-02 23:45:38 +13:00
1 parent 1c222771a5
commit 32c0ecfa76
13 files changed
+862 -9

No files matched your search

+221
View File
@@ -0,0 +1,221 @@
#!/usr/bin/env python3
"""Update the led-driver app files (.py) over ESP-NOW, through the controller.
driver_ota.py <controller> (--mac MAC [MAC ...] | --all) [--broadcast] [--driver-dir DIR] [--dry-run]
The file set matches `led-cli --src --patterns --lib`: src/ (minus patterns/) to the root,
src/patterns/ to patterns/, lib/ to lib/. Drivers skip files they already have (sha256), stage
the rest, and only move them into place on commit, then reset.
Without --broadcast drivers are updated one after another. With it, each changed file is
broadcast once and every driver is then repaired with the chunks it missed.
"""
import argparse
import hashlib
import http.client
import json
import os
import random
import sys
import time
import urllib.parse
ROOT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..")
SKIP_DIRS = {"__pycache__"}
SKIP_FILES = {"file_hashes.json"}
MAX_FILE = 65536
def file_set(driver_dir):
"""[(device path, local path)] in a stable order."""
out = []
def walk(local, dest, exclude=()):
for name in sorted(os.listdir(local)):
full = os.path.join(local, name)
if os.path.isdir(full):
if name not in SKIP_DIRS and name not in exclude:
walk(full, f"{dest}/{name}" if dest else name)
elif not name.endswith((".pyc", ".pyo")) and name not in SKIP_FILES:
out.append((f"{dest}/{name}" if dest else name, full))
src = os.path.join(driver_dir, "src")
walk(src, "", exclude=("patterns",))
if os.path.isdir(os.path.join(src, "patterns")):
walk(os.path.join(src, "patterns"), "patterns")
if os.path.isdir(os.path.join(driver_dir, "lib")):
walk(os.path.join(driver_dir, "lib"), "lib")
return out
class Controller:
def __init__(self, host):
self.host = host
def request(self, method, path, body=None, timeout=60):
c = http.client.HTTPConnection(self.host, 80, timeout=timeout)
headers = {"Content-Type": "application/octet-stream"} if body is not None else {}
c.request(method, path, body=body, headers=headers)
r = c.getresponse()
data = r.read().decode()
try:
doc = json.loads(data) if data else {}
except ValueError:
doc = {"error": data}
if r.status != 200:
raise RuntimeError(f"{method} {path.split('?')[0]}: {r.status} {doc.get('error', doc)}")
return doc
def drivers(self):
"""device id -> MAC of every ESP-NOW device."""
devs = self.request("GET", "/devices", timeout=10)
return {k: d["address"] for k, d in devs.items()
if d.get("transport") == "espnow" and len(d.get("address") or "") == 12}
def status(self):
try:
return self.request("GET", "/devices/status", timeout=10)
except (OSError, RuntimeError):
return {}
def ota(self, action, macs, sess, body=None, **params):
# the controller does not URL-decode, so keep path slashes and the MAC list commas as they are
q = urllib.parse.urlencode({"mac": ",".join(macs), "sess": sess, **params}, safe="/,")
return self.request("POST", f"/drivers/ota/{action}?{q}", body=body, timeout=120)
def norm_mac(m):
m = m.lower().replace(":", "").replace("-", "")
if len(m) != 12 or any(ch not in "0123456789abcdef" for ch in m):
sys.exit(f"bad MAC: {m}")
return m
def push(ctrl, macs, files, bad_sha=None):
"""One session for macs. Returns (MACs that committed, MACs that will reset)."""
sess = random.randint(1, 0xFFFF)
ok = set(macs)
t0 = time.time()
sent_bytes = 0
send_time = 0.0
per_driver = 0 # bytes of the files that went to at least one driver
changed = set()
for dest, local in files:
live = [m for m in macs if m in ok]
if not live:
break
with open(local, "rb") as f:
body = f.read()
sha = hashlib.sha256(body).hexdigest()
if dest == bad_sha:
sha = "0" * 64
t1 = time.time()
try:
res = ctrl.ota("file", live, sess, body=body, path=dest, sha=sha)
except (OSError, RuntimeError) as e:
res = {m: {"result": "error", "code": str(e)} for m in live}
t1 = time.time() - t1
line = []
for m in live:
r = res.get(m, {"result": "error", "code": "missing from reply"})
if r["result"] == "error":
ok.discard(m)
line.append(f"{m} ERROR {r.get('code')}")
elif r["result"] == "written":
sent_bytes += len(body)
changed.add(m)
rep = f" (+{r['repaired']} repaired)" if r.get("repaired") else ""
line.append(f"{m} written{rep}")
writers = sum(1 for m in live if res.get(m, {}).get("result") == "written")
if writers:
send_time += t1
per_driver += len(body)
if line:
print(f" {dest:40s} {len(body):6d} B {t1:5.1f} s " + ", ".join(line))
dt = time.time() - t0
failed = [m for m in macs if m not in ok]
if failed:
ctrl.ota("abort", failed, sess)
print(" aborted:", ", ".join(failed))
good = [m for m in macs if m in ok]
if good:
res = ctrl.ota("commit", good, sess)
for m in good:
if res.get(m, {}).get("result") != "ok":
print(f" {m} commit failed: {res.get(m)}")
good = [m for m in good if res.get(m, {}).get("result") == "ok"]
if sent_bytes:
rate = per_driver / send_time / 1024 if send_time else 0
print(f" {sent_bytes} B written, {dt:.1f} s in all, {rate:.1f} KB/s while sending")
else:
print(" every file was already up to date")
return good, [m for m in good if m in changed]
def wait_back(ctrl, macs, timeout=30):
"""Drivers reset after a commit; wait until each acks the link again."""
ids = {mac: k for k, mac in ctrl.drivers().items()} # /devices/status is keyed by device id
t0 = time.time()
left = set(macs)
time.sleep(2)
while left and time.time() - t0 < timeout:
st = ctrl.status()
for m in list(left):
age = st.get(ids.get(m), {}).get("last_ack_ms_ago", -1)
if 0 <= age < (time.time() - t0) * 1000:
left.discard(m)
time.sleep(1)
return left
def main():
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("controller")
g = ap.add_mutually_exclusive_group(required=True)
g.add_argument("--mac", nargs="+")
g.add_argument("--all", action="store_true", help="every ESP-NOW device in the controller's devices")
ap.add_argument("--broadcast", action="store_true", help="one transfer for all drivers, then repair each")
ap.add_argument("--driver-dir", default=os.path.join(ROOT, "led-driver"))
ap.add_argument("--dry-run", action="store_true", help="list the files and drivers, send nothing")
ap.add_argument("--bad-sha", metavar="PATH", help="test: send a wrong hash for this device path")
a = ap.parse_args()
files = file_set(a.driver_dir)
odd = [d for d, _ in files if not all(ch.isalnum() or ch in "_./-" for ch in d)]
if odd:
sys.exit(f"file names must be letters, digits and _ . / - only: {', '.join(odd)}")
big = [d for d, p in files if os.path.getsize(p) > MAX_FILE]
if big:
sys.exit(f"files over {MAX_FILE} B cannot be sent: {', '.join(big)}")
ctrl = Controller(a.controller)
macs = sorted(ctrl.drivers().values()) if a.all else [norm_mac(m) for m in a.mac]
if not macs:
sys.exit("no ESP-NOW drivers")
total = sum(os.path.getsize(p) for _, p in files)
print(f"{len(files)} files, {total} B, to {len(macs)} driver(s)" + (" by broadcast" if a.broadcast else ""))
if a.dry_run:
for d, p in files:
print(f" {d:40s} {os.path.getsize(p):6d} B")
print(" drivers:", ", ".join(macs))
return
if a.broadcast:
done, resets = push(ctrl, macs, files, a.bad_sha)
else:
done, resets = [], []
for m in macs:
print(m)
d, r = push(ctrl, [m], files, a.bad_sha)
done += d
resets += r
failed = [m for m in macs if m not in done]
if resets:
missing = wait_back(ctrl, resets)
if missing:
print("did not ack the link again within 30 s:", ", ".join(sorted(missing)))
print(f"{len(done)} of {len(macs)} driver(s) updated")
sys.exit(1 if failed else 0)
if __name__ == "__main__":
main()