berkus
/
wifi-densepose
mirror of https://github.com/ruvnet/wifi-densepose.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
wifi-densepose/docs/adr
History
rUv 0943a32248
feat: Real-time dense point cloud from camera + WiFi CSI (#405) 
* Add wifi-densepose-pointcloud: real-time dense point cloud from camera + WiFi CSI

New crate with 5 modules:
- depth: monocular depth estimation + 3D backprojection (ONNX-ready, synthetic fallback)
- pointcloud: Point3D/ColorPoint types, PLY export, Gaussian splat conversion
- fusion: WiFi occupancy volume → point cloud + multi-modal voxel fusion
- stream: HTTP + Three.js viewer server (Axum, port 9880)
- main: CLI with serve/capture/demo subcommands

Demo output: 271 WiFi points + 19,200 depth points → 4,886 fused → 1,718 Gaussian splats.
Serves interactive 3D viewer at http://localhost:9880 with Three.js orbit controls.

ADR-SYS-0021 documents the architecture for camera + WiFi CSI dense point cloud pipeline.

Co-Authored-By: claude-flow <ruv@ruv.net>

* Optimize pointcloud: larger splat voxels, smaller responses, faster fusion

- Gaussian splat voxel size: 0.10 → 0.15 (42% fewer splats: 1718 → 994)
- Splat response: 399 KB → 225 KB (44% smaller)
- Pipeline: 22.2ms mean (100 runs, σ=0.3ms)
- Cloud API: 1.11ms avg, 905 req/s
- Splats API: 1.39ms avg, 719 req/s
- Binary: 1.0 MB arm64 (Mac Mini), tested

Co-Authored-By: claude-flow <ruv@ruv.net>

* Complete implementation: camera capture, WiFi CSI receiver, training pipeline

Three new modules added to wifi-densepose-pointcloud:

1. camera.rs — Cross-platform camera capture
   - macOS: AVFoundation via Swift, ffmpeg avfoundation
   - Linux: V4L2, ffmpeg v4l2
   - Camera detection, listing, frame capture to RGB
   - Graceful fallback to synthetic data when no camera

2. csi.rs — WiFi CSI receiver for ESP32 nodes
   - UDP listener for CSI JSON frames from ESP32
   - Per-link attenuation tracking with EMA smoothing
   - Simplified RF tomography (backprojection to occupancy grid)
   - Test frame sender for development without hardware
   - Ready for real ESP32 CSI data from ruvzen

3. training.rs — Calibration and training pipeline
   - Depth calibration: grid search over scale/offset/gamma
   - Occupancy training: threshold optimization for presence detection
   - Ground truth reference points for depth RMSE measurement
   - Preference pair export (JSONL) for DPO training on ruOS brain
   - Brain integration: submit observations as memories
   - Persistent calibration files (JSON)

New CLI commands:
   ruview-pointcloud cameras         # list available cameras
   ruview-pointcloud train           # run calibration + training
   ruview-pointcloud csi-test        # send test CSI frames
   ruview-pointcloud serve --csi     # serve with live CSI input

All tested: demo, training (10 samples, 4 reference points, 3 pairs),
CSI receiver (50 test frames), server API.

Co-Authored-By: claude-flow <ruv@ruv.net>

* Fix viewer: replace WebSocket with fetch polling

Co-Authored-By: claude-flow <ruv@ruv.net>

* Wire live camera into server — real-time updating point cloud

- Server captures from /dev/video0 at 2fps via ffmpeg
- Background tokio task refreshes cloud + splats every 500ms
- Viewer polls /api/splats every 500ms, only updates on new frame
- Shows 🟢 LIVE / 🔴 DEMO indicator
- Camera position set for first-person view (looking forward into scene)
- Downsample 4x for performance (19,200 points per frame)
- Graceful fallback to demo data if camera capture fails

Co-Authored-By: claude-flow <ruv@ruv.net>

* Add MiDaS GPU depth, serial CSI reader, full sensor fusion

- MiDaS depth server: PyTorch on CUDA, real monocular depth estimation
- Rust server calls MiDaS via HTTP for neural depth (falls back to luminance)
- Serial CSI reader for ESP32 with motion detection + presence estimation
- CSI disabled by default (RUVIEW_CSI=1 to enable) — serial reader needs baud config
- Edge-enhanced depth for better object boundaries
- All sensors wired: camera, ESP32 CSI, mmWave (CSI gated until serial fixed)

Co-Authored-By: claude-flow <ruv@ruv.net>

* Complete 7-component sensor fusion pipeline (all working)

1. ADR-018 binary parser — decodes ESP32 CSI UDP frames, extracts I/Q subcarriers
2. WiFlow pose — 17 COCO keypoints from CSI (186K param model loaded)
3. Camera depth — MiDaS on CUDA + luminance fallback
4. Sensor fusion — camera depth + CSI occupancy grid + skeleton overlay
5. RF tomography — ISTA-inspired backprojection from per-node RSSI
6. Vital signs — breathing rate from CSI phase analysis
7. Motion-adaptive — skip expensive depth when CSI shows no motion

Live results: 510 CSI frames/session, 17 keypoints, 26% motion, 40 BPM breathing.
Both ESP32 nodes provisioned to send CSI to 192.168.1.123:3333.
Magic number fix: supports both 0xC5110001 (v1) and 0xC5110006 (v6) frames.

Co-Authored-By: claude-flow <ruv@ruv.net>

* Add brain bridge — sparse spatial observation sync every 60s

Stores room scan summaries, motion events, and vital signs
in the ruOS brain as memories. Only syncs every 120 frames
(~60 seconds) to keep the brain sparse and optimized.

Categories: spatial-observation, spatial-motion, spatial-vitals.

Co-Authored-By: claude-flow <ruv@ruv.net>

* Update README + user guide with dense point cloud features

Added pointcloud section to README (quick start, CLI, performance).
Added comprehensive user guide section: setup, sensors, commands,
pipeline components, API endpoints, training, output formats,
deep room scan, ESP32 provisioning.

Co-Authored-By: claude-flow <ruv@ruv.net>

* Add ruview-geo: geospatial satellite integration (11 modules, 8/8 tests)

New crate with free satellite imagery, terrain, OSM, weather, and brain integration.

Modules: types, coord, locate, cache, tiles, terrain, osm, register, fuse, brain, temporal
Tests: 8 passed (haversine, ENU roundtrip, tiles, HGT parse, registration)
Validation: real data — 43.49N 79.71W, 4 Sentinel-2 tiles, 2°C weather, brain stored

Data sources (all free, no API keys):
- EOX Sentinel-2 cloudless (10m satellite tiles)
- SRTM GL1 (30m elevation)
- Overpass API (OSM buildings/roads)
- ip-api.com (geolocation)
- Open Meteo (weather)

ADR-044 documents architecture decisions.
README.md in crate subdirectory.

Co-Authored-By: claude-flow <ruv@ruv.net>

* Update ADR-044: add Common Crawl WET, NASA FIRMS, OpenAQ, Overture Maps sources

Extended geospatial data sources leveraging ruvector's existing web_ingest
and Common Crawl support for hyperlocal context.

Co-Authored-By: claude-flow <ruv@ruv.net>

* Fix OSM/SRTM queries, add change detection + night mode

- OSM: use inclusive building filter with relation query and 25s timeout
- SRTM: switch to NASA public mirror with viewfinderpanoramas fallback
- Add detect_tile_changes() for pixel-diff satellite change detection
- Add is_night() solar-declination model for CSI-only night mode
- 6 new unit tests (night mode + tile change detection)

Co-Authored-By: claude-flow <ruv@ruv.net>

* Enhance viewer: skeleton overlay, weather, buildings, better camera

Add COCO skeleton rendering with yellow keypoint spheres and white bone
lines, info panel sections for weather/buildings/CSI rate/confidence,
overhead camera at (0,2,-4), and denser point size with sizeAttenuation.

Co-Authored-By: claude-flow <ruv@ruv.net>

* Add CSI fingerprint DB + night mode detection

Co-Authored-By: claude-flow <ruv@ruv.net>

* Fix ADR-044 numbering conflict, update geo README

Renumbered provisioning tool ADR from 044 to 050 to avoid conflict
with geospatial satellite integration ADR-044.

Co-Authored-By: claude-flow <ruv@ruv.net>

* Clean up warnings: suppress dead_code for conditional pipeline modules

Removes unused imports/variables via cargo fix and adds #[allow(dead_code)]
for modules used conditionally at runtime (CSI, depth, fusion, serial).
Pointcloud: 28 → 0 warnings. Geo: 2 → 0 warnings. 8/8 tests pass.

Co-Authored-By: claude-flow <ruv@ruv.net>

* Fix PR #405 blockers: async runtime panic, crate rename, path traversal, brain URL config

- brain_bridge.rs: replace `Handle::current().block_on(...)` inside async fn
  with `.await` (was a guaranteed "runtime within runtime" panic). Brain URL
  now read from RUVIEW_BRAIN_URL env var (default http://127.0.0.1:9876),
  logged once via OnceLock.
- wifi-densepose-geo: rename Cargo package from `ruview-geo` to
  `wifi-densepose-geo` to match directory and workspace conventions. Update
  all use sites (tests/examples/README). Same env-var pattern for brain URL
  in brain.rs + temporal.rs.
- training.rs: add sanitize_data_path() rejecting `..` components and
  safe_join() that canonicalises + enforces base-dir containment on every
  write (calibration.json, samples.json, preference_pairs.jsonl,
  occupancy_calibration.json). Defence-in-depth check also in main.rs
  before TrainingSession::new.
- osm.rs: clamp Overpass radius to MAX_RADIUS_M=5000m; return Err beyond
  that. Add parse_overpass_json() that rejects malformed payloads
  (missing top-level `elements` array).

Co-Authored-By: claude-flow <ruv@ruv.net>

* csi_pipeline: rename WiFlow stub to heuristic_pose_from_amplitude, decouple UDP

Blocker 3 (PR #405 review): The "WiFlow inference" path was a stub that
built a model from empty weight vectors and synthesised keypoints from
amplitude energy. Presenting this as "WiFlow inference" was misleading.

- Rename WiFlowModel to PoseModelMetadata (empty tag struct; we only care
  if the on-disk file exists)
- Rename load_wiflow_model() -> detect_pose_model_metadata() and log
  "amplitude-energy heuristic enabled/disabled" (no "WiFlow" claim)
- Rename estimate_pose() -> heuristic_pose_from_amplitude() with
  prominent `STUB:` doc comment saying this is NOT a trained model

Blocker 4 (PR #405 review): The UDP receiver held the shared Arc<Mutex>
across a synchronous process_frame() call, starving HTTP handlers.

- Introduce a std::sync::mpsc channel between the UDP thread (which only
  parses + pushes) and a dedicated processor thread (which locks only
  briefly around a single process_frame). HTTP snapshots via
  get_pipeline_output no longer contend with the socket read loop.

Also:
- Move ADR-018 parser to parser.rs (see next commit); csi_pipeline re-exports
- send_test_frames now uses parser::build_test_frame for synthetic frames
- Log a one-line node stats summary every 500 frames (reads every public
  CsiFrame field on the runtime path)

Co-Authored-By: claude-flow <ruv@ruv.net>

* Extract ADR-018 parser into parser.rs + wire Fingerprint CLI

File-split (strong concern #9 in PR #405 review): csi_pipeline.rs was 602
LOC; extract the pure-function ADR-018 parser + synthetic frame builder
into src/parser.rs. Inline unit tests in parser.rs cover:

- 0xC5110001 (raw CSI, v1) roundtrip
- 0xC5110006 (feature state, v6) roundtrip
- wrong magic is rejected
- truncated header is rejected
- truncated payload is rejected

main.rs: expose `fingerprint NAME [--seconds N]` subcommand wiring
record_fingerprint() (this was the only caller needed to make the public
API non-dead on the runtime path). Also:

- Replace `--host/--port` + external `--csi` with a single `--bind`
  defaulting to loopback (`127.0.0.1:9880`) — addresses strong concern
  #7 about exposing camera/CSI/vitals by default.
- Update synthetic `csi-test` to target UDP 3333 (matching the ADR-018
  listener) and use the shared parser::build_test_frame.
- Defence-in-depth: call training::sanitize_data_path on the expanded
  --data-dir before TrainingSession::new does the same.

Co-Authored-By: claude-flow <ruv@ruv.net>

* stream: extract viewer HTML to viewer.html, default bind to loopback

Strong concern #7 (PR #405): default HTTP bind leaked camera/CSI/vitals
to the LAN. The `serve` fn now takes a single `bind` arg and prints a
loud WARNING when bound outside loopback.

Strong concern #10 (PR #405): embedded HTML+JS was ~220 LOC of the 418
LOC stream.rs. Moved the markup verbatim into viewer.html and inlined
via `include_str!("viewer.html")`. Also:

- Drop the #![allow(dead_code)] crate-level silencing (reviewer point
  #11). Remove the now-unused AppState.csi_pipeline field.
- capture_camera_cloud_with_luminance returns the mean luminance of the
  captured frame; the background loop feeds that to
  CsiPipelineState::set_light_level so the night-mode flag actually
  toggles at runtime (previously it could only be set from tests).

Net effect on file size: stream.rs 418 → 232 LOC.

Co-Authored-By: claude-flow <ruv@ruv.net>

* Dead-code cleanup + tests for fusion/depth/OSM/training/fingerprinting

Reviewer point #11 (PR #405): remove the `#![allow(dead_code)]`
silencing added in 8eb808d and fix the underlying issues.

- Delete csi.rs: duplicate of csi_pipeline.rs with incompatible wire
  format (JSON vs ADR-018 binary). csi_pipeline is the real path.
- Delete serial_csi.rs: never referenced by any module.
- Drop Frame.timestamp_ms (unread), AppState.csi_pipeline (unread),
  brain_bridge::brain_available (caller-less), fusion::fetch_wifi_occupancy
  (caller-less) — these had no runtime users.
- Drop crate-level #![allow(dead_code)] from camera.rs, depth.rs,
  fusion.rs, pointcloud.rs.

Tests (target: 8-12, actual: 15 unit + 9 geo unit + 8 geo integration
= 32 total, all pass):

- parser.rs: 5 tests (v1/v6 magic roundtrip, wrong magic, truncated
  header, truncated payload).
- fusion.rs: 2 tests (non-overlapping merge, voxel dedup).
- depth.rs: 2 tests (2x2 backproject → 4 points at z=1, NaN rejected).
- training.rs: 4 tests (rejects `..`, accepts relative child, refuses
  TrainingSession::new("../etc/passwd"), accepts a clean tmpdir).
- csi_pipeline.rs: 2 tests (set_light_level toggles is_dark,
  record_fingerprint stores and self-identifies).
- osm.rs: 3 tests (parse_overpass_json minimal fixture, rejects
  malformed payload, fetch_buildings rejects > MAX_RADIUS_M).

Co-Authored-By: claude-flow <ruv@ruv.net>

* Update README + user-guide for PR #405 review-fix additions

- serve now uses --bind 127.0.0.1:9880 (loopback default) instead of --port
- Add fingerprint subcommand to CLI tables
- Document RUVIEW_BRAIN_URL env var + --brain flag
- Flag pose path as amplitude-energy heuristic stub (not trained WiFlow)
- Security note on exposing server outside loopback
- Add wifi-densepose-pointcloud + wifi-densepose-geo rows to crate table

Co-Authored-By: claude-flow <ruv@ruv.net>
 		2026-04-20 12:48:54 -04:00
..
.issue-177-body.md ruv-neural: publish 11 crates to crates.io — full implementation, no stubs 2026-03-09 10:52:24 -04:00
ADR-001-wifi-mat-disaster-detection.md feat: Add wifi-densepose-mat disaster detection module 2026-01-13 17:24:50 +00:00
ADR-002-ruvector-rvf-integration-strategy.md docs: update README, CHANGELOG, and associated ADRs for MERIDIAN 2026-03-01 12:06:09 -05:00
ADR-003-rvf-cognitive-containers-csi.md feat: Add 12 ADRs for RuVector RVF integration and proof-of-reality 2026-02-28 06:13:04 +00:00
ADR-004-hnsw-vector-search-fingerprinting.md docs: update README, CHANGELOG, and associated ADRs for MERIDIAN 2026-03-01 12:06:09 -05:00
ADR-005-sona-self-learning-pose-estimation.md docs: update README, CHANGELOG, and associated ADRs for MERIDIAN 2026-03-01 12:06:09 -05:00
ADR-006-gnn-enhanced-csi-pattern-recognition.md docs: update README, CHANGELOG, and associated ADRs for MERIDIAN 2026-03-01 12:06:09 -05:00
ADR-007-post-quantum-cryptography-secure-sensing.md feat: Add 12 ADRs for RuVector RVF integration and proof-of-reality 2026-02-28 06:13:04 +00:00
ADR-008-distributed-consensus-multi-ap.md feat: Add 12 ADRs for RuVector RVF integration and proof-of-reality 2026-02-28 06:13:04 +00:00
ADR-009-rvf-wasm-runtime-edge-deployment.md feat: Add 12 ADRs for RuVector RVF integration and proof-of-reality 2026-02-28 06:13:04 +00:00
ADR-010-witness-chains-audit-trail-integrity.md feat: Add 12 ADRs for RuVector RVF integration and proof-of-reality 2026-02-28 06:13:04 +00:00
ADR-011-python-proof-of-reality-mock-elimination.md feat: Add 12 ADRs for RuVector RVF integration and proof-of-reality 2026-02-28 06:13:04 +00:00
ADR-012-esp32-csi-sensor-mesh.md docs(adr-012): Update ESP32 CSI sensor mesh ADR to reflect implementation 2026-02-28 13:48:06 -05:00
ADR-013-feature-level-sensing-commodity-gear.md feat: Sensing-only UI mode with Gaussian splat visualization and Rust migration ADR 2026-02-28 14:37:29 -05:00
ADR-014-sota-signal-processing.md feat: Implement ADR-014 SOTA signal processing (6 algorithms, 83 tests) 2026-02-28 14:34:16 +00:00
ADR-015-public-dataset-training-strategy.md docs: Update ADR-015 with verified dataset specs from research 2026-02-28 15:14:50 +00:00
ADR-016-ruvector-integration.md docs(adr): Mark ADR-016 as Accepted — all 5 integrations complete 2026-02-28 15:46:44 +00:00
ADR-017-ruvector-signal-mat-integration.md fix: Complete ADR-011 mock elimination and fix all test stubs 2026-02-28 16:59:34 +00:00
ADR-018-esp32-dev-implementation.md docs: update ADRs with ENOMEM crash fix proof (Issue #127) 2026-03-03 16:14:54 -05:00
ADR-019-sensing-only-ui-mode.md feat: Sensing-only UI mode with Gaussian splat visualization and Rust migration ADR 2026-02-28 14:37:29 -05:00
ADR-020-rust-ruvector-ai-model-migration.md feat: Sensing-only UI mode with Gaussian splat visualization and Rust migration ADR 2026-02-28 14:37:29 -05:00
ADR-021-vital-sign-detection-rvdna-pipeline.md feat: Training mode, ADR docs, vitals and wifiscan crates 2026-02-28 23:50:20 -05:00
ADR-022-windows-wifi-enhanced-fidelity-ruvector.md feat: Training mode, ADR docs, vitals and wifiscan crates 2026-02-28 23:50:20 -05:00
ADR-023-trained-densepose-model-ruvector-pipeline.md feat: Training mode, ADR docs, vitals and wifiscan crates 2026-02-28 23:50:20 -05:00
ADR-024-contrastive-csi-embedding-model.md feat: ADR-024 Contrastive CSI Embedding Model — all 7 phases (#52) 2026-03-01 01:44:38 -05:00
ADR-025-macos-corewlan-wifi-sensing.md feat: Add macOS CoreWLAN WiFi sensing adapter and user guide 2026-03-01 02:15:44 -05:00
ADR-026-survivor-track-lifecycle.md feat(mat): add ADR-026 + survivor track lifecycle module (WIP) 2026-03-01 07:53:28 +00:00
ADR-027-cross-environment-domain-generalization.md docs: add gap closure mapping for all proposed ADRs (002-011) to ADR-027 2026-03-01 11:51:32 -05:00
ADR-028-esp32-capability-audit.md feat: 100% validated witness bundle with proof hash + generator script 2026-03-01 15:51:38 -05:00
ADR-029-ruvsense-multistatic-sensing-mode.md docs: update ADRs with ENOMEM crash fix proof (Issue #127) 2026-03-03 16:14:54 -05:00
ADR-030-ruvsense-persistent-field-model.md docs: add RuvSense persistent field model, exotic tiers, and appliance categories 2026-03-02 01:59:21 +00:00
ADR-031-ruview-sensing-first-rf-mode.md feat: combine ADR-029/030/031 + DDD domain model into implementation branch 2026-03-01 21:25:14 -05:00
ADR-032-multistatic-mesh-security-hardening.md feat: ADR-032a midstreamer QUIC transport + secure TDM + temporal gesture + attractor drift 2026-03-01 22:22:19 -05:00
ADR-033-crv-signal-line-sensing-integration.md feat: ADR-033 CRV signal-line integration + ruvector-crv 6-stage pipeline 2026-03-01 22:21:59 -05:00
ADR-034-expo-mobile-app.md feat: Implement RSSI service for iOS and Web platforms 2026-03-02 10:30:33 -05:00
ADR-035-live-sensing-ui-accuracy.md docs: update ADR-035 with dark mode, render modes, pose_source fix 2026-03-02 11:08:13 -05:00
ADR-036-rvf-training-pipeline-ui.md fix: WebSocket race condition, data source indicators, auto-start pose detection (#96) 2026-03-02 13:47:49 -05:00
ADR-037-multi-person-pose-detection.md docs: ADR-037 multi-person pose detection from single ESP32 CSI stream 2026-03-02 13:49:38 -05:00
ADR-038-sublinear-goal-oriented-action-planning.md docs: ADR-038 Sublinear Goal-Oriented Action Planning (GOAP) 2026-03-02 14:39:15 -05:00
ADR-039-esp32-edge-intelligence.md feat: ADR-069 ESP32 CSI → Cognitum Seed RVF pipeline (v0.5.4-esp32) 2026-04-02 19:32:18 -04:00
ADR-040-wasm-programmable-sensing.md feat: complete vendor repos, add edge intelligence and WASM modules 2026-03-02 23:53:25 -05:00
ADR-041-wasm-module-collection.md feat: expand ADR-041 WASM module catalog from 37 to 60 modules 2026-03-03 00:06:39 -05:00
ADR-042-coherent-human-channel-imaging.md feat: add ADR-042 CHCI protocol, 24 new edge modules, README restructure 2026-03-03 11:35:57 -05:00
ADR-043-sensing-server-ui-api-completion.md fix: complete sensing server API, WebSocket connectivity, and mobile tests (#125) 2026-03-03 13:27:03 -05:00
ADR-044-geospatial-satellite-integration.md feat: Real-time dense point cloud from camera + WiFi CSI (#405) 2026-04-20 12:48:54 -04:00
ADR-045-amoled-display-support.md docs: update README with ADR-045–048, Observatory, adaptive classifier, AMOLED display 2026-03-05 10:20:48 -05:00
ADR-046-android-tv-box-armbian-deployment.md docs: update README with ADR-045–048, Observatory, adaptive classifier, AMOLED display 2026-03-05 10:20:48 -05:00
ADR-047-psychohistory-observatory-visualization.md docs: update README with ADR-045–048, Observatory, adaptive classifier, AMOLED display 2026-03-05 10:20:48 -05:00
ADR-048-adaptive-csi-classifier.md feat: adaptive CSI classifier with signal smoothing pipeline (ADR-048) (#144) 2026-03-05 10:15:18 -05:00
ADR-049-cross-platform-wifi-interface-detection.md feat: cross-platform WiFi collector factory with graceful degradation (ADR-049) 2026-03-06 15:09:32 -05:00
ADR-050-provisioning-tool-enhancements.md feat: Real-time dense point cloud from camera + WiFi CSI (#405) 2026-04-20 12:48:54 -04:00
ADR-050-quality-engineering-security-hardening.md fix: security hardening — replace fake HMAC, add path traversal protection, OTA auth (ADR-050) 2026-03-06 13:11:04 -05:00
ADR-052-ddd-bounded-contexts.md feat: complete Tauri desktop frontend with all pages and enhanced design (#198) 2026-03-08 23:31:18 -04:00
ADR-052-tauri-desktop-frontend.md feat: complete Tauri desktop frontend with all pages and enhanced design (#198) 2026-03-08 23:31:18 -04:00
ADR-053-ui-design-system.md feat: complete Tauri desktop frontend with all pages and enhanced design (#198) 2026-03-08 23:31:18 -04:00
ADR-054-desktop-full-implementation.md feat(desktop): RuView Desktop v0.4.0 - Full ADR-054 Implementation (#212) 2026-03-09 21:58:06 -04:00
ADR-055-integrated-sensing-server.md feat(desktop): v0.4.2 - Integrated sensing server with real WebSocket data 2026-03-10 00:08:31 -04:00
ADR-056-ruview-desktop-capabilities.md feat(desktop): v0.4.2 - Integrated sensing server with real WebSocket data 2026-03-10 00:08:31 -04:00
ADR-057-firmware-csi-build-guard.md fix(firmware): enable CSI in sdkconfig and add build guard (ADR-057) 2026-03-12 13:49:20 -04:00
ADR-058-ruvector-wasm-browser-pose-example.md feat(demo): wire all 6 RuVector WASM attention mechanisms into pose fusion 2026-03-12 20:59:57 -04:00
ADR-059-live-esp32-csi-pipeline.md feat(demo): wire all 6 RuVector WASM attention mechanisms into pose fusion 2026-03-12 20:59:57 -04:00
ADR-060-provision-channel-mac-filter.md feat(firmware): --channel and --filter-mac provisioning (ADR-060) 2026-03-13 08:27:08 -04:00
ADR-061-qemu-esp32s3-firmware-testing.md feat: QEMU ESP32-S3 testing platform + swarm configurator (ADR-061/062) (#260) 2026-03-14 13:39:51 -04:00
ADR-062-qemu-swarm-configurator.md feat: QEMU ESP32-S3 testing platform + swarm configurator (ADR-061/062) (#260) 2026-03-14 13:39:51 -04:00
ADR-063-mmwave-sensor-fusion.md feat: ADR-063/064 mmWave sensor fusion + multimodal ambient intelligence (#269) 2026-03-15 16:10:10 -04:00
ADR-064-multimodal-ambient-intelligence.md feat: ADR-063/064 mmWave sensor fusion + multimodal ambient intelligence (#269) 2026-03-15 16:10:10 -04:00
ADR-065-happiness-scoring-seed-bridge.md feat: happiness scoring pipeline + ESP32 swarm with Cognitum Seed (#285) 2026-03-20 18:46:34 -04:00
ADR-066-esp32-swarm-seed-coordinator.md feat: ADR-069 ESP32 CSI → Cognitum Seed RVF pipeline (v0.5.4-esp32) 2026-04-02 19:32:18 -04:00
ADR-067-ruvector-v2.0.5-upgrade.md docs(adr): ADR-067 RuVector v2.0.5 upgrade + new crate adoption plan 2026-03-23 21:51:43 -04:00
ADR-068-per-node-state-pipeline.md feat: ADR-069 ESP32 CSI → Cognitum Seed RVF pipeline (v0.5.4-esp32) 2026-04-02 19:32:18 -04:00
ADR-069-cognitum-seed-csi-pipeline.md feat: ADR-069 ESP32 CSI → Cognitum Seed RVF pipeline (v0.5.4-esp32) 2026-04-02 19:32:18 -04:00
ADR-070-self-supervised-pretraining.md feat: ADR-070 self-supervised pretraining from live ESP32 CSI + Seed 2026-04-02 20:42:37 -04:00
ADR-071-ruvllm-training-pipeline.md feat: camera-free 17-keypoint pose training (10 sensor signals) 2026-04-02 23:05:07 -04:00
ADR-072-wiflow-architecture.md feat: ADR-072 WiFlow SOTA architecture — TCN + axial attention + pose decoder 2026-04-02 23:40:23 -04:00
ADR-073-multifrequency-mesh-scan.md feat: ADR-074 spiking neural network for real-time CSI sensing 2026-04-03 00:34:31 -04:00
ADR-074-spiking-neural-csi-sensing.md feat: ADR-074 spiking neural network for real-time CSI sensing 2026-04-03 00:34:31 -04:00
ADR-075-mincut-person-separation.md feat: ADR-075 min-cut person separation — fixes #348 2026-04-03 00:34:57 -04:00
ADR-076-csi-spectrogram-embeddings.md feat: ADR-076 CNN spectrogram embeddings + graph transformer fusion 2026-04-03 00:36:38 -04:00
ADR-077-novel-rf-sensing-applications.md feat: ADR-077 — 6 novel RF sensing applications 2026-04-03 08:50:48 -04:00
ADR-078-multifreq-mesh-applications.md feat: ADR-078 — 5 multi-frequency mesh applications 2026-04-03 08:52:50 -04:00
ADR-079-camera-ground-truth-training.md fix: remove hardcoded Tailscale IPs and usernames from public files 2026-04-06 14:39:21 -04:00
ADR-080-qe-remediation-plan.md fix: ADR-080 P0 security + CI remediation from QE analysis 2026-04-06 16:12:13 -04:00
ADR-081-adaptive-csi-mesh-firmware-kernel.md ADR-081: Implement 5-layer adaptive CSI mesh firmware kernel (#404) 2026-04-20 10:38:23 -04:00
README.md docs: add ADR index with intro on ADRs for AI-assisted development 2026-03-03 16:35:17 -05:00

README.md

Architecture Decision Records

This folder contains 44 Architecture Decision Records (ADRs) that document every significant technical choice in the RuView / WiFi-DensePose project.

Why ADRs?

Building a system that turns WiFi signals into human pose estimation involves hundreds of non-obvious decisions: which signal processing algorithms to use, how to bridge ESP32 firmware to a Rust pipeline, whether to run inference on-device or on a server, how to handle multi-person separation with limited subcarriers.

ADRs capture the context, options considered, decision made, and consequences for each of these choices. They serve three purposes:

  1. Institutional memory — Six months from now, anyone (human or AI) can read why we chose IIR bandpass filters over FIR for vital sign extraction, not just see the code.

  2. AI-assisted development — When an AI agent works on this codebase, ADRs give it the constraints and rationale it needs to make changes that align with the existing architecture. Without them, AI-generated code tends to drift — reinventing patterns that already exist, contradicting earlier decisions, or optimizing for the wrong tradeoffs.

  3. Review checkpoints — Each ADR is a reviewable artifact. When a proposed change touches the architecture, the ADR forces the author to articulate tradeoffs before writing code, not after.

ADRs and Domain-Driven Design

The project uses Domain-Driven Design (DDD) to organize code into bounded contexts — each with its own language, types, and responsibilities. ADRs and DDD work together:

  • ADRs define boundaries: ADR-029 (RuvSense) established multistatic sensing as a separate bounded context from single-node CSI. ADR-042 (CHCI) defined a new aggregate root for coherent channel imaging.
  • DDD models define the language: The RuvSense domain model defines terms like "coherence gate", "dwell time", and "TDM slot" that ADRs reference precisely.
  • Together they prevent drift: An AI agent reading ADR-039 knows that edge processing tiers are configured via NVS keys, not compile-time flags — because the ADR says so. The DDD model tells it which aggregate owns that configuration.

How ADRs are structured

Each ADR follows a consistent format:

  • Context — What problem or gap prompted this decision
  • Decision — What we chose to do and how
  • Consequences — What improved, what got harder, and what risks remain
  • References — Related ADRs, papers, and code paths

Statuses: Proposed (under discussion), Accepted (approved and/or implemented), Superseded (replaced by a later ADR).

ADR Index

Hardware and firmware

ADR Title Status
ADR-012 ESP32 CSI Sensor Mesh for Distributed Sensing Accepted (partial)
ADR-018 ESP32 Development Implementation Path Proposed
ADR-028 ESP32 Capability Audit and Witness Record Accepted
ADR-029 RuvSense Multistatic Sensing Mode (TDM, channel hopping) Proposed
ADR-032 Multistatic Mesh Security Hardening Accepted
ADR-039 ESP32-S3 Edge Intelligence Pipeline (on-device vitals) Accepted (hardware-validated)
ADR-040 WASM Programmable Sensing (Tier 3) Accepted
ADR-041 WASM Module Collection (65 edge modules) Accepted (hardware-validated)
ADR-044 Provisioning Tool Enhancements Proposed

Signal processing and sensing

ADR Title Status
ADR-013 Feature-Level Sensing on Commodity Gear Accepted
ADR-014 SOTA Signal Processing Algorithms Accepted
ADR-021 Vital Sign Detection (breathing, heart rate) Partial
ADR-030 Persistent Field Model and Drift Detection Proposed
ADR-033 CRV Signal Line Sensing Integration Proposed
ADR-037 Multi-Person Pose Detection from Single ESP32 Proposed
ADR-042 Coherent Human Channel Imaging (beyond CSI) Proposed

Machine learning and training

ADR Title Status
ADR-005 SONA Self-Learning for Pose Estimation Partial
ADR-006 GNN-Enhanced CSI Pattern Recognition Partial
ADR-015 Public Dataset Strategy (MM-Fi, Wi-Pose) Accepted
ADR-016 RuVector Training Pipeline Integration Accepted
ADR-017 RuVector Signal + MAT Integration Proposed
ADR-020 Migrate AI Inference to Rust (ONNX Runtime) Accepted
ADR-023 Trained DensePose Model with RuVector Pipeline Proposed
ADR-024 Project AETHER: Contrastive CSI Embeddings Required
ADR-027 Project MERIDIAN: Cross-Environment Generalization Proposed

Platform and UI

ADR Title Status
ADR-019 Sensing-Only UI with Gaussian Splats Accepted
ADR-022 Windows WiFi Enhanced Fidelity (multi-BSSID) Partial
ADR-025 macOS CoreWLAN WiFi Sensing Proposed
ADR-031 RuView Sensing-First RF Mode Proposed
ADR-034 Expo React Native Mobile App Accepted
ADR-035 Live Sensing UI Accuracy and Data Transparency Accepted
ADR-036 Training Pipeline UI Integration Proposed
ADR-043 Sensing Server UI API Completion (14 endpoints) Accepted

Architecture and infrastructure

ADR Title Status
ADR-001 WiFi-Mat Disaster Detection Architecture Accepted
ADR-002 RuVector RVF Integration Strategy Superseded
ADR-003 RVF Cognitive Containers for CSI Proposed
ADR-004 HNSW Vector Search for Fingerprinting Partial
ADR-007 Post-Quantum Cryptography for Sensing Proposed
ADR-008 Distributed Consensus for Multi-AP Proposed
ADR-009 RVF WASM Runtime for Edge Deployment Proposed
ADR-010 Witness Chains for Audit Trail Integrity Proposed
ADR-011 Proof-of-Reality and Mock Elimination Proposed
ADR-026 Survivor Track Lifecycle (MAT crate) Accepted
ADR-038 Sublinear GOAP for Roadmap Optimization Proposed

Related

  • DDD Domain Models — Bounded context definitions, aggregate roots, and ubiquitous language
  • User Guide — Setup, API reference, and hardware instructions
  • Build Guide — Building from source