FrameAssistant/docs/PROGRESS.md

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 QCommandLineOptions, 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.