Files
led-controller/docs/help.md
T
jimmyandClaude Sonnet 5.5 f85021d40d feat: Wi-Fi access point with a setting, password and boot button
The controller runs an AP (SSID = hostname, 192.168.5.1) next to ESP-NOW,
on by default. Network settings gain an on/off switch (ap_enabled) and an
optional WPA2 password (ap_password, 8-63 chars; empty is open). A button
on D7 (GPIO44) held at boot forces the AP on.

Wi-Fi now starts before Ethernet, and a missing W5500 no longer aborts the
boot: the web server and mDNS start anyway so the AP stays usable.

Network tuning found while testing over the AP: HTTP backlog 10 and 12 open
sockets (the default 5 dropped the 6th SYN, a 1 s stall on every page load),
larger TCP and Wi-Fi buffers, and IPv6 link-local addresses so mDNS answers
AAAA queries (browsers waited about a second for them).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-10 01:46:05 +13:00

119 lines
7.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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), a **Wi-Fi access point** switch (on by default; network named after the hostname, with an optional WPA2 password, controller at `192.168.5.1`; holding the button on D7 at boot forces it on), 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.