matzmanandClaude Opus 5.5
c5c176644a
DSH-1 ended with a negative result: the Frame's system WebEngine can't be loaded, and bundling our own failed (no sandbox, ICU resources, Vulkan abort, empty page). Reverts the tab (60deb43), the container packages (0676998) and the bundler's WebEngine support (b823ff3,e2cfa8e), and updates the docs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
177 lines
11 KiB
Markdown
177 lines
11 KiB
Markdown
# Progress
|
||
|
||
Where the project stands, and what happened in each session. Newest first. The process is in
|
||
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) still
|
||
needs its test on the Frame with the system-Qt package.
|
||
|
||
## Next steps
|
||
|
||
Requirements and design cover the whole MVP; it is **implemented in four small iterations**
|
||
(D37), each with implementation, testing and assessment:
|
||
|
||
| Iteration | Content | Platform change | Checked by |
|
||
|---|---|---|---|
|
||
| 1 | ~~DSH-1: HA web UI in a dashboard tab~~ (failed, removed: D40); configuration (D34) with start-up hook and `--config`; log file for SteamVR-started instances | start-up hook (D21), app command-line options (D38) | DSH-1 result documented; app starts on the Frame with the settings file, settings errors in the log |
|
||
| 2 | MQTT client (own thread), HA device with discovery and availability, libmosquitto in the package, status display UI-1 | modes (D22) | device appears in HA, online/offline right, reconnect works |
|
||
| 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 |
|
||
|
||
### 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
|
||
configuration; what works out of the box is tested and documented. The main tab stays
|
||
"Frame Assistant".
|
||
|
||
Platform (`vrdashboard_core`):
|
||
1. Start-up hook `prepare()` (D21).
|
||
2. App-specific command-line options (D38): the base constructor takes an optional list of
|
||
extra `QCommandLineOption`s, adds them to parsing and `--help`, and exposes their values.
|
||
|
||
App:
|
||
3. `QtWebEngineQuick::initialize()` in `main.cpp` before the app object (D39); no platform
|
||
change.
|
||
4. Configuration (`src/config/`): immutable value plus `load(path, &error)`, complete per D34;
|
||
path from `--config`, else `$XDG_CONFIG_HOME` or `~/.config/frameassistant/config.json`;
|
||
loaded in `Dashboard::prepare()` (overlay and desktop modes).
|
||
5. HA web UI (`src/ha/HaWebUi`, D18): holds the URL (injected), exposed to QML as a singleton
|
||
owned by `Dashboard`; a named, persistent WebEngine profile under
|
||
`~/.local/share/frameassistant/` so the HA login survives restarts (D39).
|
||
6. New surface `dashboard` ("HA Dashboard"), QML root `HaDashboard.qml` with a `WebEngineView`;
|
||
without a URL it shows a hint.
|
||
7. Build: `find_package(Qt6 … WebEngineQuick)`; `qt6-webengine-dev` (native and `:arm64`) in
|
||
the containers; a new static library for app logic (configuration, HaWebUi) that tests link.
|
||
|
||
Tests (D30):
|
||
8. `tst_config`: valid file, missing required fields, invalid JSON, wrong types, defaults,
|
||
derived and explicit `ha_unique_id`, unknown keys, `--config`.
|
||
9. Platform: `tst_surfaces` extended for `prepare()` (success/abort) and extra options.
|
||
10. Manual, results documented: host `--desktop`; Frame desktop mode over RDP; Frame in VR with
|
||
Vulkan and OpenGL: page loads, laser click, scrolling, SteamVR keyboard in the page's input
|
||
fields, login kept after restart; CPU/GPU while the tab is open.
|
||
11. `clang-format` clean, `ctest` green; `container-test.sh` only if Vulkan code is touched.
|
||
|
||
Docs:
|
||
12. README (configuration file, `--config`, new tab), ARCHITECTURE.md and CLAUDE.md (new hook,
|
||
app options), THIRD_PARTY_NOTICES (Qt WebEngine from the system), STEAM-FRAME.md (results),
|
||
PROGRESS.md.
|
||
|
||
Known limitation: the bundled-Qt package does not support WebEngine in this iteration.
|
||
|
||
## Log
|
||
|
||
### 2026-10-05: requirements approved
|
||
|
||
- User approved REQUIREMENTS.md including the priorities (D13). Phase 2 started.
|
||
- Q4 decided: libmosquitto, shipped in the package (D14). Qt MQTT ruled out: private Qt API
|
||
requires the exact Qt version. Checked on the Frame: no MQTT library installed; libssl/
|
||
libcrypto 3 and libcjson 1 present.
|
||
- HA discovery: own small layer on QJson, device-based discovery (D15); hacpp and the
|
||
embedded libraries rejected.
|
||
- Checked on the Frame which Qt modules, plugins and audio/network tools exist; library list
|
||
per requirement in REQUIREMENTS.md Appendix C. Notable: Qt WebEngine and Qt WebSockets are
|
||
present (relevant for Q2/Q3).
|
||
- libmosquitto ABI check: Debian's 2.0.21 needs at most `OPENSSL_3.0.0`/`GLIBC_2.34`; the
|
||
Frame has OpenSSL 3.2.1 and glibc 2.39. No libcjson dependency. D14 holds.
|
||
- DSH-1 closed (D40): the bundling experiment failed (sandbox, ICU resources, Vulkan abort,
|
||
empty page with OpenGL and in a desktop window; details in STEAM-FRAME.md). At the user's
|
||
decision the "HA Dashboard" tab, `HaWebUi`, the WebEngine build dependency and the
|
||
bundler's WebEngine support were removed (reverts of the corresponding commits). Qt WebView
|
||
is no alternative (WebEngine backend on Linux). `homeassistant.url` stays reserved for
|
||
DSH-2, where a native dashboard is the candidate.
|
||
- Phase 4 (testing on the Frame), first findings:
|
||
- `deploy-to-frame.sh` exited silently without a bundled package in `dist/` (fixed).
|
||
- The system-Qt package doesn't start: the Frame's Qt WebEngine is 6.7.0 (rest of Qt 6.8.0)
|
||
and built against FFmpeg 6, which the Frame lacks (STEAM-FRAME.md). DSH-1's out-of-the-box
|
||
variant therefore fails on the Frame; and since the app links WebEngine, the whole app
|
||
fails.
|
||
- At the user's request, experiment B: the bundled package now ships Qt WebEngine (Debian
|
||
6.8.2, own FFmpeg inside) with its helper process and resources: 141 MB archive, 352 MB
|
||
unpacked. Needs `GLIBC_2.38` and `GLIBCXX_3.4.32` from the Frame. Test pending.
|
||
- Other options noted: load WebEngine only at runtime so the app survives without it; a
|
||
native dashboard (DSH-2, Q2b). Qt WebView is no alternative (on Linux its backend is
|
||
WebEngine; native views are separate windows, not rendered into the texture).
|
||
- Phase 3 of implementation iteration 1:
|
||
- Platform: `prepare()` hook and app-specific command-line options, tested in
|
||
`tst_surfaces` (incl. `surfaces_prepare_fail`).
|
||
- Settings file (`src/config/`, new library `frameassistant_lib`), `--config`; `tst_config`
|
||
(37 cases). `config.example.json` in the package; README.txt explains the set-up.
|
||
- "HA Dashboard" tab: `WebEngineView`, `HaWebUi` with a persistent profile, WebEngine
|
||
initialisation in `main()`. Host: desktop mode loads a local test page, profile data
|
||
lands in `~/.local/share/frameassistant/webengine`; snapshot renders both tabs.
|
||
- Build containers with Qt WebEngine. Cross build: the aarch64 binary needs no private Qt
|
||
symbols, at most `Qt_6.8` and `GLIBC_2.34`. Container tests 8/8 (incl. Vulkan with
|
||
validation layers, no messages).
|
||
- Snags: moc misses classes in files with raw strings containing `//` (CLAUDE.md);
|
||
generated QML type registration includes headers by file name; Qt ≥ 6.9 hints at
|
||
`WebEngineProfilePrototype` (not in the Frame's 6.8). Deviations: `HaWebUi` lives in the
|
||
app, not the library; the password warning needs a password in the file.
|
||
- Log file for SteamVR-started instances: the manifest passes `--log-file
|
||
logs/frame-assistant.log` (user's choice among: default log path in the app, manifest
|
||
argument, document only).
|
||
- Not verified yet: WebEngine with a URL in the off-screen pipeline (Frame, phase 4); the
|
||
bundled package (not supported for WebEngine in this iteration).
|
||
- Plan for implementation iteration 1 approved; phase 3 started.
|
||
- Plan for implementation iteration 1 written; new tab "HA Dashboard" (D38, D39).
|
||
- MVP implemented in four iterations; DSH-1 first, at the user's wish (D37).
|
||
- NFR-3 measurement method, manual in the MVP (D36). MVP details done.
|
||
- Shipping libmosquitto (D35).
|
||
- Configuration file format (D34).
|
||
- MVP notification: `notify` entity with first line as title; JSON command later (D33).
|
||
- HA MQTT interface: ids (D31), topics, retain, availability (D32), MVP entity list.
|
||
- Test strategy in four levels (D30). High-level architecture done.
|
||
- Threads: MQTT client in its own thread, everything else incl. OpenVR in the main thread (D29).
|
||
- DSH-1 split: web UI out-of-the-box test in the MVP, full dashboard as DSH-2 (D28).
|
||
- Overlays: two kinds (D25), one overlay for all notifications (D26), MVP placement "spawn in
|
||
front, then stay" (D27). Researched notification UI in VR (DESIGN.md, Appendix A). Found:
|
||
premultiplied-alpha flag missing in the platform.
|
||
- HA channels: MQTT for everything device-related; dashboard channel decided with Q2/Q3 (D24).
|
||
- Entities: one class per HA entity type, native types preferred, own service only as fallback
|
||
(D23). Found: MQTT `notify` drops the title.
|
||
- Start-up hook `prepare()` in the platform (D21); modes, `--desktop-novr` and `--config`
|
||
(D22).
|
||
- New requirement UI-1: status display in the main tab (D20).
|
||
- The user installed `mosquitto` on the dev host, so native builds can use libmosquitto.
|
||
- Started docs/DESIGN.md: one process (D16), three layers (D17), HA-centric object classes
|
||
(D18). HA side: FrameAssistant needs only stock HA; how the user wraps commands (scripts,
|
||
pyscript) is up to them (NFR-6 unchanged).
|
||
- Agreed to settle the high-level architecture first (list under "Next steps"), before
|
||
component details.
|
||
- Stay with the Debian build container: an Arch container wouldn't match SteamOS's own package
|
||
versions (private repos, rolling Arch) and has no arm64 multiarch for cross builds.
|
||
|
||
### 2026-10-04/05: project set-up and requirements
|
||
|
||
- Copied the vrdashboard template. Removed what the app doesn't need:
|
||
- `examples/` (diagnostics app) and the `VRDASH_BUILD_EXAMPLES` option
|
||
- the Frame test package (`scripts/package-frame-test.sh`, `docs/FRAME-TESTING.md`,
|
||
screenshots)
|
||
- the demo UI (`src/qml/DemoPage.qml`)
|
||
|
||
`Main.qml` shows a placeholder card.
|
||
- Named the app **FrameAssistant**, "Steam Frame companion for Home Assistant":
|
||
- CMake project `frameassistant`, executable `frame-assistant`
|
||
- app key `net.matzman.frameassistant`, tab "Frame Assistant", QML module `FrameAssistant`
|
||
|
||
Names rejected:
|
||
- "Steam…" and "…Home Assistant": trademarks
|
||
- "HASS…": the user dislikes it, because "Hass" is German for hate.
|
||
- Agreed working rules (in CLAUDE.md):
|
||
- explicit permission for everything; ask instead of assuming
|
||
- iterative five-phase cycle; an informal "ok" approves a phase
|
||
- document everything in Markdown in `docs/`
|
||
- `git init`. Baseline commit `4a5b090`.
|
||
- Requirements engineering (several question rounds with the user). The results are in
|
||
REQUIREMENTS.md:
|
||
- decisions D1–D12
|
||
- 51 requirements
|
||
- research on OpenVR data sources (Appendix A)
|
||
- Checks: `native-debug` builds, `ctest` passes 6/6 (Vulkan surface test skipped, no Vulkan on
|
||
this host), `--snapshot` renders.
|