With no DHCP answer in 15 seconds the controller takes 192.168.4.1/24, for a cable straight to a PC with a static IP. /status reports why the board last restarted. First boot also seeds a default group that the default zone plays to. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
119 lines
7.1 KiB
Markdown
119 lines
7.1 KiB
Markdown
# 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](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
|
||
|
||
**Edit mode** is in the header and **Run mode** is in the **Menu** (on narrow screens, both are in the 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. The setup actions are hidden. |
|
||
| **Edit mode** | Full setup from the **Menu**: devices, groups, outputs, sequences, zones, presets, patterns, colour palette, audio and settings, plus per-tile **Edit** on the strip. |
|
||
|
||
On narrow screens, **Menu** also holds the header actions, so it is there in Run mode too.
|
||
|
||
---
|
||
|
||
## 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 `dj` zone.
|
||
- **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 name; **Edit** shows a driver's 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, driver settings (LED count, colour order, power-on pattern) and the groups it is in.
|
||
- **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** on a device, in the group or in the list to add from, blinks just that driver; **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.
|
||
- **Audio** is in the Menu in Edit mode. While it 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). With no DHCP server, as on a cable straight to a PC, the controller is at `192.168.4.1`; give the PC a static IP such as `192.168.4.2`. Network changes apply after a restart. Drivers are configured over USB with `led-cli` on a computer.
|
||
|
||

|
||
|
||
---
|
||
|
||
## Further reading
|
||
|
||
- **[API.md](API.md)**: HTTP routes, the WebSocket `/ws`, and the driver message format.
|
||
- **README**: building, flashing and updating the controller and drivers.
|