2026-11-12 00:46:11 +13:00
2026-11-12 00:46:11 +13:00
2025-04-15 10:14:46 +00:00
2026-11-12 00:46:11 +13:00

led-controller

ESP32-S3 controller for LED drivers: W5500 Ethernet, web UI, I2S microphone beat detection and an ESP-NOW link to the drivers. The firmware is C (ESP-IDF) at the repository root; see docs/BENCH_TEST.md for the bench tests.

It keeps profiles, zones, presets, device groups, sequences, palettes, patterns and outputs in its flash, and serves the web UI and JSON API (docs/API.md). Zones play to device groups. Sequences advance on the beats the microphone detects, or on a BPM clock while audio is stopped. Profiles, presets and sequences import and export as JSON bundles.

Build and flash

make build            # minify the web UI from web/, then build the firmware (ESP-IDF in Docker)
make flash            # flash over USB
make ota [HOST=<ip>] # update firmware (web UI included) over Ethernet, no USB (POST /ota); HOST defaults to led-controller.local
make monitor          # serial console
make test             # driver unit tests and the C/Python envelope cross-check
make test-api HOST=<ip>       # HTTP API tests against a running controller (its data is restored afterwards)
make test-browser HOST=<ip>   # Selenium UI tests (needs selenium and chromedriver)

make lists every target. The web UI sources are in web/ (static/, templates/, audio.html); tools/build_web.sh also packs the led-driver pattern files into the firmware, so the controller can send them to drivers.

Other directories

  • led-driver/ (submodule): MicroPython firmware for the ESP32 LED drivers.
  • led-tool/ (submodule): led-cli, configures drivers over serial and updates the controller over Ethernet (led-cli --ota HOST).
  • led-simulator/ (submodule), espnow-sender/: test helpers.
  • db/: the records a controller starts with (the default profile and group the firmware seeds at first boot, plus pattern metadata), importable with PUT /db/<name>.
  • test/api/: the API tests (test/api/README.md); test/browser/: the UI tests.

Docs

  • API reference: docs/API.md
  • User guide: docs/help.md (scripts/build_help_pdf.sh regenerates docs/help.pdf)
  • Specification: docs/SPECIFICATION.md

Network

The controller advertises <hostname>.local over mDNS (default led-controller, plus an _http._tcp service). Both settings below come from /settings and apply on reboot.

static_ips is a list of networks to try, in order, each time the Ethernet link comes up. The first entry whose gateway answers ARP is used; if none does (or the list is empty) the controller uses DHCP. netmask defaults to 255.255.255.0, dns to the gateway.

If DHCP gets no answer within 15 seconds, the controller takes 192.168.4.1/24. For a cable straight from a PC, give the PC a static IP on that subnet, such as 192.168.4.2/24, and open http://192.168.4.1/. The controller tries DHCP again only when the link next comes up.

curl -X PUT http://led-controller.local/settings/settings -H 'Content-Type: application/json' -d '{
  "hostname": "stage",
  "static_ips": [
    {"ip": "192.168.1.50", "netmask": "255.255.255.0", "gw": "192.168.1.1"},
    {"ip": "10.0.0.50",    "netmask": "255.255.255.0", "gw": "10.0.0.1"}
  ]}'
S
Description
No description provided
Readme AGPL-3.0
11 MiB
0 Stars 1 Watchers 0 Forks
Languages
Python 59.2%
JavaScript 29.6%
HTML 6.5%
CSS 3.6%
Shell 0.9%
Other 0.2%