From 35b8a777dfe572e13d10da9b9a05ec53ff0f172b Mon Sep 17 00:00:00 2001 From: Krzysztof Jamroz Date: Sat, 14 Nov 2026 18:01:31 +0100 Subject: [PATCH 01/18] feat(extension): add Waveshare LCD1602 support with REST API for text and brightness control --- docs/api.md | 54 ++- docs/hardware/testing.md | 4 +- docs/settings.md | 6 +- include/pins.h | 8 + .../.openspec.yaml | 2 + .../2026-11-14-lcd1602-extension/design.md | 96 +++++ .../2026-11-14-lcd1602-extension/proposal.md | 37 ++ .../specs/extension-http/spec.md | 46 +++ .../specs/lcd1602/spec.md | 172 +++++++++ .../2026-11-14-lcd1602-extension/tasks.md | 46 +++ openspec/specs/extension-http/spec.md | 45 +++ openspec/specs/lcd1602/spec.md | 171 +++++++++ platformio.ini | 2 +- src/api/commands.cpp | 3 +- src/audio/audio.cpp | 2 +- src/extensions/README.md | 15 + src/extensions/http_registry.cpp | 60 ++++ src/extensions/http_registry.h | 6 + src/extensions/lcd1602/http.cpp | 165 +++++++++ src/extensions/lcd1602/http.h | 9 + src/extensions/lcd1602/hw.cpp | 117 ++++++ src/extensions/lcd1602/hw.h | 10 + src/extensions/lcd1602/lcd1602.cpp | 334 ++++++++++++++++++ src/extensions/lcd1602/lcd1602.h | 40 +++ src/extensions/lcd1602/viewport.h | 36 ++ .../logic.cpp} | 2 +- .../logic.h} | 0 .../{ => push_button}/push_button.cpp | 4 +- .../{ => push_button}/push_button.h | 0 .../{push_button_sfx.h => push_button/sfx.h} | 0 src/http/play_handlers.cpp | 2 +- src/http/routes.cpp | 5 +- src/http/settings_handlers.cpp | 23 +- src/main.cpp | 5 +- src/settings/getters.cpp | 20 ++ src/settings/nvs.cpp | 17 + src/settings/nvs.h | 6 + src/settings/settings.h | 18 + src/settings/validate.cpp | 30 ++ src/settings/values.cpp | 23 +- src/settings/values.h | 5 + .../test_lcd1602_viewport.cpp | 59 ++++ .../test_push_button_logic.cpp | 4 +- .../test_settings_validate.cpp | 28 ++ ui/src/api/types.ts | 5 + ui/src/views/ApiReference.tsx | 36 ++ ui/src/views/Extensions.tsx | 99 +++++- ui/test/robot.tsx | 5 + 48 files changed, 1861 insertions(+), 21 deletions(-) create mode 100644 openspec/changes/archive/2026-11-14-lcd1602-extension/.openspec.yaml create mode 100644 openspec/changes/archive/2026-11-14-lcd1602-extension/design.md create mode 100644 openspec/changes/archive/2026-11-14-lcd1602-extension/proposal.md create mode 100644 openspec/changes/archive/2026-11-14-lcd1602-extension/specs/extension-http/spec.md create mode 100644 openspec/changes/archive/2026-11-14-lcd1602-extension/specs/lcd1602/spec.md create mode 100644 openspec/changes/archive/2026-11-14-lcd1602-extension/tasks.md create mode 100644 openspec/specs/extension-http/spec.md create mode 100644 openspec/specs/lcd1602/spec.md create mode 100644 src/extensions/README.md create mode 100644 src/extensions/http_registry.cpp create mode 100644 src/extensions/http_registry.h create mode 100644 src/extensions/lcd1602/http.cpp create mode 100644 src/extensions/lcd1602/http.h create mode 100644 src/extensions/lcd1602/hw.cpp create mode 100644 src/extensions/lcd1602/hw.h create mode 100644 src/extensions/lcd1602/lcd1602.cpp create mode 100644 src/extensions/lcd1602/lcd1602.h create mode 100644 src/extensions/lcd1602/viewport.h rename src/extensions/{push_button_logic.cpp => push_button/logic.cpp} (98%) rename src/extensions/{push_button_logic.h => push_button/logic.h} (100%) rename src/extensions/{ => push_button}/push_button.cpp (97%) rename src/extensions/{ => push_button}/push_button.h (100%) rename src/extensions/{push_button_sfx.h => push_button/sfx.h} (100%) create mode 100644 test/test_lcd1602_viewport/test_lcd1602_viewport.cpp diff --git a/docs/api.md b/docs/api.md index f0fa8058..7ba3aa9d 100644 --- a/docs/api.md +++ b/docs/api.md @@ -171,6 +171,11 @@ curl http://tiny-engineer.local/settings "serial_log": false, "push_button": false, "push_button_pin": 20, + "lcd1602": false, + "lcd1602_backlight_boot": true, + "lcd1602_boot": "none", + "lcd1602_line1": "", + "lcd1602_line2": "", "continuous_timeout": 5, "loading": "progress", "eyes_style": "classic", @@ -194,6 +199,10 @@ curl http://tiny-engineer.local/settings | `serial_log` | USB serial debug logging (default **false**). When off, diagnostic `Serial` output is suppressed | | `push_button` | Extension-port push-button reader (default **false**). When on, publishes immediate `button.down` / `button.up` plus `button.click` / `button.double_click` / `button.long_click` (see [Outbound events](#outbound-events)). Applies **immediately**. Local reactions use [Actions](#get-settingsactions) | | `push_button_pin` | GPIO on the Extension port for the push-button: **6**, **7**, **20**, or **21** (default **20**). Persists when `push_button` is off. Applies **immediately** when the extension is on | +| `lcd1602` | Waveshare LCD1602 I2C extension (default **false**). When on, serves `/extensions/lcd1602/…`. Applies **immediately**. Emits no events | +| `lcd1602_backlight_boot` | Turn backlight on at enable/boot (default **true**). When false, wait for `POST /extensions/lcd1602/brightness`. Persists when off. Applies **immediately** | +| `lcd1602_boot` | Boot content: `none`, `last`, or `config` (default **`none`**). Persists when off. Applies **immediately** | +| `lcd1602_line1` / `lcd1602_line2` | Configured boot lines when `lcd1602_boot` is `config` (max **64** chars each, default empty). Persists when off. Applies **immediately** | | `continuous_timeout` | Minutes a continuous animation (`typing` / `reading` / `thinking` / `talking`) may run before the firmware switches to `attention` then idle (default **5**) | | `loading` | Boot loading screen: `progress` (bar + large IP for 3 s) or `sleep_inertia` (eyes wake; no bar/IP). Default **`progress`**. Applies on **next reboot** | | `eyes_style` | OLED eyes look: `classic` (procedural rounded eyes), `kaomoji` (animated faces), `cover` (full-half bars for an eye-hole mask), `dots` (12×12 circles), or `kawaii` (round eyes with big moving pupils, a talking mouth, and blush). Default **`classic`**. Applies **immediately**. Classic, cover, and dots sequences are described under [`POST /anim`](#post-anim); kaomoji face mapping is under [Kaomoji eyes](#kaomoji-eyes); cover drawing is under [Cover eyes](#cover-eyes); dots drawing is under [Dots eyes](#dots-eyes); kawaii moods are under [Kawaii eyes](#kawaii-eyes) | @@ -209,7 +218,7 @@ curl http://tiny-engineer.local/settings ### `POST /settings` -Update one or more settings from a JSON object body. Values are written to NVS. `sleep_timeout`, `volume`, `welcome`, `serial_log`, `push_button`, `push_button_pin`, `continuous_timeout`, `eyes_style`, and `access_token` apply immediately; a changed `hostname` or `loading` takes effect on the **next reboot**. WiFi networks are set with [`PUT /settings/wifi`](#put-settingswifi). On-device Actions are set with [`PUT /settings/actions`](#put-settingsactions). Servo ranges (`servo_mins` + `servo_maxs`), RGB LED mapping (`rgb_order`) and OLED rotation (`oled_rotate_180`) are **setup AP only** and apply immediately. Requires Bearer when auth is enabled. +Update one or more settings from a JSON object body. Values are written to NVS. `sleep_timeout`, `volume`, `welcome`, `serial_log`, `push_button`, `push_button_pin`, `lcd1602`, `lcd1602_backlight_boot`, `lcd1602_boot`, `lcd1602_line1`, `lcd1602_line2`, `continuous_timeout`, `eyes_style`, and `access_token` apply immediately; a changed `hostname` or `loading` takes effect on the **next reboot**. WiFi networks are set with [`PUT /settings/wifi`](#put-settingswifi). On-device Actions are set with [`PUT /settings/actions`](#put-settingsactions). Servo ranges (`servo_mins` + `servo_maxs`), RGB LED mapping (`rgb_order`) and OLED rotation (`oled_rotate_180`) are **setup AP only** and apply immediately. Requires Bearer when auth is enabled. ```bash curl -X POST "http://tiny-engineer.local/settings" \ @@ -233,6 +242,11 @@ curl -X POST "http://192.168.4.1/settings" \ "serial_log": false, "push_button": false, "push_button_pin": 20, + "lcd1602": false, + "lcd1602_backlight_boot": true, + "lcd1602_boot": "none", + "lcd1602_line1": "", + "lcd1602_line2": "", "continuous_timeout": 5, "loading": "progress", "eyes_style": "classic", @@ -257,6 +271,10 @@ curl -X POST "http://192.168.4.1/settings" \ | `serial_log` | boolean | USB serial debug logging | | `push_button` | boolean | Extension-port push-button (default **false**) | | `push_button_pin` | integer | Extension-port GPIO **6**, **7**, **20**, or **21** (default **20**); persists when off | +| `lcd1602` | boolean | Waveshare LCD1602 extension (default **false**) | +| `lcd1602_backlight_boot` | boolean | Backlight on enable/boot (default **true**) | +| `lcd1602_boot` | string | `none` / `last` / `config` (default **`none`**) | +| `lcd1602_line1` / `lcd1602_line2` | string | Boot lines for `config` (max **64**) | | `continuous_timeout` | integer | 1–1440 minutes (positive) | | `loading` | string | `progress` or `sleep_inertia` | | `eyes_style` | string | `classic`, `kaomoji`, `cover`, `dots`, or `kawaii` | @@ -352,6 +370,11 @@ curl -X POST "http://tiny-engineer.local/settings/reset" "serial_log": false, "push_button": false, "push_button_pin": 20, + "lcd1602": false, + "lcd1602_backlight_boot": true, + "lcd1602_boot": "none", + "lcd1602_line1": "", + "lcd1602_line2": "", "continuous_timeout": 5, "loading": "progress", "eyes_style": "classic", @@ -538,6 +561,35 @@ Wrong fields return **400**: Save with `POST /settings` `{"oled_rotate_180":true}` (setup AP only). The saved value applies immediately and on the next boot. +### LCD 1602 extension (`/extensions/lcd1602/…`) + +Waveshare LCD1602 I2C (AiP31068 @ `0x3E`, SN3193 backlight @ `0x6B`) on the Extension I2C port. Off until `lcd1602` is true. Same access class as `POST /anim` (`Configured`). When the extension is off → **503** `extension disabled`. When on but the LCD (`0x3E`) does not ACK → text/clear **503** `lcd not found` (settings stay enabled). When the LCD is up but the backlight chip (`0x6B`) does not ACK → brightness **503** `backlight not found`. No outbound events. + +#### `GET` / `POST` / `DELETE /extensions/lcd1602/text` + +`GET` returns the full logical lines (not only the 16-column viewport): + +```json +{ + "line1": { "text": "HELLO", "align": "left" }, + "line2": { "text": "", "align": "left" } +} +``` + +`POST` accepts a partial JSON body. Omitted `line1` / `line2` leave that line unchanged. Each present line object needs `text` (0–64 chars; empty clears the line) and optional `align` (`left` / `right` / `center`, default **`left`**). Lines longer than 16 characters ignore align and marquee LTR. + +```bash +curl -X POST "http://tiny-engineer.local/extensions/lcd1602/text" \ + -H "Content-Type: application/json" \ + -d '{"line1":{"text":"HELLO","align":"center"}}' +``` + +`DELETE` clears both lines and leaves brightness unchanged. + +#### `GET` / `POST /extensions/lcd1602/brightness` + +`GET` → `{"brightness":50}`. `POST` body `{"brightness":0..100}` (0 = backlight off). SN3193 NACK → **503** `backlight not found`. Successful text/clear/brightness updates persist **last** state for `lcd1602_boot=last`. + ### `POST /servos/park` Flash-safe park: stop the current animation, smoothly move every joint to its calibrated mid, persist the pose to NVS, and keep PWM enabled until the next reboot (skips idle limp). No body. Requires Bearer when auth is enabled. Available in setup AP and after provisioning (does not require a chosen connection mode). diff --git a/docs/hardware/testing.md b/docs/hardware/testing.md index 98d8aa16..01cdff97 100644 --- a/docs/hardware/testing.md +++ b/docs/hardware/testing.md @@ -112,7 +112,9 @@ curl -X POST "http://tiny-engineer.local/test/servo" -H "Content-Type: applicati | `GET` | `/health` | Health JSON — full field list in [api.md](../api.md#get-health) | | `GET` / `POST` | `/anim` | Current animation / start one (`name`, optional `interrupt`) — full params in [api.md](../api.md#post-anim) | | `POST` | `/play` | Stream a WAV while `talking` (or `/play/{name}`) runs; answers when the clip ends — full params in [api.md](../api.md#post-play) | -| `GET` | `/settings` | Persistent settings (`sleep_timeout`, `hostname`, `volume`, `welcome`, `serial_log`, `push_button`, `push_button_pin`, `continuous_timeout`, `loading`, `eyes_style`, `access_token_set`, `wifi_configured`, `servo_mins`, `servo_maxs`, `rgb_order`, `oled_rotate_180`, `wifi_networks`) | +| `GET` | `/settings` | Persistent settings (`sleep_timeout`, `hostname`, `volume`, `welcome`, `serial_log`, `push_button`, `push_button_pin`, `lcd1602`, `lcd1602_backlight_boot`, `lcd1602_boot`, `lcd1602_line1`, `lcd1602_line2`, `continuous_timeout`, `loading`, `eyes_style`, `access_token_set`, `wifi_configured`, `servo_mins`, `servo_maxs`, `rgb_order`, `oled_rotate_180`, `wifi_networks`) | +| `GET` / `POST` / `DELETE` | `/extensions/lcd1602/text` | LCD 1602 text (extension off → 503) | +| `GET` / `POST` | `/extensions/lcd1602/brightness` | LCD 1602 backlight 0–100 | | `GET` / `PUT` | `/settings/actions` | On-device Actions list (event patterns → sound / anim) | | `POST` | `/actions/test` | Simulate an event type for Actions (no outbound publish) | | `POST` | `/settings` | Update NVS settings from a JSON object; the reply carries `reboot_required`, true once `hostname`, `loading` or the WiFi networks differ from what the robot booted with. `servo_mins` / `servo_maxs` (integer arrays), `rgb_order` and `oled_rotate_180` (boolean) are setup-AP-only | diff --git a/docs/settings.md b/docs/settings.md index f3aeac4a..31817a30 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -2,9 +2,9 @@ Persistent settings live in NVS (namespace `te`) under [`src/settings/`](../src/settings/). They are exposed on `GET`/`POST /settings`, the Config web UI, and must stay in sync with API docs. -**HTTP / JSON** (`POST /settings` body and `GET /settings` fields — see [api.md](api.md)): `sleep_timeout`, `hostname`, `volume`, `welcome`, `serial_log`, `push_button`, `push_button_pin`, `continuous_timeout`, `loading`, `eyes_style`, `access_token`, `servo_mins` / `servo_maxs`, `rgb_order`, `oled_rotate_180`. WiFi networks have their own endpoint, `PUT /settings/wifi`, and show as `wifi_networks`. On-device Actions use `GET`/`PUT /settings/actions`. +**HTTP / JSON** (`POST /settings` body and `GET /settings` fields — see [api.md](api.md)): `sleep_timeout`, `hostname`, `volume`, `welcome`, `serial_log`, `push_button`, `push_button_pin`, `lcd1602`, `lcd1602_backlight_boot`, `lcd1602_boot`, `lcd1602_line1`, `lcd1602_line2`, `continuous_timeout`, `loading`, `eyes_style`, `access_token`, `servo_mins` / `servo_maxs`, `rgb_order`, `oled_rotate_180`. WiFi networks have their own endpoint, `PUT /settings/wifi`, and show as `wifi_networks`. On-device Actions use `GET`/`PUT /settings/actions`. -**NVS keys** (≤15 chars; defined in [`nvs.h`](../src/settings/nvs.h)): `sleep_m`, `host`, `vol`, `welcome`, `serial_log`, `ext_btn` (`push_button`), `ext_btn_pin` (`push_button_pin`), `cont_to`, `loading`, `eyes_sty`, `access_tok`, `wifi_nets` (blob of up to 5 networks; replaces the older single-network `wifi_ssid` / `wifi_pass`, which are migrated on load), `actions` (Actions blob, up to 16 rows), `sranges`, `rgb_ord`, `oled_rot`. Last commanded servo angles live in the same namespace as key `spose` (internal; not a settings API field). Boot migrates legacy `btn_snd_*` keys into Actions then removes them, and drops leftover `srv_hold`. Add new short keys there — do not reuse HTTP names as NVS keys unless they already fit the length limit. +**NVS keys** (≤15 chars; defined in [`nvs.h`](../src/settings/nvs.h)): `sleep_m`, `host`, `vol`, `welcome`, `serial_log`, `ext_btn` (`push_button`), `ext_btn_pin` (`push_button_pin`), `ext_lcd` (`lcd1602`), `ext_lcd_bl` (`lcd1602_backlight_boot`), `ext_lcd_boot`, `ext_lcd_l1`, `ext_lcd_l2`, `ext_lcd_last` (LCD last-state blob; not a settings API field), `cont_to`, `loading`, `eyes_sty`, `access_tok`, `wifi_nets` (blob of up to 5 networks; replaces the older single-network `wifi_ssid` / `wifi_pass`, which are migrated on load), `actions` (Actions blob, up to 16 rows), `sranges`, `rgb_ord`, `oled_rot`. Last commanded servo angles live in the same namespace as key `spose` (internal; not a settings API field). Boot migrates legacy `btn_snd_*` keys into Actions then removes them, and drops leftover `srv_hold`. Add new short keys there — do not reuse HTTP names as NVS keys unless they already fit the length limit. Follow the same pattern for a new setting. @@ -45,7 +45,7 @@ Call the getter wherever the value affects behavior (e.g. `settingsVolume()` in ### 4. Web UI — [`ui/`](../ui/) 1. Add the field to `Settings` in [`ui/src/api/types.ts`](../ui/src/api/types.ts). -2. Add a control to `ConfigForm` in [`ui/src/config/ConfigForm.tsx`](../ui/src/config/ConfigForm.tsx): read it in `draftFrom()` and send it from `save()`. Use `.range-row` + range/number for 0–N scales (see volume). Exception: extension toggles/pin (`push_button` / `push_button_pin`) live on the Extensions page; event→effect bindings live on the Actions page (`/settings/actions`). +2. Add a control to `ConfigForm` in [`ui/src/config/ConfigForm.tsx`](../ui/src/config/ConfigForm.tsx): read it in `draftFrom()` and send it from `save()`. Use `.range-row` + range/number for 0–N scales (see volume). Exception: extension toggles/fields (`push_button` / `push_button_pin`, `lcd1602` / …) live on the Extensions page; event→effect bindings live on the Actions page (`/settings/actions`). 3. API reference table under POST `/settings` in [`ui/src/views/ApiReference.tsx`](../ui/src/views/ApiReference.tsx): param, type, range. 4. Home Config card blurb if the setting is user-facing. diff --git a/include/pins.h b/include/pins.h index 6842194e..e0546935 100644 --- a/include/pins.h +++ b/include/pins.h @@ -55,3 +55,11 @@ constexpr int SERVO_MAX_US = 2200; constexpr int OLED_WIDTH = 128; constexpr int OLED_HEIGHT = 32; constexpr uint8_t OLED_ADDRESS = 0x3C; + +// ===================================================== +// Waveshare LCD1602 I2C (AiP31068L + SN3193) — LCD 1602 extension +// ===================================================== + +// Wiki lists LCD as 8-bit 0x7C → 7-bit 0x3E. SN3193 uses 0x6B as Wire addr. +constexpr uint8_t LCD1602_ADDRESS = 0x3E; +constexpr uint8_t LCD1602_LED_ADDRESS = 0x6B; diff --git a/openspec/changes/archive/2026-11-14-lcd1602-extension/.openspec.yaml b/openspec/changes/archive/2026-11-14-lcd1602-extension/.openspec.yaml new file mode 100644 index 00000000..be831cee --- /dev/null +++ b/openspec/changes/archive/2026-11-14-lcd1602-extension/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-14 diff --git a/openspec/changes/archive/2026-11-14-lcd1602-extension/design.md b/openspec/changes/archive/2026-11-14-lcd1602-extension/design.md new file mode 100644 index 00000000..356ef84e --- /dev/null +++ b/openspec/changes/archive/2026-11-14-lcd1602-extension/design.md @@ -0,0 +1,96 @@ +# Design + +## Context + +See proposal.md — Why. Today: flat `kRoutes[]` in `src/http/routes.cpp`; push-button files sit flat under `src/extensions/`; temporary `initLcd1602Hello()` lives under `src/display/`. Settings checklist lives in `docs/settings.md`. I2C bus already shared (PCA9685 `0x40`, OLED `0x3C`). Waveshare LCD1602 uses AiP31068L @ `0x3E` + SN3193 @ `0x6B` (fixed). Pin-claims do not apply to LCD (no GPIO). + +## Goals / Non-Goals + +**Goals:** +- Opt-in LCD 1602 extension with Extensions UI + NVS settings + last-state restore +- Reusable `/extensions//…` mount table for future extensions +- Clear **per-extension** firmware tree: `src/extensions//…`; push-button moved into that layout in the same change +- Raw Wire driver (no new PlatformIO lib) for AiP31068 + SN3193 +- Scroll tick from `loop()` when a line is long + +**Non-Goals:** +- Configurable I2C addresses or PCF8574 backpacks +- Outbound events / Actions triggers from LCD +- Multi-LCD or I2C mux +- Per-line brightness or RGB backlight modes beyond single brightness 0–100 +- Moving NVS/settings core out of `src/settings/` into per-extension folders +- Changing push-button runtime behavior (move/includes only) + +## Decisions + +### 1. Extension HTTP registry beside `kRoutes` +Add a small table (e.g. `ExtHttpRoute`: `id`, `suffix`, method, `Access`, `enabled()` predicate, handler) in shared extension infra, registered from `registerHttpRoutes`. Paths become `/extensions/` + id + suffix. Gate: `Refusal::check(Configured)` then if `!enabled()` → **503** `extension disabled`. Extend `isKnownPath` so wrong methods on registered suffixes → **405**. + +**Alternatives:** stuff every path into `kRoutes` (works once, no shared disabled gate); single catch-all `UriBraces("/extensions/{}/{}")` dispatcher (harder 405/table docs). Prefer explicit table rows for docs sync and typed handlers. + +### 2. Keep SPA `GET /extensions` in `kRoutes` +Unchanged shell route. Extension APIs never collide with the page path (they need a second segment). + +### 3. Per-extension module layout +**Rule:** code that exists only for one optional extension lives under `src/extensions//`. Shared extension infrastructure stays at `src/extensions/` root. Stock robot face (OLED/eyes) stays in `src/display/` — LCD is not face firmware. + +``` +src/extensions/ + README.md # layout rule for agents/humans + pin_claims.* # shared GPIO claims + pin_claims_settings.* + http_registry.* # shared /extensions// mount + push_button/ + push_button.h/.cpp # apply / poll + logic.h/.cpp # pure debounce/gestures (native-tested) + sfx.h + lcd1602/ + lcd1602.h/.cpp # apply / poll / logical state / boot + hw.h/.cpp # AiP31068 + SN3193 + http.h/.cpp # REST handlers registered via registry +``` + +- **First:** delete smoke test (`initLcd1602Hello`, `src/display/lcd1602.*`, smoke-only pins). +- **Then:** move push-button into `push_button/` and fix includes + `platformio.ini` native filter + tests. +- **Then:** add `lcd1602/` (hw + runtime + http). Call `lcd1602ApplyFromSettings()` after settings/I2C ready and `lcd1602Poll()` from `loop()`. +- Optional UI: `ui/src/extensions/*Section.tsx` imported by `Extensions.tsx` — same split, not required for v1 if the page stays readable. + +**Alternatives rejected:** LCD hw under `src/display/` (blurs stock display vs optional extension); LCD handlers only under `src/http/` with no extension folder (scatters the feature); leave push-button flat (two layouts forever). + +### 4. Settings / NVS +JSON fields: `lcd1602`, `lcd1602_backlight_boot`, `lcd1602_boot`, `lcd1602_line1`, `lcd1602_line2`. Short NVS keys under 15 chars (e.g. `ext_lcd`, `ext_lcd_bl`, `ext_lcd_boot`, `ext_lcd_l1`, `ext_lcd_l2`). Last state: one `putBytes` blob (two 64-char lines + aligns + brightness) keyed e.g. `ext_lcd_last`. Follow `docs/settings.md` checklist end-to-end. Defaults: enable false, backlight_boot true, boot `none`, lines empty. + +### 5. Logical state vs viewport +RAM holds full strings (≤64) + align + brightness + scroll index per line. GET returns logical strings. Hardware shows 16-col window (aligned pad or marquee slice). Scroll step ~375 ms; ~750 ms pause when wrap returns to 0 (readable). + +### 6. Success vs hardware failure +Validate JSON first. If LCD missing (`0x3E` NACK): **503** on mutating routes that need HW; do not update last blob on failed HW apply. If HW OK: update RAM, write display, save last, **200** with state. GET may return RAM/NVS even when HW absent. + +### 7. Disable behavior +No I2C teardown writes (module may be gone). Stop poll; drop “active” flag. Last blob kept for later `boot=last`. + +### 8. Access +`Configured` for all `/extensions/lcd1602/*` APIs (same as `/anim`). + +### 9. Docs / UI sync +Per `.cursor/rules/sync-api-endpoints.mdc`: `routes` / extension table, `docs/api.md`, `ui/src/views/ApiReference.tsx`, settings tables, hardware testing / README if endpoint list changes. Document `src/extensions/` layout briefly (AGENTS.md or `src/extensions/README.md`). + +## Risks / Trade-offs + +- [Include-path churn for push-button] → Mitigation: mechanical move + `rg` for old paths; native tests must pass before LCD work. +- [SN3193 absent / different backlight] → Mitigation: LCD text still works if AiP31068 ACKs; brightness POST may 503 if LED NACK while LCD OK (document). +- [I2C bus load / slow Wire during scroll] → Mitigation: one short transaction per step; fixed modest period; never block HTTP long. +- [NVS wear from frequent text updates] → Mitigation: write last blob only when logical state actually changes. +- [Extension table vs docs drift] → Mitigation: same sync checklist as `kRoutes`. + +## Migration Plan + +1. Remove smoke-test code first (no HELLO on boot). +2. Move push-button into `src/extensions/push_button/`; fix includes/filters/tests; `pio run` + `pio test -e native`. +3. Land settings + `lcd1602/` + registry; LCD inert until `lcd1602` true. +4. No settings migration (new keys only). +5. Rollback: flash previous firmware; new NVS keys ignored by old builds. + +## Open Questions + +None that block specs/tasks. Scroll pause/step constants may be tuned on hardware during apply without changing the contract (“readable fixed pace”). diff --git a/openspec/changes/archive/2026-11-14-lcd1602-extension/proposal.md b/openspec/changes/archive/2026-11-14-lcd1602-extension/proposal.md new file mode 100644 index 00000000..434bde80 --- /dev/null +++ b/openspec/changes/archive/2026-11-14-lcd1602-extension/proposal.md @@ -0,0 +1,37 @@ +# Proposal + +## Why + +The Waveshare LCD1602 on the I2C extension port only has a temporary boot smoke test. Users need an opt-in extension (like push-button) that can show agent/status text over REST, with a reusable `/extensions//…` HTTP pattern for later extensions. Extension code must live in a clear per-extension tree so push-button and LCD (and future add-ons) do not sprawl across `display/` and flat `extensions/` files. + +## What Changes + +- **Remove** the always-on `initLcd1602Hello()` smoke test (and its files) first, then add a proper **LCD 1602** extension, **off by default**, toggled on the web UI **Extensions** page (immediate apply, no reboot). +- **Restructure** firmware extensions under `src/extensions//` (one folder per extension). Move the existing push-button sources into `src/extensions/push_button/`. Keep shared infra (`pin_claims*`, HTTP registry) at `src/extensions/` root. LCD driver and its HTTP handlers live under `src/extensions/lcd1602/` — not under `src/display/`. +- When enabled: drive Waveshare LCD1602 (AiP31068L @ `0x3E`, SN3193 backlight @ `0x6B` — addresses fixed in firmware). When disabled: perform **no** LCD I2C traffic (module may be unplugged). +- Add boot settings: backlight on start (or wait for API); boot content `none` | `last` | `config` (with configured line strings for `config`). +- Persist **last** display state (both lines + per-line align + brightness) after every successful text/clear/brightness API call; restore when `boot=last`. +- Expose REST under `/extensions/lcd1602/…`: `GET`/`POST` text, `DELETE` text (clear both lines), `GET`/`POST` brightness. Partial JSON text updates; per-line align; empty `text` clears that line; lines longer than 16 characters marquee LTR (`[i..i+16)`, `i++`). +- Introduce a small **extension HTTP route registry** so future extensions mount under `/extensions//…` the same way (access + disabled → 503). +- No events from this extension. No configurable I2C addresses in v1. No PCF8574 / generic HD44780 backpack support. + +No **BREAKING** HTTP route or settings semantics. Push-button behavior unchanged (path/include move only). New LCD settings and routes are additive; LCD defaults off. + +## Capabilities + +### New Capabilities + +- `extension-http`: Shared pattern for mounting extension REST routes under `/extensions//…`, including access checks and the disabled-extension refusal. +- `lcd1602`: Optional Waveshare LCD1602 I2C extension — settings, Extensions UI, boot/last content, text/brightness HTTP API, scroll, and fixed-address driver. + +### Modified Capabilities + +- (none) + +## Impact + +- **Firmware**: remove smoke-test boot HELLO; nest `push_button/` and add `lcd1602/` under `src/extensions/`; update includes + native `build_src_filter` paths; LCD driver + apply/poll + handlers inside `lcd1602/`; NVS settings + last-state blob; shared HTTP registry; `kRoutes` / `isKnownPath` aware of `/extensions//…`. +- **Web UI**: second Extensions section “LCD 1602” (optional split into `ui/src/extensions/` section components); settings types; API reference rows for new routes and settings fields. +- **Docs**: `docs/api.md`, `docs/settings.md`, hardware testing / README summaries if endpoint lists change; note J3 I2C wiring and Waveshare-only module; short note on `src/extensions/` layout. +- **Tests**: native settings validation; update push-button / pin-claims include paths; UI tests as needed. +- **Dependencies**: none new (raw Wire to AiP31068/SN3193). diff --git a/openspec/changes/archive/2026-11-14-lcd1602-extension/specs/extension-http/spec.md b/openspec/changes/archive/2026-11-14-lcd1602-extension/specs/extension-http/spec.md new file mode 100644 index 00000000..54ced537 --- /dev/null +++ b/openspec/changes/archive/2026-11-14-lcd1602-extension/specs/extension-http/spec.md @@ -0,0 +1,46 @@ +# Spec Delta + +## Purpose + +Defines how optional hardware extensions expose REST under `/extensions//…`, including access checks and refusals when an extension is disabled, so later extensions can reuse one mounting pattern. + +## ADDED Requirements + +### Requirement: Extension routes use a shared path prefix +The firmware MUST mount every extension-owned REST route under `/extensions//`, where `` is a stable kebab-case extension identifier. The SPA shell route `GET /extensions` MUST remain the Extensions page and MUST NOT be treated as an extension API route. + +#### Scenario: LCD text path shape +- **WHEN** a client calls the LCD 1602 text resource +- **THEN** the path is under `/extensions/lcd1602/` (not a top-level `/lcd1602` route) + +#### Scenario: SPA Extensions page unchanged +- **WHEN** a browser requests `GET /extensions` +- **THEN** the device serves the web UI shell as today + +### Requirement: Extension API access matches configured control routes +Extension API routes under `/extensions//…` MUST use the same access class as `POST /anim` (`Configured`: token when auth is on, and refused until connection mode is set). + +#### Scenario: Unconfigured connection mode +- **WHEN** connection mode is not yet set and a client calls an extension API route +- **THEN** the device refuses with the same class of refusal used for `POST /anim` + +### Requirement: Disabled extension refuses its API +When the settings toggle for extension `` is false, every API route under `/extensions//…` MUST answer **503** with a clear disabled message and MUST NOT perform that extension’s hardware I/O for the request. + +#### Scenario: Call while LCD extension off +- **WHEN** `lcd1602` is false and a client `POST`s `/extensions/lcd1602/text` +- **THEN** the response is **503** and the device does not talk to the LCD over I2C for that request + +### Requirement: Unknown method on a known extension path is 405 +For a path that belongs to a registered extension API route, an unsupported HTTP method MUST answer **405**. Paths that are not registered MUST answer **404**. + +#### Scenario: Wrong method on text +- **WHEN** a client sends `PUT /extensions/lcd1602/text` +- **THEN** the response is **405** + +### Requirement: Future extensions reuse the same mount table +New extension HTTP surfaces MUST be added by registering routes in the shared extension mount table (same prefix, access, and disabled gate), not by inventing a second top-level REST namespace for extensions. + +#### Scenario: Second extension later +- **WHEN** a later change adds another extension with REST +- **THEN** its routes are mounted under `/extensions//…` using the same registry pattern diff --git a/openspec/changes/archive/2026-11-14-lcd1602-extension/specs/lcd1602/spec.md b/openspec/changes/archive/2026-11-14-lcd1602-extension/specs/lcd1602/spec.md new file mode 100644 index 00000000..7693ee65 --- /dev/null +++ b/openspec/changes/archive/2026-11-14-lcd1602-extension/specs/lcd1602/spec.md @@ -0,0 +1,172 @@ +# Spec Delta + +## Purpose + +Optional Waveshare LCD1602 I2C extension that shows short status text over REST when enabled from the Extensions page, with boot content and brightness control. + +## ADDED Requirements + +### Requirement: LCD 1602 defaults off +The setting `lcd1602` MUST be a boolean on `GET /settings` and `POST /settings`, default **false** when unset, including after factory reset. Saving it MUST apply immediately without reboot. + +#### Scenario: Fresh device +- **WHEN** the device boots with no stored `lcd1602` value +- **THEN** `GET /settings` reports `lcd1602` false and the firmware does not initialize the LCD over I2C + +#### Scenario: Factory reset +- **WHEN** factory reset completes +- **THEN** `lcd1602` is false + +#### Scenario: Enable without reboot +- **WHEN** the client posts `{"lcd1602": true}` +- **THEN** the extension becomes active before the next reboot + +### Requirement: Disabled extension leaves LCD bus idle +When `lcd1602` is false, the firmware MUST NOT probe, initialize, write, or read the LCD or its backlight controller over I2C for this extension, and MUST NOT run LCD scroll ticks. + +#### Scenario: Module unplugged while off +- **WHEN** `lcd1602` is false and no LCD is connected +- **THEN** boot and runtime continue without LCD I2C traffic from this extension + +#### Scenario: Disable stops scroll +- **WHEN** the extension was scrolling and the client posts `{"lcd1602": false}` +- **THEN** scroll ticks stop and further LCD I2C writes for this extension do not run + +### Requirement: Fixed Waveshare I2C addresses +When enabled, the extension MUST use LCD address **0x3E** (AiP31068L) and backlight address **0x6B** (SN3193). Those addresses MUST NOT be settings. The extension MUST target the Waveshare LCD1602 I2C module family, not PCF8574 backpacks. + +#### Scenario: No address settings +- **WHEN** a client posts an unknown field intended as an LCD I2C address +- **THEN** `POST /settings` rejects it as an unknown or invalid field and does not save it + +### Requirement: Backlight on boot setting +The setting `lcd1602_backlight_boot` MUST be a boolean on `GET`/`POST /settings`, default **true** when unset, including after factory reset. It MUST persist when `lcd1602` is false. When the extension enables or boots with the extension on: if true, the firmware MUST turn the backlight on (default brightness unless last/config supplies another); if false, the backlight MUST stay off until a successful brightness API call. + +#### Scenario: Default true +- **WHEN** the device has no stored `lcd1602_backlight_boot` +- **THEN** `GET /settings` reports `lcd1602_backlight_boot` true + +#### Scenario: Wait for API +- **WHEN** `lcd1602` is true, `lcd1602_backlight_boot` is false, and boot content does not require a brightness from last +- **THEN** the backlight remains off until `POST /extensions/lcd1602/brightness` succeeds + +### Requirement: Boot content mode +The setting `lcd1602_boot` MUST be a string on `GET`/`POST /settings` allowing only `none`, `last`, and `config`, default **`none`** when unset, including after factory reset. Invalid values MUST be rejected without saving. The value MUST persist when `lcd1602` is false. On enable/boot with the extension on, the firmware MUST apply that mode. + +#### Scenario: none clears +- **WHEN** `lcd1602_boot` is `none` and the extension becomes active +- **THEN** both lines are cleared (empty) on the display when hardware is present + +#### Scenario: last restores +- **WHEN** `lcd1602_boot` is `last`, a last state is stored, and the extension becomes active with LCD present +- **THEN** the display shows the stored lines, aligns, and brightness + +#### Scenario: config shows settings lines +- **WHEN** `lcd1602_boot` is `config` and the extension becomes active with LCD present +- **THEN** the display shows `lcd1602_line1` and `lcd1602_line2` with default left align unless those strings are empty + +#### Scenario: invalid boot mode +- **WHEN** the client posts `{"lcd1602_boot": "welcome"}` +- **THEN** the device answers **400**, nothing is saved + +### Requirement: Boot config line strings +The settings `lcd1602_line1` and `lcd1602_line2` MUST be strings on `GET`/`POST /settings`, default empty when unset, including after factory reset. Each MUST accept at most **64** characters; longer values MUST be rejected without saving. They MUST persist when `lcd1602` is false and apply when `lcd1602_boot` is `config`. + +#### Scenario: Persist while off +- **WHEN** `lcd1602` is false and the client posts config lines +- **THEN** the values are saved and `GET /settings` returns them + +#### Scenario: Too long rejected +- **WHEN** the client posts a line longer than 64 characters +- **THEN** the device answers **400** and nothing is saved + +### Requirement: Extensions page owns LCD 1602 controls +The Extensions page MUST include an **LCD 1602** section for `lcd1602` and related boot settings. The Config page MUST NOT show these controls. Details and wiring MUST appear only while the draft toggle is on; the section MUST note `/extensions/lcd1602/` HTTP paths and that this extension emits no events. + +#### Scenario: Toggle from Extensions +- **WHEN** the user enables LCD 1602 and saves +- **THEN** the UI posts `lcd1602` true + +#### Scenario: Details hidden when off +- **WHEN** the draft LCD toggle is off +- **THEN** LCD boot/backlight/line controls and LCD wiring are not shown + +#### Scenario: Details shown when on +- **WHEN** the draft LCD toggle is on +- **THEN** the section shows backlight-on-boot, boot-content mode, Waveshare I2C Extension-port wiring, and (when mode is `config`) the two line fields + +#### Scenario: Config omits LCD +- **WHEN** the user opens the Config page +- **THEN** that page has no LCD 1602 controls + +### Requirement: Text API partial update +`POST /extensions/lcd1602/text` MUST accept JSON where omitted `line1`/`line2` leave that line unchanged, present line objects carry required `text` (0–64 chars) and optional `align` (default `left`), empty `text` clears the line, bad input is **400**, and success updates display when present, persists last state, and returns **200** with full text state. + +#### Scenario: Update one line +- **WHEN** only `line1` is posted with `{"text":"HI"}` +- **THEN** line1 becomes `HI` (align left) and line2 is unchanged + +#### Scenario: Clear one line +- **WHEN** the client posts `{"line1":{"text":""}}` +- **THEN** line1 is cleared and line2 is unchanged + +#### Scenario: Align center under 16 +- **WHEN** the client posts `{"line1":{"text":"OK","align":"center"}}` and the text length is ≤16 +- **THEN** the visible line is centered in 16 columns + +### Requirement: Long line marquees LTR +When a line’s `text` length is greater than 16, the firmware MUST ignore `align` for that line and scroll a 16-character window `[i .. i+16)` advancing `i` by one on each step (wrapping), at a fixed readable pace. Lines ≤16 MUST NOT marquee. + +#### Scenario: Long line scrolls +- **WHEN** line1 text has more than 16 characters and the extension is on with LCD present +- **THEN** the visible 16 columns advance through the string in a loop until the line is replaced or cleared + +#### Scenario: Short line static +- **WHEN** line1 text has 16 or fewer characters with align `right` +- **THEN** the line stays static and right-aligned + +### Requirement: GET text returns full logical state +`GET /extensions/lcd1602/text` MUST return JSON with `line1` and `line2` objects each containing `text` and `align` for the current logical content (full string, not only the 16-column viewport). + +#### Scenario: Get after partial post +- **WHEN** the client successfully set both lines then `GET`s `/extensions/lcd1602/text` +- **THEN** the body includes both lines’ full `text` and `align` values + +### Requirement: DELETE text clears both lines +`DELETE /extensions/lcd1602/text` MUST clear both lines, stop marquees, leave brightness unchanged, persist last state, and answer **200** with the cleared text state when the extension is on. + +#### Scenario: Clear both +- **WHEN** the client `DELETE`s `/extensions/lcd1602/text` while the extension is on +- **THEN** both lines are empty and brightness is unchanged + +### Requirement: Brightness API +`GET /extensions/lcd1602/brightness` MUST return JSON `{"brightness": <0-100>}`. `POST /extensions/lcd1602/brightness` MUST accept `{"brightness": <0-100>}`, apply backlight (0 = off), persist last state, and answer **200** with the new value. Out-of-range or bad types MUST answer **400** without changing brightness. + +#### Scenario: Set brightness +- **WHEN** the client posts `{"brightness": 50}` while the extension is on and LCD backlight is reachable +- **THEN** backlight is set near 50% and `GET` reports `50` + +#### Scenario: Invalid brightness +- **WHEN** the client posts `{"brightness": 101}` +- **THEN** the response is **400** and brightness is unchanged + +### Requirement: Missing LCD while enabled +When `lcd1602` is true but the LCD does not ACK at `0x3E`, write/clear/brightness requests that need hardware MUST answer **503** with a not-found style message. `GET` text/brightness MAY return the last known logical state from RAM/NVS. The enabled setting MUST remain true. + +#### Scenario: Write without hardware +- **WHEN** `lcd1602` is true, no device ACKs at `0x3E`, and the client posts text +- **THEN** the response is **503** and `GET /settings` still reports `lcd1602` true + +### Requirement: Last state persistence +After every successful text update, clear, or brightness change, the firmware MUST store last state: both lines’ text and align, plus brightness. Factory reset MUST clear last state to empty lines, align left, and a defined default brightness (implementation default, documented). + +#### Scenario: Boot last after power cycle +- **WHEN** last state was saved, `lcd1602_boot` is `last`, and the device reboots with the extension on and LCD present +- **THEN** the display restores that last text, align, and brightness + +### Requirement: No outbound events +The LCD 1602 extension MUST NOT publish outbound events on WebSocket or serial. + +#### Scenario: Text update silent on event bus +- **WHEN** a successful `POST /extensions/lcd1602/text` completes +- **THEN** no new outbound event is emitted for that update diff --git a/openspec/changes/archive/2026-11-14-lcd1602-extension/tasks.md b/openspec/changes/archive/2026-11-14-lcd1602-extension/tasks.md new file mode 100644 index 00000000..ccf3dda0 --- /dev/null +++ b/openspec/changes/archive/2026-11-14-lcd1602-extension/tasks.md @@ -0,0 +1,46 @@ +# Tasks + +## 1. Remove LCD smoke test + +- [x] 1.1 Delete the temporary LCD test path before building the extension: remove `initLcd1602Hello()` call from `main.cpp`, delete `src/display/lcd1602.cpp` / `src/display/lcd1602.h`, and drop smoke-only LCD address constants from `include/pins.h` if nothing else needs them yet; verify `rg` finds no `initLcd1602Hello` / `LCD1602: HELLO` and `pio run` still succeeds + +## 2. Extension tree layout (incl. push-button) + +- [x] 2.1 Move push-button sources into `src/extensions/push_button/` (`push_button`, `logic`, `sfx`), update all `#include` sites, `platformio.ini` native `build_src_filter`, and native tests; verify `pio test -e native` and `pio run` pass with unchanged push-button behavior +- [x] 2.2 Add `src/extensions/README.md` stating the rule (per-extension code under `src/extensions//`; shared infra at `src/extensions/` root; OLED/eyes stay in `src/display/`) and verify the README matches the on-disk layout after the move +- [x] 2.3 Keep `pin_claims*` at `src/extensions/` root (shared); verify pin-claim native tests still include the correct path + +## 3. Settings foundation + +- [x] 3.1 Add `lcd1602`, `lcd1602_backlight_boot`, `lcd1602_boot`, `lcd1602_line1`, `lcd1602_line2` through the settings checklist (defaults, NVS keys ≤15 chars, validate, getters, patch, GET/POST JSON) and verify `pio test -e native` covers validation (boot enum, line length ≤64, defaults false/true/none/empty) +- [x] 3.2 Add last-state NVS blob load/save (both lines text+align + brightness; factory reset clears to empty/left + documented default brightness) and verify reset + reload round-trip in native or focused firmware unit coverage where practical +- [x] 3.3 Update `docs/settings.md` field/NVS lists for the new keys and verify the listed key names match `nvs.h` + +## 4. LCD driver and extension runtime (`src/extensions/lcd1602/`) + +- [x] 4.1 Add AiP31068/SN3193 `hw` helpers (fixed `0x3E`/`0x6B` in `pins.h` as needed) under `src/extensions/lcd1602/` only — not `src/display/` — and verify `pio run` compiles +- [x] 4.2 Implement `lcd1602ApplyFromSettings` / disable path (no I2C when off; probe+init+boot mode when on) in `src/extensions/lcd1602/` and verify serial log shows skip when off and init/boot behavior when on (or soft 503 path when NACK) +- [x] 4.3 Implement logical state, align ≤16, LTR marquee `i++` with readable fixed step/pause, and `lcd1602Poll` from `loop()`; verify long line scrolls and short aligned lines stay static on hardware or with a deterministic scroll-index unit test +- [x] 4.4 Wire apply on settings save and boot after `Wire.begin`; verify enable/disable via `POST /settings` applies without reboot + +## 5. Extension HTTP registry and LCD API + +- [x] 5.1 Add shared `http_registry` at `src/extensions/` root (`/extensions//`, `Configured` access, disabled → 503, `isKnownPath` for 405), wired from `registerHttpRoutes`; verify a disabled LCD call returns 503 with no I2C side effects +- [x] 5.2 Implement `GET`/`POST`/`DELETE /extensions/lcd1602/text` handlers under `src/extensions/lcd1602/http.*` (partial JSON, empty text clears line, persist last on success, 400 on bad body, 503 if LCD NACK on mutate) and verify with curl or UI-less HTTP checks against the documented examples +- [x] 5.3 Implement `GET`/`POST /extensions/lcd1602/brightness` in the same `lcd1602` http module (0–100, persist last, 400/503 rules) and verify GET mirrors last successful value +- [x] 5.4 Sync `docs/api.md`, `ui/src/views/ApiReference.tsx`, and README / `docs/hardware/testing.md` endpoint summaries for the new routes; verify path/method/param text matches handlers + +## 6. Extensions UI + +- [x] 6.1 Add **LCD 1602** section on Extensions (toggle + backlight boot + boot mode + config lines when relevant + Waveshare I2C wiring hint + API note, no events); optionally extract push-button / LCD into `ui/src/extensions/*Section.tsx`; verify Config page has no LCD controls +- [x] 6.2 Extend `ui` Settings types and tests/fixtures for the new fields; verify `npm run lint --prefix ui` and `npm test --prefix ui` pass + +## 7. Integration check + +- [x] 7.1 Run `pio run` and confirm firmware builds clean after the full change + +## Workflow follow-up + +- Archive the change after review when implementation matches the specs. +- Verify the archived main specs for `extension-http` and `lcd1602` after archive. +- Hardware smoke (LCD on J3 + push-button after move) is manual — outside this task list. diff --git a/openspec/specs/extension-http/spec.md b/openspec/specs/extension-http/spec.md new file mode 100644 index 00000000..2530fbea --- /dev/null +++ b/openspec/specs/extension-http/spec.md @@ -0,0 +1,45 @@ +# extension-http Specification + +## Purpose +Defines how optional hardware extensions expose REST under `/extensions//…`, including access checks and refusals when an extension is disabled, so later extensions can reuse one mounting pattern. + +## Requirements + +### Requirement: Extension routes use a shared path prefix +The firmware MUST mount every extension-owned REST route under `/extensions//`, where `` is a stable kebab-case extension identifier. The SPA shell route `GET /extensions` MUST remain the Extensions page and MUST NOT be treated as an extension API route. + +#### Scenario: LCD text path shape +- **WHEN** a client calls the LCD 1602 text resource +- **THEN** the path is under `/extensions/lcd1602/` (not a top-level `/lcd1602` route) + +#### Scenario: SPA Extensions page unchanged +- **WHEN** a browser requests `GET /extensions` +- **THEN** the device serves the web UI shell as today + +### Requirement: Extension API access matches configured control routes +Extension API routes under `/extensions//…` MUST use the same access class as `POST /anim` (`Configured`: token when auth is on, and refused until connection mode is set). + +#### Scenario: Unconfigured connection mode +- **WHEN** connection mode is not yet set and a client calls an extension API route +- **THEN** the device refuses with the same class of refusal used for `POST /anim` + +### Requirement: Disabled extension refuses its API +When the settings toggle for extension `` is false, every API route under `/extensions//…` MUST answer **503** with a clear disabled message and MUST NOT perform that extension’s hardware I/O for the request. + +#### Scenario: Call while LCD extension off +- **WHEN** `lcd1602` is false and a client `POST`s `/extensions/lcd1602/text` +- **THEN** the response is **503** and the device does not talk to the LCD over I2C for that request + +### Requirement: Unknown method on a known extension path is 405 +For a path that belongs to a registered extension API route, an unsupported HTTP method MUST answer **405**. Paths that are not registered MUST answer **404**. + +#### Scenario: Wrong method on text +- **WHEN** a client sends `PUT /extensions/lcd1602/text` +- **THEN** the response is **405** + +### Requirement: Future extensions reuse the same mount table +New extension HTTP surfaces MUST be added by registering routes in the shared extension mount table (same prefix, access, and disabled gate), not by inventing a second top-level REST namespace for extensions. + +#### Scenario: Second extension later +- **WHEN** a later change adds another extension with REST +- **THEN** its routes are mounted under `/extensions//…` using the same registry pattern diff --git a/openspec/specs/lcd1602/spec.md b/openspec/specs/lcd1602/spec.md new file mode 100644 index 00000000..36a9efac --- /dev/null +++ b/openspec/specs/lcd1602/spec.md @@ -0,0 +1,171 @@ +# lcd1602 Specification + +## Purpose +Optional Waveshare LCD1602 I2C extension that shows short status text over REST when enabled from the Extensions page, with boot content and brightness control. + +## Requirements + +### Requirement: LCD 1602 defaults off +The setting `lcd1602` MUST be a boolean on `GET /settings` and `POST /settings`, default **false** when unset, including after factory reset. Saving it MUST apply immediately without reboot. + +#### Scenario: Fresh device +- **WHEN** the device boots with no stored `lcd1602` value +- **THEN** `GET /settings` reports `lcd1602` false and the firmware does not initialize the LCD over I2C + +#### Scenario: Factory reset +- **WHEN** factory reset completes +- **THEN** `lcd1602` is false + +#### Scenario: Enable without reboot +- **WHEN** the client posts `{"lcd1602": true}` +- **THEN** the extension becomes active before the next reboot + +### Requirement: Disabled extension leaves LCD bus idle +When `lcd1602` is false, the firmware MUST NOT probe, initialize, write, or read the LCD or its backlight controller over I2C for this extension, and MUST NOT run LCD scroll ticks. + +#### Scenario: Module unplugged while off +- **WHEN** `lcd1602` is false and no LCD is connected +- **THEN** boot and runtime continue without LCD I2C traffic from this extension + +#### Scenario: Disable stops scroll +- **WHEN** the extension was scrolling and the client posts `{"lcd1602": false}` +- **THEN** scroll ticks stop and further LCD I2C writes for this extension do not run + +### Requirement: Fixed Waveshare I2C addresses +When enabled, the extension MUST use LCD address **0x3E** (AiP31068L) and backlight address **0x6B** (SN3193). Those addresses MUST NOT be settings. The extension MUST target the Waveshare LCD1602 I2C module family, not PCF8574 backpacks. + +#### Scenario: No address settings +- **WHEN** a client posts an unknown field intended as an LCD I2C address +- **THEN** `POST /settings` rejects it as an unknown or invalid field and does not save it + +### Requirement: Backlight on boot setting +The setting `lcd1602_backlight_boot` MUST be a boolean on `GET`/`POST /settings`, default **true** when unset, including after factory reset. It MUST persist when `lcd1602` is false. When the extension enables or boots with the extension on: if true, the firmware MUST turn the backlight on (default brightness unless last/config supplies another); if false, the backlight MUST stay off until a successful brightness API call. + +#### Scenario: Default true +- **WHEN** the device has no stored `lcd1602_backlight_boot` +- **THEN** `GET /settings` reports `lcd1602_backlight_boot` true + +#### Scenario: Wait for API +- **WHEN** `lcd1602` is true, `lcd1602_backlight_boot` is false, and boot content does not require a brightness from last +- **THEN** the backlight remains off until `POST /extensions/lcd1602/brightness` succeeds + +### Requirement: Boot content mode +The setting `lcd1602_boot` MUST be a string on `GET`/`POST /settings` allowing only `none`, `last`, and `config`, default **`none`** when unset, including after factory reset. Invalid values MUST be rejected without saving. The value MUST persist when `lcd1602` is false. On enable/boot with the extension on, the firmware MUST apply that mode. + +#### Scenario: none clears +- **WHEN** `lcd1602_boot` is `none` and the extension becomes active +- **THEN** both lines are cleared (empty) on the display when hardware is present + +#### Scenario: last restores +- **WHEN** `lcd1602_boot` is `last`, a last state is stored, and the extension becomes active with LCD present +- **THEN** the display shows the stored lines, aligns, and brightness + +#### Scenario: config shows settings lines +- **WHEN** `lcd1602_boot` is `config` and the extension becomes active with LCD present +- **THEN** the display shows `lcd1602_line1` and `lcd1602_line2` with default left align unless those strings are empty + +#### Scenario: invalid boot mode +- **WHEN** the client posts `{"lcd1602_boot": "welcome"}` +- **THEN** the device answers **400**, nothing is saved + +### Requirement: Boot config line strings +The settings `lcd1602_line1` and `lcd1602_line2` MUST be strings on `GET`/`POST /settings`, default empty when unset, including after factory reset. Each MUST accept at most **64** characters; longer values MUST be rejected without saving. They MUST persist when `lcd1602` is false and apply when `lcd1602_boot` is `config`. + +#### Scenario: Persist while off +- **WHEN** `lcd1602` is false and the client posts config lines +- **THEN** the values are saved and `GET /settings` returns them + +#### Scenario: Too long rejected +- **WHEN** the client posts a line longer than 64 characters +- **THEN** the device answers **400** and nothing is saved + +### Requirement: Extensions page owns LCD 1602 controls +The Extensions page MUST include an **LCD 1602** section for `lcd1602` and related boot settings. The Config page MUST NOT show these controls. Details and wiring MUST appear only while the draft toggle is on; the section MUST note `/extensions/lcd1602/` HTTP paths and that this extension emits no events. + +#### Scenario: Toggle from Extensions +- **WHEN** the user enables LCD 1602 and saves +- **THEN** the UI posts `lcd1602` true + +#### Scenario: Details hidden when off +- **WHEN** the draft LCD toggle is off +- **THEN** LCD boot/backlight/line controls and LCD wiring are not shown + +#### Scenario: Details shown when on +- **WHEN** the draft LCD toggle is on +- **THEN** the section shows backlight-on-boot, boot-content mode, Waveshare I2C Extension-port wiring, and (when mode is `config`) the two line fields + +#### Scenario: Config omits LCD +- **WHEN** the user opens the Config page +- **THEN** that page has no LCD 1602 controls + +### Requirement: Text API partial update +`POST /extensions/lcd1602/text` MUST accept JSON where omitted `line1`/`line2` leave that line unchanged, present line objects carry required `text` (0–64 chars) and optional `align` (default `left`), empty `text` clears the line, bad input is **400**, and success updates display when present, persists last state, and returns **200** with full text state. + +#### Scenario: Update one line +- **WHEN** only `line1` is posted with `{"text":"HI"}` +- **THEN** line1 becomes `HI` (align left) and line2 is unchanged + +#### Scenario: Clear one line +- **WHEN** the client posts `{"line1":{"text":""}}` +- **THEN** line1 is cleared and line2 is unchanged + +#### Scenario: Align center under 16 +- **WHEN** the client posts `{"line1":{"text":"OK","align":"center"}}` and the text length is ≤16 +- **THEN** the visible line is centered in 16 columns + +### Requirement: Long line marquees LTR +When a line’s `text` length is greater than 16, the firmware MUST ignore `align` for that line and scroll a 16-character window `[i .. i+16)` advancing `i` by one on each step (wrapping), at a fixed readable pace. Lines ≤16 MUST NOT marquee. + +#### Scenario: Long line scrolls +- **WHEN** line1 text has more than 16 characters and the extension is on with LCD present +- **THEN** the visible 16 columns advance through the string in a loop until the line is replaced or cleared + +#### Scenario: Short line static +- **WHEN** line1 text has 16 or fewer characters with align `right` +- **THEN** the line stays static and right-aligned + +### Requirement: GET text returns full logical state +`GET /extensions/lcd1602/text` MUST return JSON with `line1` and `line2` objects each containing `text` and `align` for the current logical content (full string, not only the 16-column viewport). + +#### Scenario: Get after partial post +- **WHEN** the client successfully set both lines then `GET`s `/extensions/lcd1602/text` +- **THEN** the body includes both lines’ full `text` and `align` values + +### Requirement: DELETE text clears both lines +`DELETE /extensions/lcd1602/text` MUST clear both lines, stop marquees, leave brightness unchanged, persist last state, and answer **200** with the cleared text state when the extension is on. + +#### Scenario: Clear both +- **WHEN** the client `DELETE`s `/extensions/lcd1602/text` while the extension is on +- **THEN** both lines are empty and brightness is unchanged + +### Requirement: Brightness API +`GET /extensions/lcd1602/brightness` MUST return JSON `{"brightness": <0-100>}`. `POST /extensions/lcd1602/brightness` MUST accept `{"brightness": <0-100>}`, apply backlight (0 = off), persist last state, and answer **200** with the new value. Out-of-range or bad types MUST answer **400** without changing brightness. + +#### Scenario: Set brightness +- **WHEN** the client posts `{"brightness": 50}` while the extension is on and LCD backlight is reachable +- **THEN** backlight is set near 50% and `GET` reports `50` + +#### Scenario: Invalid brightness +- **WHEN** the client posts `{"brightness": 101}` +- **THEN** the response is **400** and brightness is unchanged + +### Requirement: Missing LCD while enabled +When `lcd1602` is true but the LCD does not ACK at `0x3E`, write/clear/brightness requests that need hardware MUST answer **503** with a not-found style message. `GET` text/brightness MAY return the last known logical state from RAM/NVS. The enabled setting MUST remain true. + +#### Scenario: Write without hardware +- **WHEN** `lcd1602` is true, no device ACKs at `0x3E`, and the client posts text +- **THEN** the response is **503** and `GET /settings` still reports `lcd1602` true + +### Requirement: Last state persistence +After every successful text update, clear, or brightness change, the firmware MUST store last state: both lines’ text and align, plus brightness. Factory reset MUST clear last state to empty lines, align left, and a defined default brightness (implementation default, documented). + +#### Scenario: Boot last after power cycle +- **WHEN** last state was saved, `lcd1602_boot` is `last`, and the device reboots with the extension on and LCD present +- **THEN** the display restores that last text, align, and brightness + +### Requirement: No outbound events +The LCD 1602 extension MUST NOT publish outbound events on WebSocket or serial. + +#### Scenario: Text update silent on event bus +- **WHEN** a successful `POST /extensions/lcd1602/text` completes +- **THEN** no new outbound event is emitted for that update diff --git a/platformio.ini b/platformio.ini index 728671bc..70e7d48b 100644 --- a/platformio.ini +++ b/platformio.ini @@ -87,7 +87,7 @@ build_src_filter = +