Files
led-controller/tests/engine_tests/test_outputs.py
T
jimmyandClaude Opus 5.5 a5a7fc575f feat(engine): Pi-side animation engine with protocol outputs and sequencer
Add src/engine, modelled on technicalkiwi/portal's player and sequence runner:

- Pixel generator: runs the unchanged led-driver patterns under CPython
  (utime shim + NeoPixel-like buffer) on a per-zone render thread and
  streams frames to pixel outputs, with keepalive for static frames.
- Output drivers: DDP, Art-Net (ArtDMX/ArtSync), sACN/E1.31, USB-DMX
  (Enttec Pro / Open DMX), plus an ESP32 preset output that reuses the
  existing preset + select delivery path. Registry in db/output.json,
  CRUD and test pattern at /outputs.
- Sequencer: timed preset chains per zone (portal step shape), deadline
  scheduling, loop/repeat, resume after restart; legacy sequence records
  are migrated. Zone play/stop, sequence and scene play/stop endpoints.
- CLI (python -m engine.cli), Outputs and Sequences modals, preset tiles
  drive pixel outputs, API/README docs, engine test suite.

ESP32 firmware is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 13:24:14 +13:00

304 lines
11 KiB
Python

"""Protocol driver tests: packet layout, universe splitting, frame prep, UDP, DMX, ESP32."""
import asyncio
import json
import socket
import struct
import pytest
from engine.outputs import open_output, parse_output_url
from engine.outputs.artnet import ArtNetOutput, build_artdmx, build_artsync
from engine.outputs.base import FrameOutput
from engine.outputs.ddp import DdpOutput, build_ddp_packets
from engine.outputs.dmx_serial import DmxSerialOutput, build_enttec_pro, dmx_universe
from engine.outputs.sacn import SacnOutput, build_e131, multicast_address
def frame(pixels, value=None):
if value is None:
return bytes(i % 256 for i in range(pixels * 3))
return bytes(value) * pixels
# -- base -------------------------------------------------------------------
def test_prepare_pads_truncates_and_scales():
out = FrameOutput({"pixel_count": 2})
assert out.prepare(b"\x10\x20\x30") == b"\x10\x20\x30\x00\x00\x00"
assert out.prepare(bytes(range(9))) == bytes(range(6))
half = FrameOutput({"pixel_count": 1, "brightness": 128})
assert half.prepare(b"\xff\x80\x00") == bytes((128, 64, 0))
assert out.prepare(b"\xff\xff\xff\xff\xff\xff", global_brightness=0) == bytes(6)
@pytest.mark.parametrize("order,expected", [
("rgb", b"\x01\x02\x03"), ("grb", b"\x02\x01\x03"), ("bgr", b"\x03\x02\x01"),
("brg", b"\x03\x01\x02"), ("rbg", b"\x01\x03\x02"), ("gbr", b"\x02\x03\x01"),
])
def test_color_order(order, expected):
assert FrameOutput({"pixel_count": 1, "color_order": order}).prepare(b"\x01\x02\x03") == expected
def test_reverse():
out = FrameOutput({"pixel_count": 2, "reverse": True, "color_order": "grb"})
assert out.prepare(b"\x01\x02\x03\x04\x05\x06") == b"\x05\x04\x06\x02\x01\x03"
def test_parse_output_url():
cfg = parse_output_url("ddp://10.0.0.5:4049?pixels=300&order=grb")
assert cfg["protocol"] == "ddp" and cfg["host"] == "10.0.0.5" and cfg["port"] == 4049
assert cfg["pixel_count"] == "300" and cfg["color_order"] == "grb"
out = open_output(cfg)
assert isinstance(out, DdpOutput) and out.pixel_count == 300 and out.port == 4049
dmx = parse_output_url("dmx_serial:///dev/ttyUSB1?mode=open_dmx&channel=4")
assert dmx["serial_port"] == "/dev/ttyUSB1" and dmx["dmx_mode"] == "open_dmx"
assert isinstance(open_output(parse_output_url("e131://?universe=2")), SacnOutput)
with pytest.raises(ValueError):
open_output({"protocol": "nope"})
# -- DDP --------------------------------------------------------------------
def test_ddp_packets_split_and_push():
data = frame(600) # 1800 bytes -> 1440 + 360
packets = build_ddp_packets(data, sequence=3)
assert len(packets) == 2
for pkt, (offset, length, push) in zip(packets, [(0, 1440, False), (1440, 360, True)]):
flags, seq, dtype, dest, off, ln = struct.unpack(">BBBBIH", pkt[:10])
assert flags & 0x40 and bool(flags & 0x01) == push
assert seq == 3 and dtype == 0x0B and dest == 1
assert off == offset and ln == length == len(pkt) - 10
assert b"".join(p[10:] for p in packets) == data
def test_ddp_three_packets_and_sequence_wraps():
out = DdpOutput({"host": "127.0.0.1", "pixel_count": 1000})
pkts = out.packets_for(frame(1000)) # 3000 bytes -> 3 packets
assert [struct.unpack(">I", p[4:8])[0] for p in pkts] == [0, 1440, 2880]
assert [p[0] & 0x01 for p in pkts] == [0, 0, 1]
seqs = [out.next_sequence() for _ in range(16)]
assert seqs[0] == 2 and 0 not in seqs and max(seqs) == 15 and seqs[-1] == 2
# -- Art-Net ----------------------------------------------------------------
def test_artdmx_header():
pkt = build_artdmx(0x1234, b"\x01\x02\x03", sequence=7)
assert pkt[:8] == b"Art-Net\x00"
assert struct.unpack("<H", pkt[8:10])[0] == 0x5000
assert struct.unpack(">H", pkt[10:12])[0] == 14
assert pkt[12] == 7 and pkt[13] == 0
assert pkt[14] == 0x34 and pkt[15] == 0x12 # SubUni, Net
assert struct.unpack(">H", pkt[16:18])[0] == 4 # padded to even
assert pkt[18:] == b"\x01\x02\x03\x00"
def test_artnet_universe_split():
out = ArtNetOutput({"host": "127.0.0.1", "universe": 3, "pixel_count": 400})
pkts = out.packets_for(out.prepare(frame(400)))
assert [p[14] for p in pkts] == [3, 4, 5]
assert [struct.unpack(">H", p[16:18])[0] for p in pkts] == [510, 510, 180]
assert len({p[12] for p in pkts}) == 1
def test_artnet_sequence_wrap_and_sync():
out = ArtNetOutput({"host": "127.0.0.1", "sync": True, "pixel_count": 1})
seqs = [out.next_sequence() for _ in range(256)]
assert seqs[0] == 1 and seqs[254] == 255 and seqs[255] == 1
pkts = out.packets_for(out.prepare(frame(1)))
assert pkts[-1] == build_artsync()
assert struct.unpack("<H", pkts[-1][8:10])[0] == 0x5200
def test_artnet_defaults_to_broadcast():
out = ArtNetOutput({})
assert out.host == "255.255.255.255" and out.broadcast
# -- sACN -------------------------------------------------------------------
def test_e131_layout():
cid = bytes(range(16))
pkt = build_e131(300, b"\x0a\x0b\x0c", sequence=9, cid=cid, source_name="test")
assert len(pkt) == 126 + 3
assert pkt[4:16] == b"ASC-E1.17\x00\x00\x00"
root_fl = struct.unpack(">H", pkt[16:18])[0]
assert root_fl >> 12 == 0x7 and root_fl & 0x0FFF == len(pkt) - 16
assert struct.unpack(">I", pkt[18:22])[0] == 4
assert pkt[22:38] == cid
framing_fl = struct.unpack(">H", pkt[38:40])[0]
assert framing_fl & 0x0FFF == len(pkt) - 38
assert struct.unpack(">I", pkt[40:44])[0] == 2
assert pkt[44:48] == b"test"
assert pkt[108] == 100 # priority
assert pkt[111] == 9 # sequence
assert struct.unpack(">H", pkt[113:115])[0] == 300
dmp_fl = struct.unpack(">H", pkt[115:117])[0]
assert dmp_fl & 0x0FFF == len(pkt) - 115
assert pkt[117] == 0x02 and pkt[118] == 0xA1
assert struct.unpack(">H", pkt[123:125])[0] == 4 # start code + 3 slots
assert pkt[125] == 0 and pkt[126:] == b"\x0a\x0b\x0c"
def test_sacn_multicast_split_and_stable_cid():
assert multicast_address(1) == "239.255.0.1"
assert multicast_address(300) == "239.255.1.44"
out = SacnOutput({"name": "roof", "universe": 1, "pixel_count": 200})
pkts = out.packets_for(out.prepare(frame(200)))
assert [addr for _p, addr in pkts] == [("239.255.0.1", 5568), ("239.255.0.2", 5568)]
again = SacnOutput({"name": "roof", "universe": 1, "pixel_count": 200})
assert out.cid == again.cid and len(out.cid) == 16
pkts2 = out.packets_for(out.prepare(frame(200)))
assert pkts2[0][0][111] == (pkts[0][0][111] + 1) & 0xFF
uni = SacnOutput({"host": "10.0.0.9", "universe": 5, "pixel_count": 1})
assert uni.packets_for(uni.prepare(frame(1)))[0][1] == ("10.0.0.9", 5568)
# -- UDP round trip ---------------------------------------------------------
def _udp_receiver():
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.bind(("127.0.0.1", 0))
sock.settimeout(2.0)
return sock
@pytest.mark.parametrize("cls,pixels,expected_packets", [(DdpOutput, 600, 2), (ArtNetOutput, 400, 3)])
def test_udp_round_trip(cls, pixels, expected_packets):
recv = _udp_receiver()
port = recv.getsockname()[1]
async def go():
out = cls({"host": "127.0.0.1", "port": port, "pixel_count": pixels})
await out.send(frame(pixels))
await asyncio.sleep(0.05)
if out._transport:
out._transport.close()
return out
out = asyncio.run(go())
got = [recv.recvfrom(2048)[0] for _ in range(expected_packets)]
recv.close()
assert out.stats.frames == 1 and out.stats.packets == expected_packets and out.stats.errors == 0
if cls is DdpOutput:
assert b"".join(p[10:] for p in got) == frame(pixels)
else:
assert got[0][:8] == b"Art-Net\x00"
# -- USB-DMX ----------------------------------------------------------------
class FakeSerial:
def __init__(self, output):
self.writes = []
self.breaks = []
self.closed = False
self._bc = False
@property
def break_condition(self):
return self._bc
@break_condition.setter
def break_condition(self, value):
self._bc = value
self.breaks.append(value)
def write(self, data):
self.writes.append(bytes(data))
def close(self):
self.closed = True
def test_dmx_universe_channel_offset():
u = dmx_universe(b"\x01\x02\x03", channel=10)
assert len(u) == 512 and u[9:12] == b"\x01\x02\x03" and u[:9] == bytes(9)
assert dmx_universe(bytes(600), channel=1) == bytes(512)
def test_enttec_pro_framing():
pkt = build_enttec_pro(bytes(512))
assert pkt[0] == 0x7E and pkt[1] == 6
assert struct.unpack("<H", pkt[2:4])[0] == 513
assert pkt[4] == 0 and pkt[-1] == 0xE7 and len(pkt) == 518
@pytest.mark.parametrize("mode", ["enttec_pro", "open_dmx"])
def test_dmx_serial_send(mode):
holder = {}
def factory(output):
holder["ser"] = FakeSerial(output)
return holder["ser"]
async def go():
out = DmxSerialOutput({"serial_port": "/dev/null", "dmx_mode": mode, "channel": 4, "pixel_count": 2},
serial_factory=factory)
await out.send(b"\x0a\x0b\x0c\x0d\x0e\x0f")
await out.close()
return out
out = asyncio.run(go())
ser = holder["ser"]
assert out.stats.errors == 0 and ser.closed
data = ser.writes[0]
if mode == "enttec_pro":
universe = data[5:-1]
assert data[0] == 0x7E and ser.breaks == []
else:
assert len(data) == 513 and data[0] == 0
universe = data[1:]
assert ser.breaks[:2] == [True, False]
assert universe[3:9] == b"\x0a\x0b\x0c\x0d\x0e\x0f"
assert ser.writes[-1].count(0) >= 512 # close() sends black
# -- ESP32 preset output --------------------------------------------------------
class FakeSender:
def __init__(self):
self.sent = []
async def send(self, data, addr=None):
self.sent.append((data, addr))
return True
class FakeDevices(dict):
def read(self, mac):
return self.get(mac)
def test_driver_output_matches_presets_push():
from engine.outputs.driver import DriverOutput, resolve_device_macs
devices = FakeDevices({
"aaaaaaaaaaaa": {"name": "roof", "transport": "espnow", "address": "aaaaaaaaaaaa"},
"bbbbbbbbbbbb": {"name": "roof", "transport": "espnow", "address": "bbbbbbbbbbbb"},
"cccccccccccc": {"name": "dj", "transport": "espnow", "address": "cccccccccccc"},
})
assert resolve_device_macs(["roof", "roof", "nobody"], devices) == [
("roof", "aaaaaaaaaaaa"), ("roof", "bbbbbbbbbbbb")]
sender = FakeSender()
out = DriverOutput(["dj"], sender_getter=lambda: sender, devices=devices, delay_s=0)
payload = {"p": "rainbow", "c": ["#FF0000"], "d": 100, "b": 32, "a": True,
"n1": 2, "n2": 0, "n3": 0, "n4": 0, "n5": 0, "n6": 0}
delivered = asyncio.run(out.apply("3", payload))
assert delivered == 2
msgs = [json.loads(d) for d, _a in sender.sent]
assert [a for _d, a in sender.sent] == ["cccccccccccc", "cccccccccccc"]
# Same two-message sequence presets.js sends via /presets/push (without save).
assert msgs[0] == {"v": "1", "presets": {"3": payload}}
assert msgs[1] == {"v": "1", "select": {"dj": ["3"]}}
def test_driver_output_without_sender_records_error():
from engine.outputs.driver import DriverOutput
out = DriverOutput(["dj"], sender_getter=lambda: None, devices=FakeDevices())
assert asyncio.run(out.apply("1", {"p": "on"})) == 0
assert out.stats.errors == 1