chore: move led-simulator in from its submodule

Merges led-simulator (sim-bridge, 4d8aeb5) under led-simulator/ with its history,
in place of the submodule.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
jimmyandClaude Opus 5.5 committed 2026-11-16 15:08:49 +13:00
commit 698c1463c0
41 files changed
+4369 -4

No files matched your search

+541
View File
@@ -0,0 +1,541 @@
#!/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/<path:path>")
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/<int:index>")
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())