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>
This commit is contained in:
jimmyandClaude Haiku 5.5 committed 2026-11-11 14:10:55 +13:00
1 parent 47f4eba0d6
commit 4cd3bc7973
294 files changed
+48954 -301

No files matched your search

+204 -101
View File
@@ -1,11 +1,12 @@
#!/usr/bin/env python3
"""
Test the LED driver's DDP receiver (UDP port 4048).
Test the LED driver's DDP receiver (UDP port 4048) and its frame sync (UDP broadcast port 4049).
Sends frames of RGB pixels the way a DDP controller does: a version 1 header, the pixel data split
across two packets, and the PUSH flag on the last packet of a frame. Then checks through the driver's
HTTP API that the pixels were shown, runs a few test animations, and that the pattern comes back once
the pixels stop. Every device is tested at the same time, one thread each.
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
@@ -26,11 +27,14 @@ import urllib.request
from concurrent.futures import ThreadPoolExecutor
PORT = 4048
SYNC_PORT = 4049
LEDS = 119
PUSH = 0x01
VER1 = 0x40
RGB = 0x01
ANIM_FRAMES = 40 # about 1 s at 40 fps
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):
@@ -40,25 +44,29 @@ def packet(seq, offset, data, push):
def send_frame(sock, host, pixels, seq):
"""Send pixels (a list of (r, g, b)) as two packets, PUSH on the second."""
"""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, seconds, lines):
"""Collect the driver's log lines from the USB serial port for a few seconds."""
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)
end = time.time() + seconds
buf = b""
while time.time() < end:
while not stop.is_set():
buf += ser.read(4096)
ser.close()
lines.extend(buf.decode("utf-8", "replace").splitlines())
@@ -114,6 +122,11 @@ def anim_breathe(i, k):
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)."""
@@ -131,121 +144,214 @@ def mismatch_detail(bad):
return "" if not bad else f"first mismatch LED {bad[0][0]}: got {bad[0][1]} want {bad[0][2]}"
def verify_frame(host, sock, pixels, scale):
"""Read every LED back while keeping the frame on the strip (the readback is slower than the DDP
timeout). Returns the LEDs that do not match what the driver should show."""
want_all = expected(pixels, scale)
stop = threading.Event()
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 keep_sending():
seq = 100
while not stop.is_set():
send_frame(sock, host, pixels, seq)
seq += 1
time.sleep(0.025)
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)
sender = threading.Thread(target=keep_sending, daemon=True)
sender.start()
bad = []
for i in range(LEDS):
got = get(host, f"/api/ddp?led={i}")["rgb"]
want = want_all[i]
if got != want:
bad.append((i, got, want))
stop.set()
sender.join()
return bad
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(host, serial_port):
"""Run every check against one device. Returns (failures, output lines)."""
out = []
failures = 0
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
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 log(line=""):
out.append(line)
def check(name, ok, detail=""):
nonlocal failures
log(("PASS " if ok else "FAIL ") + name + (f" {detail}" if detail else ""))
def check(h, name, ok, detail=""):
out[h].append(("PASS " if ok else "FAIL ") + name + (f" {detail}" if detail else ""))
if not ok:
failures += 1
fails[h] += 1
before = get(host, "/api/ddp")
log(f"before: active={before['active']} packets={before['packets']}")
scale = output_scale(host)
log(f"output scale: {scale}/255")
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
# A frame: LED i is a colour that depends on i, so every LED is distinguishable
def frame(k):
return [((i * 7 + k) % 256, (i * 13) % 256, (255 - i * 3) % 256) for i in range(LEDS)]
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, 3.0, serial_lines), daemon=True)
reader = threading.Thread(target=read_serial, args=(serial_port, stop_serial, serial_lines), daemon=True)
reader.start()
sent_sums = {}
last = None
for k in range(60): # about 1.5 s at 40 fps
last = frame(k)
sent_sums[frame_sum(last)] = k
send_frame(sock, host, last, k)
time.sleep(0.025)
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)
mid = get(host, "/api/ddp")
check("receiving while sending", mid["active"], f"packets={mid['packets']}")
check("packets counted", mid["packets"] - before["packets"] >= 120,
f"+{mid['packets'] - before['packets']}")
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']}")
bad = verify_frame(host, sock, last, scale)
check(f"all {LEDS} LEDs show the frame", not bad, mismatch_detail(bad))
shown = last
# 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("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_sums]
check("logged checksums are of sent frames", len(matched) == len(summaries),
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:]:
k = sent_sums.get(int(m.group(1)))
if k is not None:
sent = frame(k)
check("serial led0 and last LED match that frame",
[int(m.group(i)) for i in (2, 3, 4)] == list(sent[0]) and
[int(m.group(i)) for i in (5, 6, 7)] == list(sent[-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)}")
# Test animations: send each one, then check the last frame is shown
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():
pixels = None
for k in range(ANIM_FRAMES):
pixels = [fn(i, k) for i in range(LEDS)]
send_frame(sock, host, pixels, k)
time.sleep(0.025)
time.sleep(0.2)
bad = verify_frame(host, sock, pixels, scale)
check(f"animation {name} shows its last frame", not bad, mismatch_detail(bad))
shown = pixels
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
sock.sendto(packet(0, LEDS * 3 + 30, b"\xff" * 30, True), (host, PORT))
time.sleep(0.1)
check("out-of-range packet ignored", get(host, "/api/ddp?led=0")["rgb"] == expected([shown[0]], scale)[0])
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)
after = get(host, "/api/ddp")
check("inactive after pixels stop", not after["active"])
now_led0 = get(host, "/api/ddp?led=0")["rgb"]
check("pattern is shown again", now_led0 != expected([shown[0]], scale)[0], f"LED 0 now {now_led0}")
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}")
return failures, out
sock.close()
return out, fails
def main():
@@ -264,16 +370,13 @@ def main():
print("note: --serial is only used when testing one device\n")
serial_port = None
# All devices at the same time, one thread each
with ThreadPoolExecutor(max_workers=len(hosts)) as pool:
results = list(pool.map(lambda h: run(h, serial_port), hosts))
out, fails = run_all(hosts, serial_port)
failures = 0
for host, (device_failures, out) in zip(hosts, results):
print(f"== {host}")
print("\n".join(out))
for h in hosts:
print(f"== {h}")
print("\n".join(out[h]))
print()
failures += device_failures
failures += fails[h]
print("RESULT:", "all passed" if not failures else f"{failures} failed")
sys.exit(1 if failures else 0)