# 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_.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.