feat: simulator bridge, rig seed and web UI (in progress)

Work in progress from the same tree as the controller's sequences-v2 changes.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
This commit is contained in:
jimmyandClaude Haiku 5.5 committed 2026-11-11 14:10:55 +13:00
1 parent 4fc3345fc9
commit 4d8aeb5df8
26 files changed
+3907 -288

No files matched your search

+782
View File
@@ -0,0 +1,782 @@
"""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()