Merge branch 'main' into codex/update-entity-definitions-in-docs/entities.json

Author: baba-dev

docs/AI_Codex_Guide.md

@@ -11,7 +11,8 @@ AI execution rules: this file + docs/AI_GUIDELINES.md (if present)
 0) Mission & Constraints
 Mission
 
-Implement the Home, Rooms, Security, and Control Center screens as per the low-fi wireframes. Produce small, reviewable changes that run smoothly on device.
+Implement the Rooms, CCTV, Weather, Media, and Settings experiences as per the low-fi wireframes.
+Produce small, reviewable changes that run smoothly on device.
 
 Hard Constraints (do not deviate)
 
@@ -33,14 +34,19 @@ Keep interaction animations ≥50 FPS, ambient ≥30 FPS.
   AI_Codex_Guide.md            ← this file (you are here)
   AI_GUIDELINES.md             ← optional extra rules
 
-/ui
-  ui_theme.h                   ← tokens (spacing, colors, radii, motion)
-  ui_components.*              ← shared cards/chips/sliders/toasts
-  ui_home.*                    ← Home screen
-  ui_rooms.*                   ← Rooms screen
-  ui_security.*                ← Security (Frigate) screen
-  ui_control_center.*          ← Control Center sheet
-  ui_debug.*                   ← optional debug overlay (FPS, heap)
+/custom/ui
+  ui_theme.*                   ← tokens (spacing, colors, radii, motion)
+  ui_nav_rail.*                ← navigation rail & gestures
+  ui_root.*                    ← screen container + page routing
+  ui_wallpaper.*               ← shared wallpaper helper
+  pages/
+    ui_page_rooms.*            ← Rooms cards + detail events
+    ui_page_cctv.*             ← CCTV view + event list
+    ui_page_weather.*          ← Local climate metrics
+    ui_page_media.*            ← Media controls & scenes
+    ui_page_settings.*         ← Settings sliders + testers
+    ui_rooms_model.*           ← shared Rooms state helpers
+  widgets/                     ← shared cards/chips/sliders/toasts
 
 /assets
   icons/                       ← 1x assets sized to final use, RGB565
@@ -83,27 +89,37 @@ Do not invent new tokens, colors, or timings. If you need one, add it to docs/wi
 
 Implement exactly these behaviors:
 
-Home
+Rooms (ui_page_rooms.*)
 
-Cards: tap → expand; long-press Quick Action → confirm sheet.
+- Grid of room cards populated from `ui_rooms_model.*`.
+- Tap the toggle on a card to fire `UI_PAGE_ROOMS_EVENT_TOGGLE` with optimistic feedback.
+- Long-press a card body to request the per-room sheet via `UI_PAGE_ROOMS_EVENT_OPEN_SHEET`.
+- Cards surface temperature/humidity badges and availability state.
 
-Status chips: navigate to relevant screen; anomaly colors: accent/warn/alert.
+CCTV (ui_page_cctv.*)
 
-Rooms
+- Primary camera card with Prev/Next controls, quality picker, and mute toggle shell.
+- Live feed placeholder sized per spec; keep toggles hidden on camera/event cards.
+- Event cards list recent clips; tapping should emit an open-clip signal when bindings arrive.
 
-List left, detail right; two-finger swipe changes room.
+Weather (ui_page_weather.*)
 
-Long-press a light → per-entity detail sheet.
+- Living Room card shows indoor temperature, humidity, and HVAC mode metrics.
+- Outdoor card surfaces raw sensor IDs with current readings.
+- Forecast row presents 3 quick-glance day summaries with iconography.
 
-Security
+Media (ui_page_media.*)
 
-Camera carousel + Live tile; event chips open clip/PiP.
+- Now Playing card renders album art, metadata, transport buttons, and a volume slider.
+- Quick Scenes card exposes preset buttons for lighting/media moods.
+- Hide unused default room-card specs/toggles when not applicable.
 
-Alert mode: frame screen in warn/alert, focus automatically.
+Settings (ui_page_settings.*)
 
-Control Center
-
-Swipe-down to open; brightness, volume, toggles; sleep action.
+- Connectivity testers display pill states (Online/Degraded/Offline) per status callbacks.
+- Theme block combines dark-mode switch and theme dropdown; changes propagate via async payloads.
+- Brightness slider updates the numeric pill; action buttons (OTA, diagnostics, logs)
+  forward events.
 
 Global
 
@@ -159,29 +175,42 @@ Fallback chain: HLS → MJPEG → snapshot (UI shows badge).
 
 Skeleton screens (layout only)
 
-Create empty ui_home.*, ui_rooms.*, ui_security.*, ui_control_center.* with layout objects and placeholder components from ui_components.*.
+- Stand up `custom/ui/ui_root.*` with nav rail scaffolding.
+- Create empty `ui_page_rooms.*`, `ui_page_cctv.*`, `ui_page_weather.*`, `ui_page_media.*`,
+  and `ui_page_settings.*` with layout placeholders using shared widgets.
 
-Hook tab navigation & gestures.
+Rooms iteration
 
-Components
+- Build the room card grid with `ui_room_card` widgets and wire toggle/long-press events.
+- Populate cards from `ui_rooms_model.*`; surface climate badges and availability state.
 
-Shared Card, Chip, Slider, Toast, Tabs, Confirm Sheet—styled via ui_theme.h.
+CCTV iteration
 
-Bindings
+- Compose the live camera card with toolbar controls and video placeholder.
+- Lay out event cards for recent clips; stub tap handlers for future bindings.
 
-Wire Home card values to mock data → then swap to MQTT/Frigate bindings.
+Weather iteration
 
-Motion & feedback
+- Add Living Room and Outdoor cards with metric stacks.
+- Render the forecast row with icon + high/low pairs.
+
+Media iteration
 
-Add expand/contract, color pulse, toast confirmations; error states.
+- Flesh out the Now Playing card (album art, metadata, transport controls, volume slider).
+- Add Quick Scenes buttons and make them emit scene selection events.
 
-Control Center
+Settings iteration
+
+- Implement connectivity testers, theme toggle/dropdown, brightness slider, and action buttons.
+- Expose async setters for status/theme/brightness updates.
+
+Motion & feedback
 
-Brightness/volume toggles; sleep action; publish to HA where applicable.
+- Add transitions for card/toolbars, slider feedback, and toast confirmations; cover error states.
 
 Debug & Perf
 
-Hidden overlay; verify FPS/allocations.
+- Hidden overlay; verify FPS/allocations.
 
 Each step should be a small PR (see checklist below).
 
@@ -209,7 +238,14 @@ Each step should be a small PR (see checklist below).
 
 Use a standard preface when asking the AI for changes:
 
-Context: You are working in baba-dev/M5Tab5-UserDemo. Read docs/wireframes.md and docs/AI_Codex_Guide.md. Build only what those files describe. Use LVGL on Tab5 at 1280×720 landscape. Respect tokens in ui_theme.h. Keep changes minimal and isolated: prefer editing ui_home.*, ui_rooms.*, ui_security.*, ui_control_center.*, ui_components.*, or integration/*. Preload RGB565 assets sized to display; no runtime scaling. Use optimistic UI with rollback on timeout. Add a short note on performance and video of the result.
+Context: You are working in baba-dev/M5Tab5-UserDemo.
+Read docs/wireframes.md and docs/AI_Codex_Guide.md.
+Build only what those files describe. Use LVGL on Tab5 at 1280×720 landscape.
+Respect tokens in ui_theme.h. Keep changes minimal and isolated: prefer editing custom/ui/ui_root.*,
+custom/ui/pages/ui_page_*.*, custom/ui/pages/ui_rooms_model.*,
+custom/ui/widgets/*, or integration/*.
+Preload RGB565 assets sized to display; no runtime scaling.
+Use optimistic UI with rollback on timeout. Add a short note on performance and video of the result.
 
 Example task prompts (no code requested here)
 

docs/TASKS.md

@@ -30,64 +30,129 @@ prerequisites, and deliver a focused change.
   - Considerations: update `docs/ARCHITECTURE.md` with the decision.
 - **M0.3 — Mock providers** (status: ☐)
   - Dependencies: M0.1.
-  - Outcome: add mock data sources for Home, Rooms, and Security screens under
-    `custom/integration/` behind a build flag.
-  - Considerations: unblock UI work while MQTT is offline.
+  - Outcome: add mock data sources for Rooms, CCTV, Weather, Media, and
+    Settings pages under `custom/integration/` behind a build flag so each
+    module in `custom/ui/pages/` has sample data.
+  - Considerations: unblock UI work while MQTT is offline and document how to
+    switch between real and mock providers.
 
-### Milestone 1 — UI skeleton
+### Milestone 1 — Page scaffolding
 
-- **M1.1 — Screen scaffolding** (status: ☐)
+- **M1.1 — Rooms page scaffolding** (status: ☑)
   - Dependencies: M0.3.
-  - Outcome: create persistent LVGL objects for `ui_home.*`, `ui_rooms.*`,
-    `ui_security.*`, and `ui_control_center.*` that match the layout spec.
-  - Considerations: reuse placeholder widgets from `custom/ui/ui_components.*`.
-- **M1.2 — Shared components** (status: ☐)
-  - Dependencies: M1.1.
-  - Outcome: implement cards, chips, sliders, tabs, and confirm sheets styled
-    via `ui_theme.h`.
-  - Considerations: centralize styles so future screens stay consistent.
-- **M1.3 — Navigation and gestures** (status: ☐)
+  - Outcome: create persistent LVGL layout for `ui_page_rooms.*`, including the
+    toolbar, wallpaper, and grid of `ui_room_card` widgets managed by
+    `ui_root.c`.
+  - Current state: `ui_page_rooms_create` renders three cards with static
+    descriptors, plays intro animations, and emits toggle/sheet events backed by
+    mock `rooms_state_t` data inside the module.
+  - Considerations: keep card gestures coordinated with
+    `custom/ui/pages/ui_rooms_model.*` when real data arrives.
+- **M1.2 — CCTV page scaffolding** (status: ☑)
+  - Dependencies: M0.3.
+  - Outcome: build the CCTV layout in `ui_page_cctv.*` with toolbar controls,
+    a `ui_room_card` wrapper for the live feed, and an events row prepared for
+    camera history chips.
+  - Current state: the page renders placeholder labels, hides unused toggles,
+    and shows a stub "Live feed" container without switching logic or data.
+  - Considerations: align toolbar button styles with shared assets from
+    `custom/ui/ui_theme.h`.
+- **M1.3 — Weather page scaffolding** (status: ☑)
+  - Dependencies: M0.3.
+  - Outcome: assemble the climate dashboard in `ui_page_weather.*`, featuring
+    indoor/outdoor cards and a flexible forecast row that can accept dynamic
+    metrics.
+  - Current state: static strings populate each metric block and forecast item,
+    and the card toggles/specs are hidden until bindings are available.
+  - Considerations: confirm copy and iconography match `docs/wireframes.md`.
+- **M1.4 — Media page scaffolding** (status: ☑)
+  - Dependencies: M0.3.
+  - Outcome: layout the media experience in `ui_page_media.*`, including now
+    playing metadata, transport controls, quick scenes, and volume slider ready
+    for callbacks.
+  - Current state: album art, track labels, and transport buttons display
+    placeholder content with no LVGL event handlers attached.
+  - Considerations: ensure button spacing matches the reusable metrics from
+    `custom/ui/ui_theme.h`.
+- **M1.5 — Settings page scaffolding** (status: ☑)
+  - Dependencies: M0.3.
+  - Outcome: implement the settings hierarchy in `ui_page_settings.*` with
+    connectivity tests, theme controls, network tools, OTA prompts, and backup
+    actions surfaced through `ui_page_settings_actions_t`.
+  - Current state: the page constructs all sections, exposes setters such as
+    `ui_page_settings_set_connection_status`, and binds actions via
+    `app_launcher/view`, but integration calls still return placeholder states
+    when hardware services are offline.
+  - Considerations: document the action wiring in `docs/ARCHITECTURE.md` when
+    integration matures.
+
+### Milestone 2 — Data plumbing
+
+- **M2.1 — Rooms state pipeline** (status: ☐)
   - Dependencies: M1.1.
-  - Outcome: wire the tab rail, edge swipes, and control center sheet
-    interactions.
-  - Considerations: include optimistic animations for taps and long presses.
-
-### Milestone 2 — Feature scaffolding
-
-- **M2.1 — Home bindings** (status: ☐)
-  - Dependencies: M1.2.
-  - Outcome: connect Home cards to mock providers with optimistic updates ready
-    for MQTT swap.
-  - Considerations: keep command helpers in `custom/integration/`.
-- **M2.2 — Rooms interactions** (status: ☐)
-  - Dependencies: M1.2.
-  - Outcome: implement room detail updates, two-finger swipe navigation, and
-    long-press sheets.
-  - Considerations: validate gestures on hardware for reliability.
-- **M2.3 — Security carousel** (status: ☐)
+  - Outcome: move the static room descriptors and `INITIAL_STATE` out of
+    `ui_page_rooms.c` into a provider so `ui_page_rooms_set_state` consumes data
+    supplied by `custom/integration/`.
+  - Current state: not started; the page seeds its own mock entities and ignores
+    external updates.
+  - Considerations: surface toggle events via a shared bus so integrations can
+    publish commands.
+- **M2.2 — CCTV event model** (status: ☐)
   - Dependencies: M1.2.
-  - Outcome: build the camera carousel and event chips backed by mock Frigate
-    data.
-  - Considerations: respect the HLS → MJPEG → snapshot fallback described in
-    the AI guide.
+  - Outcome: define data structures for camera rotation and timeline chips,
+    exposing setters on `ui_page_cctv.*` so integrations can drive the view.
+  - Current state: not started; toolbar labels and chips are hard-coded.
+  - Considerations: plan for Frigate clip metadata and snapshot fallbacks.
+- **M2.3 — Weather and climate adapter** (status: ☐)
+  - Dependencies: M1.3.
+  - Outcome: add an adapter layer that formats indoor, outdoor, and forecast
+    data for `ui_page_weather.*`, including unit conversions and icon mapping.
+  - Current state: not started; the page renders placeholder Fahrenheit/Celsius
+    values without conversion helpers.
+  - Considerations: reuse formatting helpers across Settings where applicable.
+- **M2.4 — Media control hooks** (status: ☐)
+  - Dependencies: M1.4.
+  - Outcome: attach LVGL callbacks in `ui_page_media.*` that emit play/pause,
+    skip, volume, and quick-scene events to a media controller in
+    `custom/integration/`.
+  - Current state: not started; controls are visual only.
+  - Considerations: coordinate icon/text updates when playback state changes.
+- **M2.5 — Settings telemetry bridge** (status: ☐⚙)
+  - Dependencies: M1.5.
+  - Outcome: finish threading connection test results, OTA progress, and theme
+    persistence through `custom/integration/settings_controller.*` so UI status
+    pills stay in sync.
+  - Current state: partially implemented; `SettingsController` posts events but
+    lacks coverage for every action and has stubbed fallback messages when
+    platform services are unavailable.
+  - Considerations: audit async callbacks to ensure they survive suspend/resume
+    of the worker thread.
 
 ### Milestone 3 — Home Assistant integration
 
-- **M3.1 — MQTT for Home and Rooms** (status: ☐)
-  - Dependencies: M2.1 and M2.2.
-  - Outcome: replace mock providers with real MQTT subscriptions and publish
-    helpers.
-  - Considerations: extend `docs/mqtt_contract.md` with payload schemas.
-- **M3.2 — Frigate live view** (status: ☐)
-  - Dependencies: M2.3.
-  - Outcome: stream live video with fallback handling and update the event
-    timeline from Frigate.
-  - Considerations: measure frame times against `docs/PERFORMANCE.md`.
-- **M3.3 — Control center commands** (status: ☐)
+- **M3.1 — MQTT bindings for Rooms** (status: ☐)
   - Dependencies: M2.1.
-  - Outcome: publish brightness, volume, and toggle commands with rollback
-    timers.
-  - Considerations: log failures for debugging and expose status to the UI.
+  - Outcome: subscribe to room sensor and light topics defined in
+    `docs/mqtt_contract.md`, translate them into `rooms_state_t`, and publish
+    toggle commands emitted by `ui_page_rooms`.
+  - Current state: not started; Rooms still relies on compile-time mocks.
+  - Considerations: debounce slider updates so MQTT traffic stays bounded.
+- **M3.2 — Climate and weather ingestion** (status: ☐)
+  - Dependencies: M2.3.
+  - Outcome: map MQTT sensor payloads to the weather adapter and refresh indoor
+    metrics alongside settings-managed preferences like units and themes.
+  - Current state: not started; all weather values are placeholders.
+  - Considerations: document required topics and units in
+    `docs/mqtt_contract.md`.
+- **M3.3 — Media and Settings integration** (status: ☐)
+  - Dependencies: M2.4 and M2.5.
+  - Outcome: hook media control events into Assist/Home Assistant transports and
+    persist device settings (theme, brightness, updates) through MQTT or REST as
+    defined in `custom/integration/`.
+  - Current state: not started; media commands are local stubs and settings
+    persistence runs on in-memory defaults.
+  - Considerations: record integration quirks in `docs/ARCHITECTURE.md` and
+    expand `docs/mqtt_contract.md` when new topics are introduced.
 
 ### Milestone 4 — Quality and automation