diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ea90138f3..5b226914b5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **`--export-rvf` no longer silently produces a placeholder model — PR #920.** The `--export-rvf` handler ran *before* `--train`/`--pretrain` and unconditionally wrote placeholder sine-wave weights, so the documented `--train … --export-rvf ` workflow short-circuited to a fake model and never trained (while printing "exported successfully"). It now emits the placeholder **container-format demo** only standalone (with a clear warning), and falls through to real training when `--train`/`--pretrain` is set; docs point to `--save-rvf` for the real model. 3 guard tests. ### Added +- **Beginner-Friendly Quick Start Setup Flow Diagram — #951.** Added a visual Mermaid flowchart to `README.md` and `docs/readme-details.md` that guides new users and contributors through the setup options: Docker simulation, Python library integration, or live WiFi sensing using ESP32-S3/C6 hardware, optionally integrated with the Cognitum Seed system. - **ADR-151 per-room calibration & specialist training — full `baseline → enroll → extract → train` pipeline (new `wifi-densepose-calibration` crate).** "Teach the room before you teach the model": a local-first pipeline that turns a few minutes of clean human anchors — layered on the ADR-135 empty-room baseline — into a versioned bank of small, room-calibrated specialists for **presence, posture, breathing, heartbeat, restlessness, and anomaly**. Stages: guided enrollment with an adaptive quality gate (event-sourced `EnrollmentSession`, re-prompts bad anchors); feature extraction (autocorrelation periodicity in breathing/HR bands + variance/motion); six small specialists (learned threshold / nearest-prototype / band-limited periodicity / novelty); a `SpecialistBank` with baseline-drift **STALE** invalidation; and a `MixtureOfSpecialists` runtime with presence short-circuit + anomaly veto + confidence gating. Specialists are statistical heads today (runnable + hardware-validated); the frozen ADR-150 HF RF Foundation Encoder backbone is the documented upgrade path. - **CLI:** `enroll` / `train-room` / `room-status` / `room-watch`, plus the Stage-1 `calibrate-serve` HTTP API (CORS-enabled: `POST /start`, `GET /status`, `POST /stop`, `GET /result`, `GET /baselines`, `GET /health`) and a firewall-free `scripts/csi-udp-relay.py` for local Windows ESP32 testing without admin. - **Multistatic fusion (ADR-029):** `MultiNodeMixture` fuses several co-located nodes (each with its own room-calibrated bank) into one room state — presence OR'd across nodes, posture/breathing/heartbeat from the highest-confidence node, a single implausible node vetoes the room's vitals. Driven via `room-watch --node-bank N:path` (repeatable), which groups live frames by `node_id` and fuses. Same-room only; cross-room is federation (ADR-105). diff --git a/README.md b/README.md index 7451e30ddc..e7eafeccd0 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,55 @@ RuView turns ordinary WiFi into a contactless sensor. A $9 ESP32 board reads the > > 🤗 **Pretrained weights**: download from [`ruvnet/wifi-densepose-pretrained`](https://huggingface.co/ruvnet/wifi-densepose-pretrained) — see [Loading the pretrained model](#loading-the-pretrained-model) below for one-command setup. +## 🗺️ Quick Start Setup Flow + +Choose your path to get started with RuView: + +```mermaid +graph TD + classDef default fill:#1e1e2e,stroke:#cdd6f4,stroke-width:1px,color:#cdd6f4; + classDef highlight fill:#f9e2af,stroke:#f9e2af,stroke-width:2px,color:#11111b; + classDef action fill:#a6e3a1,stroke:#a6e3a1,stroke-width:1px,color:#11111b; + + Start([Start: Choose Your Goal]):::highlight + Start --> Goal{What is your goal?} + + %% Goal paths + Goal -->|"Evaluation / Testing"| Docker["Option 1: Docker Simulation"] + Goal -->|"Python Library Integration"| Python["Option 4: Python PyPI Package"] + Goal -->|"Live WiFi Sensing"| SelectHW["Option 2/3: Live WiFi Sensing"] + + %% Docker path + Docker --> DockRun["Run: docker run -p 3000:3000 ruvnet/wifi-densepose:latest"]:::action + DockRun --> ViewSim["View simulated data at http://localhost:3000"]:::action + + %% Python path + Python --> PyInstall["Run: pip install ruview"]:::action + PyInstall --> PyCode["Integrate Breathing/HeartRate extractors in your code"]:::action + PyCode --> ViewOutput["Analyze/visualize CSI features"]:::action + + %% Live Sensing / HW path + SelectHW --> HWChoice{Choose ESP32 Chip} + HWChoice -->|ESP32-S3| S3Node["Option 2a: ESP32-S3 Node"] + HWChoice -->|ESP32-C6| C6Node["Option 2b: ESP32-C6 WiFi 6 Node"] + + S3Node --> Flash["Flash Firmware (esptool / idf.py)"]:::action + C6Node --> Flash + + Flash --> Prov["Provision WiFi (provision.py)"]:::action + Prov --> SeedChoice{Do you have a Cognitum Seed?} + + %% Seed choice + SeedChoice -->|Yes| Seed["Option 3: Full Cognitum System"] + SeedChoice -->|No| Mesh["ESP32 Mesh Mode"] + + Seed --> SeedProc["Run: node scripts/rf-scan.js / processors"]:::action + SeedProc --> ViewUI["View live pose & vitals in RuView UI"]:::action + + Mesh --> MeshDirect["Connect ESP32 directly to sensing-server / browser"]:::action + MeshDirect --> ViewUI +``` + ```bash # Option 1: Docker (simulated data, no hardware needed) docker pull ruvnet/wifi-densepose:latest diff --git a/docs/readme-details.md b/docs/readme-details.md index 281498ba75..ef67b00bee 100644 --- a/docs/readme-details.md +++ b/docs/readme-details.md @@ -472,6 +472,53 @@ All crates integrate with [RuVector v2.0.4](https://github.com/ruvnet/ruvector) ## 🚀 Quick Start +Choose your setup path based on your goal: + +```mermaid +graph TD + classDef default fill:#1e1e2e,stroke:#cdd6f4,stroke-width:1px,color:#cdd6f4; + classDef highlight fill:#f9e2af,stroke:#f9e2af,stroke-width:2px,color:#11111b; + classDef action fill:#a6e3a1,stroke:#a6e3a1,stroke-width:1px,color:#11111b; + + Start([Start: Choose Your Goal]):::highlight + Start --> Goal{What is your goal?} + + %% Goal paths + Goal -->|"Evaluation / Testing"| Docker["Option 1: Docker Simulation"] + Goal -->|"Python Library Integration"| Python["Option 4: Python PyPI Package"] + Goal -->|"Live WiFi Sensing"| SelectHW["Option 2/3: Live WiFi Sensing"] + + %% Docker path + Docker --> DockRun["Run: docker run -p 3000:3000 ruvnet/wifi-densepose:latest"]:::action + DockRun --> ViewSim["View simulated data at http://localhost:3000"]:::action + + %% Python path + Python --> PyInstall["Run: pip install ruview"]:::action + PyInstall --> PyCode["Integrate Breathing/HeartRate extractors in your code"]:::action + PyCode --> ViewOutput["Analyze/visualize CSI features"]:::action + + %% Live Sensing / HW path + SelectHW --> HWChoice{Choose ESP32 Chip} + HWChoice -->|ESP32-S3| S3Node["Option 2a: ESP32-S3 Node"] + HWChoice -->|ESP32-C6| C6Node["Option 2b: ESP32-C6 WiFi 6 Node"] + + S3Node --> Flash["Flash Firmware (esptool / idf.py)"]:::action + C6Node --> Flash + + Flash --> Prov["Provision WiFi (provision.py)"]:::action + Prov --> SeedChoice{Do you have a Cognitum Seed?} + + %% Seed choice + SeedChoice -->|Yes| Seed["Option 3: Full Cognitum System"] + SeedChoice -->|No| Mesh["ESP32 Mesh Mode"] + + Seed --> SeedProc["Run: node scripts/rf-scan.js / processors"]:::action + SeedProc --> ViewUI["View live pose & vitals in RuView UI"]:::action + + Mesh --> MeshDirect["Connect ESP32 directly to sensing-server / browser"]:::action + MeshDirect --> ViewUI +``` +
First API call in 3 commands