vrr/Ruview
2
0
Fork 0
mirror of https://github.com/ruvnet/RuView.git synced 2026-05-19 08:10:07 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 12

docs: update README + user guide with v0.5.4 capabilities

Browse source 
README:
- Test badge 1300+ → 1463
- Updated capability table (171K emb/s, 100% presence, 0.012ms)
- Added "What's New in v0.5.4" section with full benchmark table
- Training pipeline quick start commands

User guide:
- Camera-Free Pose Training section (10 sensor signals, 5-phase pipeline)
- ruvllm Training Pipeline section (5 phases, quantization options)
- Publishing to HuggingFace section
- Updated table of contents

Co-Authored-By: claude-flow <ruv@ruv.net>
This commit is contained in:
ruv 2026-04-02 23:11:30 -04:00
parent ba82fcfc37
commit 73d4cb9fc2
2 changed files with 173 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

67
README.md
View file

@ -40,7 +40,7 @@ In practice this means ordinary environments gain a new kind of spatial awarenes
[![Rust 1.85+](https://img.shields.io/badge/rust-1.85+-orange.svg)](https://www.rust-lang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests: 1300+](https://img.shields.io/badge/tests-1300%2B-brightgreen.svg)](https://github.com/ruvnet/RuView)
[![Tests: 1463](https://img.shields.io/badge/tests-1463%20passed-brightgreen.svg)](https://github.com/ruvnet/RuView)
[![Docker: multi-arch](https://img.shields.io/badge/docker-amd64%20%2B%20arm64-blue.svg)](https://hub.docker.com/r/ruvnet/wifi-densepose)
[![Vital Signs](https://img.shields.io/badge/vital%20signs-breathing%20%2B%20heartbeat-red.svg)](#vital-sign-detection)
[![ESP32 Ready](https://img.shields.io/badge/ESP32--S3-CSI%20streaming-purple.svg)](#esp32-s3-hardware-pipeline)
@ -49,11 +49,13 @@ In practice this means ordinary environments gain a new kind of spatial awarenes
> | 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 |
> | **Pose estimation** | CSI subcarrier amplitude/phase → 17 COCO keypoints | 171K emb/s (M4 Pro) |
> | **Breathing detection** | Bandpass 0.1-0.5 Hz → zero-crossing BPM | 6-30 BPM |
> | **Heart rate** | Bandpass 0.8-2.0 Hz → zero-crossing BPM | 40-120 BPM |
> | **Presence sensing** | Trained model + PIR fusion — 100% accuracy | 0.012 ms latency |
> | **Through-wall** | Fresnel zone geometry + multipath modeling | Up to 5m depth |
> | **Edge intelligence** | 8-dim feature vectors + RVF store on Cognitum Seed | $27 total BOM |
> | **Camera-free training** | 10 sensor signals, no labels needed | 84s on M4 Pro |
```bash
# 30 seconds to live sensing — no toolchain required
@ -78,6 +80,61 @@ docker run -p 3000:3000 ruvnet/wifi-densepose:latest
>
---
### What's New in v0.5.4
<details open>
<summary><strong>Cognitum Seed Integration + Camera-Free Pose Training</strong></summary>
**v0.5.4 transforms RuView from a real-time sensing tool into a persistent edge AI system.** Your ESP32 now remembers what it senses, learns without cameras, and proves its data cryptographically.
| Capability | Details | Hardware |
|-----------|---------|----------|
| **Persistent vector store** | Every sensing event stored as searchable 8-dim vector in RVF format | ESP32 + [Cognitum Seed](https://cognitum.one) ($27) |
| **kNN similarity search** | "Find the 10 most similar states to right now" — anomaly detection, fingerprinting | Cognitum Seed |
| **Witness chain** | SHA-256 tamper-evident audit trail for every measurement (1,747 entries validated) | Cognitum Seed |
| **Camera-free pose training** | 17 COCO keypoints from 10 sensor signals — PIR, RSSI triangulation, subcarrier asymmetry, vibration, BME280 | 2x ESP32 + Seed |
| **Pre-trained model** | 82.8 KB (8 KB at 4-bit quantization), 100% presence accuracy, 0 skeleton violations | Download from release |
| **Sub-ms inference** | 0.012 ms latency, 171,472 embeddings/sec on M4 Pro | Any machine with Node.js |
| **SONA adaptation** | Adapts to new rooms in <1ms without retraining | ruvllm runtime |
| **LoRA room adapters** | Per-node fine-tuning with 2,048 parameters per adapter | Automatic |
| **114-tool MCP proxy** | AI assistants (Claude, GPT) query sensors directly via JSON-RPC | Cognitum Seed |
| **Security hardened** | Bearer tokens, TLS, source IP filtering, NaN rejection, credential rotation | All components |
**Training pipeline (ruvllm, no PyTorch needed):**
```bash
# Collect data (2 min, ESP32s must be streaming)
python scripts/collect-training-data.py --port 5006 --duration 120
# Train — contrastive pretraining + task heads + LoRA + quantization + EWC
node scripts/train-ruvllm.js --data data/recordings/pretrain-*.csi.jsonl
# Camera-free 17-keypoint pose (uses PIR + RSSI + vibration + subcarrier asymmetry)
node scripts/train-camera-free.js --data data/recordings/pretrain-*.csi.jsonl
# Benchmark
node scripts/benchmark-ruvllm.js --model models/csi-ruvllm
```
**Validated benchmarks (M4 Pro):**
| Metric | Value |
|--------|-------|
| Training time | 84.4s (2,360 augmented samples) |
| Contrastive improvement | 33.9% |
| Presence accuracy | 100% |
| Inference latency | 0.012 ms |
| Throughput | 171,472 emb/s |
| Model size (4-bit) | 8 KB |
| Skeleton violations | 0 / 100 frames |
| Rust tests | 1,463 passed |
See [ADR-069](docs/adr/ADR-069-cognitum-seed-csi-pipeline.md), [ADR-071](docs/adr/ADR-071-ruvllm-training-pipeline.md), and the [Cognitum Seed tutorial](docs/tutorials/cognitum-seed-pretraining.md) for full details.
</details>
---
## 📖 Documentation
| Document | Description |

112
docs/user-guide.md
View file

@ -38,7 +38,10 @@ WiFi DensePose turns commodity WiFi signals into real-time human pose estimation
14. [Hardware Setup](#hardware-setup)
- [ESP32-S3 Mesh](#esp32-s3-mesh)
- [Intel 5300 / Atheros NIC](#intel-5300--atheros-nic)
15. [Docker Compose (Multi-Service)](#docker-compose-multi-service)
15. [Camera-Free Pose Training](#camera-free-pose-training)
16. [ruvllm Training Pipeline](#ruvllm-training-pipeline)
17. [Publishing to HuggingFace](#publishing-to-huggingface)
18. [Docker Compose (Multi-Service)](#docker-compose-multi-service)
16. [Testing Firmware Without Hardware (QEMU)](#testing-firmware-without-hardware-qemu)
- [What You Need](#what-you-need)
- [Your First Test Run](#your-first-test-run)
@ -1008,6 +1011,113 @@ These are advanced setups. See the respective driver documentation for installat
---
## Camera-Free Pose Training
RuView can train a 17-keypoint COCO pose model **without any camera** by fusing 10 sensor signals from the ESP32 nodes and Cognitum Seed:
| Signal | Source | What it provides |
|--------|--------|-----------------|
| PIR sensor | Seed GPIO 6 | Binary presence ground truth |
| BME280 temperature | Seed I2C | Occupancy proxy (temp rises with people) |
| BME280 humidity | Seed I2C | Breathing confirmation |
| Cross-node RSSI | 2x ESP32 | Rough XY position (triangulation) |
| Vitals stability | ESP32 DSP | Activity level (stable HR = stationary) |
| Temporal CSI patterns | ESP32 DSP | Walk (periodic), sit (stable), empty (flat) |
| kNN clusters | Seed vector store | Natural state groupings |
| Boundary fragility | Seed graph analysis | Regime changes (enter/exit) |
| Reed switch | Seed GPIO 5 | Door open/close events |
| Vibration sensor | Seed GPIO 13 | Footstep detection |
### How It Works
The pipeline generates weak labels from sensor fusion, then trains in 5 phases:
1. **Multi-modal collection** — Syncs CSI frames with Seed sensor events
2. **Weak label generation** — RSSI triangulation for head position, subcarrier asymmetry for hands, vibration for feet
3. **5-keypoint pose proxy** — Trains head/hands/feet positions from fused signals
4. **17-keypoint interpolation** — Derives full COCO skeleton using bone length constraints
5. **Self-refinement** — Bootstraps from confident predictions (3 rounds)
```bash
# With Cognitum Seed connected (all 10 signals):
node scripts/train-camera-free.js \
--data data/recordings/pretrain-*.csi.jsonl \
--seed-url https://169.254.42.1:8443 \
--seed-token "$SEED_TOKEN"
# Without Seed (CSI-only, 3 signals — still works):
node scripts/train-camera-free.js \
--data data/recordings/pretrain-*.csi.jsonl --no-seed
```
**Output:** 82.8 KB model (8 KB at 4-bit) with 17-keypoint predictions, 0 skeleton violations, LoRA per-node adapters, and EWC protection against forgetting.
See [ADR-071](adr/ADR-071-ruvllm-training-pipeline.md) and the [pretraining tutorial](tutorials/cognitum-seed-pretraining.md) for the full walkthrough.
---
## ruvllm Training Pipeline
All training uses **ruvllm** — a Rust-native ML runtime. No Python, no PyTorch, no GPU drivers required. Runs on any machine with Node.js.
### 5-Phase Training
| Phase | What | Duration (M4 Pro) |
|-------|------|--------------------|
| Contrastive pretraining | Triplet + InfoNCE loss on CSI embeddings | ~5s |
| Task head training | Presence, activity, vitals classifiers | ~10s |
| LoRA refinement | Per-node room adaptation (rank-4) | ~4s |
| TurboQuant quantization | 2/4/8-bit with <0.5% quality loss | <1s |
| EWC consolidation | Prevent catastrophic forgetting | <1s |
```bash
# Basic training
node scripts/train-ruvllm.js --data data/recordings/pretrain-*.csi.jsonl
# Benchmark
node scripts/benchmark-ruvllm.js --model models/csi-ruvllm
```
### Quantization Options
| Bits | Size | Compression | Quality Loss | Use Case |
|------|------|-------------|-------------|----------|
| fp32 | 48 KB | 1x | 0% | Development |
| 8-bit | 16 KB | 4x | <0.01% | Cognitum Seed inference |
| 4-bit | 8 KB | 8x | <0.1% | Recommended for deployment |
| 2-bit | 4 KB | 16x | <1% | ESP32-S3 SRAM (edge inference) |
### Key Features
- **SONA adaptation** — Adapts to new rooms in <1ms without retraining
- **LoRA adapters** — 2,048 parameters per room, hot-swappable
- **EWC protection** — Learns new rooms without forgetting previous ones
- **Deterministic** — Same seed always produces same model (reproducible)
- **10x data augmentation** — Temporal interpolation, noise injection, cross-node blending
---
## Publishing to HuggingFace
Trained models can be published to HuggingFace Hub for community use:
```bash
# Publish (uses API key from GCloud Secrets)
bash scripts/publish-huggingface.sh --version v0.5.4
# Or with Python
python scripts/publish-huggingface.py --version v0.5.4
# Dry run (preview without uploading)
bash scripts/publish-huggingface.sh --dry-run
```
The HuggingFace API key is stored in Google Cloud Secrets (`HUGGINGFACE_API_KEY` in project `cognitum-20260110`). Alternatively, set the `SEED_TOKEN` environment variable directly.
Published artifacts include: SafeTensors model, quantized variants (2/4/8-bit), LoRA adapters, training metrics, and a beginner-friendly model card.
---
## Docker Compose (Multi-Service)
For production deployments with both Rust and Python services: