"""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""]