Files
led-controller/led-simulator
jimmyandClaude Haiku 5.5 02440be55d feat: sequence editor undo/redo, collapsible browser, playhead easing
Sequence editor: undo and redo, a collapsible browser with chips, search
over sequences too, name in the header row, Beats/Seconds dropdown, Delete
beside Save. Playhead eases between poll results. Lanes keep their phase
when a step ends late, so they no longer drift. The rig's default room is
two columns of bars facing each other, and the simulator has a read-only
debug hook for the playback checks.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
2026-11-17 00:28:59 +13:00
..

led-simulator

A whole LED rig in the browser, served by led-controller itself. The host build of the controller (sim-controller, and the desktop build) serves the rig at /sim/:

  • Every LED bar is its own led-driver: the real C++ firmware (led-driver/main) built to WebAssembly (../sim-driver/), one module worker per bar. The worker runs what the board's pattern task and ESP-NOW link task run (patterns_frame, espnow_link_poll) from a timer, so there are no threads, no SharedArrayBuffer, and the page works on any address. Only the hardware is replaced: NVS is kept by the controller, ESP-NOW goes through the page, and the WS2812 strip is the canvas.
  • The controller reaches the bars over ESP-NOW, through its browser bridge. The frames it would hand to a USB or network bridge board go to the page over a WebSocket (/sim/ws), and the page delivers them to each bar by MAC. Beats, sequences, groups and the reliable link all run as on hardware.
  • Rooms say where the bars are. One room per JSON file, edited on the page. The bars' places go to the controller's rig layout.
  • /sim/gallery shows every pattern side by side, from the same C++ engine, with each preset field editable.

One program and one port. There is no Python server and no UDP bridge.

Run

From the repository root:

make sim-web     # builds the drivers (Emscripten in Docker), the controller for the host, and runs it

Then open http://localhost:8080/sim/ in Chrome, Edge or Firefox. The controller's own UI is on http://localhost:8080/. Any address works, a phone on the LAN included (http://<computer>:8080/sim/): the drivers need no cross-origin isolation.

The bars register with the controller from their announces when they power on, and the page gives the controller their places from the room. Only one tab runs the rig: opening it in a second tab powers the first one's bars off.

make desktop embeds the rig too (after make sim-wasm). There, add browser to the bridges, under Settings > Network > Bridges or with the page's Add the browser bridge button. make sim-web starts the host build with LED_SIM_BRIDGE=browser. With no bridge configured, browser is the default.

Rooms

The spatial config follows the stage maps of the qlcplus simulator: one file per room, a size in metres, strip types in definitions, and fixtures keyed by id, each placed by position and heading.

{
  "name": "studio",
  "units": "metres",
  "width": 7.0,
  "depth": 5.0,
  "origin": "X=0 at the room centre, +X right; Y=0 at the front edge, +Y up the screen; headings clockwise from +Y",
  "definitions": {
    "bar-119": { "leds": 119, "pitch_m": 0.01667 }
  },
  "fixtures": {
    "sim-01": { "label": "sim-01", "def": "bar-119", "mac": "02:51:4d:00:00:01", "x": -0.1, "y": 2.55, "direction": -90 }
  }
}
  • A fixture is one bar, so one simulated driver. x, y (metres) is pixel 0, the data-in end. The bar runs from there along direction: degrees clockwise from +Y, so 90 runs right and -90 runs left. It is leds × pitch_m long. leds on a fixture overrides its type's count (1–512).
  • mac identifies the driver. Each bar's flash is kept per MAC, so a bar in two rooms (a copied room, say) is the same bar with the same presets. New bars get a MAC no room uses yet.
  • The first run makes the default room: 16 bars × 119 LEDs in 2 columns × 8 rows, pixel 0 at the centre line, sim-01 … sim-16 = 02:51:4d:00:00:01 … …:10. The rig's bridge is 02:51:4d:00:00:00.

Everything is kept in the controller's store folder (LED_SIM_DB; sim-controller/data for make sim-web):

sim/rooms/<name>.json the rooms
sim/flash/<mac>.json each bar's NVS store, {namespace: {key: [type, value]}}
sim/sim.json the active room

On every boot a bar's led.num_leds is set from its room. The first boot also takes its hostname from the fixture's label. Delete sim/flash/ to factory-reset every bar.

On the page, pick the room in the header. Edit room changes it, and every change is saved and sent to the controller's rig layout:

  • Click the floor to add a bar. Drag a bar to move it, which snaps to 5 cm; hold Alt to move it freely.
  • Drag the circle at its far end to turn it, which snaps to 15°; hold Shift to turn it freely. Delete removes the selected bar.
  • The side panel edits a bar's label, type, LED count, position and heading.
  • Size & strip types… sets the room's size and adds or changes strip types.
  • New room… makes an empty room or a copy of the current one. Delete room removes the room's file.

A bar whose LED count changes keeps running with the old count until it is power-cycled, as num_leds is read at boot.

API (on the controller)

GET /sim/api/config the active room, the room list and the bridge state
GET /sim/api/flash/<mac> a bar's NVS store
GET /sim/api/rooms {current, rooms}
POST /sim/api/rooms {name, width, depth, copy_from?} makes a room
GET, PUT, DELETE /sim/api/rooms/<name> one room: read it, replace it (validated), delete it (not the active one)
POST /sim/api/room {name} switches the rig to that room
GET /sim/api/next-mac a MAC no room uses
WS /sim/ws the page's radio: binary dst_mac + packet down, src_mac + packet up; text {"t":"flash"} up

How it fits together

led-controller (host build) ──"browser" bridge──▶ WS /sim/ws ──▶ page ──postMessage──▶ driver worker × N
    rel, beats, sequences   ◀── src_mac+pkt ─────            ◀── tx, px, flash ──    (led_driver.wasm:
    /sim/ page + rooms (sim_rig.c)                                                      sim_tick: link + patterns)
Where What
sim-controller/components/sim/sim_rig.c serves the page and the wasm from www_dist/sim.pack, the page's WebSocket, rooms and flash
main/bridge.c the browser bridge kind next to UDP and serial
tools/build_sim_web.sh packs web/ and web/wasm/ into www_dist/sim.pack. It is empty when the drivers are not built, so make desktop works without Emscripten.
../sim-driver/ the Emscripten build of the driver (led_driver) and the pattern engine for the gallery (led_fx)
web/app.js the room canvas, editor, power control, packet routing by MAC, and placements for POST /devices/layout
web/driver-worker.js loads led_driver.mjs and boots one bar
web/gallery.js one led_fx instance per pattern, each stepped every 10 ms of its own clock

Not simulated: the drivers' Wi-Fi, their own web UI and HTTP API, DDP and USB. Bars do not hear each other's ESP-NOW.

Headless (older)

python3 led-simulator/bridge_sim.py ran each bar as a CPython process with the MicroPython driver (led-driver/src, now removed from led-driver) behind a UDP bridge, so it no longer has drivers to run. Its grid comes from layout in sim.json (layout.py, rig_seed.py).