9bbe95648c
Full implementation of Project AETHER — Contrastive CSI Embedding Model. ## Phases Delivered 1. ProjectionHead (64→128→128) + L2 normalization 2. CsiAugmenter (5 physically-motivated augmentations) 3. InfoNCE contrastive loss + SimCLR pretraining 4. FingerprintIndex (4 index types: env, activity, temporal, person) 5. RVF SEG_EMBED (0x0C) + CLI integration 6. Cross-modal alignment (PoseEncoder + InfoNCE) 7. Deep RuVector: MicroLoRA, EWC++, drift detection, hard-negative mining, SEG_LORA ## Stats - 276 tests passing (191 lib + 51 bin + 16 rvf + 18 vitals) - 3,342 additions across 8 files - Zero unsafe/unwrap/panic/todo stubs - ~55KB INT8 model for ESP32 edge deployment Also fixes deprecated GitHub Actions (v3→v4) and adds feat/* branch CI triggers. Closes #50
125 lines
5.2 KiB
Markdown
125 lines
5.2 KiB
Markdown
# wifi-densepose-sensing-server
|
|
|
|
[](https://crates.io/crates/wifi-densepose-sensing-server)
|
|
[](https://docs.rs/wifi-densepose-sensing-server)
|
|
[](LICENSE)
|
|
|
|
Lightweight Axum server for real-time WiFi sensing with RuVector signal processing.
|
|
|
|
## Overview
|
|
|
|
`wifi-densepose-sensing-server` is the operational backend for WiFi-DensePose. It receives raw CSI
|
|
frames from ESP32 hardware over UDP, runs them through the RuVector-powered signal processing
|
|
pipeline, and broadcasts processed sensing updates to browser clients via WebSocket. A built-in
|
|
static file server hosts the sensing UI on the same port.
|
|
|
|
The crate ships both a library (`wifi_densepose_sensing_server`) exposing the training and inference
|
|
modules, and a binary (`sensing-server`) that starts the full server stack.
|
|
|
|
Integrates [wifi-densepose-wifiscan](../wifi-densepose-wifiscan) for multi-BSSID WiFi scanning
|
|
per ADR-022 Phase 3.
|
|
|
|
## Features
|
|
|
|
- **UDP CSI ingestion** -- Receives ESP32 CSI frames on port 5005 and parses them into the internal
|
|
`CsiFrame` representation.
|
|
- **Vital sign detection** -- Pure-Rust FFT-based breathing rate (0.1--0.5 Hz) and heart rate
|
|
(0.67--2.0 Hz) estimation from CSI amplitude time series (ADR-021).
|
|
- **RVF container** -- Standalone binary container format for packaging model weights, metadata, and
|
|
configuration into a single `.rvf` file with 64-byte aligned segments.
|
|
- **RVF pipeline** -- Progressive model loading with streaming segment decoding.
|
|
- **Graph Transformer** -- Cross-attention bottleneck between antenna-space CSI features and the
|
|
COCO 17-keypoint body graph, followed by GCN message passing (ADR-023 Phase 2). Pure `std`, no ML
|
|
dependencies.
|
|
- **SONA adaptation** -- LoRA + EWC++ online adaptation for environment drift without catastrophic
|
|
forgetting (ADR-023 Phase 5).
|
|
- **Contrastive CSI embeddings** -- Self-supervised SimCLR-style pretraining with InfoNCE loss,
|
|
projection head, fingerprint indexing, and cross-modal pose alignment (ADR-024).
|
|
- **Sparse inference** -- Activation profiling, sparse matrix-vector multiply, INT8/FP16
|
|
quantization, and a full sparse inference engine for edge deployment (ADR-023 Phase 6).
|
|
- **Dataset pipeline** -- Training dataset loading and batching.
|
|
- **Multi-BSSID scanning** -- Windows `netsh` integration for BSSID discovery via
|
|
`wifi-densepose-wifiscan` (ADR-022).
|
|
- **WebSocket broadcast** -- Real-time sensing updates pushed to all connected clients at
|
|
`ws://localhost:8765/ws/sensing`.
|
|
- **Static file serving** -- Hosts the sensing UI on port 8080 with CORS headers.
|
|
|
|
## Modules
|
|
|
|
| Module | Description |
|
|
|--------|-------------|
|
|
| `vital_signs` | Breathing and heart rate extraction via FFT spectral analysis |
|
|
| `rvf_container` | RVF binary format builder and reader |
|
|
| `rvf_pipeline` | Progressive model loading from RVF containers |
|
|
| `graph_transformer` | Graph Transformer + GCN for CSI-to-pose estimation |
|
|
| `trainer` | Training loop orchestration |
|
|
| `dataset` | Training data loading and batching |
|
|
| `sona` | LoRA adapters and EWC++ continual learning |
|
|
| `sparse_inference` | Neuron profiling, sparse matmul, INT8/FP16 quantization |
|
|
| `embedding` | Contrastive CSI embedding model and fingerprint index |
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Build the server
|
|
cargo build -p wifi-densepose-sensing-server
|
|
|
|
# Run with default settings (HTTP :8080, UDP :5005, WS :8765)
|
|
cargo run -p wifi-densepose-sensing-server
|
|
|
|
# Run with custom ports
|
|
cargo run -p wifi-densepose-sensing-server -- \
|
|
--http-port 9000 \
|
|
--udp-port 5005 \
|
|
--static-dir ./ui
|
|
```
|
|
|
|
### Using as a library
|
|
|
|
```rust
|
|
use wifi_densepose_sensing_server::vital_signs::VitalSignDetector;
|
|
|
|
// Create a detector with 20 Hz sample rate
|
|
let mut detector = VitalSignDetector::new(20.0);
|
|
|
|
// Feed CSI amplitude samples
|
|
for amplitude in csi_amplitudes.iter() {
|
|
detector.push_sample(*amplitude);
|
|
}
|
|
|
|
// Extract vital signs
|
|
if let Some(vitals) = detector.detect() {
|
|
println!("Breathing: {:.1} BPM", vitals.breathing_rate_bpm);
|
|
println!("Heart rate: {:.0} BPM", vitals.heart_rate_bpm);
|
|
}
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```text
|
|
ESP32 ──UDP:5005──> [ CSI Receiver ]
|
|
|
|
|
[ Signal Pipeline ]
|
|
(vital_signs, graph_transformer, sona)
|
|
|
|
|
[ WebSocket Broadcast ]
|
|
|
|
|
Browser <──WS:8765── [ Axum Server :8080 ] ──> Static UI files
|
|
```
|
|
|
|
## Related Crates
|
|
|
|
| Crate | Role |
|
|
|-------|------|
|
|
| [`wifi-densepose-wifiscan`](../wifi-densepose-wifiscan) | Multi-BSSID WiFi scanning (ADR-022) |
|
|
| [`wifi-densepose-core`](../wifi-densepose-core) | Shared types and traits |
|
|
| [`wifi-densepose-signal`](../wifi-densepose-signal) | CSI signal processing algorithms |
|
|
| [`wifi-densepose-hardware`](../wifi-densepose-hardware) | ESP32 hardware interfaces |
|
|
| [`wifi-densepose-wasm`](../wifi-densepose-wasm) | Browser WASM bindings for the sensing UI |
|
|
| [`wifi-densepose-train`](../wifi-densepose-train) | Full training pipeline with ruvector |
|
|
| [`wifi-densepose-mat`](../wifi-densepose-mat) | Disaster detection module |
|
|
|
|
## License
|
|
|
|
MIT OR Apache-2.0
|