API.md now documents what the firmware serves: groups, combined brightness, beat-driven sequences, import/export, /api/audio, patterns over ESP-NOW, outputs, /ws, driver OTA, and how API calls become driver messages and group commands. The user guide follows the current UI; the in-app audio help describes the microphone instead of input devices. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
6.7 KiB
LED controller — user guide
This page describes the web UI served by the controller (an ESP32-S3 on Ethernet). It covers profiles, zones, presets, device groups, sequences and audio. The controller reaches the LED drivers over ESP-NOW itself, so there is no bridge to set up.
For HTTP routes and the driver message format, see API.md. For building and flashing, see the project README.
Figures below are schematic (layout and ideas), not pixel-perfect screenshots.
Run mode and Edit mode
The header has a mode toggle (desktop and mobile menu). The label on the button is the mode you switch to.
| Mode | Purpose |
|---|---|
| Run mode | Day-to-day control: choose a zone, tap presets, apply profiles. Management buttons are hidden. |
| Edit mode | Full setup: devices, groups, zones, presets, sequences, outputs, patterns, colour palette and settings, plus per-tile Edit on the strip. |
On narrow screens, Menu reaches the same actions as the desktop header.
Zones
- Select a zone: click its button in the top bar. The main area shows the zone's preset strip.
- Zones (Edit mode): create and manage zones. A zone lists device groups, presets and sequences; presets and sequences can share a zone. Right-click a zone button for its settings.
- A zone plays to its device groups. Zones made before groups list drivers by name instead, and still work.
- Brightness slider: sets the brightness for the current zone. Each driver gets one value: global × its groups × the device × the zone.
- Search: the Devices, Zones and Presets lists have a search box that hides rows that do not match as you type.
Click the coloured part of a preset tile to select that preset on every driver in the zone. In Edit mode, drag tiles to reorder them, and use Edit and Remove on each tile.
Presets
The Presets button (Edit mode) opens the profile's presets: Add, Edit, Send, Delete, plus Import and Export (a preset as a JSON file).
The preset editor:
- Pattern and its n1–n8 parameters, colours, background, brightness and delay.
- Manual presets step once per beat instead of running freely.
- From Palette inserts a colour linked to the profile's palette (badge P). It follows the palette when the palette changes.
- Try previews on the current zone without saving on the drivers.
- Save stores the preset on the controller; Send pushes it to the drivers with save.
- Remove from zone (when opened from a zone) removes it from that zone only.
Profiles
- Apply makes a profile current. Zones, presets and sequences you see belong to it.
- Create (Edit mode) gives a new profile a palette and a default zone with starter presets. Optionally tick DJ zone for a starter
djzone. - Clone copies a profile with its own zones, presets and palette. Delete removes it with its presets and sequences.
- Export saves a profile with its zones, presets, sequences and palette as a JSON file. Import loads one as a new profile and applies it.
Devices and groups
- Devices (Edit mode) lists the LED drivers by MAC. Drivers appear by themselves when they boot or answer a ping; you can also add them by hand.
- Ping drivers checks which drivers answer (green dot with the round-trip time) and adds new ones.
- Identify blinks a driver red for two seconds.
- Update groups sends every driver its group membership.
- Edit a device for its name, brightness and driver settings (LED count, colour order, power-on pattern).
- Groups (Edit mode): put drivers in a group, set the group's brightness and driver defaults once, then attach the group to zones and sequence lanes.
- Groups are shared by every profile unless you tick this profile only.
- Identify devices in group blinks all members together.
Sequences
Sequences (Edit mode) are shows of presets in one or more lanes. Each lane plays to its own device group.
- Steps. A step is a preset and a number of beats. When a step's beats have passed, the lane moves to its next step. A sequence loops unless you turn looping off.
- Playing. Attach a sequence to a zone in the zone editor, then play it from the zone. One sequence plays at a time. Stopping a sequence clears its presets from the zone's drivers.
- Switching. Starting another sequence waits for the next beat, or the next downbeat when the header toggle says Downbeat and the microphone is timing.
- Syncing. Press S (or the BPM button) on a downbeat to line the sequence up with the music.
Audio
- The controller listens through its microphone and detects the tempo and the bar.
- While Audio is started, the microphone's beats time sequences and go to the drivers, so manual presets step on the music.
- While it is stopped, a clock at the simulated BPM does both instead.
- Reset detector forgets a stuck tempo. The /audio page has a full readout, a tap for beat 1 and a live listen.
Patterns, outputs and palette
- Patterns (Edit mode) lists the patterns and their typical delays. Send pushes a pattern file to the drivers over ESP-NOW; they reset to load it. Create pattern uploads your own pattern file.
- Outputs (Edit mode) lists network pixel fixtures (DDP, Art-Net, sACN). Test flashes red, green, blue and white, then black. Zones do not drive outputs on this controller.
- Colour Palette (Edit mode) edits the current profile's swatches. Preset colours linked with From Palette update with it.
Settings
Settings (Edit mode) holds the controller's name, the ESP-NOW channel (for reference: the controller's channel is set at build time), its mDNS hostname and the static IPs it tries on the Ethernet link (DHCP when none answers). Network changes apply after a restart. Drivers are configured over USB with led-cli on a computer.
Further reading
- API.md: HTTP routes, the WebSocket
/ws, and the driver message format. - README: building, flashing and updating the controller and drivers.