From 6a2ef110357854b57e048f32811b07f48fb734bc Mon Sep 17 00:00:00 2001 From: ruv Date: Sun, 1 Mar 2026 11:00:46 -0500 Subject: [PATCH] docs: cross-platform support in README, changelog, user guide - README: update hardware table, crate description, scan layer heading for macOS + Linux support, bump ADR count to 25 - CHANGELOG: add cross-platform adapters and byte counter fix - User guide: add macOS CoreWLAN and Linux iw data source sections - CLAUDE.md: add pre-merge checklist (8 items) Co-Authored-By: claude-flow --- CHANGELOG.md | 9 ++++++++- README.md | 12 +++++++----- claude.md | 13 +++++++++++++ docs/user-guide.md | 23 +++++++++++++++++++++++ 4 files changed, 51 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d2a228e..6ad2b83 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added -- macOS CoreWLAN WiFi sensing adapter with user guide (`a6382fb`) +- **Cross-platform RSSI adapters** — macOS CoreWLAN (`MacosCoreWlanScanner`) and Linux `iw` (`LinuxIwScanner`) Rust adapters with `#[cfg(target_os)]` gating +- macOS CoreWLAN Python sensing adapter with Swift helper (`mac_wifi.swift`) +- macOS synthetic BSSID generation (FNV-1a hash) for Sonoma 14.4+ BSSID redaction +- Linux `iw dev scan` parser with freq-to-channel conversion and `scan dump` (no-root) mode +- ADR-025: macOS CoreWLAN WiFi Sensing (ORCA) + +### Fixed +- Removed synthetic byte counters from Python `MacosWifiCollector` — now reports `tx_bytes=0, rx_bytes=0` instead of fake incrementing values --- diff --git a/README.md b/README.md index c9f4a15..7b026e4 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ docker run -p 3000:3000 ruvnet/wifi-densepose:latest > |--------|----------|------|----------|-------------| > | **ESP32 Mesh** (recommended) | 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/Linux laptop | $0 | No | RSSI-only: coarse presence and motion | +> | **Any WiFi** | Windows, macOS, or Linux laptop | $0 | No | RSSI-only: coarse presence and motion | > > No hardware? Verify the signal processing pipeline with the deterministic reference signal: `python v1/data/proof/verify.py` @@ -48,7 +48,7 @@ docker run -p 3000:3000 ruvnet/wifi-densepose:latest | [User Guide](docs/user-guide.md) | Step-by-step guide: installation, first run, API usage, hardware setup, training | | [WiFi-Mat User Guide](docs/wifi-mat-user-guide.md) | Disaster response module: search & rescue, START triage | | [Build Guide](docs/build-guide.md) | Building from source (Rust and Python) | -| [Architecture Decisions](docs/adr/) | 24 ADRs covering signal processing, training, hardware, security | +| [Architecture Decisions](docs/adr/) | 25 ADRs covering signal processing, training, hardware, security | --- @@ -354,7 +354,7 @@ cargo add wifi-densepose-wifiscan # Multi-BSSID WiFi scanning | [`wifi-densepose-mat`](https://crates.io/crates/wifi-densepose-mat) | Mass Casualty Assessment Tool (disaster survivor detection) | `solver`, `temporal-tensor` | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-mat.svg)](https://crates.io/crates/wifi-densepose-mat) | | [`wifi-densepose-vitals`](https://crates.io/crates/wifi-densepose-vitals) | Vital signs: breathing (6-30 BPM), heart rate (40-120 BPM) | -- | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-vitals.svg)](https://crates.io/crates/wifi-densepose-vitals) | | [`wifi-densepose-hardware`](https://crates.io/crates/wifi-densepose-hardware) | ESP32, Intel 5300, Atheros CSI sensor interfaces | -- | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-hardware.svg)](https://crates.io/crates/wifi-densepose-hardware) | -| [`wifi-densepose-wifiscan`](https://crates.io/crates/wifi-densepose-wifiscan) | Multi-BSSID WiFi scanning (Windows-enhanced) | -- | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-wifiscan.svg)](https://crates.io/crates/wifi-densepose-wifiscan) | +| [`wifi-densepose-wifiscan`](https://crates.io/crates/wifi-densepose-wifiscan) | Multi-BSSID WiFi scanning (Windows, macOS, Linux) | -- | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-wifiscan.svg)](https://crates.io/crates/wifi-densepose-wifiscan) | | [`wifi-densepose-wasm`](https://crates.io/crates/wifi-densepose-wasm) | WebAssembly bindings for browser deployment | -- | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-wasm.svg)](https://crates.io/crates/wifi-densepose-wasm) | | [`wifi-densepose-sensing-server`](https://crates.io/crates/wifi-densepose-sensing-server) | Axum server: UDP ingestion, WebSocket broadcast | -- | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-sensing-server.svg)](https://crates.io/crates/wifi-densepose-sensing-server) | | [`wifi-densepose-cli`](https://crates.io/crates/wifi-densepose-cli) | Command-line tool for MAT disaster scanning | -- | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-cli.svg)](https://crates.io/crates/wifi-densepose-cli) | @@ -606,7 +606,7 @@ See [ADR-021](docs/adr/ADR-021-vital-sign-detection-rvdna-pipeline.md).
-📡 WiFi Scan Domain Layer (ADR-022) — 8-stage RSSI pipeline for Windows WiFi +📡 WiFi Scan Domain Layer (ADR-022/025) — 8-stage RSSI pipeline for Windows, macOS, and Linux WiFi | Stage | Purpose | |-------|---------| @@ -1090,6 +1090,8 @@ WebSocket: `ws://localhost:3001/ws/sensing` (real-time sensing + vital signs) | Intel 5300 | Firmware mod | ~$15 | Linux `iwl-csi` | | Atheros AR9580 | ath9k patch | ~$20 | Linux only | | Any Windows WiFi | RSSI only | $0 | [Tutorial #36](https://github.com/ruvnet/wifi-densepose/issues/36) | +| Any macOS WiFi | RSSI only (CoreWLAN) | $0 | [ADR-025](docs/adr/ADR-025-macos-corewlan-wifi-sensing.md) | +| Any Linux WiFi | RSSI only (`iw`) | $0 | Requires `iw` + `CAP_NET_ADMIN` |
@@ -1263,7 +1265,7 @@ The largest release to date — delivers the complete end-to-end training pipeli - **`--export-rvf` CLI flag** — Standalone RVF model container generation with vital config, training proof, and SONA profiles - **`--train` CLI flag** — Full training mode with best-epoch snapshotting and checkpoint saving - **Vital sign detection (ADR-021)** — FFT-based breathing (6-30 BPM) and heartbeat (40-120 BPM) extraction, 11,665 fps benchmark -- **WiFi scan domain layer (ADR-022)** — 8-stage pure-Rust signal intelligence pipeline for Windows WiFi RSSI +- **WiFi scan domain layer (ADR-022/025)** — 8-stage pure-Rust signal intelligence pipeline for Windows, macOS, and Linux WiFi RSSI - **New crates** — `wifi-densepose-vitals` (1,863 lines) and `wifi-densepose-wifiscan` (4,829 lines) - **542+ Rust tests** — All passing, zero mocks diff --git a/claude.md b/claude.md index ad4b2fd..9e545b5 100644 --- a/claude.md +++ b/claude.md @@ -89,6 +89,19 @@ All development on: `claude/validate-code-quality-WNrNw` - **HNSW**: Enabled - **Neural**: Enabled +## Pre-Merge Checklist + +Before merging any PR, verify each item applies and is addressed: + +1. **Tests pass** — `cargo test` (Rust) and `python -m pytest` (Python) green +2. **README.md** — Update platform tables, crate descriptions, hardware tables, feature summaries if scope changed +3. **CHANGELOG.md** — Add entry under `[Unreleased]` with what was added/fixed/changed +4. **User guide** (`docs/user-guide.md`) — Update if new data sources, CLI flags, or setup steps were added +5. **ADR index** — Update ADR count in README docs table if a new ADR was created +6. **Docker Hub image** — Only rebuild if Dockerfile, dependencies, or runtime behavior changed (not needed for platform-gated code that doesn't affect the Linux container) +7. **Crate publishing** — Only needed if a crate is published to crates.io and its public API changed (workspace-internal crates don't need publishing) +8. **`.gitignore`** — Add any new build artifacts or binaries + ## Build & Test ```bash diff --git a/docs/user-guide.md b/docs/user-guide.md index 8297711..4e30a62 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -194,6 +194,29 @@ docker run --network host ruvnet/wifi-densepose:latest --source windows --tick-m See [Tutorial #36](https://github.com/ruvnet/wifi-densepose/issues/36) for a walkthrough. +### macOS WiFi (RSSI Only) + +Uses CoreWLAN via a Swift helper binary. macOS Sonoma 14.4+ redacts real BSSIDs; the adapter generates deterministic synthetic MACs so the multi-BSSID pipeline still works. + +```bash +# Compile the Swift helper (once) +swiftc -O v1/src/sensing/mac_wifi.swift -o mac_wifi + +# Run natively +./target/release/sensing-server --source macos --http-port 3000 --ws-port 3001 --tick-ms 500 +``` + +See [ADR-025](adr/ADR-025-macos-corewlan-wifi-sensing.md) for details. + +### Linux WiFi (RSSI Only) + +Uses `iw dev scan` to capture RSSI. Requires `CAP_NET_ADMIN` (root) for active scans; use `scan dump` for cached results without root. + +```bash +# Run natively (requires root for active scanning) +sudo ./target/release/sensing-server --source linux --http-port 3000 --ws-port 3001 --tick-ms 500 +``` + ### ESP32-S3 (Full CSI) Real Channel State Information at 20 Hz with 56-192 subcarriers. Required for pose estimation, vital signs, and through-wall sensing.