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>
This commit is contained in:
jimmyandClaude Opus 5.5 committed 2026-10-22 13:24:14 +13:00
1 parent 827eb97203
commit a5a7fc575f
42 files changed
+4117 -75

No files matched your search

+254
View File
@@ -0,0 +1,254 @@
"""Common output-driver interface and helpers.
Two kinds of output:
* ``FrameOutput`` — the Pi renders pixels and streams raw RGB frames
(DDP, Art-Net, sACN, USB-DMX).
* ``PresetOutput`` — the device renders itself; the engine only tells it which
preset to run (our ESP32 led-drivers over Wi-Fi / ESP-NOW).
"""
import asyncio
import functools
import socket
COLOR_ORDERS = {
"rgb": (0, 1, 2),
"rbg": (0, 2, 1),
"grb": (1, 0, 2),
"gbr": (1, 2, 0),
"brg": (2, 0, 1),
"bgr": (2, 1, 0),
}
DEFAULT_FPS = 40
def _int(value, default, lo=None, hi=None):
try:
v = int(value)
except (TypeError, ValueError):
v = default
if lo is not None:
v = max(lo, v)
if hi is not None:
v = min(hi, v)
return v
def _bool(value, default=False):
if isinstance(value, bool):
return value
if isinstance(value, (int, float)):
return bool(value)
if isinstance(value, str):
s = value.strip().lower()
if s in ("1", "true", "yes", "on"):
return True
if s in ("0", "false", "no", "off"):
return False
return default
class OutputStats:
def __init__(self):
self.frames = 0
self.packets = 0
self.bytes = 0
self.errors = 0
self.last_error = None
def error(self, exc):
self.errors += 1
self.last_error = repr(exc)
def to_dict(self):
return {
"frames": self.frames,
"packets": self.packets,
"bytes": self.bytes,
"errors": self.errors,
"last_error": self.last_error,
}
class FrameOutput:
"""Base class for pixel-streaming outputs."""
kind = "frame"
protocol = ""
# Resend the last frame this often when the pattern is static, so receivers
# don't time out (sACN drops a source after 2.5 s; DMX expects a steady stream).
keepalive_s = 1.0
def __init__(self, cfg):
cfg = dict(cfg or {})
self.cfg = cfg
self.name = str(cfg.get("name") or cfg.get("id") or self.protocol)
self.pixel_count = _int(cfg.get("pixel_count"), 60, 1, 100000)
self.pixel_offset = _int(cfg.get("pixel_offset"), 0, 0)
order = str(cfg.get("color_order") or "rgb").lower()
self.color_order = order if order in COLOR_ORDERS else "rgb"
self.reverse = _bool(cfg.get("reverse"), False)
self.brightness = _int(cfg.get("brightness"), 255, 0, 255)
self.fps = _int(cfg.get("fps"), DEFAULT_FPS, 1, 120)
self.stats = OutputStats()
self._index_map = self._build_index_map()
# -- frame preparation -------------------------------------------------
def _build_index_map(self):
"""Byte index map: out[i] = src[map[i]] (colour order + reverse)."""
order = COLOR_ORDERS[self.color_order]
n = self.pixel_count
idx = []
for p in range(n):
src_px = (n - 1 - p) if self.reverse else p
base = src_px * 3
idx.extend((base + order[0], base + order[1], base + order[2]))
return idx
@staticmethod
@functools.lru_cache(maxsize=64)
def brightness_table(level):
level = max(0, min(255, int(level)))
return bytes((v * level + 127) // 255 for v in range(256))
def prepare(self, rgb, global_brightness=255):
"""Pad/truncate, apply brightness, colour order and reverse."""
need = self.pixel_count * 3
data = bytes(rgb[:need])
if len(data) < need:
data = data + bytes(need - len(data))
level = (self.brightness * max(0, min(255, int(global_brightness))) + 127) // 255
if level < 255:
data = data.translate(self.brightness_table(level))
if self.color_order == "rgb" and not self.reverse:
return data
m = self._index_map
return bytes(data[i] for i in m)
# -- lifecycle -----------------------------------------------------------
async def open(self):
pass
async def send(self, rgb, global_brightness=255):
"""Send one frame of logical RGB (pixel_count*3 bytes)."""
try:
payload = self.prepare(rgb, global_brightness)
await self._send_prepared(payload)
self.stats.frames += 1
except Exception as e:
self.stats.error(e)
async def _send_prepared(self, payload):
raise NotImplementedError
async def blackout(self):
await self.send(bytes(self.pixel_count * 3))
async def close(self):
try:
await self.blackout()
except Exception:
pass
def status(self):
return {
"name": self.name,
"protocol": self.protocol,
"kind": self.kind,
"pixel_count": self.pixel_count,
**self.stats.to_dict(),
}
class _DatagramSink(asyncio.DatagramProtocol):
def __init__(self, owner):
self.owner = owner
def error_received(self, exc):
self.owner.stats.error(exc)
class UdpFrameOutput(FrameOutput):
"""FrameOutput that sends UDP datagrams to one host:port."""
default_port = 0
def __init__(self, cfg):
super().__init__(cfg)
self.host = str(self.cfg.get("host") or "").strip()
self.port = _int(self.cfg.get("port"), self.default_port, 1, 65535)
self.broadcast = _bool(self.cfg.get("broadcast"), False)
self._transport = None
def destination(self):
return (self.host, self.port)
def _make_socket(self):
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.setblocking(False)
if self.broadcast or self.host.endswith(".255"):
sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
return sock
async def open(self):
if self._transport is not None:
return
loop = asyncio.get_running_loop()
self._transport, _ = await loop.create_datagram_endpoint(
lambda: _DatagramSink(self), sock=self._make_socket()
)
def sendto(self, packet, addr=None):
if self._transport is None:
raise RuntimeError("output not open")
self._transport.sendto(packet, addr or self.destination())
self.stats.packets += 1
self.stats.bytes += len(packet)
async def send(self, rgb, global_brightness=255):
if self._transport is None:
try:
await self.open()
except Exception as e:
self.stats.error(e)
return
await super().send(rgb, global_brightness)
async def close(self):
await super().close()
if self._transport is not None:
self._transport.close()
self._transport = None
class PresetOutput:
"""Base class for outputs that render presets on the device itself."""
kind = "preset"
protocol = ""
def __init__(self, cfg=None):
self.cfg = dict(cfg or {})
self.name = str(self.cfg.get("name") or self.protocol)
self.stats = OutputStats()
async def open(self):
pass
async def apply(self, preset_id, preset_payload):
raise NotImplementedError
async def close(self):
pass
def status(self):
return {"name": self.name, "protocol": self.protocol, "kind": self.kind, **self.stats.to_dict()}
def split_universes(data, channels_per_universe=510):
"""Split RGB bytes into DMX-universe sized chunks (170 RGB px = 510 ch)."""
return [data[i:i + channels_per_universe] for i in range(0, len(data), channels_per_universe)] or [b""]