From 27d17431c50d6def788cbe0d85420a3c7c5e4143 Mon Sep 17 00:00:00 2001 From: ruv Date: Thu, 2 Apr 2026 19:48:01 -0400 Subject: [PATCH] docs: update README and user guide with Cognitum Seed integration - Add ESP32 + Cognitum Seed as recommended hardware option ($27 BOM) - Add v0.5.4-esp32 to firmware release table - Add Cognitum Seed setup section to user guide with bridge usage, feature vector dimensions, and architecture diagram - Update table of contents Co-Authored-By: claude-flow --- README.md | 34 +++++++++++++++++++++-- docs/user-guide.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 99 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index de0546e0..391c3dd1 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,8 @@ docker run -p 3000:3000 ruvnet/wifi-densepose:latest > > | Option | Hardware | Cost | Full CSI | Capabilities | > |--------|----------|------|----------|-------------| -> | **ESP32 Mesh** (recommended) | 3-6x ESP32-S3 + WiFi router | ~$54 | Yes | Pose, breathing, heartbeat, motion, presence | +> | **ESP32 + Cognitum Seed** (recommended) | ESP32-S3 + Cognitum Seed (Pi Zero 2 W) | ~$27 | Yes | Pose, breathing, heartbeat, motion, presence + persistent vector store, kNN search, witness chain, MCP proxy | +> | **ESP32 Mesh** | 3-6x ESP32-S3 + WiFi router | ~$54 | Yes | Pose, breathing, heartbeat, motion, presence | > | **Research NIC** | Intel 5300 / Atheros AR9580 | ~$50-100 | Yes | Full CSI with 3x3 MIMO | > | **Any WiFi** | Windows, macOS, or Linux laptop | $0 | No | RSSI-only: coarse presence and motion | > @@ -1057,7 +1058,8 @@ Download a pre-built binary — no build toolchain needed: | Release | What's included | Tag | |---------|-----------------|-----| -| [v0.5.0](https://github.com/ruvnet/RuView/releases/tag/v0.5.0-esp32) | **Stable** — mmWave sensor fusion ([ADR-063](docs/adr/ADR-063-mmwave-sensor-fusion.md)), auto-detect MR60BHA2/LD2410, 48-byte fused vitals, all v0.4.3.1 fixes | `v0.5.0-esp32` | +| [v0.5.4](https://github.com/ruvnet/RuView/releases/tag/v0.5.4-esp32) | **Latest** — Cognitum Seed integration ([ADR-069](docs/adr/ADR-069-cognitum-seed-csi-pipeline.md)), 8-dim feature vectors at 1 Hz, RVF vector store ingest, witness chain attestation, security hardening | `v0.5.4-esp32` | +| [v0.5.0](https://github.com/ruvnet/RuView/releases/tag/v0.5.0-esp32) | mmWave sensor fusion ([ADR-063](docs/adr/ADR-063-mmwave-sensor-fusion.md)), auto-detect MR60BHA2/LD2410, 48-byte fused vitals, all v0.4.3.1 fixes | `v0.5.0-esp32` | | [v0.4.3.1](https://github.com/ruvnet/RuView/releases/tag/v0.4.3.1-esp32) | Fall detection fix ([#263](https://github.com/ruvnet/RuView/issues/263)), 4MB flash ([#265](https://github.com/ruvnet/RuView/issues/265)), watchdog fix ([#266](https://github.com/ruvnet/RuView/issues/266)) | `v0.4.3.1-esp32` | | [v0.4.1](https://github.com/ruvnet/RuView/releases/tag/v0.4.1-esp32) | CSI build fix, compile guard, AMOLED display, edge intelligence ([ADR-057](docs/adr/ADR-057-firmware-csi-build-guard.md)) | `v0.4.1-esp32` | | [v0.3.0-alpha](https://github.com/ruvnet/RuView/releases/tag/v0.3.0-alpha-esp32) | Alpha — adds on-device edge intelligence and WASM modules ([ADR-039](docs/adr/ADR-039-esp32-edge-intelligence.md), [ADR-040](docs/adr/ADR-040-wasm-programmable-sensing.md)) | `v0.3.0-alpha-esp32` | @@ -1103,6 +1105,34 @@ python firmware/esp32-csi-node/provision.py --port COM8 \ Nodes can also hop across WiFi channels (1, 6, 11) to increase sensing bandwidth — configured via [ADR-029](docs/adr/ADR-029-ruvsense-multistatic-sensing-mode.md) channel hopping. +### Cognitum Seed integration (ADR-069) + +Connect an ESP32 to a [Cognitum Seed](https://cognitum.one) (Pi Zero 2 W, ~$15) for persistent vector storage, kNN search, cryptographic witness chain, and AI-accessible MCP proxy: + +``` +ESP32-S3 ($9) ──UDP──> Host bridge ──HTTPS──> Cognitum Seed ($15) + CSI capture seed_csi_bridge.py RVF vector store + 8-dim features @ 1 Hz kNN similarity search + Vitals + presence Ed25519 witness chain + 114-tool MCP proxy +``` + +```bash +# 1. Provision ESP32 to send features to your laptop +python firmware/esp32-csi-node/provision.py --port COM9 \ + --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20 --target-port 5006 + +# 2. Run the bridge (forwards to Seed via HTTPS) +export SEED_TOKEN="your-pairing-token" +python scripts/seed_csi_bridge.py \ + --seed-url https://169.254.42.1:8443 --token "$SEED_TOKEN" --validate + +# 3. Check Seed stats +python scripts/seed_csi_bridge.py --token "$SEED_TOKEN" --stats +``` + +The 8-dim feature vector captures: presence, motion, breathing rate, heart rate, phase variance, person count, fall detection, and RSSI — all normalized to [0.0, 1.0]. See [ADR-069](docs/adr/ADR-069-cognitum-seed-csi-pipeline.md) for the full architecture. + ### On-device intelligence (v0.3.0-alpha) The alpha firmware can analyze signals locally and send compact results instead of raw data. This means the ESP32 works standalone — no server needed for basic sensing. Disabled by default for backward compatibility. diff --git a/docs/user-guide.md b/docs/user-guide.md index 78b185f3..9d09a2c3 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -21,6 +21,7 @@ WiFi DensePose turns commodity WiFi signals into real-time human pose estimation - [Windows WiFi (RSSI Only)](#windows-wifi-rssi-only) - [ESP32-S3 (Full CSI)](#esp32-s3-full-csi) - [ESP32 Multistatic Mesh (Advanced)](#esp32-multistatic-mesh-advanced) + - [Cognitum Seed Integration (ADR-069)](#cognitum-seed-integration-adr-069) 5. [REST API Reference](#rest-api-reference) 6. [WebSocket Streaming](#websocket-streaming) 7. [Web UI](#web-ui) @@ -314,6 +315,72 @@ The mesh uses a **Time-Division Multiplexing (TDM)** protocol so nodes take turn See [ADR-029](adr/ADR-029-ruvsense-multistatic-sensing-mode.md) and [ADR-032](adr/ADR-032-multistatic-mesh-security-hardening.md) for the full design. +### Cognitum Seed Integration (ADR-069) + +Connect an ESP32-S3 to a [Cognitum Seed](https://cognitum.one) (Pi Zero 2 W, ~$15) for persistent vector storage, kNN similarity search, cryptographic witness chain, and AI-accessible sensing via MCP proxy. + +**What the Seed adds:** +- **RVF vector store** — Persistent 8-dim feature vectors with content-addressed IDs and kNN search (cosine, L2, dot product) +- **Witness chain** — SHA-256 tamper-evident audit trail for every ingest operation +- **Ed25519 custody** — Device-bound keypair for cryptographic attestation of sensing data +- **Sensor fusion** — BME280 (temp/humidity/pressure), PIR motion, reed switch, 4-ch ADC provide environmental ground truth +- **MCP proxy** — 114 tools via JSON-RPC 2.0 so AI assistants (Claude, GPT) can query sensing state directly +- **Reflex rules** — Automatic alarm triggers based on fragility, drift, and anomaly thresholds + +**Setup:** + +```bash +# 1. Plug in the Cognitum Seed via USB — appears as a network adapter at 169.254.42.1 + +# 2. Pair your client (opens a 30-second window, USB-only for security) +curl -sk -X POST https://169.254.42.1:8443/api/v1/pair/window +curl -sk -X POST https://169.254.42.1:8443/api/v1/pair \ + -H 'Content-Type: application/json' -d '{"client_name":"my-laptop"}' +# Save the returned token — it is shown only once + +# 3. Provision ESP32 to send features to your laptop (where the bridge runs) +python firmware/esp32-csi-node/provision.py --port COM9 \ + --ssid "YourWiFi" --password "secret" \ + --target-ip 192.168.1.20 --target-port 5006 --node-id 1 + +# 4. Run the bridge (receives ESP32 UDP, ingests into Seed via HTTPS) +export SEED_TOKEN="your-pairing-token" +python scripts/seed_csi_bridge.py \ + --seed-url https://169.254.42.1:8443 --token "$SEED_TOKEN" \ + --udp-port 5006 --batch-size 10 --validate + +# 5. Check Seed status +python scripts/seed_csi_bridge.py --token "$SEED_TOKEN" --stats + +# 6. Trigger compaction (reclaim disk space from deleted vectors) +python scripts/seed_csi_bridge.py --token "$SEED_TOKEN" --compact +``` + +**Feature vector dimensions (magic `0xC5110003`, 48 bytes, 1 Hz):** + +| Dim | Feature | Range | Source | +|-----|---------|-------|--------| +| 0 | Presence score | 0.0–1.0 | `s_presence_score / 10.0` | +| 1 | Motion energy | 0.0–1.0 | `s_motion_energy / 10.0` | +| 2 | Breathing rate | 0.0–1.0 | `s_breathing_bpm / 30.0` | +| 3 | Heart rate | 0.0–1.0 | `s_heartrate_bpm / 120.0` | +| 4 | Phase variance | 0.0–1.0 | Mean Welford variance of top-K subcarriers | +| 5 | Person count | 0.0–1.0 | Active persons / 4 | +| 6 | Fall detected | 0.0 or 1.0 | Binary fall flag | +| 7 | RSSI | 0.0–1.0 | `(rssi + 100) / 100` | + +**Architecture:** + +``` +ESP32-S3 ($9) ──UDP:5006──> Host (bridge) ──HTTPS──> Cognitum Seed ($15) + CSI @ 100 Hz seed_csi_bridge.py RVF vector store + Features @ 1 Hz Batches, validates kNN graph + boundary + Vitals @ 1 Hz NaN rejection Witness chain + Source IP filtering 114-tool MCP proxy +``` + +See [ADR-069](adr/ADR-069-cognitum-seed-csi-pipeline.md) for the complete design, validation results, and security analysis. + --- ## REST API Reference