#!/usr/bin/env python3 """led-simulator web app: a simulated Wi-Fi ESP-NOW bridge plus a browser rig. One Microdot server (from ``led-driver/lib``, no extra installs) provides: - UDP ``8766`` the bridge for led-controller's ``settings.bridge`` (and its host build, ``sim-controller/``): ``dst_mac + packet`` down, ``src_mac + packet`` up. - ``/ws`` the older bridge WebSocket, same protocol as ``bridge-wifi``: binary wire packets are broadcast, v1 JSON envelopes are split per MAC, and driver transmissions go up as ``0x00 + mac + packet``. - ``/`` the simulator page. Every strip is a led-driver running the real ``led-driver/src/main.py`` and patterns in Pyodide, one web worker each. - ``/sim`` the page's radio link: the server hands it the ESP-NOW packets the bridge would transmit and takes back what the drivers transmit. Strips register with the controller the way hardware does: each driver sends its JSON hello once when it powers on. A strip that boots while no controller is connected has to be power-cycled to register. Run from the repository root:: python3 led-simulator/server.py # http://localhost:8765/ """ from __future__ import annotations import argparse import asyncio import json import socket import sys from pathlib import Path SIM_ROOT = Path(__file__).resolve().parent REPO_ROOT = SIM_ROOT.parent DRIVER_ROOT = REPO_ROOT / "led-driver" DRIVER_SRC = DRIVER_ROOT / "src" DRIVER_LIB = DRIVER_ROOT / "lib" WEB_ROOT = SIM_ROOT / "web" STUBS_ROOT = SIM_ROOT / "stubs" WORKSPACE = SIM_ROOT / "workspace" DRIVERS_DIR = WORKSPACE / "drivers" SIM_DEFAULTS = SIM_ROOT / "sim.default.json" SIM_CONFIG = WORKSPACE / "sim.json" DRIVER_SETTINGS_TEMPLATE = SIM_ROOT / "settings.default.json" sys.path.insert(0, str(SIM_ROOT)) sys.path.insert(0, str(DRIVER_LIB)) from layout import normalise_layout, side_name, strip_places # noqa: E402 from rig_seed import seed, seed_soon # noqa: E402 BROADCAST = b"\xff\xff\xff\xff\xff\xff" WIRE = 0x4C MAX_ESPNOW = 250 # Locally administered MACs 02:51:4d:00:00:NN. The bridge is NN=00. MAC_PREFIX = bytes([0x02, 0x51, 0x4D, 0x00, 0x00]) BRIDGE_MAC = MAC_PREFIX + b"\x00" # Files a driver may persist in its simulated flash (workspace/drivers/NN/). # Patterns are not persisted: every boot loads led-driver/src/patterns. FLASH_FILES = ("settings.json", "presets.json") BUILTIN_DEFAULTS = { "bridge": { "name": "bridge-sim", "host": "0.0.0.0", "ws_port": 8765, "wifi_channel": 5, "debug": False, }, "layout": {}, "drivers": { "name": "sim-{n:02d}", "fps": 30, "loop_sleep_ms": 2, "boot_concurrency": 4, }, "pyodide_url": "https://cdn.jsdelivr.net/pyodide/v0.26.4/full/", } CONTENT_TYPES = { ".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".mjs": "text/javascript; charset=utf-8", ".css": "text/css; charset=utf-8", ".json": "application/json", ".svg": "image/svg+xml", ".png": "image/png", ".ico": "image/x-icon", ".py": "text/x-python; charset=utf-8", } 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]) 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) 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: 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 bridge_downlink(raw: bytes, debug: bool = False) -> list[tuple[bytes, bytes]]: """What the bridge transmits for one controller WebSocket message. Same rules as ``bridge-wifi/src/main.py`` ``downlink``. Returns a list of ``(dest_mac, espnow_packet)``. """ out: list[tuple[bytes, bytes]] = [] n = len(raw) if not raw: return out if raw[0] == WIRE: if n < 2 or n > MAX_ESPNOW: if debug: print("[bridge] dl skip wire", n) return out out.append((BROADCAST, bytes(raw))) return out if n < 8 or raw[:1] != b"{": return out try: data = json.loads(raw) except ValueError: return out if not isinstance(data, dict): return out devs = data.get("dv") or data.get("devices") if data.get("v") != "1" or not isinstance(devs, dict): return out for mac_s, body in devs.items(): if not isinstance(body, dict): continue h = str(mac_s).replace(":", "").replace("-", "").strip().lower() try: dest = BROADCAST if h == "ffffffffffff" else bytes.fromhex(h) except ValueError: continue if len(dest) != 6: continue msg = {"v": "1"} msg.update(body) pkt = json.dumps(msg, separators=(",", ":")).encode() if len(pkt) > MAX_ESPNOW: if debug: print("[bridge] dl skip big", len(pkt)) continue out.append((dest, pkt)) return out class Rig: """Strip list, simulated flash on disk, and the two WebSocket sides.""" def __init__(self, cfg: dict): self.cfg = cfg self.layout = cfg["layout"] self.debug = bool(cfg["bridge"].get("debug", False)) self.places = strip_places(self.layout) self.strips = [] name_fmt = str(cfg["drivers"].get("name", "sim-{n:02d}")) for p in self.places: default_name = name_fmt.format( n=p.number, row=p.row + 1, col=p.col + 1, side=side_name(p.col, self.layout["columns"]), ) self.strips.append( { "index": p.index, "n": p.number, "row": p.row, "col": p.col, "leds": p.leds, "reversed": p.reversed, "mac": mac_str(driver_mac(p.index)), "default_name": default_name, "dir": DRIVERS_DIR / ("%02d" % p.number), } ) self.controllers: set = set() self.page = None self.udp = None # asyncio datagram transport self.udp_peer = None # the controller that last sent a datagram self.hellos: dict[bytes, bytes] = {} # mac -> boot hello, replayed to a new UDP controller self.port = int(cfg["bridge"]["ws_port"]) # ----- flash ---------------------------------------------------------- def flash(self, index: int) -> dict: """Read (creating on first use) a strip's settings.json and presets.json.""" s = self.strips[index] d: Path = s["dir"] d.mkdir(parents=True, exist_ok=True) template = _read_json(DRIVER_SETTINGS_TEMPLATE) current = _read_json(d / "settings.json") settings = dict(template) settings.update(current) if not current.get("name"): settings["name"] = s["default_name"] # Strip length is physical: the layout decides it. settings["num_leds"] = s["leds"] settings["wifi_channel"] = int(self.cfg["bridge"].get("wifi_channel", 5)) settings_text = json.dumps(settings) (d / "settings.json").write_text(settings_text, encoding="utf-8") presets_path = d / "presets.json" if not presets_path.is_file(): presets_path.write_text("{}", encoding="utf-8") return { "settings.json": settings_text, "presets.json": presets_path.read_text(encoding="utf-8"), } def write_flash(self, index, path, data) -> bool: try: index = int(index) except (TypeError, ValueError): return False if not (0 <= index < len(self.strips)) or path not in FLASH_FILES: return False if not isinstance(data, str) or len(data) > 512 * 1024: return False d: Path = self.strips[index]["dir"] d.mkdir(parents=True, exist_ok=True) tmp = d / (path + ".tmp") tmp.write_text(data, encoding="utf-8") tmp.replace(d / path) return True def bundle(self) -> dict: """Files for a driver's flash: led-driver/src (with patterns) and stubs.""" driver = {} for f in sorted(DRIVER_SRC.rglob("*.py")): rel = f.relative_to(DRIVER_SRC).as_posix() if "__pycache__" in rel: continue driver[rel] = f.read_text(encoding="utf-8") stubs = {} for f in sorted(STUBS_ROOT.glob("*.py")): stubs[f.name] = f.read_text(encoding="utf-8") return {"driver": driver, "stubs": stubs} def public_config(self) -> dict: return { "bridge": { "name": self.cfg["bridge"]["name"], "mac": mac_str(BRIDGE_MAC), "port": self.port, "udp_port": int(self.cfg["bridge"].get("udp_port", 8766)), "lan_ip": lan_ip(), "wifi_channel": int(self.cfg["bridge"].get("wifi_channel", 5)), }, "layout": self.layout, "drivers": { k: self.cfg["drivers"][k] for k in ("fps", "loop_sleep_ms", "boot_concurrency") if k in self.cfg["drivers"] }, "pyodide_url": self.cfg["pyodide_url"], "strips": [ dict({k: v for k, v in s.items() if k != "dir"}, place=_read_json(s["dir"] / "settings.json").get("place")) for s in self.strips ], } # ----- radio ------------------------------------------------------------ async def to_page(self, frame): page = self.page if page is None: return try: await page.send(frame) except Exception: if self.page is page: self.page = None async def page_status(self): n = len(self.controllers) + (1 if self.udp_peer is not None else 0) await self.to_page(json.dumps({"t": "status", "controllers": n})) async def from_controller(self, raw: bytes): for dest, pkt in bridge_downlink(raw, self.debug): if self.debug: print("[bridge] dl", mac_str(dest), len(pkt)) # Nobody listening (page closed) = radio packet lost, as on air. await self.to_page(dest + pkt) def from_udp(self, data: bytes, addr): if len(data) < 7: return if addr != self.udp_peer: self.udp_peer = addr print("[bridge] udp controller %s:%d" % addr) seed_soon(self.cfg, {s["index"]: s["mac"] for s in self.strips}, addr[0]) asyncio.ensure_future(self.page_status()) for mac, pkt in self.hellos.items(): self.udp.sendto(mac + pkt, addr) if self.debug: print("[bridge] udp dl", mac_str(data[:6]), len(data) - 6) asyncio.ensure_future(self.to_page(bytes(data))) async def from_page(self, frame: bytes): """``src_mac + packet`` from a driver: the bridge forwards it up.""" if len(frame) < 7: return if frame[6:7] == b"{" or frame[6:8] == bytes([0x4C, 0x01]): self.hellos[frame[:6]] = frame[6:] if self.udp is not None and self.udp_peer is not None: self.udp.sendto(frame, self.udp_peer) up = bytes([0]) + frame if self.debug: print("[bridge] up", mac_str(frame[:6]), len(frame) - 6) for ws in list(self.controllers): try: await ws.send(up) except Exception: self.controllers.discard(ws) def build_app(rig: Rig): from microdot import Microdot, Response, send_file from microdot.websocket import WebSocketError, with_websocket app = Microdot() @app.after_request async def isolation_headers(request, response): # SharedArrayBuffer (driver packet rings) needs a cross-origin isolated # page. credentialless keeps the Pyodide CDN loading, as in led-editor. if response is not None and response is not Response.already_handled: response.headers["Cross-Origin-Opener-Policy"] = "same-origin" response.headers["Cross-Origin-Embedder-Policy"] = "credentialless" response.headers["Cache-Control"] = "no-cache" return response def static(path: Path): try: path = path.resolve() path.relative_to(WEB_ROOT.resolve()) except (OSError, ValueError): return "Not found", 404 if not path.is_file(): return "Not found", 404 ctype = CONTENT_TYPES.get(path.suffix.lower(), "application/octet-stream") return send_file(str(path), content_type=ctype) @app.route("/") async def index(request): return static(WEB_ROOT / "index.html") @app.route("/web/") async def web(request, path): return static(WEB_ROOT / path) @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 rig.udp_peer is None: return {"error": "no controller on the UDP bridge yet"}, 409 macs = {s["index"]: s["mac"] for s in rig.strips} reply = await asyncio.to_thread(seed, rig.cfg, macs, rig.udp_peer[0], print, 30) return {"sent": reply} @app.route("/api/config") async def api_config(request): return rig.public_config() @app.route("/api/bundle") async def api_bundle(request): return rig.bundle() @app.route("/api/flash/") async def api_flash(request, index): if not (0 <= index < len(rig.strips)): return {"error": "no such strip"}, 404 return rig.flash(index) @app.route("/ws") @with_websocket async def controller_ws(request, ws): rig.controllers.add(ws) print("[bridge] controller + (%d)" % len(rig.controllers)) await rig.page_status() try: while True: try: raw = await ws.receive() except WebSocketError: break if not raw: break if isinstance(raw, str): raw = raw.encode("utf-8") await rig.from_controller(raw) finally: rig.controllers.discard(ws) print("[bridge] controller - (%d)" % len(rig.controllers)) await rig.page_status() @app.route("/sim") @with_websocket async def page_ws(request, ws): old = rig.page rig.page = ws if old is not None: try: await old.send(json.dumps({"t": "takeover"})) await old.close() except Exception: pass print("[sim] page connected") await rig.page_status() try: while True: try: msg = await ws.receive() except WebSocketError: break if not msg: break if rig.page is not ws: break if isinstance(msg, (bytes, bytearray)): await rig.from_page(bytes(msg)) continue try: data = json.loads(msg) except ValueError: continue if isinstance(data, dict) and data.get("t") == "flash": rig.write_flash(data.get("n"), data.get("path"), data.get("data")) finally: if rig.page is ws: rig.page = None print("[sim] page disconnected") return app def main(argv=None): ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0]) ap.add_argument("--port", type=int, help="HTTP + bridge WebSocket port (default 8765)") ap.add_argument("--host", help="listen address (default 0.0.0.0)") ap.add_argument("--udp-port", type=int, help="UDP bridge port (default 8766, 0 = off)") ap.add_argument("--debug", action="store_true", help="log every bridge packet") args = ap.parse_args(argv) if not (DRIVER_SRC / "main.py").is_file(): print("led-driver/src/main.py not found next to led-simulator.", file=sys.stderr) return 1 try: import microdot # noqa: F401 except ImportError: print("Microdot not found in led-driver/lib.", file=sys.stderr) return 1 cfg = load_config() if args.port: cfg["bridge"]["ws_port"] = args.port if args.host: cfg["bridge"]["host"] = args.host if args.debug: cfg["bridge"]["debug"] = True if args.udp_port is not None: cfg["bridge"]["udp_port"] = args.udp_port rig = Rig(cfg) app = build_app(rig) udp_port = int(cfg["bridge"].get("udp_port", 8766)) host = str(cfg["bridge"]["host"]) port = rig.port lay = rig.layout print( "led-simulator: %d strips x %d LEDs (%d x %d)" % (len(rig.strips), lay["leds_per_strip"], lay["columns"], lay["rows"]) ) print(" simulator page: http://localhost:%d/" % port) if udp_port: print(" bridge for led-controller: settings.bridge \"%s:%d\" (or 127.0.0.1:%d)" % (lan_ip(), udp_port, udp_port)) class Udp(asyncio.DatagramProtocol): def datagram_received(self, data, addr): rig.from_udp(data, addr) async def run(): if udp_port: rig.udp, _ = await asyncio.get_running_loop().create_datagram_endpoint( Udp, local_addr=(host, udp_port) ) await app.start_server(host=host, port=port) try: asyncio.run(run()) except KeyboardInterrupt: pass return 0 if __name__ == "__main__": sys.exit(main())