Files
led-controller/desktop/README.md
T
jimmyandClaude Opus 5.5 581b751904 feat: browser simulator served by the controller, desktop build, browser bridge
- led-simulator: the rig runs the C++ led-driver as WebAssembly (sim-driver/),
  one single-threaded worker per bar, no cross-origin isolation needed. Rooms
  (one JSON per room) with an on-page editor, and a pattern gallery. The
  Python server, Pyodide boot and ring buffer are removed.
- sim-controller sim_rig.c: serves /sim/ from an embedded pack, the page's
  WebSocket and the rooms/flash API. The desktop build embeds it too.
- bridge.c: a "browser" bridge kind that carries ESP-NOW frames to the page;
  devices announced through it are marked sim.
- UI: Simulator in the Menu, split view with resize and pop-out, swipe
  between controller and rig on phones; SIM/REAL badges in Devices.
- Fades: preset pushes and Wi-Fi driver bodies always carry fade and
  beat_time, so "off" no longer inherits an earlier fade.
- Also the sequences-v2 work in progress: desktop port, bridge firmware,
  serial bridge, Wi-Fi drivers, sequence timeline, audio and API changes.
- led-driver: ESP-NOW link, beat sync, control messages, sim hooks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 19:32:46 +13:00

70 lines
3.5 KiB
Markdown

# led-controller on a desktop
The controller firmware (`main/`) built as a program for Linux: no ESP-IDF, no Docker, no board. The web
UI and API are the same as the board's. ESP-NOW goes through a bridge: the USB bridge board (`bridge/`)
or a UDP bridge such as `led-simulator`.
## Build and run
Needs `cmake`, a C compiler, and `www_dist/www.pack` (`make web` builds it with `node`).
```bash
make desktop # builds build-desktop/led-controller
make desktop-run # the web UI on http://localhost:8080/
make test-desktop # starts the program and runs the API tests against it
```
Or run it directly:
```bash
build-desktop/led-controller --db ./data --port 8080
```
| option | environment | meaning |
| --- | --- | --- |
| `--db DIR` | `LED_CONTROLLER_DB` | the store (default `/db`) |
| `--port N` | `LED_CONTROLLER_HTTP_PORT` | web UI and API port (default 8080) |
`LED_LOG_LEVEL=error|warn|info|debug|verbose` sets how much is logged (default `info`).
## Install as a service (.deb)
```bash
make deb # build-desktop/led-controller_0.1.0_<arch>.deb
sudo apt install ./build-desktop/led-controller_0.1.0_*.deb
```
The package installs `/usr/bin/led-controller`, the `led-cli` command-line tool (`/usr/bin/led-cli`), the LED driver
firmware image (`/usr/share/led-controller/firmware/led_driver.bin`), a systemd unit (`led-controller.service`) that runs it as a
dynamic user with its store in `/var/lib/led-controller`, and `/etc/default/led-controller` for the port. The service starts at install and restarts after a restart from
the web UI. The bridges are kept in the controller's settings, so set them in the web UI under Settings > Network >
Bridges. Change the port in `/etc/default/led-controller`, then `sudo systemctl restart led-controller`. The bridge's serial port is
owned by `dialout`, which the service joins.
`packaging/led-bridge.udev.example` (installed in `/usr/share/doc/led-controller/`) gives the bridge board a
stable name, `/dev/led-bridge`, by its serial number.
## How it is built
`desktop/CMakeLists.txt` compiles the firmware's own sources (`main/`, and the host stand-ins in
`sim-controller/components/sim/`: mic, OTA, littlefs and the timers) with a small port of the ESP-IDF APIs
they use:
- `port/src/freertos.c`: tasks, queues, semaphores, stream buffers and event groups on POSIX threads.
- `port/src/esp_glue.c`: logging, error names, random numbers, the MAC (from the first real network
interface), restart (an exit, for the service manager), and the app description.
- `port/src/desktop_crypto.c`: SHA-1 and base64 for the WebSocket handshake.
- `port/src/www_pack.c`: the web UI pack (`www_dist/www.pack`) embedded in the program.
- `port/include/`: the headers. `sdkconfig.h` is the config the sim's build generated.
Third-party code is vendored in `third_party/`: the HTTP server and `http_parser` from ESP-IDF v6.1, and cJSON.
`tools/vendor.sh` refreshes them (it runs `espressif/idf:v6.1` to copy the httpd sources). Its patch
(`tools/patch_vendor.py`) swaps the handshake's mbedTLS and PSA calls for `desktop_crypto.c`.
## Limits
- ESP-NOW needs the bridge. Without one the program runs, and its ESP-NOW frames go nowhere.
- The Wi-Fi drivers are not discovered automatically: their mDNS discovery is not in the desktop build yet.
- Firmware OTA is not available (the API answers 501, as in the simulator).
- The mic is simulated: beats come from the BPM clock, as in the simulator.