Files

ruv e8e4bf6da9 fix: Update project development start date in README

2026-03-01 00:19:46 -05:00

36 KiB

Raw Blame History

WiFi DensePose

See through walls with WiFi. No cameras. No wearables. Just radio waves.

WiFi DensePose turns commodity WiFi signals into real-time human pose estimation, vital sign monitoring, and presence detection — all without a single pixel of video. By analyzing Channel State Information (CSI) disturbances caused by human movement, the system reconstructs body position, breathing rate, and heartbeat using physics-based signal processing and machine learning.

What How Speed

Pose estimation CSI subcarrier amplitude/phase → DensePose UV maps 54K fps (Rust)

Breathing detection Bandpass 0.1-0.5 Hz → FFT peak 6-30 BPM

Heart rate Bandpass 0.8-2.0 Hz → FFT peak 40-120 BPM

Presence sensing RSSI variance + motion band power < 1ms latency

Through-wall Fresnel zone geometry + multipath modeling Up to 5m depth

What	How	Speed
Pose estimation	CSI subcarrier amplitude/phase → DensePose UV maps	54K fps (Rust)
Breathing detection	Bandpass 0.1-0.5 Hz → FFT peak	6-30 BPM
Heart rate	Bandpass 0.8-2.0 Hz → FFT peak	40-120 BPM
Presence sensing	RSSI variance + motion band power	< 1ms latency
Through-wall	Fresnel zone geometry + multipath modeling	Up to 5m depth

# 30 seconds to live sensing — no toolchain required
docker pull ruvnet/wifi-densepose:latest
docker run -p 3000:3000 ruvnet/wifi-densepose:latest
# Open http://localhost:3000

Hardware options for live CSI capture:

Option Hardware Cost Capabilities

ESP32 Mesh (recommended) 3-6x ESP32-S3 + WiFi router ~$54 Presence, motion, breathing, heartbeat

Research NIC Intel 5300 / Atheros AR9580 ~$50-100 Full CSI with 3x3 MIMO

Any WiFi Windows/Linux laptop $0 RSSI-based presence and motion

No hardware? Verify the pipeline with the deterministic reference signal: python v1/data/proof/verify.py

Option	Hardware	Cost	Capabilities
ESP32 Mesh (recommended)	3-6x ESP32-S3 + WiFi router	~$54	Presence, motion, breathing, heartbeat
Research NIC	Intel 5300 / Atheros AR9580	~$50-100	Full CSI with 3x3 MIMO
Any WiFi	Windows/Linux laptop	$0	RSSI-based presence and motion

📋 Table of Contents

📡 Signal Processing & Sensing — From raw WiFi frames to vital signs

The signal processing stack transforms raw WiFi Channel State Information into actionable human sensing data. Starting from 56-192 subcarrier complex values captured at 20 Hz, the pipeline applies research-grade algorithms (SpotFi phase correction, Hampel outlier rejection, Fresnel zone modeling) to extract breathing rate, heart rate, motion level, and multi-person body pose — all in pure Rust with zero external ML dependencies.

Section	Description	Docs
Key Features	Privacy-first sensing, real-time performance, multi-person tracking, Docker	—
ESP32-S3 Hardware Pipeline	20 Hz CSI streaming, binary frame parsing, flash & provision	ADR-018 · Tutorial #34
Vital Sign Detection	Breathing 6-30 BPM, heartbeat 40-120 BPM, FFT peak detection	ADR-021
WiFi Scan Domain Layer	8-stage RSSI pipeline, multi-BSSID fingerprinting, Windows WiFi	ADR-022 · Tutorial #36
WiFi-Mat Disaster Response	Search & rescue, START triage, 3D localization through debris	ADR-001 · User Guide
SOTA Signal Processing	SpotFi, Hampel, Fresnel, STFT spectrogram, subcarrier selection, BVP	ADR-014

🧠 Models & Training — DensePose pipeline, RVF containers, SONA adaptation

The neural pipeline uses a graph transformer with cross-attention to map CSI feature matrices to 17 COCO body keypoints and DensePose UV coordinates. Models are packaged as single-file .rvf containers with progressive loading (Layer A instant, Layer B warm, Layer C full). SONA (Self-Optimizing Neural Architecture) enables continuous on-device adaptation via micro-LoRA + EWC++ without catastrophic forgetting.

Section	Description	Docs
RVF Model Container	Binary packaging with Ed25519 signing, progressive 3-layer loading, SIMD quantization	ADR-023
Training & Fine-Tuning	MM-Fi/Wi-Pose pre-training, 6-term composite loss, cosine-scheduled SGD, SONA LoRA	ADR-023
RuVector Crates	11 vendored Rust crates: HNSW, attention, GNN, temporal compression, min-cut, solver	Source

🖥️ Usage & Configuration — CLI flags, API endpoints, hardware setup

The Rust sensing server is the primary interface, offering a comprehensive CLI with flags for data source selection, model loading, training, benchmarking, and RVF export. A REST API (Axum) and WebSocket server provide real-time data access. The Python v1 CLI remains available for legacy workflows.

Section	Description	Docs
CLI Usage	`--source`, `--train`, `--benchmark`, `--export-rvf`, `--model`, `--progressive`	—
REST API & WebSocket	6 REST endpoints (sensing, vitals, BSSID, SONA), WebSocket real-time stream	—
Hardware Support	ESP32-S3 ($8), Intel 5300 ($15), Atheros AR9580 ($20), Windows RSSI ($0)	ADR-012 · ADR-013

⚙️ Development & Testing — 542+ tests, CI, deployment

The project maintains 542+ pure-Rust tests across 7 crate suites with zero mocks — every test runs against real algorithm implementations. Hardware-free simulation mode (--source simulate) enables full-stack testing without physical devices. Docker images are published on Docker Hub for zero-setup deployment.

Section	Description	Docs
Testing	7 test suites: sensing-server (229), signal (83), mat (139), wifiscan (91), RVF (16), vitals (18)	—
Deployment	Docker images (132 MB Rust / 569 MB Python), docker-compose, env vars	—
Contributing	Fork → branch → test → PR workflow, Rust and Python dev setup	—

📊 Performance & Benchmarks — Measured throughput, latency, resource usage

All benchmarks are measured on the Rust sensing server using cargo bench and the built-in --benchmark CLI flag. The Rust v2 implementation delivers 810x end-to-end speedup over the Python v1 baseline, with motion detection reaching 5,400x improvement. The vital sign detector processes 11,665 frames/second in a single-threaded benchmark.

Section	Description	Key Metric
Performance Metrics	Vital signs, CSI pipeline, motion detection, Docker image, memory	11,665 fps vitals · 54K fps pipeline
Rust vs Python	Side-by-side benchmarks across 5 operations	810x full pipeline speedup

📄 Meta — License, changelog, support

WiFi DensePose is MIT-licensed open source, developed by ruvnet. The project has been in active development since March 2025, with 3 major releases delivering the Rust port, SOTA signal processing, disaster response module, and end-to-end training pipeline.

Section	Description	Link
Changelog	v2.3.0 (training pipeline + Docker), v2.2.0 (SOTA + WiFi-Mat), v2.1.0 (Rust port)	—
License	MIT License	LICENSE
Support	Bug reports, feature requests, community discussion	Issues · Discussions

🚀 Key Features

Feature	Description
Privacy-First	No cameras — uses WiFi signals for pose detection
Real-Time	Sub-100µs/frame (Rust), 11,665 fps vital sign benchmark
Vital Signs	Contactless breathing (6-30 BPM) and heart rate (40-120 BPM)
Multi-Person	Simultaneous tracking of up to 10 individuals
Docker Ready	`docker pull ruvnet/wifi-densepose:latest` (132 MB)
RVF Portable Models	Single-file `.rvf` containers with progressive loading
542+ Tests	Comprehensive Rust test suite, zero mocks

📡 Signal Processing & Sensing

📡 ESP32-S3 Hardware Pipeline (ADR-018) — 20 Hz CSI streaming, flash & provision

ESP32-S3 (STA + promiscuous)     UDP/5005      Rust aggregator
┌─────────────────────────┐    ──────────>    ┌──────────────────┐
│ WiFi CSI callback 20 Hz │    ADR-018        │ Esp32CsiParser   │
│ ADR-018 binary frames   │    binary         │ CsiFrame output  │
│ stream_sender (UDP)     │                   │ presence detect  │
└─────────────────────────┘                   └──────────────────┘

Metric	Measured
Frame rate	~20 Hz sustained
Subcarriers	64 / 128 / 192 (LLTF, HT, HT40)
Latency	< 1ms (UDP loopback)
Presence detection	Motion score 10/10 at 3m

# Pre-built binaries — no toolchain required
# https://github.com/ruvnet/wifi-densepose/releases/tag/v0.1.0-esp32

python -m esptool --chip esp32s3 --port COM7 --baud 460800 \
  write-flash --flash-mode dio --flash-size 4MB \
  0x0 bootloader.bin 0x8000 partition-table.bin 0x10000 esp32-csi-node.bin

python scripts/provision.py --port COM7 \
  --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20

cargo run -p wifi-densepose-hardware --bin aggregator -- --bind 0.0.0.0:5005 --verbose

See firmware/esp32-csi-node/README.md and Tutorial #34.

🦀 Rust Implementation (v2) — 810x faster, 54K fps pipeline

Performance Benchmarks (Validated)

Operation	Python (v1)	Rust (v2)	Speedup
CSI Preprocessing (4x64)	~5ms	5.19 µs	~1000x
Phase Sanitization (4x64)	~3ms	3.84 µs	~780x
Feature Extraction (4x64)	~8ms	9.03 µs	~890x
Motion Detection	~1ms	186 ns	~5400x
Full Pipeline	~15ms	18.47 µs	~810x
Vital Signs	N/A	86 µs	11,665 fps

Resource	Python (v1)	Rust (v2)
Memory	~500 MB	~100 MB
Docker Image	569 MB	132 MB
Tests	41	542+
WASM Support	No	Yes

cd rust-port/wifi-densepose-rs
cargo build --release
cargo test --workspace
cargo bench --package wifi-densepose-signal

💓 Vital Sign Detection (ADR-021) — Breathing and heartbeat via FFT

Capability	Range	Method
Breathing Rate	6-30 BPM (0.1-0.5 Hz)	Bandpass filter + FFT peak detection
Heart Rate	40-120 BPM (0.8-2.0 Hz)	Bandpass filter + FFT peak detection
Sampling Rate	20 Hz (ESP32 CSI)	Real-time streaming
Confidence	0.0-1.0 per sign	Spectral coherence + signal quality

./target/release/sensing-server --source simulate --ui-path ../../ui
curl http://localhost:8080/api/v1/vital-signs

See ADR-021.

📡 WiFi Scan Domain Layer (ADR-022) — 8-stage RSSI pipeline for Windows WiFi

Stage	Purpose
Predictive Gating	Pre-filter scan results using temporal prediction
Attention Weighting	Weight BSSIDs by signal relevance
Spatial Correlation	Cross-AP spatial signal correlation
Motion Estimation	Detect movement from RSSI variance
Breathing Extraction	Extract respiratory rate from sub-Hz oscillations
Quality Gating	Reject low-confidence estimates
Fingerprint Matching	Location and posture classification via RF fingerprints
Orchestration	Fuse all stages into unified sensing output

cargo test -p wifi-densepose-wifiscan

See ADR-022 and Tutorial #36.

🚨 WiFi-Mat: Disaster Response — Search & rescue, START triage, 3D localization

Feature	Description
Vital Signs	Breathing (4-60 BPM), heartbeat via micro-Doppler
3D Localization	Position estimation through debris up to 5m
START Triage	Automatic Immediate/Delayed/Minor/Deceased classification
Real-time Alerts	Priority-based notifications with escalation

use wifi_densepose_mat::{DisasterResponse, DisasterConfig, DisasterType, ScanZone, ZoneBounds};

let config = DisasterConfig::builder()
    .disaster_type(DisasterType::Earthquake)
    .sensitivity(0.85)
    .max_depth(5.0)
    .build();

let mut response = DisasterResponse::new(config);
response.initialize_event(location, "Building collapse")?;
response.add_zone(ScanZone::new("North Wing", ZoneBounds::rectangle(0.0, 0.0, 30.0, 20.0)))?;
response.start_scanning().await?;

WiFi-Mat User Guide | ADR-001 | Domain Model

🔬 SOTA Signal Processing (ADR-014) — 6 research-grade algorithms

Algorithm	Purpose	Reference
Conjugate Multiplication	Cancels CFO/SFO from raw CSI phase	SpotFi (SIGCOMM 2015)
Hampel Filter	Robust outlier removal using median/MAD	Hampel (1974)
Fresnel Zone Model	Physics-based breathing detection	FarSense (MobiCom 2019)
CSI Spectrogram	STFT time-frequency matrices	Standard since 2018
Subcarrier Selection	Variance-ratio top-K ranking	WiDance (MobiCom 2017)
Body Velocity Profile	Domain-independent velocity x time	Widar 3.0 (MobiSys 2019)

🧠 Models & Training

📦 RVF Model Container — Single-file deployment with progressive loading

Property	Detail
Format	Segment-based binary (magic `0x52564653`) with 64-byte headers
Progressive Loading	Layer A <5ms, Layer B 100ms-1s, Layer C full graph
Signing	Ed25519 training proofs for verifiable provenance
Quantization	f32/f16/u8 via `rvf-quant` with SIMD distance
CLI	`--export-rvf`, `--save-rvf`, `--load-rvf`, `--model`

# Export model package
./target/release/sensing-server --export-rvf wifi-densepose-v1.rvf

# Load and run with progressive loading
./target/release/sensing-server --model wifi-densepose-v1.rvf --progressive

See ADR-023.

🧬 Training & Fine-Tuning — MM-Fi/Wi-Pose pre-training, SONA adaptation

Three-tier data strategy:

Pre-train on public datasets (MM-Fi, Wi-Pose) for cross-environment generalization
Fine-tune with ESP32 data + camera pseudo-labels for environment-specific multipath
SONA adaptation via micro-LoRA + EWC++ for continuous on-device learning

# Pre-train
./target/release/sensing-server --train --dataset data/ --dataset-type mmfi --epochs 100

# Or via Docker
docker run --rm -v $(pwd)/data:/data ruvnet/wifi-densepose:latest \
  --train --dataset /data --epochs 100 --export-rvf /data/model.rvf

🔩 RuVector Crates — 11 vendored signal intelligence crates

Crate	Purpose
`ruvector-core`	VectorDB, HNSW index, SIMD distance, quantization
`ruvector-attention`	Scaled dot-product, MoE, sparse attention
`ruvector-gnn`	Graph neural network, graph attention, EWC training
`ruvector-nervous-system`	PredictiveLayer, OscillatoryRouter, Hopfield
`ruvector-coherence`	Spectral coherence, HNSW health, Fiedler value
`ruvector-temporal-tensor`	Tiered temporal compression (8/7/5/3-bit)
`ruvector-mincut`	Subpolynomial dynamic min-cut
`ruvector-attn-mincut`	Attention-gated min-cut
`ruvector-solver`	Sparse Neumann solver O(sqrt(n))
`ruvector-graph-transformer`	Proof-gated graph transformer
`ruvector-sparse-inference`	PowerInfer-style sparse execution

See vendor/ruvector/ for full source.

🏗️ System Architecture

End-to-end data flow — From CSI capture to REST/WebSocket API

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   WiFi Router   │    │   WiFi Router   │    │   WiFi Router   │
│   (CSI Source)  │    │   (CSI Source)  │    │   (CSI Source)  │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────▼─────────────┐
                    │     CSI Data Collector    │
                    │   (Hardware Interface)    │
                    └─────────────┬─────────────┘
                                  │
                    ┌─────────────▼─────────────┐
                    │    Signal Processor       │
                    │  (RuVector + Phase San.)  │
                    └─────────────┬─────────────┘
                                  │
                    ┌─────────────▼─────────────┐
                    │   Graph Transformer       │
                    │  (DensePose + GNN Head)   │
                    └─────────────┬─────────────┘
                                  │
                    ┌─────────────▼─────────────┐
                    │   Vital Signs + Tracker   │
                    │  (Breathing, Heart, Pose) │
                    └─────────────┬─────────────┘
                                  │
          ┌───────────────────────┼───────────────────────┐
          │                       │                       │
┌─────────▼─────────┐   ┌─────────▼─────────┐   ┌─────────▼─────────┐
│   REST API        │   │  WebSocket API    │   │   Analytics       │
│  (Axum / FastAPI) │   │ (Real-time Stream)│   │  (Fall Detection) │
└───────────────────┘   └───────────────────┘   └───────────────────┘

Component	Description
CSI Processor	Extracts Channel State Information from WiFi signals (ESP32 or RSSI)
Signal Processor	RuVector-powered phase sanitization, Hampel filter, Fresnel model
Graph Transformer	GNN body-graph reasoning with cross-attention CSI-to-pose mapping
Vital Signs	FFT-based breathing (0.1-0.5 Hz) and heartbeat (0.8-2.0 Hz) extraction
REST API	Axum (Rust) or FastAPI (Python) for data access and control
WebSocket	Real-time pose, sensing, and vital sign streaming
Analytics	Fall detection, activity recognition, START triage

📦 Installation

Guided Installer — Interactive hardware detection and profile selection

./install.sh

The installer walks through 7 steps: system detection, toolchain check, WiFi hardware scan, profile recommendation, dependency install, build, and verification.

Profile	What it installs	Size	Requirements
`verify`	Pipeline verification only	~5 MB	Python 3.8+
`python`	Full Python API server + sensing	~500 MB	Python 3.8+
`rust`	Rust pipeline (~810x faster)	~200 MB	Rust 1.70+
`browser`	WASM for in-browser execution	~10 MB	Rust + wasm-pack
`iot`	ESP32 sensor mesh + aggregator	varies	Rust + ESP-IDF
`docker`	Docker-based deployment	~1 GB	Docker
`field`	WiFi-Mat disaster response kit	~62 MB	Rust + wasm-pack
`full`	Everything available	~2 GB	All toolchains

# Non-interactive
./install.sh --profile rust --yes

# Hardware check only
./install.sh --check-only

From Source — Rust (primary) or Python

git clone https://github.com/ruvnet/wifi-densepose.git
cd wifi-densepose

# Rust (primary — 810x faster)
cd rust-port/wifi-densepose-rs
cargo build --release
cargo test --workspace

# Python (legacy v1)
pip install -r requirements.txt
pip install -e .

# Or via pip
pip install wifi-densepose
pip install wifi-densepose[gpu]   # GPU acceleration
pip install wifi-densepose[all]   # All optional deps

Docker — Pre-built images, no toolchain needed

# Rust sensing server (132 MB — recommended)
docker pull ruvnet/wifi-densepose:latest
docker run -p 3000:3000 -p 3001:3001 -p 5005:5005/udp ruvnet/wifi-densepose:latest

# Python sensing pipeline (569 MB)
docker pull ruvnet/wifi-densepose:python
docker run -p 8765:8765 -p 8080:8080 ruvnet/wifi-densepose:python

# Both via docker-compose
cd docker && docker compose up

# Export RVF model
docker run --rm -v $(pwd):/out ruvnet/wifi-densepose:latest --export-rvf /out/model.rvf

Image	Tag	Size	Ports
`ruvnet/wifi-densepose`	`latest`, `rust`	132 MB	3000 (REST), 3001 (WS), 5005/udp (ESP32)
`ruvnet/wifi-densepose`	`python`	569 MB	8765 (WS), 8080 (UI)

System Requirements

Rust: 1.70+ (primary runtime — install via rustup)
Python: 3.8+ (for verification and legacy v1 API)
OS: Linux (Ubuntu 18.04+), macOS (10.15+), Windows 10+
Memory: Minimum 4GB RAM, Recommended 8GB+
Storage: 2GB free space for models and data
Network: WiFi interface with CSI capability (optional — installer detects what you have)
GPU: Optional (NVIDIA CUDA or Apple Metal)

🚀 Quick Start

First API call in 3 commands

1. Install

# Fastest path — Docker
docker pull ruvnet/wifi-densepose:latest
docker run -p 3000:3000 ruvnet/wifi-densepose:latest

# Or from source (Rust)
./install.sh --profile rust --yes

2. Start the System

from wifi_densepose import WiFiDensePose

system = WiFiDensePose()
system.start()
poses = system.get_latest_poses()
print(f"Detected {len(poses)} persons")
system.stop()

3. REST API

# Health check
curl http://localhost:3000/api/v1/health

# Latest sensing frame
curl http://localhost:3000/api/v1/sensing

# Vital signs
curl http://localhost:3000/api/v1/vital-signs

4. Real-time WebSocket

import asyncio, websockets, json

async def stream():
    async with websockets.connect("ws://localhost:3001/ws/sensing") as ws:
        async for msg in ws:
            data = json.loads(msg)
            print(f"Persons: {len(data.get('persons', []))}")

asyncio.run(stream())

🖥️ CLI Usage

Rust Sensing Server — Primary CLI interface

# Start with simulated data (no hardware)
./target/release/sensing-server --source simulate --ui-path ../../ui

# Start with ESP32 CSI hardware
./target/release/sensing-server --source esp32 --udp-port 5005

# Start with Windows WiFi RSSI
./target/release/sensing-server --source wifi

# Run vital sign benchmark
./target/release/sensing-server --benchmark

# Export RVF model package
./target/release/sensing-server --export-rvf model.rvf

# Train a model
./target/release/sensing-server --train --dataset data/ --epochs 100

# Load trained model with progressive loading
./target/release/sensing-server --model wifi-densepose-v1.rvf --progressive

Flag	Description
`--source`	Data source: `auto`, `wifi`, `esp32`, `simulate`
`--http-port`	HTTP port for UI and REST API (default: 8080)
`--ws-port`	WebSocket port (default: 8765)
`--udp-port`	UDP port for ESP32 CSI frames (default: 5005)
`--benchmark`	Run vital sign benchmark (1000 frames) and exit
`--export-rvf`	Export RVF container package and exit
`--load-rvf`	Load model config from RVF container
`--save-rvf`	Save model state on shutdown
`--model`	Load trained `.rvf` model for inference
`--progressive`	Enable progressive loading (Layer A instant start)
`--train`	Train a model and exit
`--dataset`	Path to dataset directory (MM-Fi or Wi-Pose)
`--epochs`	Training epochs (default: 100)

REST API & WebSocket — Endpoints reference

REST API (Rust Sensing Server)

GET  /api/v1/sensing              # Latest sensing frame
GET  /api/v1/vital-signs          # Breathing, heart rate, confidence
GET  /api/v1/bssid                # Multi-BSSID registry
GET  /api/v1/model/layers         # Progressive loading status
GET  /api/v1/model/sona/profiles  # SONA profiles
POST /api/v1/model/sona/activate  # Activate SONA profile

WebSocket: ws://localhost:8765/ws/sensing (real-time sensing + vital signs)

Hardware Support — Devices, cost, and guides

Hardware	CSI	Cost	Guide
ESP32-S3	Native	~$8	Tutorial #34
Intel 5300	Firmware mod	~$15	Linux `iwl-csi`
Atheros AR9580	ath9k patch	~$20	Linux only
Any Windows WiFi	RSSI only	$0	Tutorial #36

Python Legacy CLI — v1 API server commands

wifi-densepose start                    # Start API server
wifi-densepose -c config.yaml start     # Custom config
wifi-densepose -v start                 # Verbose logging
wifi-densepose status                   # Check status
wifi-densepose stop                     # Stop server
wifi-densepose config show              # Show configuration
wifi-densepose db init                  # Initialize database
wifi-densepose tasks list               # List background tasks

Documentation Links

WiFi-Mat User Guide | Domain Model
ADR-021 | ADR-022 | ADR-023

🧪 Testing

542+ tests across 7 suites — zero mocks, hardware-free simulation

# Rust tests (primary — 542+ tests)
cd rust-port/wifi-densepose-rs
cargo test --workspace

# Sensing server tests (229 tests)
cargo test -p wifi-densepose-sensing-server

# Vital sign benchmark
./target/release/sensing-server --benchmark

# Python tests
python -m pytest v1/tests/ -v

# Pipeline verification (no hardware needed)
./verify

Suite	Tests	What It Covers
sensing-server lib	147	Graph transformer, trainer, SONA, sparse inference, RVF
sensing-server bin	48	CLI integration, WebSocket, REST API
RVF integration	16	Container build, read, progressive load
Vital signs integration	18	FFT detection, breathing, heartbeat
wifi-densepose-signal	83	SOTA algorithms, Doppler, Fresnel
wifi-densepose-mat	139	Disaster response, triage, localization
wifi-densepose-wifiscan	91	8-stage RSSI pipeline

🚀 Deployment

Docker deployment — Production setup with docker-compose

# Rust sensing server (132 MB)
docker pull ruvnet/wifi-densepose:latest
docker run -p 3000:3000 -p 3001:3001 -p 5005:5005/udp ruvnet/wifi-densepose:latest

# Python pipeline (569 MB)
docker pull ruvnet/wifi-densepose:python
docker run -p 8765:8765 -p 8080:8080 ruvnet/wifi-densepose:python

# Both via docker-compose
cd docker && docker compose up

# Export RVF model
docker run --rm -v $(pwd):/out ruvnet/wifi-densepose:latest --export-rvf /out/model.rvf

Environment Variables

RUST_LOG=info                    # Logging level
WIFI_INTERFACE=wlan0             # WiFi interface for RSSI
POSE_CONFIDENCE_THRESHOLD=0.7    # Minimum confidence
POSE_MAX_PERSONS=10              # Max tracked individuals

📊 Performance Metrics

Measured benchmarks — Rust sensing server, validated via cargo bench

Rust Sensing Server

Metric	Value
Vital sign detection	11,665 fps (86 µs/frame)
Full CSI pipeline	54,000 fps (18.47 µs/frame)
Motion detection	186 ns (~5,400x vs Python)
Docker image	132 MB
Memory usage	~100 MB
Test count	542+

Python vs Rust

Operation	Python	Rust	Speedup
CSI Preprocessing	~5 ms	5.19 µs	1000x
Phase Sanitization	~3 ms	3.84 µs	780x
Feature Extraction	~8 ms	9.03 µs	890x
Motion Detection	~1 ms	186 ns	5400x
Full Pipeline	~15 ms	18.47 µs	810x

🤝 Contributing

Dev setup, code standards, PR process

git clone https://github.com/ruvnet/wifi-densepose.git
cd wifi-densepose

# Rust development
cd rust-port/wifi-densepose-rs
cargo build --release
cargo test --workspace

# Python development
python -m venv venv && source venv/bin/activate
pip install -r requirements-dev.txt && pip install -e .
pre-commit install

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes
Push and open a Pull Request

📄 Changelog

Release history

v2.3.0 — 2026-03-01

The largest release to date — delivers the complete end-to-end training pipeline, Docker images, and vital sign detection. The Rust sensing server now supports full model training, RVF export, and progressive model loading from a single binary.

Docker images published — ruvnet/wifi-densepose:latest (132 MB Rust) and :python (569 MB)
8-phase DensePose training pipeline (ADR-023) — Dataset loaders (MM-Fi, Wi-Pose), graph transformer with cross-attention, 6-term composite loss, cosine-scheduled SGD, PCK/OKS validation, SONA adaptation, sparse inference engine, RVF model packaging
--export-rvf CLI flag — Standalone RVF model container generation with vital config, training proof, and SONA profiles
--train CLI flag — Full training mode with best-epoch snapshotting and checkpoint saving
Vital sign detection (ADR-021) — FFT-based breathing (6-30 BPM) and heartbeat (40-120 BPM) extraction, 11,665 fps benchmark
WiFi scan domain layer (ADR-022) — 8-stage pure-Rust signal intelligence pipeline for Windows WiFi RSSI
New crates — wifi-densepose-vitals (1,863 lines) and wifi-densepose-wifiscan (4,829 lines)
542+ Rust tests — All passing, zero mocks

v2.2.0 — 2026-02-28

Introduced the guided installer, SOTA signal processing algorithms, and the WiFi-Mat disaster response module. This release established the ESP32 hardware path and security hardening.

Guided installer — ./install.sh with 7-step hardware detection and 8 install profiles
6 SOTA signal algorithms (ADR-014) — SpotFi conjugate multiplication, Hampel filter, Fresnel zone model, CSI spectrogram, subcarrier selection, body velocity profile
WiFi-Mat disaster response — START triage, scan zones, 3D localization, priority alerts — 139 tests
ESP32 CSI hardware parser — Binary frame parsing with I/Q extraction — 28 tests
Security hardening — 10 vulnerabilities fixed (CVE remediation, input validation, path security)

v2.1.0 — 2026-02-28

The foundational Rust release — ported the Python v1 pipeline to Rust with 810x speedup, integrated the RuVector signal intelligence crates, and added the Three.js real-time visualization.

RuVector integration — 11 vendored crates (ADR-002 through ADR-013) for HNSW indexing, attention, GNN, temporal compression, min-cut, solver
ESP32 CSI sensor mesh — $54 starter kit with 3-6 ESP32-S3 nodes streaming at 20 Hz
Three.js visualization — 3D body model with 17 joints, real-time WebSocket streaming
CI verification pipeline — Determinism checks and unseeded random scan across all signal operations

📄 License

MIT License — see LICENSE for details.

📞 Support

GitHub Issues | Discussions | PyPI

WiFi DensePose — Privacy-preserving human pose estimation through WiFi signals.

36 KiB Raw Blame History