SteamFrame/FrameAssistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document iteration 1: settings file, HA Dashboard tab, new hooks

Browse Source 
README: settings file, --config, the new tab. ARCHITECTURE.md and
CLAUDE.md: prepare() hook, app command-line options, app code layout,
WebEngine notes, the moc raw-string pitfall. THIRD_PARTY_NOTICES: Qt
WebEngine. Ship config.example.json; the package README explains the
set-up. PROGRESS.md and DESIGN.md: phase 3 results and deviations.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
matzman
2026-10-05 22:21:34 +02:00
co-authored by Claude Opus 5.5
parent 0676998033
commit 179316db52
9 changed files with 175 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+56 -12
View File
@@ -9,8 +9,9 @@ the headset to Home Assistant in both directions:
- **Services:** Home Assistant can call it, e.g. to show notifications in the headset.
- **Dashboard:** a SteamVR dashboard tab to view and control Home Assistant from inside VR.
> **Status:** early development. The overlay platform works on the Frame; the Home Assistant
> parts are being planned; see [docs/REQUIREMENTS.md](docs/REQUIREMENTS.md),
> **Status:** early development. The overlay platform works on the Frame. The Home Assistant
> parts are being built: so far a settings file and an "HA Dashboard" tab with Home
> Assistant's web UI. See [docs/REQUIREMENTS.md](docs/REQUIREMENTS.md),
> [docs/DESIGN.md](docs/DESIGN.md) and [docs/PROGRESS.md](docs/PROGRESS.md).
### Platform
@@ -33,8 +34,8 @@ FrameAssistant grew out of a SteamVR dashboard-overlay template, which it still
## Quick start
Requirements:
- CMake ≥ 3.22, Ninja, a C++20 compiler, and Qt ≥ 6.5 (Quick, QuickControls2, OpenGL;
Test for the tests)
- CMake ≥ 3.22, Ninja, a C++20 compiler, and Qt ≥ 6.5 (Quick, QuickControls2, OpenGL,
WebEngineQuick; Test for the tests)
- Vulkan headers (optional; without them the build is OpenGL only)
- Docker or Podman, for the Frame builds
@@ -45,12 +46,14 @@ The OpenVR SDK files are downloaded automatically when CMake configures the buil
cmake --preset native-debug && cmake --build --preset native-debug
ctest --preset native-debug
build/native-debug/bin/frame-assistant --desktop # UI in a window, no SteamVR
build/native-debug/bin/frame-assistant --snapshot out.png # one frame through the VR path
build/native-debug/bin/frame-assistant --desktop # UI in windows, no SteamVR
build/native-debug/bin/frame-assistant --snapshot out.png # one frame per tab through the VR path
build/native-debug/bin/frame-assistant # as dashboard tab (SteamVR running)
build/native-debug/bin/frame-assistant --install-manifest # register + auto-start with SteamVR
```
Overlay and desktop mode need a settings file (below); `--snapshot` and `--benchmark` don't.
On the Steam Frame:
```sh
@@ -60,6 +63,41 @@ scripts/deploy-to-frame.sh <user>@<frame> # copy over SSH and install (SteamVR
Details are in [docs/STEAM-FRAME.md](docs/STEAM-FRAME.md).
## Settings
FrameAssistant reads its settings from `~/.config/frameassistant/config.json`
(`$XDG_CONFIG_HOME` is respected; `--config <path>` picks another file). Start from
[`resources/config.example.json`](resources/config.example.json), which packages ship as
`share/frameassistant/config.example.json`:
```json
{
"device": { "name": "Steam Frame" },
"mqtt": { "host": "homeassistant.local", "username": "frameassistant", "password": "…" },
"homeassistant": { "url": "http://homeassistant.local:8123" }
}
```
| Key | Required | Default | Meaning |
|-----|----------|---------|---------|
| `device.name` | yes | | Name of this headset in Home Assistant |
| `device.ha_unique_id` | no | derived from the name | Fixed id, so the name can change without creating a new device |
| `mqtt.host` | yes | | MQTT broker |
| `mqtt.port` | no | 1883, 8883 with TLS | |
| `mqtt.username`, `mqtt.password` | no | no login | |
| `mqtt.tls.enabled` | no | `false` | |
| `mqtt.tls.ca_file` | no | system certificates | CA of the broker's certificate |
| `mqtt.tls.cert_file`, `mqtt.tls.key_file` | no | | Client certificate |
| `homeassistant.discovery_prefix` | no | `homeassistant` | |
| `homeassistant.url` | no | | Home Assistant web UI for the "HA Dashboard" tab |
| `notifications.timeout_s` | no | 10 | How long notifications stay |
Invalid or missing settings stop the app with an error message and exit code 1. Unknown keys
only produce a warning. Keep the file private (`chmod 600`) when it holds a password.
The "HA Dashboard" tab keeps the Home Assistant login in
`~/.local/share/frameassistant/webengine`.
## Development
- **App identity** (app key `net.matzman.frameassistant`, tab name, executable name
@@ -68,8 +106,10 @@ Details are in [docs/STEAM-FRAME.md](docs/STEAM-FRAME.md).
- **UI:** `src/qml/`, with `Main.qml` as the root. List new QML files under `QML_FILES` in
`vrdash_add_dashboard()` in `src/CMakeLists.txt`. Iterate with `--desktop` and `--snapshot`.
- **C++ logic:** the app class `src/Dashboard.h/.cpp` derives from `DashboardApplication`.
It adds views in its constructor (`addSurface()`), keeps its objects as members and wires
them up in the `loading()`/`started()` overrides.
It adds views in its constructor (`addSurface()`) and its own command-line options,
keeps its objects as members, loads the settings in `prepare()` and wires things up in
the `loading()`/`started()` overrides. Logic without SteamVR or rendering goes into the
static library `frameassistant_lib` (e.g. `src/config/`), which the tests link.
- **Controller buttons:** actions and default bindings are in `resources/input/`.
- **Ship it:** `scripts/package-release.sh` and `scripts/deploy-to-frame.sh`, see
[docs/STEAM-FRAME.md](docs/STEAM-FRAME.md).
@@ -84,6 +124,7 @@ How the pieces fit together: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
|--------|---------|
| *(none)* | Run as SteamVR dashboard overlay (SteamVR must be running) |
| `--desktop` | Show the UI in desktop windows, one per surface; no SteamVR |
| `--config <path>` | Settings file (default `~/.config/frameassistant/config.json`) |
| `--snapshot <png>` | Render one frame per surface off-screen and save it (`<name>-<id>.png` with several surfaces) |
| `--benchmark <frames>` | Render frames back to back with a full GPU wait each and print frame times |
| `--graphics-api vulkan\|opengl` | Render backend. Default: Vulkan, falling back to OpenGL if Vulkan doesn't start; an explicit choice never falls back |
@@ -107,17 +148,20 @@ VK_DRIVER=lvp scripts/container-test.sh # same on the lavapipe software driver
| Path | Content |
|------|---------|
| `src/main.cpp`, `src/Dashboard.*`, `src/qml/` | **The app** |
| `src/config/` | Settings file (`frameassistant_lib`) |
| `src/ha/` | Home Assistant parts: `HaWebUi` (web UI tab) |
| `src/app/` | `DashboardApplication` (app base class), `Surface` (one view) |
| `src/render/` | Off-screen Qt Quick renderer; Vulkan and OpenGL backends |
| `src/vr/` | SteamVR connection, overlays (dashboard tab) |
| `src/input/` | Laser/scroll/keyboard → Qt events; SteamVR Input navigation |
| `resources/` | SteamVR manifest template, input actions and bindings |
| `resources/` | SteamVR manifest template, input actions and bindings, example settings |
| `tests/` | Unit and render tests |
| `cmake/` | `vrdash_add_dashboard()`, OpenVR download, Qt bundling, toolchain |
| `docker/`, `scripts/` | Build containers; build, package, deploy and test scripts |
| `docs/` | Requirements, progress, architecture, Steam Frame notes |
| `docs/` | Requirements, design, progress, architecture, Steam Frame notes |
## License
MIT, see [LICENSE](LICENSE). Third-party components (OpenVR SDK, Qt; in bundled builds also
their dependencies) are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
MIT, see [LICENSE](LICENSE). Third-party components (OpenVR SDK, Qt incl. Qt WebEngine; in
bundled builds also their dependencies) are listed in
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).