feat: ESP-NOW link, beat sync and control messages in the C++ driver

- espnow_link, ctrl_msg and beat_sync: the reliable link, envelopes and
  beat-synced timing.
- ctrl_msg: accept an envelope with the trailing save byte.
- patterns_frame() and espnow_link_poll() split out of their tasks, so the
  WebAssembly simulator can drive one frame and one link pass from a timer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
jimmyandClaude Opus 5.5 committed 2026-11-16 19:32:36 +13:00
1 parent 94e300f6ad
commit 24dd5ffb15
30 files changed
+2159 -158

No files matched your search

+168 -35
View File
@@ -9,18 +9,22 @@ packet, with the PUSH flag set (the one-off checks in the full test still send t
driver's HTTP API the test checks that the pixels were shown, that a frame waits for a sync, runs a few
test animations, and that the last frame stays up once the pixels stop.
python3 tools/ddp_test.py # finds every device on this machine's subnet (/24)
python3 tools/ddp_test.py # the devices in tools/rig.json (their IPs and places in the rig)
python3 tools/ddp_test.py --broadcast-only # send the sync only as a broadcast (default: also to each device by unicast)
python3 tools/ddp_test.py --discover # finds every device on this machine's subnet (/24)
python3 tools/ddp_test.py --subnet=192.168.4 # pick the network: devices are found on it and the sync goes to its broadcast address (192.168.4.255)
python3 tools/ddp_test.py --fps=30 # frames per second (default 60)
python3 tools/ddp_test.py --fps=30 # frames per second (default 60, lowered for big rigs: 250 / number of devices)
python3 tools/ddp_test.py --brightness=20 # send the colours at 20% (default and maximum 25)
python3 tools/ddp_test.py --interactive # pick patterns from a menu and watch them on the rig
python3 tools/ddp_test.py --soak=600 # long run: cycle the soak patterns for 600 s, sampling LEDs as it goes
python3 tools/ddp_test.py --expect=5 # keep scanning until 5 devices answer (a busy device can be slow)
python3 tools/ddp_test.py led1.local led2.local # or name hosts explicitly
python3 tools/ddp_test.py led1.local --serial=/dev/ttyACM0 # also check the serial log (one host only)
"""
import asyncio
import colorsys
import os
import random
import json
import math
@@ -34,6 +38,8 @@ import urllib.request
from concurrent.futures import ThreadPoolExecutor
PORT = 4048
RIG_FILE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "rig.json")
ROW_OF = {} # device index in the soak -> its row in the rig, for the patterns that follow the layout
SYNC_PORT = 4049
LEDS = 119
PUSH = 0x01
@@ -41,6 +47,7 @@ VER1 = 0x40
RGB = 0x01
FPS = 60 # frames per second (--fps=N)
TICK = 1 / FPS # seconds between ticks
FRAME_BUDGET = 250 # frames per second the Wi-Fi carried for the whole rig (measured with 16 bars: 15 fps worked, 25+ did not)
ACK_WAIT = TICK * 0.6 # seconds to wait for each device's ack before the sync goes out anyway
ANIM_FRAMES = 40 # frames of each test animation
@@ -52,6 +59,18 @@ def set_fps(fps):
ACK_WAIT = TICK * 0.6
def load_rig(path=RIG_FILE):
"""The rig map: {"rows", "columns", "devices": [{name, ip, row, column, reversed, usb?}]}, in the order
the soak lays the bars out (row by row, left to right). None if there is no map file."""
try:
with open(path) as f:
rig = json.load(f)
except FileNotFoundError:
return None
rig["devices"].sort(key=lambda d: (d["row"], d["column"]))
return rig
def packet(seq, offset, data, push):
"""Every DDP packet is built here, so this is the hard limit: no byte leaves above the brightness cap,
whatever the pattern, the test or a bug upstream put in it."""
@@ -70,9 +89,21 @@ def send_frame(sock, host, pixels, seq):
sock.sendto(packet(seq, split, raw[split:], True), (host, PORT))
def send_sync(sock, seq, broadcast):
"""Broadcast a sync to the network's broadcast address: every device shows the frame it holds."""
sock.sendto(b"LSY1" + struct.pack(">I", seq & 0xFFFFFFFF), (broadcast, SYNC_PORT))
UNICAST_SYNC = True # also send each device its own copy of every sync (--broadcast-only turns this off)
def send_sync(sock, seq, broadcast, devices=()):
"""Broadcast a sync to the network's broadcast address: every device shows the frame it holds. A Wi-Fi
access point may not deliver broadcasts to every client (one of ours got none), so with UNICAST_SYNC each
of `devices` is also sent the sync directly. A device that gets both shows the frame on the first and
finds nothing held on the second, which does nothing."""
msg = b"LSY1" + struct.pack(">I", seq & 0xFFFFFFFF)
targets = [broadcast] + (list(devices) if UNICAST_SYNC else [])
for t in targets:
try:
sock.sendto(msg, (t, SYNC_PORT))
except BlockingIOError:
pass # the socket's send buffer is full: this copy is dropped, as a lost packet would be
def frame_sum(pixels):
@@ -91,9 +122,33 @@ def read_serial(port, stop, lines):
lines.extend(buf.decode("utf-8", "replace").splitlines())
def get(host, path):
with urllib.request.urlopen(f"http://{host}{path}", timeout=5) as r:
return json.loads(r.read().decode())
def get(host, path, timeout=5, tries=3):
"""GET a JSON path from a device. A device busy with a stream can miss a request, so a timeout is
retried (tries in all) before it is raised; the soak's samples use tries=1 and count a miss instead."""
for n in range(tries):
try:
with urllib.request.urlopen(f"http://{host}{path}", timeout=timeout) as r:
return json.loads(r.read().decode())
except OSError:
if n == tries - 1:
raise
class Missing(dict):
"""What soft_get returns for a device that did not answer: every field reads as a value that fails
its check (rgb is -1, active is False, counters are -1), so one silent device fails its own checks
and the test goes on with the rest."""
def __missing__(self, key):
return [-1, -1, -1] if key == "rgb" else False if key == "active" else -1
def soft_get(host, path, **kw):
"""get(), but a device that does not answer gives a Missing instead of ending the whole run."""
try:
return get(host, path, **kw)
except OSError:
return Missing()
def local_prefix():
@@ -107,20 +162,49 @@ def local_prefix():
return ip.rsplit(".", 1)[0]
def find_devices(prefix):
"""Every host on the subnet that answers the driver's /api/ddp endpoint."""
def neighbours(prefix):
"""Addresses on the subnet that this machine has seen on the LAN (its ARP table), whether or not they
answered HTTP: a device that is up but slow to answer shows here."""
import subprocess
try:
out = subprocess.run(["ip", "-4", "neigh"], capture_output=True, text=True, timeout=5).stdout
except Exception:
return []
ips = []
for line in out.splitlines():
parts = line.split()
if parts and parts[0].startswith(prefix + ".") and "FAILED" not in parts and "INCOMPLETE" not in parts:
ips.append(parts[0])
return ips
def probe(ip):
def find_devices(prefix, expect=None):
"""Every host on the subnet that answers the driver's /api/ddp endpoint. A device that is busy can be
slow to answer, so after the full sweep, hosts seen on the LAN that did not answer are retried with a
longer timeout (3 times). If fewer than `expect` devices answered, one more full sweep runs."""
def probe(ip, timeout):
try:
with urllib.request.urlopen(f"http://{ip}/api/ddp", timeout=1) as r:
with urllib.request.urlopen(f"http://{ip}/api/ddp", timeout=timeout) as r:
json.loads(r.read().decode())
return ip
except Exception:
return None
ips = [f"{prefix}.{i}" for i in range(1, 255)]
with ThreadPoolExecutor(64) as pool:
return [ip for ip in pool.map(probe, ips) if ip]
def sweep(ips, timeout):
with ThreadPoolExecutor(64) as pool:
return {ip for ip in pool.map(lambda ip: probe(ip, timeout), ips) if ip}
all_ips = [f"{prefix}.{i}" for i in range(1, 255)]
found = sweep(all_ips, 1.5)
for _ in range(3):
silent = [ip for ip in neighbours(prefix) if ip not in found]
if not silent:
break
found |= sweep(silent, 3.0)
if expect is not None and len(found) < expect:
found |= sweep([ip for ip in all_ips if ip not in found], 3.0)
return sorted(found, key=lambda ip: int(ip.rsplit(".", 1)[1]))
# Test animations: each maps (LED index, frame number) to an RGB colour
@@ -225,7 +309,7 @@ class Sender:
# can beat the slowest device's frame (it then shows a frame late and falls out of line). So the
# sync for the last tick's frames goes out at the start of this tick, a whole tick after them.
if self.sync and self.pending_sync is not None:
send_sync(self.sock, self.pending_sync, self.broadcast)
send_sync(self.sock, self.pending_sync, self.broadcast, self.ip_of.values())
await asyncio.gather(*(self.send_host(loop, h, frames[h], self.seq) for h in due))
self.pending_sync = self.seq
return
@@ -239,7 +323,7 @@ class Sender:
rest = t0 + ACK_WAIT - time.monotonic()
if rest > 0:
await asyncio.sleep(rest) # sync at a fixed point in the tick, so quick or slow acks don't move it
send_sync(self.sock, self.seq, self.broadcast)
send_sync(self.sock, self.seq, self.broadcast, self.ip_of.values())
async def wait_acks(self, loop, nibble, hosts):
"""Wait until each device acks this frame (the driver acks a completed frame with "LAK1" and its
@@ -340,6 +424,13 @@ def soak_ripple(i, k, n):
return (v, 0, 255 - v)
def soak_row_sweep(i, k, n):
row = ROW_OF.get(i // LEDS, 0)
rows = max(ROW_OF.values(), default=0) + 1
lit = (k // 30) % rows # one row of the rig lit at a time, 0.75 s each, top to bottom
return (255, 80, 0) if row == lit else (10, 0, 0)
def soak_strobe(i, k, n):
return (255, 255, 255) if (k // 20) % 2 else (0, 0, 0) # a flash every 0.5 s: a hard test for dropped frames
@@ -542,6 +633,7 @@ SOAK = {
"gradient sweep": soak_gradient_sweep,
"slow breathe": soak_slow_breathe,
"bar chase": soak_bar_chase,
"row sweep": soak_row_sweep,
"ripple": soak_ripple,
"strobe": soak_strobe,
"rig sweep": soak_rig_sweep,
@@ -577,7 +669,9 @@ def run_soak(hosts, broadcast, seconds):
sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
sender = Sender(sock, hosts, broadcast)
before = {h: get(h, "/api/ddp") for h in hosts}
stats = {h: {"samples": 0, "bad": 0, "idle": 0, "examples": []} for h in hosts}
# The devices apply their max brightness ceiling to DDP frames, so a sample is compared to that
scale = {h: get(h, "/api/hardware")["max_brightness"] for h in hosts}
stats = {h: {"samples": 0, "bad": 0, "idle": 0, "errors": 0, "examples": []} for h in hosts}
names = list(SOAK)
sender.start()
start = time.time()
@@ -602,14 +696,21 @@ def run_soak(hosts, broadcast, seconds):
if time.time() >= next_sample:
next_sample = time.time() + SOAK_SAMPLE
led = random.randrange(LEDS)
wants = {h: {tuple(f[led]) for f in history[h]} for h in hosts}
wants = {h: {tuple(expected([f[led]], scale[h])[0]) for f in history[h]} for h in hosts}
def sample(h, led=led):
r = get(h, f"/api/ddp?led={led}")
# A short timeout: the sender waits for this, so a slow device must not stall the frames
try:
r = get(h, f"/api/ddp?led={led}", timeout=1.0, tries=1)
except OSError:
return h, led, None, None, wants[h]
return h, led, tuple(r["rgb"]), r["active"], wants[h]
for h, l, got, active, w in pool.map(sample, hosts):
st = stats[h]
if got is None: # no answer in time: counted, but not a mismatch
st["errors"] += 1
continue
st["samples"] += 1
if got not in w:
st["bad"] += 1
@@ -625,12 +726,14 @@ def run_soak(hosts, broadcast, seconds):
print(f"\nsoak finished: {elapsed:.0f} s, {k} frames sent, {sender.seq} ticks\n")
failures = 0
for h in hosts:
a = get(h, "/api/ddp")
a = soft_get(h, "/api/ddp")
sy, sb = a["sync"], before[h]["sync"]
if not isinstance(sy, dict):
sy = {"frames": sb["frames"] - 1, "shown": sb["shown"] - 1}
st = stats[h]
print(f"== {h}: frames +{sy['frames'] - sb['frames']}, shown +{sy['shown'] - sb['shown']}, "
f"samples {st['samples']}, "
f"mismatches {st['bad']}, idle-pattern flickers {st['idle']}")
f"mismatches {st['bad']}, no answer {st['errors']}, idle-pattern flickers {st['idle']}")
for e in st["examples"]:
print(" " + e)
if st["idle"]:
@@ -731,9 +834,9 @@ def run_all(hosts, serial_port, broadcast):
before, scale = {}, {}
for h in hosts:
before[h] = get(h, "/api/ddp")
before[h] = soft_get(h, "/api/ddp")
# DDP frames ignore the device and master brightness, but the max brightness ceiling still applies
scale[h] = get(h, "/api/hardware")["max_brightness"]
scale[h] = soft_get(h, "/api/hardware")["max_brightness"]
out[h].append(f"before: active={before[h]['active']} packets={before[h]['packets']}")
out[h].append(f"output scale: {scale[h]}/255")
@@ -757,9 +860,9 @@ def run_all(hosts, serial_port, broadcast):
for h in hosts:
out[h].append(f"frames not acked in time while streaming: {sender.missed[h]}")
for h in hosts:
mid = get(h, "/api/ddp")
mid = soft_get(h, "/api/ddp")
check(h, "receiving while sending", mid["active"], f"packets={mid['packets']}")
check(h, "packets counted", mid["packets"] - before[h]["packets"] >= 120,
check(h, "packets counted", mid["packets"] - before[h]["packets"] >= 50, # one packet per frame, 60 frames (a few may be lost)
f"+{mid['packets'] - before[h]['packets']}")
# A frame waits for a sync: send one by unicast alone, then a sync, and check the strip changes
@@ -767,19 +870,19 @@ def run_all(hosts, serial_port, broadcast):
time.sleep(0.1)
waiting = frame(200)
sent[frame_sum(waiting)] = waiting
send_sync(sock, sender.seq + 1, broadcast) # sync mode is on: a sync was sent a moment ago
send_sync(sock, sender.seq + 1, broadcast, sender.ip_of.values()) # sync mode is on: a sync was sent a moment ago
time.sleep(0.06) # later than the devices' 30 ms sync window, so the frame is held
for h in hosts:
send_frame(sock, h, waiting, sender.seq + 1)
time.sleep(0.3)
for h in hosts:
got = get(h, "/api/ddp?led=0")["rgb"]
got = soft_get(h, "/api/ddp?led=0")["rgb"]
check(h, "frame waits for a sync", got != expected([waiting[0]], scale[h])[0],
f"LED 0 shows {got} before the sync")
send_sync(sock, sender.seq + 2, broadcast)
send_sync(sock, sender.seq + 2, broadcast, sender.ip_of.values())
time.sleep(0.2)
for h in hosts:
got = get(h, "/api/ddp?led=0")["rgb"]
got = soft_get(h, "/api/ddp?led=0")["rgb"]
check(h, "frame shows on the sync", got == expected([waiting[0]], scale[h])[0], f"LED 0 {got}")
sender.paused = False
@@ -806,7 +909,11 @@ def run_all(hosts, serial_port, broadcast):
want_all = expected(pixels, scale[h])
bad = []
for i in range(LEDS):
got = get(h, f"/api/ddp?led={i}")["rgb"]
try:
got = get(h, f"/api/ddp?led={i}", timeout=3, tries=2)["rgb"]
except OSError: # no answer: this check fails for the device, the run goes on
bad.append((i, "no answer", want_all[i]))
break
if got != want_all[i]:
bad.append((i, got, want_all[i]))
return bad
@@ -844,15 +951,15 @@ def run_all(hosts, serial_port, broadcast):
time.sleep(0.2)
for h in hosts:
check(h, "out-of-range packet ignored",
get(h, "/api/ddp?led=0")["rgb"] == expected([shown[0]], scale[h])[0])
soft_get(h, "/api/ddp?led=0")["rgb"] == expected([shown[0]], scale[h])[0])
# Stop sending: the pattern should come back after the timeout
sender.stop()
time.sleep(3.0)
for h in hosts:
after = get(h, "/api/ddp")
after = soft_get(h, "/api/ddp")
check(h, "inactive after pixels stop", not after["active"])
now0 = get(h, "/api/ddp?led=0")["rgb"]
now0 = soft_get(h, "/api/ddp?led=0")["rgb"]
check(h, "last frame stays up", now0 == expected([shown[0]], scale[h])[0], f"LED 0 now {now0}")
sock.close()
@@ -866,12 +973,30 @@ def main():
global BRIGHTNESS
BRIGHTNESS = min(MAX_BRIGHTNESS, int(next((a.split("=", 1)[1] for a in sys.argv[1:] if a.startswith("--brightness=")), MAX_BRIGHTNESS)))
set_fps(int(next((a.split("=", 1)[1] for a in sys.argv[1:] if a.startswith("--fps=")), FPS)))
global UNICAST_SYNC
UNICAST_SYNC = "--broadcast-only" not in sys.argv[1:]
expect = next((a.split("=", 1)[1] for a in sys.argv[1:] if a.startswith("--expect=")), None)
prefix = subnet or local_prefix()
broadcast = f"{prefix}.255" # the sync is broadcast to this network's broadcast address
rig = None if "--discover" in sys.argv[1:] else load_rig()
if args:
hosts = args
elif rig:
hosts = [d["ip"] for d in rig["devices"]]
ROW_OF.update({n: d["row"] - 1 for n, d in enumerate(rig["devices"])})
print(f"rig map {os.path.basename(RIG_FILE)}: {len(hosts)} device(s)")
for d in rig["devices"]:
print(f" {d['name']} {d['ip']} row {d['row']} column {d['column']}"
f"{' reversed' if d.get('reversed') else ''}{' usb ' + d['usb'] if d.get('usb') else ''}")
print()
if serial_port is None:
usb = [d for d in rig["devices"] if d.get("usb")]
if len(hosts) == 1 and usb:
serial_port = usb[0]["usb"]
else:
hosts = find_devices(prefix)
hosts = find_devices(prefix, int(expect) if expect else None)
if expect and len(hosts) < int(expect):
print(f"warning: expected {expect} device(s), found {len(hosts)}")
print(f"found {len(hosts)} device(s) on {prefix}.0/24: {', '.join(hosts) or 'none'}\n")
if not hosts:
sys.exit(1)
@@ -879,6 +1004,14 @@ def main():
print("note: --serial is only used when testing one device\n")
serial_port = None
if not any(a.startswith("--fps=") for a in sys.argv[1:]):
# Every bar gets every frame, so the network carries bars x fps frames a second: past FRAME_BUDGET the
# devices stop answering HTTP and frames are lost. A big rig runs slower unless --fps says otherwise.
fps = max(1, min(FPS, FRAME_BUDGET // len(hosts)))
if fps < FPS:
set_fps(fps)
print(f"{len(hosts)} devices: running at {fps} fps (the Wi-Fi carries about {FRAME_BUDGET} frames a second in all; --fps=N overrides)\n")
if "--interactive" in sys.argv[1:] or "-i" in sys.argv[1:]:
run_interactive(hosts, broadcast)
return