Files
led-controller/led-simulator
jimmyandClaude Opus 5.5 698c1463c0 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>
2026-11-16 15:08:49 +13:00
..

led-simulator

A web app that simulates a whole LED rig behind a Wi‑Fi bridge.

  • To led-controller it is a bridge-wifi: a WebSocket on /ws with the same downlink rules (binary wire packets are broadcast; v1 JSON envelopes {"v":"1","dv":{mac: body}} are split per MAC) and the same uplink framing (0x00 + peer MAC + ESP-NOW packet).
  • In the browser, every strip is its own led-driver: a web worker running the real led-driver/src/main.py and led-driver/src/patterns/ in Pyodide, as led-editor runs MicroPython. Only the hardware modules are stubbed (stubs/: machine, neopixel, network, espnow, utime, urandom, ubinascii).

Strips register like hardware: each driver sends its JSON hello once when it powers on, and the bridge forwards it to the controllers connected at that moment. A strip that booted while no controller was connected is not registered until you power-cycle it.

Default rig

16 strips × 119 LEDs in 2 columns × 8 rows. Each strip runs along its row and starts in the middle: pixel 0 is next to the centre line, so left-column strips run right-to-left and right-column strips run left-to-right.

Strip Name MAC
1 … 16 sim-01 … sim-16 02:51:4d:00:00:01 … 02:51:4d:00:00:10
bridge bridge-sim 02:51:4d:00:00:00

Strip 1 is row 1 left, strip 2 row 1 right, and so on (layout.order).

With the simulated controller (no hardware at all)

From the repository root:

make sim-web     # this page at http://localhost:8765/ + led-controller built for the host at :8080
make sim         # the same with headless drivers (bridge_sim.py), for tests
make test-sim    # API and rig tests (groups, field patterns, sequences) against `make sim`

The controller reaches the strips over the UDP bridge on port 8766: each datagram is dst_mac(6) + packet down and src_mac(6) + packet up, exactly the frames it would send over ESP-NOW. A board can use it too: set "bridge": "<this computer>:8766" in its settings and restart it.

Headless

python3 led-simulator/bridge_sim.py [--udp-port 8766] [--port 8765] runs every strip as its own CPython process (sim_driver.py, stubs/_simlink_proc.py) with no browser. GET /api/pixels on its port returns each strip's place and current RGB frame (rgb, hex, pixel 0 first).

Run

From the repository root (Python 3.10+, no extra packages; Microdot comes from led-driver/lib):

python3 led-simulator/server.py          # --port 8765 --host 0.0.0.0 --debug
  1. Open http://localhost:8765/ in Chrome, Edge or Firefox on the same computer. Drivers need SharedArrayBuffer, which browsers only allow on a cross-origin isolated page in a secure context: localhost or HTTPS, not a plain http://192.168.… address.
  2. In led-controller add a bridge: transport ip, address 127.0.0.1 (controller on this computer) or this computer's LAN address, port 8765.
  3. Power the strips on (or power-cycle them) once the controller is connected, so their hellos reach it.

The first boot downloads Pyodide (~10 MB) from the CDN; after that the browser caches it. Strips boot four at a time (drivers.boot_concurrency).

Only one tab runs the rig: opening the page in a second tab powers the first one's strips off.

Page

  • Power on all / Power cycle all / Power off all, and Power on when opened.
  • Click a strip for its details: state, MAC, packets received and sent, power on / reset / off, and its serial output (what the board would print over USB).
  • The dot at each strip's start end shows its state: grey off, amber booting, green running, red stopped (see its serial log for the traceback).

Configuration

workspace/sim.json overrides sim.default.json (keep only the keys you change):

{
  "bridge": { "name": "bridge-sim", "host": "0.0.0.0", "ws_port": 8765, "wifi_channel": 5, "debug": false },
  "layout": { "rows": 8, "columns": 2, "leds_per_strip": 119, "order": "row", "start": "center" },
  "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/"
}
  • layout.order: row (1 = row 1 left, 2 = row 1 right, …) or column (1–8 down the left column, 9–16 down the right).
  • layout.start: center (pixel 0 next to the middle), left, or right.
  • drivers.name: format for new strips; {n}, {row}, {col}, {side} (left/right). A name the controller sets is kept.
  • drivers.fps: how often each strip sends its pixels to the page.
  • drivers.loop_sleep_ms: sleep per driver main-loop pass (in the WDT.feed() stub) so 16 drivers do not pin the CPU.
  • pyodide_url: point at a local copy of Pyodide (full distribution folder, trailing /) to run offline.

Simulated flash

Each strip keeps settings.json and presets.json in workspace/drivers/NN/ on the server: created from settings.default.json on first boot, then saved whenever the driver writes them. num_leds always follows the layout. Delete workspace/drivers/ to factory-reset every strip.

Driver code and patterns are always the current led-driver/src, loaded fresh on every boot. Patterns the controller pushes by OTA live only until that strip powers off.

How it fits together

led-controller ──ws /ws──▶ server.py (bridge rules) ──ws /sim──▶ page ──SharedArrayBuffer──▶ worker × 16
               ◀── 0x00+mac+pkt ──                ◀── mac+pkt ──      ◀──── postMessage ────  (Pyodide, main.py)
  • server.py – HTTP + both WebSockets, bridge downlink rules, flash files.
  • web/app.js – rig canvas, power control, packet routing by MAC.
  • web/driver-worker.js – loads Pyodide, writes the strip's flash, runs web/driver_boot.py.
  • web/ring.js – the SharedArrayBuffer queue that delivers packets to a driver while main.py runs (it never yields to the JavaScript event loop).
  • stubs/_simlink.py – the driver side of that link (radio, pixels, flash, sleeps).

Notes

  • machine.reset() in a driver reboots that strip.
  • The ping reply that led-driver sends from a thread runs from the main loop after the same 50–500 ms delay (Pyodide has no threads).
  • Strips do not hear each other's ESP-NOW broadcasts; the bridge forwards driver transmissions to the controller only.