"""Simulated Wi-Fi ESP-NOW bridge with a rig of simulated led-drivers behind it. To led-controller this looks like ``bridge-wifi``: a WebSocket on ``/ws`` with the same downlink handling (binary wire packets are broadcast, v1 JSON envelopes are split per MAC) and the same uplink framing (``0x00 + peer_mac + packet``). Add it in the controller as an IP bridge. Behind the bridge, every strip is a separate process running the real ``led-driver/src/main.py`` (see ``sim_driver.py``), so each strip keeps its own settings, presets, groups and pattern state, as on hardware. """ from __future__ import annotations import asyncio import json import os import secrets import shutil import socket import subprocess import sys import threading import time from multiprocessing.connection import Listener, wait from pathlib import Path from layout import normalise_layout, side_name, strip_places from rig_seed import seed, seed_soon SIM_ROOT = Path(__file__).resolve().parent WORKSPACE = SIM_ROOT / "workspace" DRIVERS_DIR = WORKSPACE / "drivers" SHARED_PATTERNS = WORKSPACE / "patterns" SIM_DEFAULTS = SIM_ROOT / "sim.default.json" SIM_CONFIG = WORKSPACE / "sim.json" DRIVER_SETTINGS_TEMPLATE = SIM_ROOT / "settings.default.json" DRIVER_ROOT = SIM_ROOT.parent / "led-driver" DRIVER_SRC = DRIVER_ROOT / "src" DRIVER_LIB = DRIVER_ROOT / "lib" SIM_DRIVER = SIM_ROOT / "sim_driver.py" BROADCAST = b"\xff\xff\xff\xff\xff\xff" WIRE = 0x4C MSG_ANNOUNCE = 0x01 MAX_ESPNOW = 250 RESET_EXIT_CODE = 75 # stubs/machine.py: machine.reset() # Locally administered MACs: 02:51:4d ("QM") : 00 : 00 : NN. The bridge is NN=00. MAC_PREFIX = bytes([0x02, 0x51, 0x4D, 0x00, 0x00]) BUILTIN_DEFAULTS = { "bridge": { "name": "bridge-sim", "host": "0.0.0.0", "ws_port": 8765, "udp_port": 8766, "wifi_channel": 5, "debug": False, }, "layout": {}, "drivers": { "name": "sim-{n:02d}", "fps": 30, "loop_sleep_ms": 2, }, } def mac_str(mac: bytes) -> str: return ":".join("%02x" % b for b in mac) def driver_mac(index: int) -> bytes: return MAC_PREFIX + bytes([(index + 1) & 0xFF]) BRIDGE_MAC = MAC_PREFIX + b"\x00" def _merge(base: dict, extra: dict) -> dict: out = dict(base) for k, v in (extra or {}).items(): if isinstance(v, dict) and isinstance(out.get(k), dict): out[k] = _merge(out[k], v) else: out[k] = v return out def _read_json(path: Path) -> dict: try: with open(path, encoding="utf-8") as f: data = json.load(f) return data if isinstance(data, dict) else {} except (OSError, ValueError): return {} def load_config() -> dict: """Built-in defaults <- sim.default.json <- workspace/sim.json.""" WORKSPACE.mkdir(parents=True, exist_ok=True) if not SIM_CONFIG.is_file() and SIM_DEFAULTS.is_file(): shutil.copy2(SIM_DEFAULTS, SIM_CONFIG) cfg = _merge(BUILTIN_DEFAULTS, _read_json(SIM_DEFAULTS)) cfg = _merge(cfg, _read_json(SIM_CONFIG)) cfg["layout"] = normalise_layout(cfg.get("layout")) return cfg def lan_ip() -> str: """Best guess at this computer's LAN address (for the controller to dial).""" s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) try: s.connect(("10.255.255.255", 1)) return s.getsockname()[0] except OSError: return "127.0.0.1" finally: s.close() def sync_patterns() -> None: """Copy led-driver/src/patterns into the shared simulated flash patterns/ folder. Files the controller pushed by OTA under other names are kept. """ SHARED_PATTERNS.mkdir(parents=True, exist_ok=True) src = DRIVER_SRC / "patterns" if not src.is_dir(): return for f in src.glob("*.py"): dst = SHARED_PATTERNS / f.name try: if not dst.exists() or f.stat().st_mtime > dst.stat().st_mtime: shutil.copy2(f, dst) except OSError as e: print("[sim] pattern copy failed:", f.name, e) class Strip: def __init__(self, place, name: str): self.place = place self.index = place.index self.mac = driver_mac(place.index) self.name = name self.dir = DRIVERS_DIR / ("%02d" % place.number) self.proc: subprocess.Popen | None = None self.conn = None self.frame = bytes(place.leds * 3) self.hello: bytes | None = None self.announce: bytes | None = None self.rx_packets = 0 self.tx_packets = 0 self.reported = False class BridgeSim: """Owns the WebSocket server (asyncio thread) and the driver processes.""" def __init__(self, cfg: dict | None = None): self.cfg = cfg or load_config() self.layout = self.cfg["layout"] self.places = strip_places(self.layout) dcfg = self.cfg["drivers"] self.strips: list[Strip] = [] for p in self.places: name = str(dcfg.get("name", "sim-{n:02d}")).format( n=p.number, row=p.row + 1, col=p.col + 1, side=side_name(p.col, self.layout["columns"]), ) self.strips.append(Strip(p, name)) self.by_mac = {s.mac: s for s in self.strips} self.running = False self.port = int(self.cfg["bridge"]["ws_port"]) self.error: str | None = None self.debug = bool(self.cfg["bridge"].get("debug", False)) self._lock = threading.Lock() self._dirty: set[int] = set() self._clients: set = set() self._loop: asyncio.AbstractEventLoop | None = None self._loop_thread: threading.Thread | None = None self._reader_thread: threading.Thread | None = None self._accept_thread: threading.Thread | None = None self._listener: Listener | None = None self._authkey = b"" self._stopping = False self._app = None self.downlink_count = 0 self.uplink_count = 0 # UDP bridge (led-controller settings.bridge): dst_mac(6)+packet down, src_mac(6)+packet up self.udp_port = int(self.cfg["bridge"].get("udp_port", 8766)) self._udp: socket.socket | None = None self._udp_peer = None self._udp_thread: threading.Thread | None = None # ----- public ------------------------------------------------------- @property def client_count(self) -> int: return len(self._clients) def take_dirty_frames(self) -> dict[int, bytes]: with self._lock: out = {i: self.strips[i].frame for i in self._dirty} self._dirty.clear() return out def alive_count(self) -> int: return sum(1 for s in self.strips if s.proc is not None and s.proc.poll() is None) def connected_count(self) -> int: return sum(1 for s in self.strips if s.conn is not None) def start(self, port: int | None = None) -> None: if self.running: return if port is not None: self.port = int(port) self.error = None self._stopping = False self._check_paths() sync_patterns() self._prepare_driver_dirs() # Bind the WebSocket port first so a clash fails before drivers boot. ready = threading.Event() self._loop_thread = threading.Thread( target=self._loop_main, args=(ready,), name="bridge-ws", daemon=True ) self._loop_thread.start() ready.wait(5) if self.error: raise RuntimeError(self.error) if self.udp_port: self._udp = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) self._udp.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) self._udp.bind((str(self.cfg["bridge"].get("host", "0.0.0.0")), self.udp_port)) self._udp.settimeout(0.5) self._authkey = secrets.token_bytes(16) # backlog: all strips connect at once; the default of 1 makes late # drivers wait on SYN retries. self._listener = Listener(("127.0.0.1", 0), authkey=self._authkey, backlog=64) self.running = True if self._udp is not None: self._udp_thread = threading.Thread(target=self._udp_main, name="bridge-udp", daemon=True) self._udp_thread.start() self._accept_thread = threading.Thread( target=self._accept_main, name="bridge-accept", daemon=True ) self._accept_thread.start() for s in self.strips: s.reported = False self._spawn(s) self._reader_thread = threading.Thread( target=self._reader_main, name="bridge-drivers", daemon=True ) self._reader_thread.start() print( "[sim] bridge %s ws://%s:%d/ws udp %d %d strips x %d LEDs" % ( self.cfg["bridge"]["name"], lan_ip(), self.port, self.udp_port, len(self.strips), self.layout["leds_per_strip"], ) ) def stop(self) -> None: if not self.running and self._loop is None: return self._stopping = True self.running = False if self._udp is not None: if self._udp_thread is not None: self._udp_thread.join(1) self._udp.close() self._udp = None if self._reader_thread is not None: self._reader_thread.join(1) self._reader_thread = None for s in self.strips: if s.proc is not None and s.proc.poll() is None: s.proc.terminate() deadline = time.monotonic() + 3 for s in self.strips: if s.proc is None: continue try: s.proc.wait(max(0.1, deadline - time.monotonic())) except subprocess.TimeoutExpired: s.proc.kill() s.proc = None if s.conn is not None: try: s.conn.close() except OSError: pass s.conn = None s.hello = None s.announce = None s.frame = bytes(s.place.leds * 3) with self._lock: self._dirty.update(range(len(self.strips))) if self._listener is not None: # close() does not wake a thread blocked in accept() on Linux; # a throwaway connection does. try: socket.create_connection(self._listener.address, timeout=0.5).close() except OSError: pass try: self._listener.close() except OSError: pass self._listener = None loop = self._loop if loop is not None: fut = asyncio.run_coroutine_threadsafe(self._shutdown_ws(), loop) try: fut.result(3) except Exception: pass if self._loop_thread is not None: self._loop_thread.join(3) if self._loop_thread.is_alive(): loop.call_soon_threadsafe(loop.stop) self._loop_thread.join(1) self._loop = None self._clients.clear() print("[sim] stopped") # ----- driver processes -------------------------------------------- def _check_paths(self): if not (DRIVER_SRC / "main.py").is_file(): raise RuntimeError("led-driver/src/main.py not found next to led-simulator") def _prepare_driver_dirs(self): template = _read_json(DRIVER_SETTINGS_TEMPLATE) for s in self.strips: s.dir.mkdir(parents=True, exist_ok=True) settings_path = s.dir / "settings.json" current = _read_json(settings_path) merged = dict(template) merged.update(current) if not current.get("name"): merged["name"] = s.name # Strip length is physical: the layout decides it. merged["num_leds"] = s.place.leds merged["wifi_channel"] = int(self.cfg["bridge"].get("wifi_channel", 5)) with open(settings_path, "w", encoding="utf-8") as f: json.dump(merged, f) s.name = merged["name"] presets_path = s.dir / "presets.json" if not presets_path.is_file(): presets_path.write_text("{}\n", encoding="utf-8") self._link_patterns(s.dir / "patterns") def _link_patterns(self, link: Path): if link.is_symlink() or link.exists(): return try: link.symlink_to(SHARED_PATTERNS.resolve(), target_is_directory=True) except OSError: # No symlinks (e.g. Windows without developer mode): private copy. shutil.copytree(SHARED_PATTERNS, link) def _spawn(self, s: Strip): addr = self._listener.address env = dict(os.environ) env.update( { "LED_SIM_INDEX": str(s.index), "LED_SIM_MAC": s.mac.hex(), "LED_SIM_DIR": str(s.dir), "LED_SIM_ADDR": "%s:%d" % addr, "LED_SIM_AUTH": self._authkey.hex(), "LED_SIM_FPS": str(self.cfg["drivers"].get("fps", 30)), "LED_SIM_LOOP_SLEEP_MS": str(self.cfg["drivers"].get("loop_sleep_ms", 2)), "PYTHONDONTWRITEBYTECODE": "1", "PYTHONUNBUFFERED": "1", } ) s.proc = subprocess.Popen( [sys.executable, str(SIM_DRIVER)], cwd=str(s.dir), env=env, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, ) def _accept_main(self): listener = self._listener while self.running and listener is not None: try: conn = listener.accept() except (OSError, EOFError): if not self.running: return # A failed auth handshake (stray client): keep listening. continue try: first = conn.recv_bytes() except (OSError, EOFError): continue if first[:1] != b"H" or len(first) < 2 or first[1] >= len(self.strips): conn.close() continue self.strips[first[1]].conn = conn def _report_dead(self, s: Strip): log = s.dir / "driver.log" tail = "" try: tail = log.read_text(encoding="utf-8", errors="replace")[-600:] except OSError: pass print("[sim] strip %d (%s) stopped. Last log lines:\n%s" % (s.place.number, s.name, tail)) def _reader_main(self): while self.running: for s in self.strips: if s.conn is None and not s.reported and s.proc is not None and s.proc.poll() is not None: s.reported = True self._report_dead(s) conns = {s.conn: s for s in self.strips if s.conn is not None} if not conns: time.sleep(0.2) continue try: ready = wait(list(conns), timeout=0.2) except OSError: continue for c in ready: s = conns[c] try: frame = c.recv_bytes() except (OSError, EOFError): self._driver_gone(s) continue kind = frame[:1] if kind == b"P": with self._lock: s.frame = frame[1:] self._dirty.add(s.index) elif kind == b"T" and len(frame) >= 7: s.tx_packets += 1 self._from_driver(s, frame[1:7], frame[7:]) def _driver_gone(self, s: Strip): if s.conn is not None: try: s.conn.close() except OSError: pass s.conn = None if self._stopping or not self.running: return code = None if s.proc is not None: try: code = s.proc.wait(2) except subprocess.TimeoutExpired: code = None if code == RESET_EXIT_CODE: print("[sim] strip %d reset, booting again" % s.place.number) self._spawn(s) return s.reported = True self._report_dead(s) with self._lock: s.frame = bytes(s.place.leds * 3) self._dirty.add(s.index) def _to_driver(self, s: Strip, packet: bytes): if s.conn is None: return try: s.conn.send_bytes(b"R" + BRIDGE_MAC + packet) s.rx_packets += 1 except (OSError, EOFError, ValueError): pass def _from_driver(self, s: Strip, dest: bytes, packet: bytes): """Driver ESP-NOW transmit. The bridge forwards everything it hears.""" if packet[:1] == b"{": s.hello = packet elif len(packet) >= 2 and packet[0] == WIRE and packet[1] == MSG_ANNOUNCE: s.announce = packet if self.debug: print("[sim] up %s %d B" % (mac_str(s.mac), len(packet))) udp, peer = self._udp, self._udp_peer if udp is not None and peer is not None: try: udp.sendto(s.mac + packet, peer) self.uplink_count += 1 except OSError: pass loop = self._loop if loop is not None: frame = bytes([0]) + s.mac + packet loop.call_soon_threadsafe(self._uplink_soon, frame) # ----- UDP bridge ---------------------------------------------------- def _udp_main(self): udp = self._udp while self.running and udp is not None: try: data, addr = udp.recvfrom(2048) except socket.timeout: continue except OSError: return if len(data) < 7: continue if self._udp_peer != addr: self._udp_peer = addr print("[sim] udp controller", "%s:%d" % addr) seed_soon(self.cfg, {st.index: mac_str(st.mac) for st in self.strips}, addr[0]) # A controller that (re)started after the strips booted still gets their hellos for st in self.strips: for pkt in (st.hello, st.announce): if pkt: try: udp.sendto(st.mac + pkt, addr) except OSError: pass self.downlink_count += 1 if self.debug: print("[sim] udp dl %s %d B" % (mac_str(data[:6]), len(data) - 6)) self._deliver(bytes(data[:6]), bytes(data[6:])) def pixels(self) -> dict: with self._lock: frames = [s.frame for s in self.strips] return { "layout": self.layout, "strips": [ { "n": s.place.number, "name": s.name, "mac": mac_str(s.mac), "row": s.place.row, "col": s.place.col, "reversed": s.place.reversed, "running": s.conn is not None, "rx": s.rx_packets, "tx": s.tx_packets, "place": _read_json(s.dir / "settings.json").get("place"), "rgb": frames[i].hex(), } for i, s in enumerate(self.strips) ], } # ----- WebSocket side (asyncio thread) ------------------------------ def _loop_main(self, ready: threading.Event): for p in (str(DRIVER_LIB),): if p not in sys.path: sys.path.insert(0, p) try: from microdot import Microdot from microdot.websocket import WebSocketError, with_websocket except ImportError as e: self.error = "Microdot not found in led-driver/lib (%s)" % e ready.set() return app = Microdot() self._app = app bridge = self @app.route("/ws") @with_websocket async def ws_handler(request, ws): bridge._clients.add(ws) print("[sim] ws client + (%d)" % len(bridge._clients)) # A real bridge forwards boot hellos only to clients that are # connected at the time. Replay them so the controller learns the # strips even when it connects after Start. for s in bridge.strips: for pkt in (s.hello, s.announce): if pkt: try: await ws.send(bytes([0]) + s.mac + pkt) except Exception: pass try: while True: try: raw = await ws.receive() except WebSocketError: break if not raw: break if isinstance(raw, str): raw = raw.encode("utf-8") bridge.downlink_count += 1 bridge._downlink(raw) finally: bridge._clients.discard(ws) print("[sim] ws client - (%d)" % len(bridge._clients)) @app.route("/api/pixels") async def api_pixels(request): return bridge.pixels() @app.route("/api/seed-layout", methods=["POST"]) async def api_seed_layout(request): """Send the simulator's layout to the controller for every unplaced strip, now.""" if bridge._udp_peer is None: return {"error": "no controller on the UDP bridge yet"}, 409 macs = {st.index: mac_str(st.mac) for st in bridge.strips} reply = await asyncio.to_thread(seed, bridge.cfg, macs, bridge._udp_peer[0], print, 30) return {"sent": reply} @app.route("/") async def index(request): info = { "bridge": bridge.cfg["bridge"]["name"], "mac": mac_str(BRIDGE_MAC), "ws": "/ws", "strips": [ {"n": s.place.number, "name": s.name, "mac": mac_str(s.mac)} for s in bridge.strips ], } return info loop = asyncio.new_event_loop() self._loop = loop asyncio.set_event_loop(loop) host = str(self.cfg["bridge"].get("host", "0.0.0.0")) async def run(): try: # Probe the port so a clash is reported at Start. srv = await asyncio.start_server(lambda r, w: None, host, self.port) srv.close() await srv.wait_closed() except OSError as e: self.error = "Port %d not available: %s" % (self.port, e.strerror or e) ready.set() return ready.set() await app.start_server(host=host, port=self.port) try: loop.run_until_complete(run()) except Exception as e: # noqa: BLE001 if not self._stopping: self.error = str(e) print("[sim] ws server error:", e) finally: ready.set() try: loop.close() except Exception: pass async def _shutdown_ws(self): for ws in list(self._clients): try: await ws.close() except Exception: pass try: ws.request.sock[1].close() except Exception: pass if self._app is not None and getattr(self._app, "server", None): self._app.shutdown() def _uplink_soon(self, frame: bytes): self.uplink_count += 1 for ws in list(self._clients): asyncio.ensure_future(self._send_ws(ws, frame)) async def _send_ws(self, ws, frame): try: await ws.send(frame) except Exception: self._clients.discard(ws) def _deliver(self, dest: bytes, packet: bytes): if dest == BROADCAST: for s in self.strips: self._to_driver(s, packet) return s = self.by_mac.get(dest) if s is None: if self.debug: print("[sim] dl no such peer", mac_str(dest)) return self._to_driver(s, packet) def _downlink(self, raw: bytes): """Same rules as bridge-wifi/src/main.py ``downlink``.""" n = len(raw) if not raw: return if raw[0] == WIRE: if n < 2: return if n > MAX_ESPNOW: if self.debug: print("[sim] dl skip big wire", n) return self._deliver(BROADCAST, raw) return if n < 8 or raw[:1] != b"{": return try: data = json.loads(raw) except ValueError: return if not isinstance(data, dict): return devs = data.get("dv") or data.get("devices") if data.get("v") != "1" or not isinstance(devs, dict): return for mac_s, body in devs.items(): if not isinstance(body, dict): continue try: h = str(mac_s).replace(":", "").replace("-", "").strip().lower() dest = BROADCAST if h == "ffffffffffff" else bytes.fromhex(h) if len(dest) != 6: continue except ValueError: continue msg = {"v": "1"} msg.update(body) pkt = json.dumps(msg, separators=(",", ":")).encode() if len(pkt) > MAX_ESPNOW: if self.debug: print("[sim] dl skip big", len(pkt)) continue self._deliver(dest, pkt) def main(argv=None): """Headless rig: ``python3 led-simulator/bridge_sim.py [--udp-port 8766] [--port 8765]``.""" import argparse import signal ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) ap.add_argument("--port", type=int, help="WebSocket/HTTP port (default from sim.json, 8765)") ap.add_argument("--udp-port", type=int, help="UDP bridge port (default 8766, 0 = off)") ap.add_argument("--debug", action="store_true") a = ap.parse_args(argv) cfg = load_config() if a.udp_port is not None: cfg["bridge"]["udp_port"] = a.udp_port if a.debug: cfg["bridge"]["debug"] = True sim = BridgeSim(cfg) sim.start(a.port) stop = threading.Event() signal.signal(signal.SIGTERM, lambda *_: stop.set()) signal.signal(signal.SIGINT, lambda *_: stop.set()) try: while not stop.wait(5): print(flush=True, *("[sim] running %d/%d dl %d ul %d" % (sim.connected_count(), len(sim.strips), sim.downlink_count, sim.uplink_count),)) finally: sim.stop() if __name__ == "__main__": main()