From ef968ebe395ec6d852392e21418b0d81b5550047 Mon Sep 17 00:00:00 2001 From: Jimmy Date: Sat, 21 Mar 2026 23:51:00 +1300 Subject: [PATCH] docs: run/edit mode, profiles behavior, send presets Made-with: Cursor --- README.md | 34 ++++++++++++++++++++++++++++++++-- docs/API.md | 23 ++++++++++++++++++++++- 2 files changed, 54 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4c2ba8f..2f37bc5 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,36 @@ # led-controller -## Run on port 80 without root +LED controller web app for managing profiles, tabs, presets, and color palettes, and sending commands to LED devices over the serial -> ESP-NOW bridge. -Run once: `sudo scripts/setup-port80.sh`. Then start the app with: `pipenv run run`. +## Run + +- One-time setup for port 80 without root: `sudo scripts/setup-port80.sh` +- Start app: `pipenv run run` +- Dev watcher (auto-restart on `src/` changes): `pipenv run dev` + +## UI modes + +- **Run mode**: focused control view. Select tabs/presets and apply profiles. Editing actions are hidden. +- **Edit mode**: management view. Shows Tabs, Presets, Patterns, Color 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 tab content. +- In **Run mode**, Profiles supports apply-only behavior (no create/clone/delete). +- In **Edit mode**, Profiles supports create/clone/delete. +- Creating a profile always creates a populated `default` tab (starter presets). +- Optional **DJ tab** seeding creates: + - `dj` tab bound to device name `dj` + - starter DJ presets (rainbow, single color, transition) + +## Preset colors and palette linking + +- In preset editor, selecting a color picker value auto-adds it when the picker closes. +- Use **From Palette** to add a palette-linked preset color. +- Linked colors are stored as palette references and shown with a `P` badge. +- When profile palette colors change, linked preset colors update across that profile. + +## API docs + +- Main API reference: `docs/API.md` diff --git a/docs/API.md b/docs/API.md index 735b48b..2333779 100644 --- a/docs/API.md +++ b/docs/API.md @@ -11,6 +11,22 @@ All JSON APIs use `Content-Type: application/json` for bodies and responses unle --- +## UI behavior notes + +The main UI has two modes controlled by the mode toggle: + +- **Run mode**: optimized for operation (tab/preset selection and profile apply). +- **Edit mode**: shows editing/management controls (tabs, presets, patterns, color palette, send presets, and profile management actions). + +Profiles are available in both modes, but behavior differs: + +- **Run mode**: profile **apply** only. +- **Edit mode**: profile **create/clone/delete/apply**. + +`POST /presets/send` is wired to the **Send Presets** UI action, which is exposed in Edit mode. + +--- + ## Session and scoping Several routes use **`@with_session`**: the server stores a **current profile** in the session (cookie). Endpoints that scope data to “the current profile” (notably **`/presets`**) only return or mutate presets whose `profile_id` matches that session value. @@ -61,7 +77,7 @@ Below, `` values are string identifiers used by the JSON stores (numeric str | GET | `/profiles` | `{"profiles": {...}, "current_profile_id": ""}`. Ensures a default current profile when possible. | | GET | `/profiles/current` | `{"id": "...", "profile": {...}}` | | GET | `/profiles/` | Single profile. If `` is `current`, same as `/profiles/current`. | -| POST | `/profiles` | Create profile. Body may include `name` and other fields. Returns `{ "": { ... } }` with status 201. | +| POST | `/profiles` | Create profile. Body may include `name` and other fields. Optional `seed_dj_tab` (request-only) seeds a DJ tab + presets. New profiles always get a populated `default` tab. Returns `{ "": { ... } }` with status 201. | | POST | `/profiles//apply` | Sets session current profile to ``. | | POST | `/profiles//clone` | Clone profile (tabs, palettes, presets). Body may include `name`. | | PUT | `/profiles/current` | Update the current profile (from session). | @@ -99,6 +115,11 @@ Scoped to **current profile** in session (see above). Response on success includes `presets_sent`, `messages_sent` (chunking splits payloads so each JSON string stays ≤ 240 bytes). +Stored preset records can include: + +- `colors`: resolved hex colors for editor/display. +- `palette_refs`: optional array of palette indexes parallel to `colors`. If a slot contains an integer index, the color is linked to the current profile palette at that index. + ### Tabs — `/tabs` | Method | Path | Description |