# 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**. ![Schematic: zone buttons on the left; Profiles, Help and Menu on the right.](images/help/header-toolbar.svg) | 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. ![Schematic: zone title, brightness slider, and a row of preset tiles; Edit mode adds an Edit control and drag handles.](images/help/tab-preset-strip.svg) 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). ![Schematic: preset editor with name, pattern, colour swatches (one with a P badge for palette-linked), and action buttons.](images/help/preset-editor.svg) 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. ![Schematic: palette modal with a row of swatches for the current profile.](images/help/colour-palette.svg) --- ## 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. **Driver** in Settings sends a driver its name, LED count, colour order, startup mode, maximum brightness and direction over ESP-NOW, with no cable. **Update code** there sends a driver, or all of them, the led-driver code built into the controller. `led-cli` on a computer edits a driver's whole `settings.json` over USB. ![Schematic: narrow layout with Menu and the same header actions in a dropdown.](images/help/mobile-menu.svg) --- ## 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.