mirror of
https://github.com/ruvnet/RuView
synced 2026-08-02 19:11:46 +00:00
Compare commits
3 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 ruv
|
42492e14a5 | ||
|
ruv
|
7309458b40 | ||
|
ruv
|
b77b682a6b |
@@ -6,10 +6,15 @@
|
||||
</a>
|
||||
</p>
|
||||
<p align="center">
|
||||
<a href="https://cognitum.one/marketplace/musica">
|
||||
<a href="https://cognitum.one/marketplace">
|
||||
<img src="assets/musica-promo.png" alt="Cognitum Musica" width="100%">
|
||||
</a>
|
||||
</p>
|
||||
<p align="center">
|
||||
<a href="https://github.com/ruvnet/RuCelium">
|
||||
<img src="assets/rucelium-hero.png" alt="RuCelium — environmental intelligence" width="100%">
|
||||
</a>
|
||||
</p>
|
||||
|
||||
## **See through walls with WiFi** ##
|
||||
|
||||
@@ -32,6 +37,43 @@ Every WiFi router already fills your space with radio waves. When people move, b
|
||||
- **Environment mapping** — RF fingerprinting identifies rooms, detects moved furniture, spots new objects
|
||||
- **Sleep quality** — overnight monitoring with sleep stage classification and apnea screening
|
||||
|
||||
**Also included:**
|
||||
|
||||
- **Camera-free pose** — estimate 17 body keypoints from WiFi CSI
|
||||
- **Built-in model workflow** — record CSI, train models, load RVF files, and switch LoRA profiles
|
||||
- **Local automation** — HOMECORE provides state, history, automations, signed Wasm plugins, voice hooks, and HomeKit support
|
||||
- **Unified RF world model** — combine WiFi CSI, radar, UWB, and cellular sensing in one privacy-bounded scene model; accuracy is still synthetic until real-data validation
|
||||
- **Governed evidence** — attach privacy policy, uncertainty, provenance, and witness records to sensing events
|
||||
- **RuView MetaHarness** — use an AI operator to onboard, calibrate, train, verify, and check sensing claims
|
||||
|
||||
<details>
|
||||
<summary><strong>RuView MetaHarness</strong> — guided operation for humans and AI agents</summary>
|
||||
|
||||
The RuView-specific metaharness we created is published as [`@ruvnet/ruview`](harness/ruview/README.md). It provides source-cited guidance, guarded Claude Code/Codex agents, deterministic verification, and an honesty check for accuracy claims.
|
||||
|
||||
```bash
|
||||
# Check the local setup and get source-cited guidance
|
||||
npx @ruvnet/ruview@0.3.1 doctor
|
||||
npx @ruvnet/ruview@0.3.1 guidance --topic sensing --query "model loading"
|
||||
|
||||
# Run a read-only RuView agent through Codex
|
||||
npx @ruvnet/ruview@0.3.1 agent run --host codex --repo . \
|
||||
--prompt "Find the nearest tests and cite the source files"
|
||||
|
||||
# Search or verify the reviewed contributor brain
|
||||
npx @ruvnet/ruview@0.3.1 brain search --query "calibration"
|
||||
npx @ruvnet/ruview@0.3.1 brain verify --repo .
|
||||
|
||||
# Check claims, replay the deterministic proof, or expose the MCP server
|
||||
npx @ruvnet/ruview@0.3.1 claim-check --file REPORT.md
|
||||
npx @ruvnet/ruview@0.3.1 verify
|
||||
npx @ruvnet/ruview@0.3.1 mcp start
|
||||
```
|
||||
|
||||
Agent runs are read-only by default. Workspace writes require both `--allow-write` and `--confirm`; retrieved brain content is evidence, not authority.
|
||||
|
||||
</details>
|
||||
|
||||
Built on [RuVector](https://github.com/ruvnet/ruvector/) and [Cognitum Seed](https://cognitum.one), RuView runs entirely on edge hardware — an ESP32 mesh (as low as $9 per node) paired with a Cognitum Seed for persistent memory, cryptographic attestation, and AI integration. No cloud, no cameras, no internet required.
|
||||
|
||||
The system learns each environment locally using spiking neural networks that adapt in under 30 seconds, with multi-frequency mesh scanning across 6 WiFi channels that uses your neighbors' routers as free radar illuminators. Every measurement is cryptographically attested via an Ed25519 witness chain.
|
||||
@@ -74,6 +116,9 @@ 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.
|
||||
|
||||
<details>
|
||||
<summary><strong>Quick start options</strong> — Docker, ESP32-S3/C6, Cognitum Seed, and Python</summary>
|
||||
|
||||
```bash
|
||||
# Option 1: Docker (simulated data, no hardware needed)
|
||||
docker pull ruvnet/wifi-densepose:latest
|
||||
@@ -119,6 +164,8 @@ pip install "ruview[client]" # or: pip install "wifi-densepose[clie
|
||||
# from ruview.client import SensingClient, RuViewMqttClient
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
[](https://pypi.org/project/ruview/) [](https://pypi.org/project/wifi-densepose/)
|
||||
|
||||
> [!NOTE]
|
||||
@@ -130,7 +177,7 @@ pip install "ruview[client]" # or: pip install "wifi-densepose[clie
|
||||
> |--------|----------|------|----------|-------------|
|
||||
> | **ESP32 + Cognitum Seed** (recommended) | ESP32-S3 + [Cognitum Seed](https://cognitum.one) | ~$140 | Yes | Presence, motion, breathing, heart rate, fall detection, multi-person counting, 17-keypoint pose (signed Cog binary — first-cut on-device model, see [Model weights: what's real, what's not](#model-weights-whats-real-whats-not)), 105-cog catalog, persistent vector store, kNN search, witness chain, MCP proxy |
|
||||
> | **ESP32 Mesh** | 3-6× ESP32-S3 + WiFi router | ~$54 | Yes | Same capabilities as above without the persistent-memory features |
|
||||
> | **ESP32-C6 research node** ([ADR-110](docs/adr/ADR-110-esp32-c6-firmware-extension.md), [witness](docs/WITNESS-LOG-110.md), [reviewer guide](docs/ADR-110-REVIEW-GUIDE.md), [firmware v0.7.0](https://github.com/ruvnet/RuView/releases/tag/v0.7.0-esp32)) | ESP32-C6-DevKit ($6–10) | ~$10 | Yes (Wi-Fi 6 capable) | Same CSI pipeline as S3 with the dual-target firmware. **Firmware-side ADR-110 substrate now closed** (v0.7.0): ESP-NOW cross-board mesh quantified at **99.56 % match / 104 µs smoothed offset stdev / 3.95× EMA suppression** over a 5-min two-board soak (witness §A0.10), 32-byte UDP sync packet with operator-tunable cadence (§A0.12), ADR-018 byte 19 bit 4 wire-fix sourced from the working ESP-NOW path (§A0.13). Wire format ready for HE-LTF PPDU tagging in ADR-018 bytes 18-19 (firmware encoder + Rust + Python decoders verified end-to-end across 23 unit tests). LP-core motion-gate RISC-V program and Wi-Fi 6 soft-AP with TWT Responder both ship as opt-in code paths (default off). **Hardware-gated for measurement**: HE-LTF live subcarrier capture needs an 11ax AP (IDF v5.4 doesn't expose AP-side HE config — §A0.6); ~5 µA LP-core hibernation needs an INA meter to capture; 802.15.4 raw RX is broken in IDF v5.4 (workaround: ESP-NOW transport, shipped + measured). See witness log for the empirical / claimed split. |
|
||||
> | **ESP32-C6 research node** ([ADR-110](docs/adr/ADR-110-esp32-c6-firmware-extension.md), [witness](docs/WITNESS-LOG-110.md), [reviewer guide](docs/ADR-110-REVIEW-GUIDE.md), [firmware v0.7.0](https://github.com/ruvnet/RuView/releases/tag/v0.7.0-esp32)) | ESP32-C6-DevKit ($6–10) | ~$10 | Yes (Wi-Fi 6 capable) | Dual-target CSI with **99.56% measured ESP-NOW sync match** and measured HE-LTF capture on IDF 5.5.2. TWT and ~5 µA operation still need hardware validation. |
|
||||
> | **Research NIC** | Intel 5300 / Atheros AR9580 | ~$50-100 | Yes | Full CSI with 3x3 MIMO |
|
||||
> | **Qualcomm CSI beta** ([ADR-268](docs/adr/ADR-268-qualcomm-atheros-csi-platform.md)) | QCA9300 now; QCN9074/QCN9274 experimental | ~$30-200 | Simulator now; hardware adapter gated | Rust `QCS1` codec, deterministic replay, UDP/API integration; modern ath11k/ath12k profiles do not claim public CSI export |
|
||||
> | **Vendor provider beta** ([ADR-270](docs/adr/ADR-270-vendor-rf-sensing-integration-program.md)) | Origin, Plume, Mist, NETGEAR, Electric Imp, RF Solutions, Luma, Nest, Linksys, Wifigarden | Varies | Capability-dependent | Bounded Rust adapters and deterministic fixtures; telemetry/network-only/unsupported states cannot masquerade as CSI |
|
||||
@@ -178,9 +225,9 @@ huggingface-cli download ruvnet/wifi-densepose-pretrained --local-dir models/wif
|
||||
|----------|-------------|--------|
|
||||
| Python training / evaluation / embedding extraction | `model.safetensors` | ✅ Works — load with `safetensors.torch.load_file` |
|
||||
| Inspect / re-export the bundle | `model.rvf.jsonl` (line-by-line JSON) | ✅ Works — plain JSONL |
|
||||
| Sensing-server `--model <PATH>` flag | binary RVF (`RVFS` magic) | ⚠️ Loader does not yet accept the JSONL container |
|
||||
| Sensing-server `--model <PATH>` flag | native RVF, `model.safetensors`, or `model.rvf.jsonl` | ✅ Native RVF loads directly; safetensors and JSONL auto-convert in memory |
|
||||
|
||||
**Known gap:** the HF model ships in JSONL RVF format, but `v2/crates/wifi-densepose-sensing-server/src/rvf_container.rs` only parses the binary RVF segment format. Pointing `--model` at `model.rvf.jsonl` currently errors with `invalid magic at offset 0: expected 0x52564653, got 0x7974227B` and the live pipeline degrades to null output rather than falling back to heuristic mode — so for the live sensing-server, run **without** `--model` until a JSONL adapter lands (or the model is re-published as binary RVF). Use the weights from Python / training in the meantime.
|
||||
**Loader scope:** `--model` now accepts native RVF and auto-converts the published safetensors or JSONL files. The quantized `model-q*.bin` files still need a compatible reader, and loading weights does not supply the matching pose-decoder architecture or establish end-to-end pose accuracy.
|
||||
|
||||
**Quantization choices** (all in the HF repo): `model-q2.bin` (4 KB) · `model-q4.bin` ⭐ recommended (8 KB) · `model-q8.bin` (16 KB) · `model.safetensors` full (48 KB)
|
||||
|
||||
@@ -188,6 +235,11 @@ The separate **17-keypoint pose-estimation model** is now published at [`ruvnet/
|
||||
|
||||
### Results & proof
|
||||
|
||||
See the measured benchmarks, witness records, and one-command reproducibility check.
|
||||
|
||||
<details>
|
||||
<summary><strong>View benchmark and proof details</strong></summary>
|
||||
|
||||
| What | Where | Numbers |
|
||||
|------|-------|---------|
|
||||
| **MM-Fi pose model (SOTA)** | [`ruvnet/wifi-densepose-mmfi-pose`](https://huggingface.co/ruvnet/wifi-densepose-mmfi-pose) | 82.69% torso-PCK@20 (single) · 83.59% (ensemble+TTA) · 75K-param micro variant 74.30% |
|
||||
@@ -206,8 +258,15 @@ python archive/v1/data/proof/verify.py
|
||||
|
||||
Tracked in [#509](https://github.com/ruvnet/RuView/issues/509); see [ADR-079](docs/adr/ADR-079-camera-ground-truth-training.md) phases P7–P9 for the camera-supervised fine-tune path.
|
||||
|
||||
</details>
|
||||
|
||||
### Model weights: what's real, what's not
|
||||
|
||||
See which checkpoints are validated, experimental, or architecture-only.
|
||||
|
||||
<details>
|
||||
<summary><strong>View model maturity details</strong></summary>
|
||||
|
||||
"WiFi → pose" means three different things in this repo, at three different maturity
|
||||
levels. Read the label, not the headline ([ADR-187](docs/adr/ADR-187-archive-v1-deprecation-honest-labeling.md)):
|
||||
|
||||
@@ -225,13 +284,17 @@ project can stand behind today is the **MM-Fi benchmark number**, not a live sin
|
||||
number. The path to a first *reproducible* on-device baseline (PCK@20 ≥ 35%) is tracked in
|
||||
[ADR-079](docs/adr/ADR-079-camera-ground-truth-training.md) / [#645](https://github.com/ruvnet/RuView/issues/645) — do not advertise the live single-ESP32 17-keypoint feature without the "first-cut, below-target, runtime-stub" caveat until that baseline is measured.
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
## 🧩 Edge Module Catalog
|
||||
|
||||
<details>
|
||||
<summary><b>🧩 105 edge modules ready to install on a Cognitum appliance</b> — live catalog from <code>app-registry.json</code> v2.1.0 (updated 2026-05-13). Browse + install at <a href="https://seed.cognitum.one/store">seed.cognitum.one/store</a> or your local appliance <code>http://<appliance>:9000/cogs</code>.</summary>
|
||||
Add signed modules for health, security, buildings, industry, research, AI, and more.
|
||||
|
||||
Each module is a small signed binary (~400 KB) that runs alongside the WiFi-DensePose sensing stack on a Cognitum-V0 appliance. The catalog updates over the air — your appliance fetches it via <code>GET /api/v1/edge/registry</code> ([ADR-102](docs/adr/ADR-102-edge-module-registry.md)) and verifies each binary against an Ed25519 signature ([ADR-100](docs/adr/ADR-100-cog-packaging-specification.md)) before install.
|
||||
<details>
|
||||
<summary><strong>Browse the full edge module catalog</strong></summary>
|
||||
|
||||
Browse and install modules at [seed.cognitum.one/store](https://seed.cognitum.one/store) or on your appliance at `http://<appliance>:9000/cogs`. Each module is a small signed binary that runs beside the sensing stack. The appliance updates the catalog over the air and verifies every module before installation ([ADR-100](docs/adr/ADR-100-cog-packaging-specification.md), [ADR-102](docs/adr/ADR-102-edge-module-registry.md)).
|
||||
|
||||
### 🫀 Health — <sub>14 modules</sub>
|
||||
|
||||
@@ -514,8 +577,12 @@ These scenarios exploit WiFi's ability to penetrate solid materials — concrete
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Self-Learning WiFi AI
|
||||
|
||||
Learn compact room fingerprints from raw CSI and adapt the model to each environment.
|
||||
|
||||
<details>
|
||||
<summary><strong>🧠 Self-Learning WiFi AI (ADR-024)</strong> — Adaptive recognition, self-optimization, and intelligent anomaly detection</summary>
|
||||
<summary><strong>View self-learning architecture and commands</strong></summary>
|
||||
|
||||
Every WiFi signal that passes through a room creates a unique fingerprint of that space. WiFi-DensePose already reads these fingerprints to track people, but until now it threw away the internal "understanding" after each reading. The Self-Learning WiFi AI captures and preserves that understanding as compact, reusable vectors — and continuously optimizes itself for each new environment.
|
||||
|
||||
@@ -598,7 +665,12 @@ See [`docs/adr/ADR-024-contrastive-csi-embedding-model.md`](docs/adr/ADR-024-con
|
||||
|
||||
## 🧩 Claude Code & Codex Plugin
|
||||
|
||||
RuView ships a [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin (and Codex prompt mirror) that wraps the whole workflow — onboarding, ESP32 setup, configuration, sensing apps, model training, advanced multistatic sensing, CLI/API/WASM, mmWave radar, and witness verification — as 9 skills, 7 `/ruview-*` commands, and 3 agents. It lives in [`plugins/ruview/`](plugins/ruview/README.md); the marketplace manifest is [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json) at the repo root.
|
||||
Use the in-repo plugin for guided setup, sensing, training, and verification in Claude Code or Codex.
|
||||
|
||||
<details>
|
||||
<summary><strong>View plugin installation and commands</strong></summary>
|
||||
|
||||
RuView's [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin and Codex prompt mirror cover onboarding, ESP32 setup, sensing apps, model training, advanced sensing, CLI/API/WASM, mmWave radar, and witness verification. The source lives in [`plugins/ruview/`](plugins/ruview/README.md); the marketplace manifest is [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json).
|
||||
|
||||
```bash
|
||||
# In Claude Code — add this repo as a plugin marketplace, then install:
|
||||
@@ -622,12 +694,19 @@ claude --plugin-dir ./plugins/ruview
|
||||
|
||||
Verify the plugin structure: `bash plugins/ruview/scripts/smoke.sh`. Full details: [`plugins/ruview/README.md`](plugins/ruview/README.md).
|
||||
|
||||
**Portable harness — `npx @ruvnet/ruview`:** a lighter, host-portable companion to the in-repo plugin, minted via [MetaHarness](https://www.npmjs.com/package/metaharness) and hardened per [ADR-182](docs/adr/ADR-182-npx-ruview-harness-via-metaharness.md). It runs **without cloning this repo** and on more hosts (Claude Code, Codex, Copilot, opencode, …), exposing the RuView operator tools (`onboard`, `verify`, `node_monitor`, `calibrate`, `node_flash`) over an MCP server — plus the project's **MEASURED-vs-CLAIMED honesty guardrail enforced in code** (`ruview.claim_check` flags untagged or retracted-"100%" accuracy claims). v0.1: the onboarding/verify/claim-check paths are tested (17/17, `verify.py` → PASS); the hardware tools are fail-closed wrappers. Try `npx @ruvnet/ruview` to onboard, or `npx @ruvnet/ruview claim-check --text "…"`. Source: [`harness/ruview/`](harness/ruview/README.md).
|
||||
For the portable RuView MetaHarness, use `npx @ruvnet/ruview@0.3.1`; the quick commands and fuller explanation are in the collapsed MetaHarness section near the top of this README and in [`harness/ruview/`](harness/ruview/README.md).
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 📖 Documentation
|
||||
|
||||
Start with the user, build, and calibration guides; expand for the full reference map.
|
||||
|
||||
<details>
|
||||
<summary><strong>Browse all documentation</strong></summary>
|
||||
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [User Guide](docs/user-guide.md) | Step-by-step guide: installation, first run, API usage, hardware setup, training |
|
||||
@@ -649,6 +728,8 @@ Verify the plugin structure: `bash plugins/ruview/scripts/smoke.sh`. Full detail
|
||||
| [Medical Examples](examples/medical/README.md) | Contactless blood pressure, heart rate, breathing rate via 60 GHz mmWave radar — $15 hardware, no wearable |
|
||||
| [Extended Documentation](docs/readme-details.md) | Latest additions, key features, installation, quick start, signal processing, training, CLI, testing, deployment, and changelog |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🚧 Beta software
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 303 KiB |
@@ -7013,11 +7013,12 @@ fn diagnose_model_load_error(path: &std::path::Path, data: &[u8], err: &str) ->
|
||||
/// HuggingFace formats when the native RVF loader rejects them (issue #894).
|
||||
///
|
||||
/// Order of operations:
|
||||
/// 1. Try the native RVF `ProgressiveLoader` (the only format with `RVFS` magic).
|
||||
/// 2. On failure, **auto-detect** the format. If it is convertible
|
||||
/// 1. **Detect the format before constructing the lazy progressive loader.**
|
||||
/// 2. Load native RVF directly (the only format with `RVFS` magic).
|
||||
/// 3. If the format is convertible
|
||||
/// (`safetensors` / `model.rvf.jsonl`), convert it in-memory to RVF and load
|
||||
/// that — so the published `model.safetensors` becomes loadable here.
|
||||
/// 3. If it is a non-convertible format (quantized blob / unknown), return the
|
||||
/// 4. If it is a non-convertible format (quantized blob / unknown), return the
|
||||
/// typed, actionable [`model_format::ModelLoadError`] message — never the
|
||||
/// opaque "invalid magic …" string.
|
||||
///
|
||||
@@ -7028,11 +7029,6 @@ fn load_or_convert_model(
|
||||
) -> Result<ProgressiveLoader, String> {
|
||||
use model_format::{convert_to_rvf, detect_format, ModelFormat};
|
||||
|
||||
// 1. Native RVF.
|
||||
if let Ok(loader) = ProgressiveLoader::new(data) {
|
||||
return Ok(loader);
|
||||
}
|
||||
|
||||
let name = path
|
||||
.file_name()
|
||||
.and_then(|n| n.to_str())
|
||||
@@ -7044,7 +7040,13 @@ fn load_or_convert_model(
|
||||
.unwrap_or("converted-model");
|
||||
|
||||
match detect_format(data, &name) {
|
||||
// 2. Convertible formats: convert in-memory, then load.
|
||||
// Native RVF is the only format passed straight to the lazy loader.
|
||||
// Detect first: ProgressiveLoader::new intentionally defers parsing and
|
||||
// can otherwise accept JSONL as an empty container until a later layer.
|
||||
ModelFormat::Rvf => ProgressiveLoader::new(data).map_err(|e| {
|
||||
model_format::classify_load_failure(data, &name, &e).to_string()
|
||||
}),
|
||||
// Convertible formats: convert in-memory, then load.
|
||||
ModelFormat::Safetensors | ModelFormat::JsonlManifest => {
|
||||
match convert_to_rvf(data, &name, model_id) {
|
||||
Ok(rvf_bytes) => {
|
||||
@@ -9098,9 +9100,19 @@ mod mqtt_bridge_tests {
|
||||
|
||||
#[cfg(test)]
|
||||
mod model_load_diagnostic_tests {
|
||||
use super::diagnose_model_load_error;
|
||||
use super::{diagnose_model_load_error, load_or_convert_model};
|
||||
use std::path::Path;
|
||||
|
||||
#[test]
|
||||
fn jsonl_model_loads_through_model_flag_path() {
|
||||
let data = b"{\"model_id\":\"published\"}\n{\"weights\":[1.0,2.0]}\n";
|
||||
let mut loader = load_or_convert_model(Path::new("model.rvf.jsonl"), data)
|
||||
.expect("--model must auto-convert JSONL");
|
||||
loader.load_layer_a().expect("Layer A");
|
||||
let layer_c = loader.load_layer_c().expect("Layer C");
|
||||
assert_eq!(layer_c.all_weights, vec![1.0, 2.0]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn safetensors_is_named_and_points_at_894() {
|
||||
// 8-byte LE header length then '{' — the safetensors signature.
|
||||
|
||||
Reference in New Issue
Block a user