Files
led-driver/tools/ddp_test.py
T
jimmyandClaude Haiku 5.5 4cd3bc7973 feat: DDP frame sync over UDP broadcast, DDP acks, DDP enable setting
- Driver acks each completed DDP frame; the test waits for the acks before broadcasting the sync.
- Sync listener on UDP 4049: a frame is held until the next sync, then shown.
- DDP pixels are shown at full brightness, ignoring the device brightness settings.
- "DDP and sync receive on" setting (NVS, network API, web UI); off ignores DDP and sync packets.
- ddp_test.py: finds devices on the subnet, drives them in lockstep at a fixed rate, runs animations.
- /api/ddp reports sync counters for diagnosis.
- Includes in-progress WebSocket, multi-driver web UI and Wi-Fi work from the same tree.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
2026-11-11 14:10:55 +13:00

386 lines
14 KiB
Python

#!/usr/bin/env python3
"""
Test the LED driver's DDP receiver (UDP port 4048) and its frame sync (UDP broadcast port 4049).
Every frame goes to each device as unicast DDP: a version 1 header, the pixel data split across two
packets, and the PUSH flag on the last packet. After each tick, one broadcast sync ("LSY1" + seq) tells
all devices to show the frame they hold. The devices are driven together, from one sender. Through the
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 pattern comes back once the pixels stop.
python3 tools/ddp_test.py # finds every device on this machine's subnet (/24)
python3 tools/ddp_test.py --subnet=192.168.4 # or pick the subnet
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 colorsys
import json
import math
import re
import socket
import struct
import sys
import threading
import time
import urllib.request
from concurrent.futures import ThreadPoolExecutor
PORT = 4048
SYNC_PORT = 4049
LEDS = 119
PUSH = 0x01
VER1 = 0x40
RGB = 0x01
TICK = 0.025 # seconds between ticks (40 fps)
ACK_WAIT = 0.02 # seconds to wait for each device's ack before the sync goes out anyway
ANIM_FRAMES = 40 # about 1 s
def packet(seq, offset, data, push):
flags = VER1 | (PUSH if push else 0)
header = struct.pack(">BBBBIH", flags, seq & 0x0F, RGB, 1, offset, len(data))
return header + data
def send_frame(sock, host, pixels, seq):
"""Unicast pixels (a list of (r, g, b)) as two packets, PUSH on the second."""
raw = bytes(c for px in pixels for c in px)
split = (len(pixels) // 2) * 3
sock.sendto(packet(seq, 0, raw[:split], False), (host, PORT))
sock.sendto(packet(seq, split, raw[split:], True), (host, PORT))
def send_sync(sock, seq):
"""Broadcast a sync: every device shows the frame it holds."""
sock.sendto(b"LSY1" + struct.pack(">I", seq & 0xFFFFFFFF), ("255.255.255.255", SYNC_PORT))
def frame_sum(pixels):
"""The driver's checksum of a frame: the sum of its bytes, as an unsigned 32-bit value."""
return sum(c for px in pixels for c in px) & 0xFFFFFFFF
def read_serial(port, stop, lines):
"""Collect the driver's log lines from the USB serial port until stop is set."""
import serial
ser = serial.Serial(port, 115200, timeout=0.2)
buf = b""
while not stop.is_set():
buf += ser.read(4096)
ser.close()
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 local_prefix():
"""The first three octets of this machine's IPv4 address (assumes a /24 subnet)."""
s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
try:
s.connect(("8.8.8.8", 80))
ip = s.getsockname()[0]
finally:
s.close()
return ip.rsplit(".", 1)[0]
def find_devices(prefix):
"""Every host on the subnet that answers the driver's /api/ddp endpoint."""
def probe(ip):
try:
with urllib.request.urlopen(f"http://{ip}/api/ddp", timeout=1) 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]
# Test animations: each maps (LED index, frame number) to an RGB colour
def anim_chase(i, k):
return (255, 160, 0) if (i - 2 * k) % LEDS < 6 else (0, 0, 0)
def anim_rainbow(i, k):
r, g, b = colorsys.hsv_to_rgb(((i * 3 + k * 5) % 256) / 256, 1, 1)
return (int(r * 255), int(g * 255), int(b * 255))
def anim_breathe(i, k):
v = int(127.5 * (1 - math.cos(k / 6)))
return (v, v, v)
ANIMATIONS = {"chase": anim_chase, "rainbow": anim_rainbow, "breathe": anim_breathe}
def frame(k):
"""A frame: LED i is a colour that depends on i, so every LED is distinguishable."""
return [((i * 7 + k) % 256, (i * 13) % 256, (255 - i * 3) % 256) for i in range(LEDS)]
def output_scale(host):
"""The factor the driver applies to every pixel before it is shown: global x master x max brightness,
with the same integer steps as the firmware (patterns.cpp)."""
st = get(host, "/api/status")
hw = get(host, "/api/hardware")
return st["global_brightness"] * st["master_brightness"] // 255 * hw["max_brightness"] // 255
def expected(pixels, scale):
"""What the driver shows for a pixel: each channel scaled by the output factor."""
return [[c * scale // 255 for c in px] for px in pixels]
def mismatch_detail(bad):
return "" if not bad else f"first mismatch LED {bad[0][0]}: got {bad[0][1]} want {bad[0][2]}"
class Sender:
"""Drives every device from one thread. Each tick sends each device its current frame (unicast),
then one sync broadcast that all devices show their frame on."""
def __init__(self, sock, hosts):
self.sock = sock
self.hosts = hosts
self.ip_of = {h: socket.gethostbyname(h) for h in hosts}
self.host_of = {ip: h for h, ip in self.ip_of.items()}
self.missed = {h: 0 for h in hosts} # frames a device did not ack in time
self.sock.settimeout(ACK_WAIT)
self.frames = {h: None for h in hosts}
self.seq = 0
self.paused = False
self.lock = threading.Lock()
self.stop_event = threading.Event()
self.thread = threading.Thread(target=self._run, daemon=True)
def set_frames(self, pixels_by_host):
with self.lock:
self.frames.update(pixels_by_host)
def tick(self):
with self.lock:
frames = dict(self.frames)
self.seq = (self.seq + 1) & 0xFFFFFFFF
sent = [h for h in self.hosts if frames[h] is not None]
for h in sent:
send_frame(self.sock, h, frames[h], self.seq)
self.wait_acks(self.seq & 0x0F, sent)
send_sync(self.sock, self.seq)
def wait_acks(self, nibble, hosts):
"""Wait until each device acks this frame (the driver acks a completed frame with "LAK1" and its
DDP seq), up to ACK_WAIT. Devices that do not ack in time are counted as missed."""
waiting = {self.ip_of[h] for h in hosts}
deadline = time.time() + ACK_WAIT
while waiting and time.time() < deadline:
try:
data, addr = self.sock.recvfrom(64)
except OSError:
continue
if data[:4] == b"LAK1" and len(data) >= 5 and (data[4] & 0x0F) == nibble:
waiting.discard(addr[0])
for ip in waiting:
self.missed[self.host_of[ip]] += 1
def _run(self):
# Fixed rate: ticks start every TICK seconds on a schedule, so the ack waits don't stretch the rate
next_tick = time.monotonic()
while not self.stop_event.is_set():
if not self.paused:
self.tick()
next_tick += TICK
delay = next_tick - time.monotonic()
if delay > 0:
time.sleep(delay)
else:
next_tick = time.monotonic() # fell behind: start the schedule again from now
def start(self):
self.thread.start()
def stop(self):
self.stop_event.set()
self.thread.join()
def run_all(hosts, serial_port):
"""Run every check against every device together. Returns (output lines, failures) per host."""
out = {h: [] for h in hosts}
fails = {h: 0 for h in hosts}
def check(h, name, ok, detail=""):
out[h].append(("PASS " if ok else "FAIL ") + name + (f" {detail}" if detail else ""))
if not ok:
fails[h] += 1
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
before, scale = {}, {}
for h in hosts:
before[h] = get(h, "/api/ddp")
scale[h] = 255 # DDP frames are shown at full brightness, whatever the device's brightness settings
out[h].append(f"before: active={before[h]['active']} packets={before[h]['packets']}")
out[h].append(f"output scale: {scale[h]}/255")
sender = Sender(sock, hosts)
sent = {} # frame checksum -> pixels, for the serial log check
stop_serial = threading.Event()
serial_lines = []
reader = None
if serial_port:
reader = threading.Thread(target=read_serial, args=(serial_port, stop_serial, serial_lines), daemon=True)
reader.start()
sender.start()
for k in range(60): # about 1.5 s
px = frame(k)
sent[frame_sum(px)] = px
sender.set_frames({h: px for h in hosts})
time.sleep(TICK)
time.sleep(0.2)
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")
check(h, "receiving while sending", mid["active"], f"packets={mid['packets']}")
check(h, "packets counted", mid["packets"] - before[h]["packets"] >= 120,
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
sender.paused = True
time.sleep(0.1)
waiting = frame(200)
sent[frame_sum(waiting)] = waiting
send_sync(sock, sender.seq + 1) # 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"]
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)
time.sleep(0.2)
for h in hosts:
got = 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
stop_serial.set()
if reader is not None:
reader.join()
h = hosts[0]
pat = re.compile(r"DDP frames=\d+ packets=\d+ sum=(\d+) led0=(\d+),(\d+),(\d+) led_last=(\d+),(\d+),(\d+)")
summaries = [m for m in (pat.search(line) for line in serial_lines) if m]
check(h, "serial log has DDP summaries", len(summaries) > 0, f"{len(summaries)} lines")
matched = [m for m in summaries if int(m.group(1)) in sent]
check(h, "logged checksums are of sent frames", len(matched) == len(summaries),
f"{len(matched)}/{len(summaries)} match")
for m in summaries[-1:]:
px = sent.get(int(m.group(1)))
if px is not None:
check(h, "serial led0 and last LED match that frame",
[int(m.group(i)) for i in (2, 3, 4)] == list(px[0]) and
[int(m.group(i)) for i in (5, 6, 7)] == list(px[-1]),
f"led0 {m.group(2, 3, 4)} led_last {m.group(5, 6, 7)}")
def readback(h, pixels):
"""Read every LED back and return the ones that do not match what the driver should show."""
want_all = expected(pixels, scale[h])
bad = []
for i in range(LEDS):
got = get(h, f"/api/ddp?led={i}")["rgb"]
if got != want_all[i]:
bad.append((i, got, want_all[i]))
return bad
def check_readback(name, pixels):
# Lost frames are expected, and the sender repeats each frame, so give the strips up to 1 s to
# settle on it before reading back: the check passes once every LED matches
deadline = time.time() + 1.0
while True:
with ThreadPoolExecutor(len(hosts)) as pool:
bads = list(pool.map(lambda h: readback(h, pixels), hosts))
if all(not bad for bad in bads) or time.time() > deadline:
break
time.sleep(0.05)
for h, bad in zip(hosts, bads):
check(h, name, not bad, mismatch_detail(bad))
shown = frame(59)
sender.set_frames({h: shown for h in hosts})
time.sleep(0.1)
check_readback(f"all {LEDS} LEDs show the frame", shown)
for name, fn in ANIMATIONS.items():
for k in range(ANIM_FRAMES):
px = [fn(i, k) for i in range(LEDS)]
sender.set_frames({h: px for h in hosts})
time.sleep(TICK)
time.sleep(0.1)
check_readback(f"animation {name} shows its last frame", px)
shown = px
# Pixels past the strip end are ignored and don't break the rest
for h in hosts:
sock.sendto(packet(0, LEDS * 3 + 30, b"\xff" * 30, True), (h, PORT))
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])
# 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")
check(h, "inactive after pixels stop", not after["active"])
now0 = get(h, "/api/ddp?led=0")["rgb"]
check(h, "pattern is shown again", now0 != expected([shown[0]], scale[h])[0], f"LED 0 now {now0}")
sock.close()
return out, fails
def main():
args = [a for a in sys.argv[1:] if not a.startswith("--")]
serial_port = next((a.split("=", 1)[1] for a in sys.argv[1:] if a.startswith("--serial=")), None)
subnet = next((a.split("=", 1)[1] for a in sys.argv[1:] if a.startswith("--subnet=")), None)
if args:
hosts = args
else:
prefix = subnet or local_prefix()
hosts = find_devices(prefix)
print(f"found {len(hosts)} device(s) on {prefix}.0/24: {', '.join(hosts) or 'none'}\n")
if not hosts:
sys.exit(1)
if serial_port and len(hosts) > 1:
print("note: --serial is only used when testing one device\n")
serial_port = None
out, fails = run_all(hosts, serial_port)
failures = 0
for h in hosts:
print(f"== {h}")
print("\n".join(out[h]))
print()
failures += fails[h]
print("RESULT:", "all passed" if not failures else f"{failures} failed")
sys.exit(1 if failures else 0)
if __name__ == "__main__":
main()