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