From 92a6986b794a5029e6da58ea7d7304c1f0e28da4 Mon Sep 17 00:00:00 2001 From: ruv Date: Sun, 15 Mar 2026 16:17:40 -0400 Subject: [PATCH] docs: update all docs for v0.5.0-esp32 release - README: v0.5.0 in release table, binary size 990/773 KB - CHANGELOG: v0.5.0 entry with mmWave fusion, ADR-063/064 - User guide: v0.5.0 as recommended, binary size updated - CLAUDE.md: supported hardware table, firmware build/release process, real-hardware-first testing policy Co-Authored-By: claude-flow --- CHANGELOG.md | 11 +++++++++++ CLAUDE.md | 46 +++++++++++++++++++++++++++++++++++++++++----- README.md | 5 +++-- docs/user-guide.md | 5 +++-- 4 files changed, 58 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bd7cda85..e37cd28c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [v0.5.0-esp32] — 2026-03-15 + +### Added +- **60 GHz mmWave sensor fusion (ADR-063)** — Auto-detects Seeed MR60BHA2 (60 GHz, HR/BR/presence) and HLK-LD2410 (24 GHz, presence/distance) on UART at boot. Probes 115200 then 256000 baud, registers device capabilities, starts background parser. +- **48-byte fused vitals packet** (magic `0xC5110004`) — Kalman-style fusion: mmWave 80% + CSI 20% when both available. Automatic fallback to standard 32-byte CSI-only packet. +- **Server-side fusion bridge** (`scripts/mmwave_fusion_bridge.py`) — Reads two serial ports simultaneously for dual-sensor setups where mmWave runs on a separate ESP32. +- **Multimodal ambient intelligence roadmap (ADR-064)** — 25+ applications from fall detection to sleep monitoring to RF tomography. + +### Verified +- Real hardware: ESP32-S3 (COM7) WiFi CSI + ESP32-C6/MR60BHA2 (COM4) 60 GHz mmWave running concurrently. HR=75 bpm, BR=25/min at 52 cm range. All 11 QEMU CI jobs green. + ## [v0.4.3-esp32] — 2026-03-15 ### Fixed diff --git a/CLAUDE.md b/CLAUDE.md index c13a39ab..4c11fd73 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -70,6 +70,17 @@ All 5 ruvector crates integrated in workspace: - ADR-031: RuView sensing-first RF mode (Proposed) - ADR-032: Multistatic mesh security hardening (Proposed) +### Supported Hardware + +| Device | Port | Chip | Role | Cost | +|--------|------|------|------|------| +| ESP32-S3 (8MB flash) | COM7 | Xtensa dual-core | WiFi CSI sensing node | ~$9 | +| ESP32-S3 SuperMini (4MB) | — | Xtensa dual-core | WiFi CSI (compact) | ~$6 | +| ESP32-C6 + Seeed MR60BHA2 | COM4 | RISC-V + 60 GHz FMCW | mmWave HR/BR/presence | ~$15 | +| HLK-LD2410 | — | 24 GHz FMCW | Presence + distance | ~$3 | + +**Not supported:** ESP32 (original), ESP32-C3 — single-core, can't run CSI DSP pipeline. + ### Build & Test Commands (this repo) ```bash # Rust — full workspace tests (1,031+ tests, ~2 min) @@ -79,11 +90,6 @@ cargo test --workspace --no-default-features # Rust — single crate check (no GPU needed) cargo check -p wifi-densepose-train --no-default-features -# Rust — publish crates (dependency order) -cargo publish -p wifi-densepose-core --no-default-features -cargo publish -p wifi-densepose-signal --no-default-features -# ... see crate publishing order below - # Python — deterministic proof verification (SHA-256) python v1/data/proof/verify.py @@ -91,6 +97,36 @@ python v1/data/proof/verify.py cd v1 && python -m pytest tests/ -x -q ``` +### ESP32 Firmware Build (Windows — Python subprocess required) +```bash +# Build 8MB firmware (real WiFi CSI mode, no mocks) +# See CLAUDE.local.md for the full Python subprocess command +# Key: must strip MSYSTEM env vars for ESP-IDF v5.4 on Git Bash + +# Build 4MB firmware +cp sdkconfig.defaults.4mb sdkconfig.defaults +# then same build process + +# Flash to COM7 +# [python, idf_py, '-p', 'COM7', 'flash'] + +# Provision WiFi +python firmware/esp32-csi-node/provision.py --port COM7 \ + --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20 + +# Monitor serial +python -m serial.tools.miniterm COM7 115200 +``` + +### Firmware Release Process +1. Build 8MB from `sdkconfig.defaults.template` (no mock) +2. Build 4MB from `sdkconfig.defaults.4mb` (no mock) +3. Save 6 binaries: `esp32-csi-node.bin`, `bootloader.bin`, `partition-table.bin`, `ota_data_initial.bin`, `esp32-csi-node-4mb.bin`, `partition-table-4mb.bin` +4. Tag: `git tag v0.X.Y-esp32 && git push origin v0.X.Y-esp32` +5. Release: `gh release create v0.X.Y-esp32 --title "..." --notes-file ...` +6. Verify on real hardware (COM7) before publishing +7. **CRITICAL:** Always test with real WiFi CSI, not mock mode — mock missed the Kconfig threshold bug + ### Crate Publishing Order Crates must be published in dependency order: 1. `wifi-densepose-core` (no internal deps) diff --git a/README.md b/README.md index 6a16553b..41bb8d06 100644 --- a/README.md +++ b/README.md @@ -1038,7 +1038,7 @@ ESP32-S3 node UDP/5005 Host server (optional) | Subcarriers per frame | 64 / 128 / 192 (depends on WiFi mode) | | UDP latency | < 1 ms on local network | | Presence detection range | Reliable at 3 m through walls | -| Binary size | 978 KB (8MB flash) / 755 KB (4MB flash) | +| Binary size | 990 KB (8MB flash) / 773 KB (4MB flash) | | Boot to ready | ~3.9 seconds | ### Flash and provision @@ -1047,7 +1047,8 @@ Download a pre-built binary — no build toolchain needed: | Release | What's included | Tag | |---------|-----------------|-----| -| [v0.4.3.1](https://github.com/ruvnet/RuView/releases/tag/v0.4.3.1-esp32) | **Stable** — 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.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.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` | | [v0.2.0](https://github.com/ruvnet/RuView/releases/tag/v0.2.0-esp32) | Raw CSI streaming, multi-node TDM, channel hopping | `v0.2.0-esp32` | diff --git a/docs/user-guide.md b/docs/user-guide.md index 32dca5f5..78b185f3 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -819,7 +819,8 @@ Pre-built binaries are available at [Releases](https://github.com/ruvnet/RuView/ | Release | What It Includes | Tag | |---------|-----------------|-----| -| [v0.4.3.1](https://github.com/ruvnet/RuView/releases/tag/v0.4.3.1-esp32) | **Stable (recommended)** — Fall detection fix ([#263](https://github.com/ruvnet/RuView/issues/263)), 4MB flash support ([#265](https://github.com/ruvnet/RuView/issues/265)), watchdog fix ([#266](https://github.com/ruvnet/RuView/issues/266)) | `v0.4.3.1-esp32` | +| [v0.5.0](https://github.com/ruvnet/RuView/releases/tag/v0.5.0-esp32) | **Stable (recommended)** — mmWave sensor fusion (MR60BHA2/LD2410 auto-detect), 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 (ADR-039) | `v0.3.0-alpha-esp32` | | [v0.2.0](https://github.com/ruvnet/RuView/releases/tag/v0.2.0-esp32) | Raw CSI streaming, TDM, channel hopping, QUIC mesh | `v0.2.0-esp32` | @@ -911,7 +912,7 @@ Key NVS settings for edge processing: When Tier 2 is active, the node sends a 32-byte vitals packet at 1 Hz (configurable) containing presence state, motion score, breathing BPM, heart rate BPM, confidence values, fall flag, and occupancy estimate. The packet uses magic `0xC5110002` and is sent to the same aggregator IP and port as raw CSI frames. -Binary size: 978 KB (53% free in the 2 MB app partition, 8MB flash) or 755 KB (4MB flash). +Binary size: 990 KB (8MB flash, 52% free) or 773 KB (4MB flash). v0.5.0 adds mmWave sensor fusion (~12 KB larger). > **Alpha notice**: Vital sign estimation uses heuristic BPM extraction. Accuracy is best with stationary subjects in controlled environments. Not for medical use.