This guide describes the Mac sensing implementation. See Mac and Windows options for platform availability; features and permissions vary by platform.
How Room Sensing Works: WiFi and Acoustic Sensing Explained
"Room sensing" sounds like science fiction: a house that knows which rooms are occupied without a camera in sight. The underlying physics, though, is old and well understood — sonar has guided ships for a century, and radio engineers have always known that bodies disturb signals. What's new is that ordinary consumer hardware is now sensitive enough, and computers fast enough, to do it at home.
This guide walks through the two sensing families most relevant to a modern setup — acoustic sonar and WiFi channel-state sensing — and then covers the part most product pages skip: the privacy model, and what these systems can and cannot actually tell about you.
Acoustic sonar: hearing the shape of a room
Sonar works by emitting sound and measuring what comes back. A home implementation uses a speaker to play a signal near or above the top of the human hearing range — Vigil's Room Sonar, for example, operates in the 18–22 kHz band, which most adults cannot hear — and a microphone to record the reflections.
Three things make the echoes informative:
- Timing. Sound travels at a known speed, so the delay of each reflection encodes the distance to whatever produced it. A room's walls and furniture return a stable pattern; a new reflector — a person — changes it.
- The Doppler effect. Reflections off a moving surface come back shifted in frequency, exactly like a siren changing pitch as it passes. Walking, gesturing, even shifting in a chair produce measurable Doppler signatures.
- Periodicity. Breathing moves the chest wall back and forth in a slow, regular rhythm. Across many seconds of echoes, that rhythm shows up as a periodic signal — which is how sonar can suggest a still, breathing person is present when a motion sensor would report an empty room.
The limits are physical: sound doesn't pass through walls, so sonar covers the room the device sits in. Loud environments, absorbent furnishings, and distance all weaken the signal. An honest sonar pipeline reports motion and breathing only when the echo pattern clearly supports it.
WiFi sensing: reading the radio environment
Every WiFi packet that crosses a room arrives at its receiver as many overlapping copies — one for each path the radio waves took, bouncing off walls, floors, furniture, and people. Receivers characterize this multipath environment with a measurement called channel state information (CSI): for each frequency subcarrier in the WiFi channel, how much the signal was attenuated and how its phase shifted in transit.
That measurement exists because WiFi needs it to decode data at all. Sensing repurposes it: since a human body absorbs and reflects 2.4/5 GHz radio waves, a person who enters, moves through, or simply breathes inside the coverage area perturbs the CSI in ways that stand out from the static background of the room.
What CSI-based sensing can support, depending on hardware and conditions:
- Presence — the coverage area's radio "fingerprint" is being disturbed by a body.
- Motion and coarse location — how strongly and where the disturbance shows up.
- Micro-motion — with a stable link and careful processing, the periodic chest movement of breathing can appear in the signal.
The property that makes CSI genuinely different from every camera and every sonar: radio passes through interior walls. A single well-placed sensing node can cover space it cannot see, which is what makes whole-home, no-camera coverage possible. In Vigil, inexpensive ESP32-based nodes stream CSI frames over the network (UDP port 5005) to the Mac, which does all the processing; a bundled simulator streams a recorded capture into the same pipeline so you can explore the through-wall view before owning any node hardware.
The privacy model: why sensing is not surveillance
The instinctive worry — "my house is watching me" — deserves a direct answer. It comes in two parts.
1. The signal itself carries very little about you
A camera frame contains your face, your screen, your mail, and your body. A CSI frame contains per-subcarrier amplitudes and phases. Acoustic sensing is different: a microphone necessarily reads audio samples, which can contain ambient sound even though the pipeline is trying to measure its own emitted signal and reflections. Vigil processes those samples transiently in memory and is designed not to save or upload conventional recordings. Derived presence, motion, and breathing patterns can still be sensitive.
2. Where the processing happens decides who learns it
Even narrow signals form a pattern over time — when you're home, which rooms you use, when you sleep. That occupancy pattern is sensitive, and the architecture question is who gets to see it. A cloud-processed sensor ships raw or semi-raw readings to a vendor's servers, where the pattern accumulates outside your control. An on-device system processes everything on hardware you own, so the pattern never exists anywhere else. This is the single most consequential design choice in a sensing product; our guide on keeping smart-home data on your own hardware covers it in depth.
What room sensing honestly cannot do
- Identify people. Presence sensing knows that, not who. Security systems built on it use armed/disarmed modes for context instead of recognition — see how camera-free security works.
- Guarantee detection. Radio and acoustics are physical signals in messy environments. Wall construction, interference, and placement all matter. Treat any claim of guaranteed or near-perfect detection as marketing.
- Measure vitals medically. Breathing and heart-adjacent signals from sonar or CSI are best-effort estimates that can be delayed, missed, or wrong. Signal-quality gating does not make them clinically valid. Do not use them for diagnosis, treatment, emergency, or life-safety decisions.
- See fine detail. Sensing resolves bodies and motion, not objects, text, or expressions. For sensing's purpose — occupancy, automation, security — that's a feature.
Putting it together
A practical room-sensing stack layers the approaches: sonar covers the room your computer sits in with zero extra hardware; camera-based pose (strictly optional, permission-gated) adds detail in that same room; CSI nodes extend coverage through walls to the rest of the home. Each layer feeds one shared model of occupancy, which then drives automations — lights that follow real presence — and a security layer that treats confirmed presence in an armed, empty house as the event worth alerting on.