Files
led-controller/desktop
jimmyandClaude Haiku 5.5 f0615dc1b7 feat: users, roles and per-area permissions, production demo image
The controller checks every route against the signed-in user's role, with
levels none, view, control and edit per area. Guests get the permissions
of a built-in guest role. Auth stays off until the first user exists;
LED_ADMIN_USER and LED_ADMIN_PASSWORD create the first admin.

Sessions are cookies, passwords are PBKDF2-SHA256, and logins lock per
username after five failures. The simulator's WebSocket checks the view
permission at handshake and per frame; /ws needs devices control. The web
UI gets a sign-in button, a sign-in prompt on refused changes, and a users
and roles screen.

Also: the device build gets the bridge include path and forward type it
was missing, Dockerfile.sim runs non-root, and Dockerfile.prod with
docker-compose.prod.yml runs the controller on an internal network behind
Caddy for HTTPS.

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

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).

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:

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)

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.