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:
1 parent
4fc3345fc9
commit
4d8aeb5df8
26 files changed
+3907
-288
No files matched your search
@@ -1,48 +1,134 @@
|
||||
# led-simulator
|
||||
|
||||
Graphical **NeoPixel** simulator for host Python. It uses the same layout as device flash:
|
||||
A web app that simulates a whole LED rig behind a **Wi‑Fi bridge**.
|
||||
|
||||
- **`led-driver/src`** → flash root **`/`** (application modules, `patterns/`, `presets.json`, …)
|
||||
- **`led-driver/lib`** → **`/lib`** (Microdot, utemplate, …)
|
||||
- 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](https://pyodide.org),
|
||||
as [led-editor](https://git.technical.kiwi/technicalkiwi/led-editor) runs MicroPython. Only the
|
||||
hardware modules are stubbed (`stubs/`: `machine`, `neopixel`, `network`, `espnow`, `utime`,
|
||||
`urandom`, `ubinascii`).
|
||||
|
||||
It runs the **whole application**: **`led-driver/src/main.py`** as **`__main__`** (`runpy.run_path(..., run_name="__main__")` → `asyncio.run(main(port=…))`). Startup matches the device — **`Settings`**, **`presets.load`**, **default preset** from settings, **`patterns/`**, **Microdot** **`/ws`**, **`presets_loop`**, **UDP hello**. Only **`machine`**, **`neopixel`**, **`network`**, **`utime`**, and **`ubinascii`** are stubbed (`stubs/`).
|
||||
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.
|
||||
|
||||
The GUI sets **`LED_SIM_ROOT`** so **`main.py`** can register the Microdot app for **Stop**, and **`LED_SIM_PORT`** for the HTTP/WebSocket listen port (default **80** on device when unset). On the ESP32 those variables are unset.
|
||||
## Default rig
|
||||
|
||||
## Requirements
|
||||
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.
|
||||
|
||||
- Python 3.10+
|
||||
- Tk (e.g. `python3-tk` on Debian/Ubuntu if the window fails to open)
|
||||
| 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` |
|
||||
|
||||
## Run
|
||||
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:
|
||||
|
||||
```bash
|
||||
pipenv install # optional; Microdot is vendored under led-driver/lib
|
||||
python3 led-simulator/gui_main.py
|
||||
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`
|
||||
```
|
||||
|
||||
## UI
|
||||
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.
|
||||
|
||||
- **Start** / **Stop**: start or stop the full **`main.py`** process (same code path as the chip).
|
||||
- **HTTP / WS port**: Microdot listen port; WebSocket URL **`ws://127.0.0.1:<port>/ws`** (JSON **v1**).
|
||||
### Headless
|
||||
|
||||
Configure the app like on flash: **`workspace/settings.json`** (patched as device settings path), **`presets.json`** and **`patterns/`** under **`led-simulator/workspace/`** when the simulator creates symlinks from **`src/`**, or edit files directly under **`led-driver/src/`** if you use a real **`patterns/`** directory there.
|
||||
`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).
|
||||
|
||||
Example pattern modules: **`led-simulator/examples/`** (`Blink`, `Chase`). Copy into **`patterns/`** as on the device.
|
||||
## Run
|
||||
|
||||
From the repository root (Python 3.10+, no extra packages; Microdot comes from `led-driver/lib`):
|
||||
|
||||
```bash
|
||||
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):
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
- Changing the port spinbox only takes effect on the next **Start**.
|
||||
- If **`led-driver/src/patterns`** already exists as a normal directory, the simulator leaves it in place.
|
||||
|
||||
## Shell (no GUI)
|
||||
|
||||
```bash
|
||||
cd led-driver/src
|
||||
PYTHONPATH="../lib:../../led-simulator/stubs" LED_SIM_ROOT="../../led-simulator" LED_SIM_PORT=8765 \
|
||||
python3 main.py
|
||||
```
|
||||
|
||||
(Adjust paths from your checkout root; **`LED_SIM_ROOT`** must point at **`led-simulator/`** so **Stop**-style hooks work if you use them.)
|
||||
- `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.
|
||||
Reference in new issue
Block a user