Jimmy
cfdd6de291
Align API, architecture, and help with devices envelope transport, bridge wifi/serial settings, and MAC-keyed device registry. Fix endpoint tests for envelope identify payloads; remove obsolete p2p.py. Bump led-tool for --serial-usb bridge provisioning. Co-authored-by: Cursor <cursoragent@cursor.com>
47 lines
2.7 KiB
Markdown
47 lines
2.7 KiB
Markdown
# led-controller
|
||
|
||
LED controller web app for managing profiles, **zones**, presets, and colour palettes, and sending commands to LED devices over **ESP-NOW** (peer-to-peer on 2.4 GHz Wi‑Fi radio).
|
||
|
||
- **Bridge ESP32**: routes Pi traffic to drivers. The Pi connects over **WebSocket** (`bridge_transport`: `wifi`, `bridge_ws_url` e.g. `ws://192.168.4.1/ws`) or **USB serial** (`bridge_transport`: `serial`, `bridge_serial_port`).
|
||
- **LED drivers**: announce on boot via ESP-NOW broadcast; the controller registers them (MAC-keyed) and pushes group membership.
|
||
- Optional **Wi-Fi drivers** on the LAN still work over UDP discovery + outbound WebSocket.
|
||
- Architecture (diagrams): [docs/espnow-architecture.md](docs/espnow-architecture.md)
|
||
- Wire format (byte layouts): [docs/espnow-binary-protocol.md](docs/espnow-binary-protocol.md) (≤250 bytes per ESP-NOW frame; Pi ↔ bridge uses JSON devices envelope)
|
||
|
||
## Run
|
||
|
||
- One-time setup for port 80 without root: `sudo scripts/setup-port80.sh`
|
||
- Start app: `pipenv run run` (override listen port with the **`PORT`** environment variable)
|
||
- Dev watcher (auto-restart on `src/` changes): `pipenv run dev`
|
||
- Regenerate **`docs/help.pdf`** from **`docs/help.md`**: `pipenv run help-pdf` (requires **pandoc** and **chromium** on the host)
|
||
|
||
## UI modes
|
||
|
||
- **Run mode**: focused control view. Select zones/presets and apply profiles. Editing actions are hidden.
|
||
- **Edit mode**: management view. Shows **Zones**, Presets, Patterns, Colour Palette, and Send Presets controls, plus per-tile preset edit/remove and drag-reorder.
|
||
|
||
## Profiles
|
||
|
||
- Applying a profile updates session scope and refreshes the active zone content.
|
||
- In **Run mode**, Profiles supports apply-only behaviour (no create/clone/delete).
|
||
- In **Edit mode**, Profiles supports create/clone/delete.
|
||
- Creating a profile always creates a populated `default` zone (starter presets).
|
||
- Optional **DJ zone** seeding creates:
|
||
- `dj` zone bound to device name `dj`
|
||
- starter DJ presets (rainbow, single colour, transition)
|
||
|
||
## Preset colours and palette linking
|
||
|
||
- In preset editor, selecting a colour picker value auto-adds it when the picker closes.
|
||
- Use **From Palette** to add a palette-linked preset colour.
|
||
- Linked colours are stored as palette references and shown with a `P` badge.
|
||
- When profile palette colours change, linked preset colours update across that profile.
|
||
|
||
## API docs
|
||
|
||
- Main API reference: `docs/API.md`
|
||
|
||
## Driver pattern modules
|
||
|
||
Pattern **`.py`** sources live under **`led-driver/src/patterns`**. The Pi app resolves that path via `util.driver_patterns.driver_patterns_dir()`. If you deploy without that tree next to the app, set **`LED_CONTROLLER_PATTERNS_DIR`** to the directory that contains those files.
|