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

• Iteration 1, phase 2 (planning and design). Phase 1 is approved (D13); REQUIREMENTS.md is the baseline. High-level architecture done (DESIGN.md); MVP details next.

Next steps

Phase 2: the high-level architecture is done (D16–D30, DESIGN.md). Next, the details for the MVP (D8, plus DSH-1 by D28), in this order:

1. Topics and payloads: topic scheme, device and entity ids, discovery content, MVP entity list, retain and availability.
2. MVP notification: command format and title (MQTT notify drops the title).
3. Configuration file format, incl. TLS/CA settings.
4. Shipping libmosquitto (build, package, licence text).
5. NFR-3 measurement method.

Then the platform changes (start-up hook D21, desktop modes D22, world overlay D25, WebEngine initialisation for DSH-1) and the implementation plan for iteration 1.

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.
• 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.