wifi-ruview/docs/releases/v0.7.0-mqtt-matter.md

v0.7.0 — Home Assistant + Matter integration

Branch: feat/adr-115-ha-mqtt-matter (PR #778) · Tracking issue: #776 · ADR: ADR-115

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

8 Starter HA Blueprints

Ready-to-import YAML under 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/ — 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.

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

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

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.