#!/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()