RuView: WiFi CSI sensing with ESP32 nodes, and how to install it

What RuView senses, and who the ESP32 mesh is actually for

RuView reads Channel State Information, the per-subcarrier amplitude and phase report that modern WiFi chipsets produce for every received frame. A person standing in a room changes how those subcarriers reflect and attenuate, and the change is measurable even when nobody is moving much. The project's pitch is that this signal is enough to answer questions a camera would otherwise answer: is someone in the room, how many people, are they breathing normally, did they just fall.

The intended user is not a researcher with a software-defined radio. The README targets people who already have a smart home and want sensing without cameras: an ESP32 mesh, quoted as low as $9 per node, plus a Cognitum Seed for persistent memory and attestation. Nodes run edge modules directly, so no cloud round trip is needed for the basic detections. The four integrations listed are Home Assistant through an MQTT publisher, Apple Home and HomePod as a discoverable HAP-1.1 bridge, and Google Home plus Alexa through the same Home Assistant bridge or a Matter endpoint. If you are not already in one of those ecosystems, you are building the consumer side yourself.

The claimed outputs are presence and occupancy, breathing rate, heart rate, activity recognition including falls, RF fingerprinting for rooms, and overnight sleep staging. The README also lists camera-free pose estimation of 17 body keypoints and a unified RF world model that can combine WiFi CSI with radar, UWB and cellular. That last item carries its own caveat in the README: accuracy is still synthetic until real-data validation. Treat the pose and world-model features as research surface, not as shipping capability.

The sensing pipeline from CSI frame to semantic state

The data flow starts at the radio. An ESP32 sensor captures CSI and either runs an edge module locally or forwards frames to the host. The README describes multi-frequency mesh scanning across 6 WiFi channels, using neighbouring routers as illuminators rather than transmitting everything itself. That is a real design decision: it lowers the transmit burden per node but makes the signal dependent on what your neighbours' access points are doing.

On the processing side, the README gives specific filter bands. Breathing rate is extracted with a bandpass of 0.1 to 0.5 Hz on wrapped phase, then circular variance and zero-crossing counting to produce a BPM figure, reported over 6 to 30 BPM. Heart rate uses a bandpass of 0.8 to 2.0 Hz with zero-crossing BPM, reported over 40 to 120 BPM. Those bands are standard for the physiology, and the overlap between them is why separating respiration from cardiac motion in a single CSI stream is hard. The README does not describe how the two bands are disambiguated when a subject is moving.

Above the signal layer sits a learned head. The pretrained model is published on Hugging Face as ruvnet/wifi-densepose-pretrained, quantized to 4-bit at roughly 8 KB, and the README says it runs in microseconds on a Raspberry Pi. The v2 encoder reports a label-free held-out temporal-triplet accuracy of 82.3%, up from 66.4% raw. The README explicitly retracts an older 100% presence figure, noting it was measured on a single-class recording. That retraction is the most useful sentence in the document, because it tells you the project has started distinguishing a demo from a measurement.

Each measurement is attested through an Ed25519 witness chain, and the README describes attaching privacy policy, uncertainty, provenance and witness records to sensing events. The consequence is that you can audit where a reading came from, which matters if you ever want to act on a distress signal.

Installing RuView and a first run against a live sensor

The repository ships an interactive installer at install.sh and a Makefile that wraps it. The README does not present a pip install as the primary path, so start with the script. Clone the repository, then run the guided installer, which will ask about your target profile.

make install

If you would rather not answer prompts, the Makefile exposes non-interactive profiles. The python profile is the right starting point if you only want the API and processing stack and do not yet have hardware.

make install-python

Before installing anything, you can check the machine without changing it. This is the step to run first if you are unsure whether your toolchain is complete.

make check

The project also publishes a Rust workspace under v2, built with cargo. The README lists a crates.io package named wifi-densepose-ruvector, and the Makefile builds the workspace in release mode.

make build-rust

Once installed, the trust kill switch replays the deterministic proof that the pipeline produces consistent output. Run it before you trust any number you see from your own hardware.

make verify

For a first real use, the examples directory is the entry point rather than the API docs. It contains examples/ruview_live.py plus scenario folders for through-wall, sleep, stress, medical and research-sota. The README does not spell out the flags for those scripts, so read examples/README.md before running them; do not assume an argument exists because a folder name suggests it.

Separately, the project publishes an operator harness as an npm package. It is not required to run the sensor, but it is the documented way to get source-cited guidance and to check whether an accuracy claim is supported.

npx @ruvnet/[email protected] doctor
npx @ruvnet/[email protected] guidance --topic sensing --query "model loading"

Agent runs through that harness are read-only by default. The README states that workspace writes require both --allow-write and --confirm.

Where RuView breaks: calibration, band overlap and the retracted number

The first limitation is environmental. The README says the system learns each environment locally using spiking neural networks that adapt in under 30 seconds. Thirty seconds is fast, and fast adaptation on a small sample is exactly the condition under which a model fits the room rather than the person. Move the furniture, or move the access point, and the RF fingerprint that identifies a room changes. The README lists moved-furniture detection as a feature; the same sensitivity is a liability when you want stable readings.

The second is the physiology. Breathing at 0.1 to 0.5 Hz and heart rate at 0.8 to 2.0 Hz are cleanly separated on paper. In practice the zero-crossing method the README describes counts crossings in a filtered signal, and a subject who shifts position introduces low-frequency phase motion that lands inside the respiration band. The README does not document how the pipeline rejects that. If you need heart rate during movement, this is not the tool.

The third is the accuracy story. The current headline is 82.3% temporal-triplet accuracy, label-free and held out. That is honest and it is also not high. Roughly one in five evaluations does not match. The README retracts the earlier 100% presence figure because it came from a single-class recording, which means the project's own history includes a number that should never have been published. Read the retraction as a signal about how to read the rest: check whether any claim you depend on has a held-out evaluation behind it.

The fourth is scope. The unified RF world model that combines WiFi, radar, UWB and cellular is described in the README as synthetic until real-data validation. Do not architect around it. Similarly, the camera-free 17-keypoint pose output has no accuracy figure attached in the README.

Finally, there is no rollback documentation. The README does not describe how to revert a firmware flash or a model swap, and the release cadence is fast: three releases between 2026-08-26 and 2026-08-27. That pace is worth knowing before you pin a version in a home you actually live in.

RuView versus a passive infrared sensor or a camera

The obvious alternative for presence is a passive infrared sensor, and the difference is not subtle. A PIR sensor detects a moving heat source across its field of view and reports a binary. It is cheap, it needs no calibration, it draws almost nothing, and it fails completely when a person is still. RuView's whole argument is the still case: breathing and heart rate require the subject to be relatively stationary, and CSI sees the chest wall move where PIR sees nothing. If your only requirement is turning a light on when someone walks in, PIR is the correct engineering choice and RuView is overkill.

The second alternative is a camera with on-device inference. A camera gives you far more spatial resolution and it will outperform CSI pose estimation on any benchmark you care to run. The trade is privacy and coverage. RuView's README leans on the absence of pixels and the ability to work in the dark and through walls. A camera in a bathroom or a bedroom is a different product decision than a radio that reports a breathing rate. If your constraint is regulatory or social rather than technical, that difference decides the choice.

The third comparison is to other WiFi sensing research stacks. Most published CSI work assumes you can instrument the environment and collect labelled data for your own space. RuView's bet is the opposite: a pretrained 8 KB model plus local adaptation, so a user with no ML background can deploy. The cost of that bet is the 82.3% figure. A bespoke model trained on your own labelled recordings would very likely beat it, and the repository does expose a model workflow for recording CSI and training. If you have the patience to label data, the pretrained head is a starting point rather than the ceiling.

Licence, release cadence and what an upgrade actually costs

RuView is MIT licensed, and the Python package metadata in pyproject.toml repeats license = "MIT" with version 1.2.0. MIT is permissive: you can use it commercially, modify it and redistribute it, provided you keep the copyright notice and the licence text. The repository also depends on torch, torchvision, opencv-python and scikit-learn, each under its own licence, and those obligations travel with your deployment. This is not legal advice; check the licences of the dependencies you actually ship.

The upgrade cost is the more practical concern. The three most recent releases, v2390, v2400 and v2403, all landed within roughly two days of each other in late August 2026. The last push to the default branch was on 2026-08-27. Version numbers in that range with that cadence suggest the project is still moving quickly, and the README's own retraction of a published accuracy figure shows that behaviour can change between releases in ways that affect what you can claim about your deployment.

There is no documented migration guide in the README, and no documented rollback path for firmware or models. If you deploy this, pin the release you validated, keep the RVF model file you tested against, and re-run make verify after any upgrade before you let automations act on the output. The verify target exists precisely so that a version bump can be checked against the deterministic proof rather than trusted.

Editorial conclusion

Adopt RuView if you already run Home Assistant or another MQTT consumer and you are willing to place ESP32 nodes and calibrate per room; the 82.3% temporal-triplet figure is a starting point, not a guarantee, so measure your own space before trusting any vitals output. Do not adopt it for clinical monitoring, fall detection you would bet a person's safety on, or any deployment where a missed detection has consequences, because the README itself flags the unified RF world model as synthetic until real-data validation and retracts the earlier 100% presence number. Before you commit, run make check to confirm your hardware and toolchain, run make verify to replay the deterministic proof, and confirm which ESP32 board revision your firmware directory actually supports.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes