Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit d8fd5f4

Browse files
ruvnetruvnet
committed
docs: add How It Works section, fix ToC, update changelog to v3.0.0, add crates.io badge
- Add "How It Works" explainer between Key Features and Use Cases - Add Self-Learning WiFi AI and AI Backbone to Table of Contents - Update Key Features entry in ToC to match new sub-sections - Fix changelog: v2.3.0/v2.2.0/v2.1.0 → v3.0.0/v2.0.0 (matches CHANGELOG.md) - Add crates.io badge for wifi-densepose-ruvector Co-Authored-By: claude-flow <[email protected]>
1 parent 9e483e2 commit d8fd5f4

1 file changed

Lines changed: 46 additions & 26 deletions

File tree

‎README.md‎

Lines changed: 46 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ WiFi DensePose turns commodity WiFi signals into real-time human pose estimation
1010
[![Docker: 132 MB](https://img.shields.io/badge/docker-132%20MB-blue.svg)](https://hub.docker.com/r/ruvnet/wifi-densepose)
1111
[![Vital Signs](https://img.shields.io/badge/vital%20signs-breathing%20%2B%20heartbeat-red.svg)](#vital-sign-detection)
1212
[![ESP32 Ready](https://img.shields.io/badge/ESP32--S3-CSI%20streaming-purple.svg)](#esp32-s3-hardware-pipeline)
13+
[![crates.io](https://img.shields.io/crates/v/wifi-densepose-ruvector.svg)](https://crates.io/crates/wifi-densepose-ruvector)
1314

1415
> | What | How | Speed |
1516
> |------|-----|-------|
@@ -88,6 +89,28 @@ Fast enough for real-time use, small enough for edge devices, simple enough for
8889

8990
---
9091

92+
## 🔬 How It Works
93+
94+
WiFi routers flood every room with radio waves. When a person moves — or even breathes — those waves scatter differently. WiFi DensePose reads that scattering pattern and reconstructs what happened:
95+
96+
```
97+
WiFi Router → radio waves pass through room → hit human body → scatter
98+
↓
99+
ESP32 / WiFi NIC captures 56+ subcarrier amplitudes & phases (CSI) at 20 Hz
100+
↓
101+
Signal Processing cleans noise, removes interference, extracts motion signatures
102+
↓
103+
AI Backbone (RuVector) applies attention, graph algorithms, and compression
104+
↓
105+
Neural Network maps processed signals → 17 body keypoints + vital signs
106+
↓
107+
Output: real-time pose, breathing rate, heart rate, presence, room fingerprint
108+
```
109+
110+
No training cameras required — the [Self-Learning system (ADR-024)](#self-learning-wifi-ai-adr-024) bootstraps from raw WiFi data alone.
111+
112+
---
113+
91114
## 🏢 Use Cases & Applications
92115

93116
WiFi sensing works anywhere WiFi exists. No new hardware in most cases — just software on existing access points or a $8 ESP32 add-on. Because there are no cameras, deployments avoid privacy regulations (GDPR video, HIPAA imaging) by design.
@@ -466,7 +489,8 @@ The signal processing stack transforms raw WiFi Channel State Information into a
466489

467490
| Section | Description | Docs |
468491
|---------|-------------|------|
469-
| [Key Features](#key-features) | Privacy-first sensing, real-time performance, multi-person tracking, Docker | — |
492+
| [Key Features](#key-features) | Sensing, Intelligence, and Performance & Deployment capabilities | — |
493+
| [How It Works](#how-it-works) | End-to-end pipeline: radio waves → CSI capture → signal processing → AI → pose + vitals | — |
470494
| [ESP32-S3 Hardware Pipeline](#esp32-s3-hardware-pipeline) | 20 Hz CSI streaming, binary frame parsing, flash & provision | [ADR-018](docs/adr/ADR-018-esp32-dev-implementation.md) · [Tutorial #34](https://github.com/ruvnet/wifi-densepose/issues/34) |
471495
| [Vital Sign Detection](#vital-sign-detection) | Breathing 6-30 BPM, heartbeat 40-120 BPM, FFT peak detection | [ADR-021](docs/adr/ADR-021-vital-sign-detection-rvdna-pipeline.md) |
472496
| [WiFi Scan Domain Layer](#wifi-scan-domain-layer) | 8-stage RSSI pipeline, multi-BSSID fingerprinting, Windows WiFi | [ADR-022](docs/adr/ADR-022-windows-wifi-enhanced-fidelity-ruvector.md) · [Tutorial #36](https://github.com/ruvnet/wifi-densepose/issues/36) |
@@ -485,6 +509,8 @@ The neural pipeline uses a graph transformer with cross-attention to map CSI fea
485509
| [RVF Model Container](#rvf-model-container) | Binary packaging with Ed25519 signing, progressive 3-layer loading, SIMD quantization | [ADR-023](docs/adr/ADR-023-trained-densepose-model-ruvector-pipeline.md) |
486510
| [Training & Fine-Tuning](#training--fine-tuning) | 8-phase pure Rust pipeline (7,832 lines), MM-Fi/Wi-Pose pre-training, 6-term composite loss, SONA LoRA | [ADR-023](docs/adr/ADR-023-trained-densepose-model-ruvector-pipeline.md) |
487511
| [RuVector Crates](#ruvector-crates) | 11 vendored Rust crates from [ruvector](https://github.com/ruvnet/ruvector): attention, min-cut, solver, GNN, HNSW, temporal compression, sparse inference | [GitHub](https://github.com/ruvnet/ruvector) · [Source](vendor/ruvector/) |
512+
| [AI Backbone (RuVector)](#ai-backbone-ruvector) | 5 AI capabilities replacing hand-tuned thresholds: attention, graph min-cut, sparse solvers, tiered compression | [crates.io](https://crates.io/crates/wifi-densepose-ruvector) |
513+
| [Self-Learning WiFi AI (ADR-024)](#self-learning-wifi-ai-adr-024) | Contrastive self-supervised learning, room fingerprinting, anomaly detection, 55 KB model | [ADR-024](docs/adr/ADR-024-contrastive-csi-embedding-model.md) |
488514

489515
</details>
490516

@@ -533,7 +559,7 @@ WiFi DensePose is MIT-licensed open source, developed by [ruvnet](https://github
533559

534560
| Section | Description | Link |
535561
|---------|-------------|------|
536-
| [Changelog](#changelog) | v2.3.0 (training pipeline + Docker), v2.2.0 (SOTA + WiFi-Mat), v2.1.0 (Rust port) | — |
562+
| [Changelog](#changelog) | v3.0.0 (AETHER AI + Docker), v2.0.0 (Rust port + SOTA + WiFi-Mat) | [CHANGELOG.md](CHANGELOG.md) |
537563
| [License](#license) | MIT License | [LICENSE](LICENSE) |
538564
| [Support](#support) | Bug reports, feature requests, community discussion | [Issues](https://github.com/ruvnet/wifi-densepose/issues) · [Discussions](https://github.com/ruvnet/wifi-densepose/discussions) |
539565

@@ -1315,37 +1341,31 @@ pre-commit install
13151341
<details>
13161342
<summary><strong>Release history</strong></summary>
13171343

1318-
### v2.3.0 — 2026-03-01
1344+
### v3.0.0 — 2026-03-01
13191345

1320-
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.
1346+
Major release: AETHER contrastive embedding model, AI signal processing backbone, cross-platform adapters, Docker Hub images, and comprehensive README overhaul.
13211347

1348+
- **Project AETHER (ADR-024)** — Self-supervised contrastive learning for WiFi CSI fingerprinting, similarity search, and anomaly detection; 55 KB model fits on ESP32
1349+
- **AI Backbone (`wifi-densepose-ruvector`)** — 7 RuVector integration points replacing hand-tuned thresholds with attention, graph algorithms, and smart compression; [published to crates.io](https://crates.io/crates/wifi-densepose-ruvector)
1350+
- **Cross-platform RSSI adapters** — macOS CoreWLAN and Linux `iw` Rust adapters with `#[cfg(target_os)]` gating (ADR-025)
13221351
- **Docker images published** — `ruvnet/wifi-densepose:latest` (132 MB Rust) and `:python` (569 MB)
1323-
- **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
1324-
- **`--export-rvf` CLI flag** — Standalone RVF model container generation with vital config, training proof, and SONA profiles
1325-
- **`--train` CLI flag** — Full training mode with best-epoch snapshotting and checkpoint saving
1326-
- **Vital sign detection (ADR-021)** — FFT-based breathing (6-30 BPM) and heartbeat (40-120 BPM) extraction, 11,665 fps benchmark
1327-
- **WiFi scan domain layer (ADR-022/025)** — 8-stage pure-Rust signal intelligence pipeline for Windows, macOS, and Linux WiFi RSSI
1328-
- **New crates** — `wifi-densepose-vitals` (1,863 lines) and `wifi-densepose-wifiscan` (4,829 lines)
1352+
- **8-phase DensePose training pipeline (ADR-023)** — Graph transformer, 6-term composite loss, SONA adaptation, RVF packaging
1353+
- **Vital sign detection (ADR-021)** — FFT-based breathing (6-30 BPM) and heartbeat (40-120 BPM), 11,665 fps
1354+
- **WiFi scan domain layer (ADR-022/025)** — 8-stage signal intelligence pipeline for Windows, macOS, and Linux
13291355
- **542+ Rust tests** — All passing, zero mocks
13301356

1331-
### v2.2.0 — 2026-02-28
1332-
1333-
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.
1334-
1335-
- **Guided installer** — `./install.sh` with 7-step hardware detection and 8 install profiles
1336-
- **6 SOTA signal algorithms (ADR-014)** — SpotFi conjugate multiplication, Hampel filter, Fresnel zone model, CSI spectrogram, subcarrier selection, body velocity profile
1337-
- **WiFi-Mat disaster response** — START triage, scan zones, 3D localization, priority alerts — 139 tests
1338-
- **ESP32 CSI hardware parser** — Binary frame parsing with I/Q extraction — 28 tests
1339-
- **Security hardening** — 10 vulnerabilities fixed (CVE remediation, input validation, path security)
1340-
1341-
### v2.1.0 — 2026-02-28
1357+
### v2.0.0 — 2026-02-28
13421358

1343-
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.
1359+
Complete Rust sensing server, SOTA signal processing, WiFi-Mat disaster response, ESP32 hardware, RuVector integration, guided installer, and security hardening.
13441360

1345-
- **RuVector integration** — 11 vendored crates (ADR-002 through ADR-013) for HNSW indexing, attention, GNN, temporal compression, min-cut, solver
1346-
- **ESP32 CSI sensor mesh** — $54 starter kit with 3-6 ESP32-S3 nodes streaming at 20 Hz
1347-
- **Three.js visualization** — 3D body model with 17 joints, real-time WebSocket streaming
1348-
- **CI verification pipeline** — Determinism checks and unseeded random scan across all signal operations
1361+
- **Rust sensing server** — Axum REST API + WebSocket, 810x speedup over Python, 54K fps pipeline
1362+
- **RuVector integration** — 11 vendored crates for HNSW, attention, GNN, temporal compression, min-cut, solver
1363+
- **6 SOTA signal algorithms (ADR-014)** — SpotFi, Hampel, Fresnel, spectrogram, subcarrier selection, BVP
1364+
- **WiFi-Mat disaster response** — START triage, 3D localization, priority alerts — 139 tests
1365+
- **ESP32 CSI hardware** — Binary frame parsing, $54 starter kit, 20 Hz streaming
1366+
- **Guided installer** — 7-step hardware detection, 8 install profiles
1367+
- **Three.js visualization** — 3D body model, 17 joints, real-time WebSocket
1368+
- **Security hardening** — 10 vulnerabilities fixed
13491369

13501370
</details>
13511371

0 commit comments

Comments
 (0)