From cd62e571839f9b92876c4ec039b6401b641fe5da Mon Sep 17 00:00:00 2001 From: Matzman Date: Tue, 6 Oct 2026 13:46:08 +0200 Subject: [PATCH] Close iteration 1 and record the requirements of iteration 2 Frame checks 3 and 4 are postponed (no device access). Iteration 2 publishes a dummy sensor instead of a real one (D41) and includes TLS, --desktop-novr and --ha-remove. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 5 +++- docs/PROGRESS.md | 63 +++++++++++++++++++++++++++++++++++++------- docs/REQUIREMENTS.md | 1 + 3 files changed, 58 insertions(+), 11 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 823f6cb..beb1391 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -30,7 +30,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co it reports headset/environment sensors to Home Assistant, offers services Home Assistant can call (e.g. notifications in the headset), and shows a Home Assistant dashboard as a SteamVR dashboard tab. Status: the overlay platform works; the Home Assistant parts are being built -(implementation iteration 1: settings file; the web UI tab was dropped, see REQUIREMENTS.md D40). +(iteration 1, settings file, is done; the web UI tab was dropped, see REQUIREMENTS.md D40; +implementation iteration 2: MQTT and HA device). **Start every session by reading `docs/PROGRESS.md`** (current state, next steps, log). @@ -332,3 +333,5 @@ Check these when testing on the device, and update this list: - The restructured app code (base class `DashboardApplication`, `Surface`, `Overlay` base, active-surface navigation) has only been tested off the device so far. - Several dashboard tabs from one process (works in `tst_surfaces`, not tried in SteamVR). +- Settings errors when started by SteamVR: the app exits and the log names the error (e.g. + missing `device.name`); covered by `tst_config` off the device (iteration 1 checks 3, 4). diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md index 637389b..63816a0 100644 --- a/docs/PROGRESS.md +++ b/docs/PROGRESS.md @@ -5,22 +5,23 @@ CLAUDE.md ("Working rules"). ## Current state -- **Implementation iteration 1, phase 4 (testing on the Frame).** DSH-1 is done with a - negative result: HA's web UI via Qt WebEngine doesn't work on the Frame, so the "HA - Dashboard" tab and the WebEngine dependency were removed (D40). What remains of iteration 1 - (platform hooks, settings file, `--config`, log file for SteamVR-started instances) is being - tested on the Frame with the system-Qt package (3.7 MB). -- **Frame test results so far (2026-10-05):** +- **Iteration 1 closed (2026-10-06); implementation iteration 2, phase 2 (planning and + design).** Requirements of iteration 2 approved (see "Next steps", D41). DSH-1 had a negative result: HA's web UI via Qt WebEngine doesn't work on + the Frame, so the "HA Dashboard" tab and the WebEngine dependency were removed (D40). The + rest of iteration 1 (platform hooks, settings file, `--config`, log file for + SteamVR-started instances) works on the Frame with the system-Qt package (3.7 MB). +- **Frame test results of iteration 1 (2026-10-05):** | # | Check | Result | |---|---|---| | 1 | Started by SteamVR: process runs, log file from the manifest's `--log-file`, settings loaded, rendering with Vulkan (Turnip, Adreno 750) | ✓ | | 2 | In VR: tab "Frame Assistant" visible and usable | ✓ | - | 3 | Settings without `device.name`, `./install.sh` → app exits, log says "Setting 'device.name' is required" | open | - | 4 | Settings restored, `./install.sh` → runs again | open | + | 3 | Settings without `device.name`, `./install.sh` → app exits, log says "Setting 'device.name' is required" | skipped (no device access), postponed | + | 4 | Settings restored, `./install.sh` → runs again | skipped (no device access), postponed | -- **Next session:** checks 3 and 4, then record the results and go to phase 5 (assessment of - iteration 1 with the user). Then iteration 2 (MQTT, HA device, UI-1). + The error itself is covered off the device by `tst_config`. Checks 3 and 4 run in the next + session on the Frame (iteration 2 testing needs it too). +- **Next:** plan and design of iteration 2 (MQTT, HA device with a dummy sensor, UI-1). ## Next steps @@ -34,6 +35,36 @@ Requirements and design cover the whole MVP; it is **implemented in four small i | 3 | OpenVR wrappers and the 13 sensor entities | `--desktop` with optional SteamVR (D22) | sensor values in HA on the Frame | | 4 | notification manager, `notify` entity, world overlay | world overlay, premultiplied flag (D25) | notification from HA in VR, also in a game | +### Requirements of implementation iteration 2: MQTT, HA device, UI-1 + +Approved 2026-10-06. Goal: FrameAssistant connects to the user's broker, appears in HA as a +device that goes online and offline correctly, and the main tab shows the connection status. +No real sensors yet: a **dummy sensor** stands in for them (D41). + +- **Dummy sensor "Uptime":** a `sensor` with the seconds since start, `entity_category: + diagnostic`, updated every 10 s. In the code a generic test entity whose value is set from + outside: the app feeds it a timer, unit tests set values directly. Ships in iteration 2 + builds; iteration 3 decides whether it is removed from HA (component with only `p` once) or + kept as a diagnostic entity. + +| Item | Acceptance criterion | +|---|---| +| CON-1, CFG-3 | Connects without login, with login, and with TLS (self-signed CA); connection state and errors are logged | +| CON-2 | The device with the dummy sensor appears in HA via device-based discovery, without configuration in HA | +| CON-3 | Online while running; normal exit and `kill -9` make it unavailable | +| CON-4 | After a broker restart it reconnects with backoff and republishes discovery and states; also republishes after HA's birth message | +| CON-5 | Two settings files with different device names give two HA devices | +| SEN-14 | The dummy sensor's updates are throttled | +| UI-1 | The main tab shows device name, broker, connected or not, and the last error, and follows a broker stop and start | +| Modes (D22) | Overlay, `--desktop` and the new `--desktop-novr` load the settings and connect; in iteration 2 the two desktop modes behave alike (neither uses SteamVR yet) | +| `--ha-remove` (D32) | Clears all retained topics, after which the device is gone from HA; `uninstall.sh` calls it | +| D35 | libmosquitto is in both packages; `package-release.sh`'s symbol-version check passes | +| Tests (D30) | Unit tests with a fake MQTT client; integration tests against a local mosquitto (connect, last will, reconnect, login, TLS) | +| Manual | CON, UI and `--ha-remove` checks from the PC against the user's HA (possible because nothing needs SteamVR). On the Frame: the package with libmosquitto runs; the postponed checks 3 and 4 of iteration 1 | + +To find out during the iteration: where the Frame keeps its system certificates (default +for `mqtt.tls.ca_file`). + ### Plan for implementation iteration 1: DSH-1 and configuration Goal: a second dashboard tab **"HA Dashboard"** shows HA's web UI at the URL from the @@ -77,6 +108,18 @@ Known limitation: the bundled-Qt package does not support WebEngine in this iter ## Log +### 2026-10-06: iteration 1 closed + +- Frame checks 3 and 4 (settings error when started by SteamVR) skipped: the user had no + access to the device. Postponed to the next session on the Frame; listed in CLAUDE.md + under "Not yet verified on a Steam Frame". +- Phase 5 (assessment) of iteration 1: the user agreed to close it with checks 3 and 4 + postponed and to start iteration 2. +- Requirements of iteration 2 approved (see "Next steps"). User's choices: a dummy sensor + instead of a real one (D41); TLS, `--desktop-novr` and `--ha-remove` in this iteration. + Since nothing in iteration 2 needs SteamVR (`--desktop` doesn't call `VR_Init`), the + MQTT/HA checks run from the PC; the Frame only for the package. + ### 2026-10-05: requirements approved - User approved REQUIREMENTS.md including the priorities (D13). Phase 2 started. diff --git a/docs/REQUIREMENTS.md b/docs/REQUIREMENTS.md index 3557ba7..bffb587 100644 --- a/docs/REQUIREMENTS.md +++ b/docs/REQUIREMENTS.md @@ -164,6 +164,7 @@ FrameAssistant. | D20 | 2026-10-05 | New requirement UI-1 (status display in the main tab), MVP | Helps testing on the device; little effort | | D28 | 2026-10-05 | DSH-1 split: DSH-1 (MVP) = HA web UI in a tab as an out-of-the-box test; DSH-2 (Should) = the full dashboard. The MVP (D8) now also contains DSH-1 | The user wants to see early whether the simple variant works | | D40 | 2026-10-05 | DSH-1 done with a negative result: HA's web UI via Qt WebEngine doesn't work on the Frame (system WebEngine not loadable; bundling our own failed). The "HA Dashboard" tab and the WebEngine dependency are removed; the MVP no longer contains a dashboard. `homeassistant.url` stays reserved for DSH-2 | The out-of-the-box test answered its question; a WebEngine dependency would keep the whole app from starting on the Frame | +| D41 | 2026-10-06 | Implementation iteration 2 publishes a **dummy sensor** ("Uptime", diagnostic) instead of a real one; TLS, `--desktop-novr` and `--ha-remove` are part of iteration 2 | MQTT and HA discovery can be tested without real sensors; the same entity serves the unit tests; without SteamVR the HA checks run from the PC | Design decisions (D16 onward) are in [DESIGN.md](DESIGN.md).