105 lines
7.2 KiB
Markdown
105 lines
7.2 KiB
Markdown
# v0.7.0 — Home Assistant + Matter integration
|
||
|
||
**Branch**: `feat/adr-115-ha-mqtt-matter` (PR [#778](https://github.com/ruvnet/RuView/pull/778)) · **Tracking issue**: [#776](https://github.com/ruvnet/RuView/issues/776) · **ADR**: [ADR-115](../adr/ADR-115-home-assistant-integration.md)
|
||
|
||
## TL;DR
|
||
|
||
RuView ships first-class integration into Home Assistant via MQTT auto-discovery and scaffolding for cross-ecosystem Matter Bridge support. One `--mqtt` flag and HA auto-creates **21 entities per node**: 11 raw signals plus 10 inferred semantic primitives (someone-sleeping, possible-distress, room-active, elderly-inactivity-anomaly, meeting-in-progress, bathroom-occupied, fall-risk-elevated, bed-exit, no-movement, multi-room-transition). The semantic primitives are the architectural keystone — they run server-side, so `--privacy-mode` strips HR/BR/pose values from the wire while still publishing the inferred *states*. That's the architectural win that makes RuView deployable in healthcare and AAL contexts.
|
||
|
||
Plus 3 starter HA Blueprints, 3 drop-in Lovelace dashboards, an ESP32 hardware-validation harness, a witness bundle that self-verifies, and **420 lib tests including ~2,560 fuzzed assertions** per CI run.
|
||
|
||
## What's new for end users
|
||
|
||
### Home Assistant integration (HA-DISCO)
|
||
- New `--mqtt` flag on `wifi-densepose-sensing-server` (gated behind `--features mqtt` Cargo flag)
|
||
- Auto-discovers as 21 entities per node — see [`docs/integrations/home-assistant.md`](../integrations/home-assistant.md) for the full table
|
||
- mTLS support, configurable per-entity publish rates, `--privacy-mode` for healthcare/AAL deployments
|
||
- Pinned tested against **Home Assistant Core 2025.5** + **Mosquitto 2.0.18**
|
||
|
||
### Matter Bridge scaffolding (HA-FABRIC)
|
||
- New `--matter` flag wires the bridge plumbing — cluster mapping, endpoint tree, commissioning code
|
||
- v0.7.0 ships **SDK-independent** — actual `rs-matter` integration deferred to v0.7.1 per ADR §9.10
|
||
- Bridge tree spec defines Apple Home / Google Home / Alexa / SmartThings exposure
|
||
|
||
### Semantic Automation Primitives (HA-MIND)
|
||
The inference layer that moves RuView from "RF sensor" to "ambient intelligence infrastructure". 10 v1 primitives, each with warmup gate + hysteresis + explainability tags. Per-primitive precision/recall published in [`docs/integrations/semantic-primitives-metrics.md`](../integrations/semantic-primitives-metrics.md).
|
||
|
||
### 8 Starter HA Blueprints
|
||
Ready-to-import YAML under [`examples/ha-blueprints/`](../../examples/ha-blueprints/) covering distress notification, sleep-aware hallway dimming, wake routines, elderly inactivity escalation, meeting room automation, bathroom fan, fall risk escalation, auto-arm security.
|
||
|
||
### 3 Lovelace Dashboards
|
||
Drop-in views under [`examples/lovelace/`](../../examples/lovelace/) — single-room overview, multi-node grid, healthcare/AAL care view (privacy-mode-compatible).
|
||
|
||
## What's new for operators
|
||
|
||
| Flag | Purpose |
|
||
|---|---|
|
||
| `--mqtt`, `--mqtt-host`, `--mqtt-port`, `--mqtt-username`, `--mqtt-password-env`, `--mqtt-client-id`, `--mqtt-prefix` | Broker connectivity |
|
||
| `--mqtt-tls`, `--mqtt-ca-file`, `--mqtt-client-cert`, `--mqtt-client-key` | TLS / mTLS |
|
||
| `--mqtt-refresh-secs`, `--mqtt-rate-{vitals,motion,count,rssi,pose}`, `--mqtt-publish-pose` | Rate control |
|
||
| `--privacy-mode` | Strip HR/BR/pose at the wire boundary |
|
||
| `--matter`, `--matter-setup-file`, `--matter-reset`, `--matter-vendor-id`, `--matter-product-id` | Matter bridge |
|
||
| `--semantic`, `--semantic-thresholds-file`, `--semantic-zones-file`, `--semantic-baseline-window-days`, `--no-semantic <PRIMITIVE>` | Inference layer |
|
||
|
||
Full CLI matrix: [`docs/integrations/home-assistant.md`](../integrations/home-assistant.md#configuration).
|
||
|
||
## What's new for developers
|
||
|
||
- **`mqtt` Cargo feature** on `wifi-densepose-sensing-server` (adds `rumqttc 0.24` with rustls)
|
||
- **`matter` Cargo feature** — scaffolding only, no SDK pulled in
|
||
- New modules: `mqtt::{config,discovery,privacy,publisher,security,state}` and `semantic::{bus,common,sleeping,distress,room_active,elderly_anomaly,meeting,bathroom,fall_risk,bed_exit,no_movement,multi_room}` and `matter::{clusters,bridge,commissioning}`
|
||
- **420 unit tests passing** including 10 `proptest` cases that fuzz the wire boundary + semantic dispatch (~2,560 fuzzed assertions per CI run)
|
||
- **3 integration tests** against real Mosquitto in `.github/workflows/mqtt-integration.yml`
|
||
- **6 criterion benchmarks** — see [`docs/integrations/benchmarks.md`](../integrations/benchmarks.md)
|
||
- **ESP32 validation harness** — `scripts/validate-esp32-mqtt.sh` runs end-to-end against attached hardware
|
||
- **Witness bundle generator** — `scripts/witness-adr-115.sh` produces self-verifying tarballs
|
||
|
||
## Benchmarks (laptop, release build)
|
||
|
||
| Hot path | Measured | Target | Better |
|
||
|---|---|---|---|
|
||
| `state::event_fall` encode | 259 ns | <2 µs | 7.7× |
|
||
| `rate_limiter::allow_first` | 49.7 ns | <100 ns | 2× |
|
||
| `rate_limiter::allow_within_gap` | 62.1 ns | <100 ns | 1.6× |
|
||
| `privacy::decide_hr_strip` | 0.24 ns | <50 ns | 208× |
|
||
| `privacy::decide_presence_keep` | 0.24 ns | <50 ns | 208× |
|
||
| `semantic::bus_tick_all_10_primitives` | 717 ns | <10 µs | 14× |
|
||
|
||
Every target beaten by ≥1.6×, several by 100×+. Full numbers + reproduction recipe in [`docs/integrations/benchmarks.md`](../integrations/benchmarks.md).
|
||
|
||
## Security
|
||
|
||
- **Wire-boundary audit** (`mqtt::security`) — topic-segment safety (rejects MQTT wildcards `+`/`#`, NUL, `/`), TLS path safety (NUL/newline rejection), 32 KB payload-size cap, credential-hygiene canary (`--mqtt-password` regression-detector), `RUVIEW_MQTT_STRICT_TLS=1` v0.8.0 upgrade path
|
||
- **5 property-based fuzz cases** in `mqtt::security::tests` covering random Unicode + injected wildcards/NULs at arbitrary offsets
|
||
- **`--privacy-mode`** enforced at every layer — discovery suppression + state stripping + Matter cluster gating
|
||
|
||
## Reproducibility
|
||
|
||
```bash
|
||
git checkout v0.7.0
|
||
cd v2
|
||
cargo test -p wifi-densepose-sensing-server --no-default-features --lib # 420 passed
|
||
cargo test -p wifi-densepose-sensing-server --features mqtt --no-default-features --lib # also 420 passed
|
||
RUVIEW_RUN_INTEGRATION=1 cargo test -p wifi-densepose-sensing-server \
|
||
--features mqtt --no-default-features --test mqtt_integration -- --test-threads=1
|
||
cargo bench -p wifi-densepose-sensing-server --features mqtt --bench mqtt_throughput
|
||
cd ..
|
||
bash scripts/witness-adr-115.sh
|
||
cd dist/witness-bundle-ADR115-*/ && bash VERIFY.sh # "ADR-115 witness bundle: VERIFIED ✓"
|
||
```
|
||
|
||
## Deferred to v0.7.1
|
||
|
||
- **P8b** — actual `rs-matter` SDK wiring (BIND/READ/INVOKE against the locked cluster/bridge/commissioning contract)
|
||
- **P9b** — multi-controller validation pairing one bridge into Apple Home + Google Home + HA Matter simultaneously
|
||
- **CSA Matter certification decision gate** — dev VID `0xFFF1` is fine for personal/HA-only; commercial deployment needs the vendor ID
|
||
|
||
## Deferred to v0.8.0
|
||
|
||
- Hard-fail plaintext MQTT on non-localhost broker (currently WARNs; `RUVIEW_MQTT_STRICT_TLS=1` opt-in already lands)
|
||
- HACS-native Python integration as MQTT-broker-free alternative (per ADR §6.A)
|
||
|
||
## Acknowledgements
|
||
|
||
Maintainer ACK on all 13 ADR §9 open questions (#776). 17 commits on the feat branch, each phase-tagged. PR review: [#778](https://github.com/ruvnet/RuView/pull/778).
|