Home Assistant integration

RuView publishes its full WiFi-sensing capability set to Home Assistant via MQTT auto-discovery (HA-DISCO) and to any Matter controller (Apple Home / Google Home / Alexa / SmartThings / HA) via a built-in Matter Bridge (HA-FABRIC). This document is the operator guide for both paths. Design rationale: ADR-115.

Tested against Home Assistant Core 2025.5, Mosquitto add-on 6.4, and Matter (chip-tool) 1.3. Bump the matrix when you change tested versions.

Quick start

1. Prereqs

• A running MQTT broker on your LAN. The easiest path is the Mosquitto add-on inside Home Assistant OS (one click from the Add-on Store). EMQX and VerneMQ also work — see §Advanced brokers below.
• Home Assistant 2025.5 or newer with the MQTT integration enabled and pointed at your broker.
• A RuView wifi-densepose-sensing-server v0.7.0+ binary (or cargo run from source).

2. Start the publisher

# Docker (recommended for non-developers):
docker run --rm --net=host \
    ruvnet/wifi-densepose:0.7.0 \
    --source esp32 \
    --mqtt --mqtt-host 192.168.1.10 \
    --mqtt-username homeassistant --mqtt-password-env MQTT_PASSWORD

# Or from a source checkout (Rust 1.78+):
MQTT_PASSWORD='your-broker-password' \
cargo run --release -p wifi-densepose-sensing-server \
    --features mqtt -- \
    --source esp32 --mqtt \
    --mqtt-host 192.168.1.10 \
    --mqtt-username homeassistant

Within ~5 seconds of starting, Home Assistant should auto-create:

• One device per RuView node (named after the MAC or the friendly_name from your zones config)
• 17+ entities per device (presence, person count, heart rate, breathing rate, motion, fall events, signal strength, zones, and the 10 semantic primitives)

If nothing appears in HA's Settings → Devices, see Troubleshooting.

3. Stop the publisher cleanly

Ctrl-C — the publisher pushes offline to every availability topic before disconnect so HA marks all entities unavailable instantly. A kill -9 triggers MQTT LWT, which has the same effect within ~30 s.

Entity reference

RuView publishes three classes of entity. Names below are the unique_id slugs — Home Assistant assigns friendly names automatically.

Raw signals (11 entities)

Heart rate, breathing rate, and pose are biometric entities — they are stripped from MQTT (and never published over Matter) when --privacy-mode is set. See Privacy below.

Semantic automation primitives (10 entities)

These are the inferred high-level states that customer automations actually use. Each one is a small finite-state machine running server-side with explicit warmup, hysteresis, and refractory windows. Per-primitive precision/recall is published in semantic-primitives-metrics.md.

Every state change carries a reason attribute (e.g. ["motion<5%", "br=12bpm", "presence=true"]) so you can template against it in HA automations to understand why an automation triggered.

Matter device-type mapping

Per ADR-115 §3.11.1, the Matter Bridge exposes a subset on standard clusters so Apple Home / Google Home / Alexa / SmartThings can consume RuView without HA. Biometrics and pose stay MQTT-only — Matter has no clusters for HR / BR / pose keypoints yet.

Configuration

CLI matrix

Zone tag file format

# semantic-zones.yaml — passed to --semantic-zones-file
zones:
  bathroom: ["zone_3", "zone_7"]
  bedroom:  ["zone_1"]
  kitchen:  ["zone_2"]
  living:   ["zone_5"]
bed_zones: ["zone_1"]

Threshold overrides

# semantic-thresholds.yaml — passed to --semantic-thresholds-file
sleep_dwell_secs: 300
distress_hr_multiple: 1.5
room_active_motion_threshold: 0.10
elderly_anomaly_multiple: 2.0
meeting_min_persons: 2
no_movement_dwell_secs: 1800
fall_risk_event_threshold: 70.0

Privacy

When deploying in healthcare, AAL (aging-in-place), or commercial settings, set --privacy-mode. This:

• Strips heart rate, breathing rate, and pose keypoints from every outbound MQTT publication.
• Suppresses discovery for those entities entirely — HA never even sees they exist.
• Keeps every semantic primitive enabled. Sleeping / distress / room-active / etc are inferred states. The inference happens server-side and only the boolean or score crosses the wire. This is the architectural win that makes the platform deployable in regulated contexts.

Always pair --privacy-mode with --mqtt-tls on non-localhost brokers.

Three starter blueprints

Drop these YAML files into <HA config>/blueprints/automation/ruvnet/ and import them from the HA UI (Settings → Automations → Blueprints → Import).

1. Notify on possible distress

blueprint:
  name: RuView — notify on possible distress
  description: >
    Send a push notification when RuView detects sustained elevated heart
    rate + agitated motion (possible distress).
  domain: automation
  input:
    distress_entity:
      name: Possible distress entity
      selector: { entity: { domain: binary_sensor } }
    notify_target:
      name: Notify target (e.g. notify.mobile_app_pixel)
      selector: { text: {} }

trigger:
  - platform: state
    entity_id: !input distress_entity
    to: "on"

action:
  - service: !input notify_target
    data:
      title: "Possible distress detected"
      message: >
        RuView flagged sustained elevated heart rate + agitated motion.
        Reason: {{ state_attr(trigger.entity_id, 'reason') }}.

2. Dim hallway when someone is sleeping

blueprint:
  name: RuView — dim hallway when someone sleeping
  description: >
    Drop hallway lights to 10 % brightness when anyone in the bedroom is
    in the someone-sleeping state, so a midnight bathroom trip doesn't
    require full lights.
  domain: automation
  input:
    sleeping_entity:
      name: Someone sleeping entity
      selector: { entity: { domain: binary_sensor } }
    hallway_light:
      name: Hallway light
      selector: { entity: { domain: light } }

trigger:
  - platform: state
    entity_id: !input sleeping_entity
    to: "on"
  - platform: state
    entity_id: !input sleeping_entity
    to: "off"

action:
  - choose:
      - conditions:
          - condition: state
            entity_id: !input sleeping_entity
            state: "on"
        sequence:
          - service: light.turn_on
            target: { entity_id: !input hallway_light }
            data: { brightness_pct: 10 }
    default:
      - service: light.turn_off
        target: { entity_id: !input hallway_light }

3. Wake-up routine on bed exit

blueprint:
  name: RuView — wake-up routine on bed exit
  description: >
    When bed_exit fires between 05:00 and 09:00, ramp up bedroom lights
    over 10 minutes, start the coffee maker, and disarm the home alarm.
  domain: automation
  input:
    bed_exit_event:
      name: Bed exit event entity
      selector: { entity: { domain: event } }
    bedroom_light:
      name: Bedroom light
      selector: { entity: { domain: light } }
    coffee_maker:
      name: Coffee maker switch
      selector: { entity: { domain: switch } }

trigger:
  - platform: state
    entity_id: !input bed_exit_event

condition:
  - condition: time
    after: "05:00:00"
    before: "09:00:00"

action:
  - service: light.turn_on
    target: { entity_id: !input bedroom_light }
    data:
      brightness_pct: 100
      transition: 600   # 10 min ramp
  - service: switch.turn_on
    target: { entity_id: !input coffee_maker }
  - service: alarm_control_panel.alarm_disarm
    target: { entity_id: alarm_control_panel.home }

Lovelace dashboard examples

Single-room overview card

type: vertical-stack
title: Bedroom
cards:
  - type: glance
    entities:
      - entity: binary_sensor.ruview_bedroom_presence
      - entity: sensor.ruview_bedroom_heart_rate
      - entity: sensor.ruview_bedroom_breathing_rate
      - entity: sensor.ruview_bedroom_motion_level
  - type: entities
    entities:
      - entity: binary_sensor.ruview_bedroom_someone_sleeping
      - entity: binary_sensor.ruview_bedroom_room_active
      - entity: binary_sensor.ruview_bedroom_no_movement
      - entity: sensor.ruview_bedroom_fall_risk_elevated

Multi-node grid

type: grid
columns: 2
cards:
  - type: tile
    entity: binary_sensor.ruview_bedroom_presence
    name: Bedroom
  - type: tile
    entity: binary_sensor.ruview_living_presence
    name: Living
  - type: tile
    entity: binary_sensor.ruview_kitchen_presence
    name: Kitchen
  - type: tile
    entity: binary_sensor.ruview_bathroom_occupied
    name: Bathroom

Advanced brokers

Mosquitto is the recommended default. The integration also works with:

• EMQX (https://www.emqx.io/) — clustering, MQTT 5.0, dashboard UI. Good for ≥10 RuView nodes.
• VerneMQ (https://vernemq.com/) — Erlang-based, multi-protocol bridges (AMQP, WebSocket).
• HiveMQ Edge (https://www.hivemq.com/edge/) — managed cloud relay if you need off-LAN access.

All three accept the same HA discovery topics RuView publishes. Performance and discovery semantics are identical.

Troubleshooting

No entities appear in HA

1. Subscribe to the discovery topic with mosquitto_sub:
   bashCopy

   mosquitto_sub -h <broker> -t 'homeassistant/#' -v | head -50
   

   You should see one config topic per entity per node, with a JSON payload.
2. If mosquitto_sub shows nothing, RuView is not reaching the broker. Check --mqtt-host, network reachability, and credentials.
3. If mosquitto_sub shows configs but HA shows no devices, HA's MQTT integration may not be pointed at the same broker. Verify under Settings → Devices & Services → MQTT.

Entities appear but state never updates

1. Check that sensing-server is actually receiving CSI frames (tail -f the server log, look for [ws] / [edge_vitals] lines).
2. Verify the broadcast channel is alive by hitting /ws/sensing with wscat:
   bashCopy

   wscat -c ws://localhost:8765/ws/sensing
   

3. Confirm rate limits aren't dropping everything: --mqtt-rate-vitals 1.0 for diagnosis (default 0.2 Hz = every 5 s).

"Plaintext MQTT on non-localhost broker" WARN

Per ADR-115 §3.9, v0.7.0 warns and continues; v0.8.0 will hard-fail. Either:

• Add --mqtt-tls and supply a CA if your broker uses a self-signed cert, or
• Move the broker to localhost (e.g. run Mosquitto inside the same host as sensing-server).

Matter pairing fails

1. Check the setup code in your --matter-setup-file log (defaults to printing on startup).
2. Make sure the host running sensing-server is on the same WiFi subnet as the controller.
3. If Apple Home complains about an unknown vendor, that's expected — RuView uses dev VID 0xFFF1 until P10 (see ADR §9.9). Tap "Add anyway".

Applications — what people actually do with this

The 21 entities per node — 11 raw signals (presence, person count, breathing, heart rate, motion, RSSI, etc.) and 10 inferred semantic states (someone-sleeping, possible-distress, room-active, elderly-inactivity-anomaly, meeting-in-progress, bathroom-occupied, fall-risk-elevated, bed-exit, no-movement, multi-room-transition) — slot into Home Assistant like any other sensor. The list below groups real-world uses so you can pick the ones that match your space.

Personal & home

Healthcare & assisted living (AAL)

Security & safety

Commercial buildings & retail

Industrial & infrastructure

Education & public spaces

Energy & sustainability

Research, prototyping & developer use

Combining entities — recipe patterns

A few patterns appear over and over; if you understand these you can build most of the above yourself:

1. "Negative + duration" trip wires — no_movement for N minutes AND time-of-day window → most healthcare and pet/child safety automations.
2. "Two states agree" guards — presence == false AND security panel disarmed AND no door sensor open → strong "house is empty" signal.
3. "Threshold + cooldown" — presence_score > 0.7 for 30 s before triggering (smooths over flicker), then a 5 min cooldown before re-arming (prevents oscillation).
4. "Calendar vs reality" — pair an HA calendar event with n_persons → meeting-room auto-release, classroom unused-period detection.
5. "Privacy-mode + semantic-only" — run --privacy-mode, expose only the semantic primitives to HA, keep biometrics on-device. The right default for any deployment with non-tenant occupants.

What about regulated environments?

Run RuView with --privacy-mode and only the 10 inferred semantic states reach Home Assistant — heart rate, breathing rate, and pose values are stripped at the MQTT wire. Per ADR-115 §6, this passes:

• HIPAA-style minimum-necessary (no biometric numbers leave the device)
• GDPR purpose-limitation (the inferred states are the smallest dataset that supports the automation)
• CCPA "sensitive personal information" (no health data crosses the wire)

The fall-risk-elevated / possible-distress / someone-sleeping flags still work — they're computed inside the sensor pipeline and only the boolean outputs are published. That's the architectural win that makes RuView deployable in care homes, hospitals, schools, and shared-housing scenarios where raw biometrics would be a non-starter.

References

• ADR-115 — full design rationale
• semantic-primitives-metrics.md — per-primitive precision/recall
• Home Assistant MQTT integration: https://www.home-assistant.io/integrations/mqtt/
• Mosquitto add-on: https://github.com/home-assistant/addons/tree/master/mosquitto
• HACS follow-on (planned): https://github.com/ruvnet/hass-wifi-densepose
• Matter spec: https://csa-iot.org/all-solutions/matter/