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 <ruv@ruv.net>
2026-06-09 10:13:17 +00:00 · 2026-04-02 19:48:01 -04:00
parent a4bd2308b7
commit 27d17431c5
2 changed files with 99 additions and 2 deletions
@@ -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.
@@ -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