ruvnet/RuView

What is RuView?

RuView (pronounced “π RuView”) is an open‑source Wi‑Fi‑based sensing platform that turns ordinary radio signals into a privacy‑preserving “spatial intelligence” layer for smart‑home and edge‑AI applications. By reading Channel State Information (CSI) from low‑cost ESP32‑S3/C6 boards, it can infer:

• Presence & occupancy – detect people through walls, count them, and track room transitions.
• Vital signs – contact‑less breathing‑rate and heart‑rate monitoring.
• Activity & pose – walking, sitting, gestures, falls, and even a 17‑key‑point body pose estimated from Wi‑Fi alone.
• Environment mapping – RF fingerprinting to recognise rooms, moved furniture, or new objects.
• Sleep quality – sleep‑stage classification and apnea screening.

All inference runs locally on edge hardware (ESP32 mesh nodes, a Raspberry Pi, or a Cognitum Seed box). No cameras, no cloud, and no internet connection are required.

---

Key components

Component	What it does	How you interact with it
ESP32‑CSI nodes (firmware in firmware/esp32-csi-node)	Capture raw CSI streams from Wi‑Fi packets and stream them over UDP.	Flash with esptool/idf.py, provision Wi‑Fi, then run the node.
RuView AI toolkit (harness/ruview)	Provides a CLI (npx @ruvnet/ruview …) that can:

• list devices, stream live CSI, run analysis pipelines,
• start a MCP server that lets LLMs (ChatGPT, Claude) query the sensor stack,
• verify model claims with deterministic proofs. | Install via npm (npx @ruvnet/ruview@0.9.1 …). | | Pre‑trained models (hosted on Hugging Face) | wifi‑densepose‑pretrained – a 4‑bit quantised encoder (≈8 KB) that outputs 128‑dim CSI embeddings and a 17‑keypoint pose; also models for breathing, heart‑rate, occupancy, etc. | Load automatically through the CLI or the Python package (ruview). | | Home‑assistant / Matter integration | Publishes up to 21 entities per node (raw signals + 10 inferred semantic states) via MQTT or as a HAP‑1.1 bridge, exposing presence, vitals, fall‑risk, room activity, etc. | Add the --mqtt flag to the Docker image or run the built‑in Home‑Assistant bridge. | | Edge‑module catalog (app-registry.json) | 105 ready‑to‑run “cogs” (small Rust/Wasm modules) for specific use‑cases such as occupancy‑zone counting, elevator‑flow, security alerts, etc. | Enable via the REST API (/api/v1/config/...) or through Home‑Assistant blueprints. | | Cognitum Seed (optional) | Provides persistent vector storage, k‑NN search, and Ed25519‑based attestation of every sensing event. | Connect ESP32 nodes to a Seed box; the Seed runs the RuView kernel as a Wasm service. |

---

Getting started (quick‑start options)

1. Docker demo – runs a simulated pipeline, no hardware needed.

   docker pull ruvnet/wifi-densepose:latest
   export RUVIEW_API_TOKEN=$(openssl rand -hex 32)
   docker run -p 127.0.0.1:3000:3000 -e RUVIEW_API_TOKEN ruvnet/wifi-densepose:latest
   

2. Live ESP32‑S3 node – flash the firmware, provision Wi‑Fi, and start streaming CSI.

   python -m esptool --chip esp32s3 --port COM9 --baud 460800 \
     write_flash 0x0 bootloader.bin 0x8000 partition-table.bin \
     0xf000 ota_data_initial.bin 0x20000 esp32-csi-node.bin
   python firmware/esp32-csi-node/provision.py --port COM9 \
     --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20
   

3. Full system with Cognitum Seed – combine the mesh with persistent storage and the RuView kernel for on‑device vector search.
4. Python package – install the same inference code via PyPI.

   pip install ruview[client]
   

   Then use from ruview import BreathingExtractor, HeartRateExtractor or the MQTT client.

---

Why it matters

• Privacy‑first – no cameras, no personal data leaves the house; all data is signed with an Ed25519 witness chain.
• Ultra‑low cost – each ESP32‑CSI node costs ~ $9, making large‑scale deployments feasible.
• Edge AI – models run in microseconds on a Raspberry Pi or even directly on the ESP32 (via Wasm), eliminating latency and cloud fees.
• Open‑source & extensible – the whole stack (firmware, Rust crates, Python wheels, Docker image, and the AI‑operator harness) is MIT‑licensed and hosted on GitHub.

---

Where to learn more

• User guide – docs/user-guide.md (starts with hardware setup, then model loading, then automation).
• Home‑Assistant integration – docs/integrations/home-assistant.md.
• Model repository – Hugging Face ruvnet/wifi-densepose-pretrained.
• Meta‑harness docs – harness/ruview/README.md (how to run the LLM‑driven operator).
• Benchmarks & ADRs – see docs/benchmarks/ and docs/adr/ for detailed performance numbers and design decisions.

RuView therefore sits squarely at the intersection of radio‑frequency sensing, edge machine‑learning, and smart‑home automation, offering a concrete, open‑source path to camera‑free, contact‑less monitoring.