docs: add 4 DDD domain models covering all major subsystems
Create complete Domain-Driven Design specifications for: - Signal Processing (3 contexts: CSI Preprocessing, Feature Extraction, Motion Analysis) - Training Pipeline (4 contexts: Dataset Management, Model Architecture, Training Orchestration, Embedding & Transfer) - Hardware Platform (5 contexts: Sensor Node, Edge Processing, WASM Runtime, Aggregation, Provisioning) - Sensing Server (5 contexts: CSI Ingestion, Model Management, CSI Recording, Training Pipeline, Visualization) Update DDD index (3 → 7 models) and README docs table. Co-Authored-By: claude-flow <ruv@ruv.net>
This commit is contained in:
ruv
parent
8658cc3de0
commit
2ad510782e
|
|
@ -50,7 +50,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 |
|
||||
| [Build Guide](docs/build-guide.md) | Building from source (Rust and Python) |
|
||||
| [Architecture Decisions](docs/adr/README.md) | 44 ADRs — why each technical choice was made, organized by domain (hardware, signal processing, ML, platform, infrastructure) |
|
||||
| [Domain Models](docs/ddd/README.md) | 3 DDD models (RuvSense, WiFi-Mat, CHCI) — bounded contexts, aggregates, domain events, and ubiquitous language |
|
||||
| [Domain Models](docs/ddd/README.md) | 7 DDD models (RuvSense, Signal Processing, Training Pipeline, Hardware Platform, Sensing Server, WiFi-Mat, CHCI) — bounded contexts, aggregates, domain events, and ubiquitous language |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -9,8 +9,12 @@ DDD organizes the codebase around the problem being solved — not around techni
|
|||
| Model | What it covers | Bounded Contexts |
|
||||
|-------|---------------|------------------|
|
||||
| [RuvSense](ruvsense-domain-model.md) | Multistatic WiFi sensing, pose tracking, vital signs, edge intelligence | 7 contexts: Sensing, Coherence, Tracking, Field Model, Longitudinal, Spatial Identity, Edge Intelligence |
|
||||
| [WiFi-Mat](wifi-mat-domain-model.md) | Disaster response: survivor detection, START triage, mass casualty assessment | Scan Zone, Survivor Tracking, Triage |
|
||||
| [CHCI](chci-domain-model.md) | Coherent Human Channel Imaging: sub-millimeter body surface reconstruction | Sounding, Channel Estimation, Imaging |
|
||||
| [Signal Processing](signal-processing-domain-model.md) | SOTA signal processing: phase cleaning, feature extraction, motion analysis | 3 contexts: CSI Preprocessing, Feature Extraction, Motion Analysis |
|
||||
| [Training Pipeline](training-pipeline-domain-model.md) | ML training: datasets, model architecture, embeddings, domain generalization | 4 contexts: Dataset Management, Model Architecture, Training Orchestration, Embedding & Transfer |
|
||||
| [Hardware Platform](hardware-platform-domain-model.md) | ESP32 firmware, edge intelligence, WASM runtime, aggregation, provisioning | 5 contexts: Sensor Node, Edge Processing, WASM Runtime, Aggregation, Provisioning |
|
||||
| [Sensing Server](sensing-server-domain-model.md) | Single-binary Axum server: CSI ingestion, model management, recording, training, visualization | 5 contexts: CSI Ingestion, Model Management, CSI Recording, Training Pipeline, Visualization |
|
||||
| [WiFi-Mat](wifi-mat-domain-model.md) | Disaster response: survivor detection, START triage, mass casualty assessment | 3 contexts: Detection, Localization, Alerting |
|
||||
| [CHCI](chci-domain-model.md) | Coherent Human Channel Imaging: sub-millimeter body surface reconstruction | 3 contexts: Sounding, Channel Estimation, Imaging |
|
||||
|
||||
## How to read these
|
||||
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,842 @@
|
|||
# Sensing Server Domain Model
|
||||
|
||||
The Sensing Server is the single-binary deployment surface of WiFi-DensePose. It receives raw CSI frames from ESP32 nodes, processes them into sensing features, streams live data to a web UI, and provides a self-contained workflow for recording data, training models, and running inference -- all without external dependencies.
|
||||
|
||||
This document defines the system using [Domain-Driven Design](https://martinfowler.com/bliki/DomainDrivenDesign.html) (DDD): bounded contexts that own their data and rules, aggregate roots that enforce invariants, value objects that carry meaning, and domain events that connect everything. The server is implemented as a single Axum binary (`wifi-densepose-sensing-server`) with all state managed through `Arc<RwLock<AppStateInner>>`.
|
||||
|
||||
**Bounded Contexts:**
|
||||
|
||||
| # | Context | Responsibility | Key ADRs | Code |
|
||||
|---|---------|----------------|----------|------|
|
||||
| 1 | [CSI Ingestion](#1-csi-ingestion-context) | Receive, decode, and feature-extract CSI frames from ESP32 UDP | [ADR-019](../adr/ADR-019-sensing-only-ui-mode.md), [ADR-035](../adr/ADR-035-live-sensing-ui-accuracy.md) | `sensing-server/src/main.rs` |
|
||||
| 2 | [Model Management](#2-model-management-context) | Load, unload, list RVF models; LoRA profile activation | [ADR-043](../adr/ADR-043-sensing-server-ui-api-completion.md) | `sensing-server/src/model_manager.rs` |
|
||||
| 3 | [CSI Recording](#3-csi-recording-context) | Record CSI frames to .jsonl files, manage recording sessions | [ADR-043](../adr/ADR-043-sensing-server-ui-api-completion.md) | `sensing-server/src/recording.rs` |
|
||||
| 4 | [Training Pipeline](#4-training-pipeline-context) | Background training runs, progress streaming, contrastive pretraining | [ADR-043](../adr/ADR-043-sensing-server-ui-api-completion.md) | `sensing-server/src/training_api.rs` |
|
||||
| 5 | [Visualization](#5-visualization-context) | WebSocket streaming to web UI, Gaussian splat rendering, data transparency | [ADR-019](../adr/ADR-019-sensing-only-ui-mode.md), [ADR-035](../adr/ADR-035-live-sensing-ui-accuracy.md) | `ui/` |
|
||||
|
||||
All code paths shown are relative to `rust-port/wifi-densepose-rs/crates/wifi-densepose-` unless otherwise noted.
|
||||
|
||||
---
|
||||
|
||||
## Domain-Driven Design Specification
|
||||
|
||||
### Ubiquitous Language
|
||||
|
||||
| Term | Definition |
|
||||
|------|------------|
|
||||
| **Sensing Update** | A complete JSON message broadcast to WebSocket clients each tick, containing node data, features, classification, signal field, and optional vital signs |
|
||||
| **Tick** | One processing cycle of the sensing loop (default 100ms = 10 fps, configurable via `--tick-ms`) |
|
||||
| **Data Source** | Origin of CSI data: `esp32` (UDP port 5005), `wifi` (Windows RSSI), `simulated` (synthetic), or `auto` (try ESP32 then fall back) |
|
||||
| **RVF Model** | A `.rvf` container file holding trained weights, manifest metadata, optional LoRA adapters, and vital sign configuration |
|
||||
| **LoRA Profile** | A lightweight adapter applied on top of a base RVF model for environment-specific fine-tuning without retraining the full model |
|
||||
| **Recording Session** | A period during which CSI frames are appended to a `.csi.jsonl` file, identified by a session ID and optional activity label |
|
||||
| **Training Run** | A background task that loads recorded CSI data, extracts features, trains a regularised linear model, and exports a `.rvf` container |
|
||||
| **Frame History** | A circular buffer of the last 100 CSI amplitude vectors used for temporal analysis (sliding-window variance, Goertzel breathing estimation) |
|
||||
| **Goertzel Filter** | A frequency-domain estimator applied to the frame history to detect breathing rate (0.1--0.5 Hz) via a 9-candidate filter bank |
|
||||
| **Signal Field** | A 20x1x20 grid of interpolated signal intensity values rendered as Gaussian splats in the UI |
|
||||
| **Pose Source** | Whether pose keypoints are `signal_derived` (analytical from CSI features) or `model_inference` (from a loaded RVF model) |
|
||||
| **Progressive Loader** | A two-layer model loading strategy: Layer A loads instantly for basic inference, Layer B loads in background for full accuracy |
|
||||
| **Sensing-Only Mode** | UI mode when the DensePose backend is unavailable; suppresses DensePose tabs, shows only sensing and signal visualization |
|
||||
| **AppStateInner** | The single shared state struct holding all server state, accessed via `Arc<RwLock<AppStateInner>>` |
|
||||
| **PCK Score** | Percentage of Correct Keypoints -- the primary accuracy metric for pose estimation models |
|
||||
| **Contrastive Pretraining** | Self-supervised training on unlabeled CSI data that learns signal representations before supervised fine-tuning (ADR-024) |
|
||||
|
||||
---
|
||||
|
||||
## Bounded Contexts
|
||||
|
||||
### 1. CSI Ingestion Context
|
||||
|
||||
**Responsibility:** Receive raw CSI frames from ESP32 nodes via UDP (port 5005), decode the binary protocol, extract temporal and frequency-domain features, and produce a `SensingUpdate` each tick.
|
||||
|
||||
```
|
||||
+------------------------------------------------------------+
|
||||
| CSI Ingestion Context |
|
||||
+------------------------------------------------------------+
|
||||
| |
|
||||
| +----------------+ +----------------+ |
|
||||
| | UDP Listener | | Data Source | |
|
||||
| | (port 5005) | | Selector | |
|
||||
| | Esp32Frame | | (auto/esp32/ | |
|
||||
| | parser | | wifi/sim) | |
|
||||
| +-------+--------+ +-------+--------+ |
|
||||
| | | |
|
||||
| +----------+----------+ |
|
||||
| v |
|
||||
| +-------------------+ |
|
||||
| | Frame History | |
|
||||
| | Buffer | |
|
||||
| | (VecDeque<Vec>, | |
|
||||
| | 100 frames) | |
|
||||
| +--------+----------+ |
|
||||
| v |
|
||||
| +-------------------+ |
|
||||
| | Feature | |
|
||||
| | Extractor | |
|
||||
| | (Welford stats, | |
|
||||
| | Goertzel FFT, | |
|
||||
| | L2 motion) | |
|
||||
| +--------+----------+ |
|
||||
| v |
|
||||
| +-------------------+ |
|
||||
| | Vital Sign | |
|
||||
| | Detector |---> SensingUpdate |
|
||||
| | (HR, RR, | |
|
||||
| | breathing) | |
|
||||
| +-------------------+ |
|
||||
| |
|
||||
+------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Aggregates:**
|
||||
|
||||
```rust
|
||||
/// Aggregate Root: The central shared state of the sensing server.
|
||||
/// All mutations go through RwLock. All handler functions receive
|
||||
/// State<Arc<RwLock<AppStateInner>>>.
|
||||
pub struct AppStateInner {
|
||||
/// Most recent sensing update broadcast to clients.
|
||||
latest_update: Option<SensingUpdate>,
|
||||
/// RSSI history for sparkline display.
|
||||
rssi_history: VecDeque<f64>,
|
||||
/// Circular buffer of recent CSI amplitude vectors (100 frames).
|
||||
frame_history: VecDeque<Vec<f64>>,
|
||||
/// Monotonic tick counter.
|
||||
tick: u64,
|
||||
/// Active data source identifier ("esp32", "wifi", "simulated").
|
||||
source: String,
|
||||
/// Broadcast channel for WebSocket fan-out.
|
||||
tx: broadcast::Sender<String>,
|
||||
/// Vital sign detector instance.
|
||||
vital_detector: VitalSignDetector,
|
||||
/// Most recent vital signs reading.
|
||||
latest_vitals: VitalSigns,
|
||||
/// Smoothed person count (EMA) for hysteresis.
|
||||
smoothed_person_score: f64,
|
||||
// ... model, recording, training fields (see other contexts)
|
||||
}
|
||||
```
|
||||
|
||||
**Value Objects:**
|
||||
|
||||
```rust
|
||||
/// A complete sensing update broadcast to WebSocket clients each tick.
|
||||
pub struct SensingUpdate {
|
||||
pub msg_type: String, // always "sensing_update"
|
||||
pub timestamp: f64, // Unix timestamp with ms precision
|
||||
pub source: String, // "esp32" | "wifi" | "simulated"
|
||||
pub tick: u64, // monotonic tick counter
|
||||
pub nodes: Vec<NodeInfo>, // per-node CSI data
|
||||
pub features: FeatureInfo, // extracted signal features
|
||||
pub classification: ClassificationInfo,
|
||||
pub signal_field: SignalField,
|
||||
pub vital_signs: Option<VitalSigns>,
|
||||
pub persons: Option<Vec<PersonDetection>>,
|
||||
pub estimated_persons: Option<usize>,
|
||||
}
|
||||
|
||||
/// Per-node CSI data received from one ESP32.
|
||||
pub struct NodeInfo {
|
||||
pub node_id: u8,
|
||||
pub rssi_dbm: f64,
|
||||
pub position: [f64; 3],
|
||||
pub amplitude: Vec<f64>,
|
||||
pub subcarrier_count: usize,
|
||||
}
|
||||
|
||||
/// Extracted signal features from the frame history buffer.
|
||||
pub struct FeatureInfo {
|
||||
pub mean_rssi: f64,
|
||||
pub variance: f64,
|
||||
pub motion_band_power: f64,
|
||||
pub breathing_band_power: f64,
|
||||
pub dominant_freq_hz: f64,
|
||||
pub change_points: usize,
|
||||
pub spectral_power: f64,
|
||||
}
|
||||
|
||||
/// Motion classification derived from features.
|
||||
pub struct ClassificationInfo {
|
||||
pub motion_level: String, // "empty" | "static" | "active"
|
||||
pub presence: bool,
|
||||
pub confidence: f64,
|
||||
}
|
||||
|
||||
/// Interpolated signal field for Gaussian splat visualization.
|
||||
pub struct SignalField {
|
||||
pub grid_size: [usize; 3], // [20, 1, 20]
|
||||
pub values: Vec<f64>,
|
||||
}
|
||||
|
||||
/// ESP32 binary CSI frame (ADR-018 protocol, 20-byte header).
|
||||
pub struct Esp32Frame {
|
||||
pub magic: u32, // 0xC5100001
|
||||
pub node_id: u8,
|
||||
pub n_antennas: u8,
|
||||
pub n_subcarriers: u8,
|
||||
pub freq_mhz: u16,
|
||||
pub sequence: u32,
|
||||
pub rssi: i8,
|
||||
pub noise_floor: i8,
|
||||
pub amplitudes: Vec<f64>,
|
||||
pub phases: Vec<f64>,
|
||||
}
|
||||
|
||||
/// Data source selection enum.
|
||||
pub enum DataSource {
|
||||
Esp32Udp, // Real ESP32 CSI via UDP port 5005
|
||||
WindowsRssi, // Windows WiFi RSSI via netsh
|
||||
Simulated, // Synthetic sine-wave data
|
||||
Auto, // Try ESP32, fall back to Windows, then simulated
|
||||
}
|
||||
```
|
||||
|
||||
**Domain Services:**
|
||||
- `FeatureExtractionService` -- Computes temporal variance (Welford), Goertzel breathing estimation (9-band filter bank), L2 frame-to-frame motion score, SNR-based signal quality
|
||||
- `VitalSignDetectionService` -- Estimates breathing rate, heart rate, and confidence from CSI phase history
|
||||
- `DataSourceSelectionService` -- Probes UDP port 5005 for ESP32 frames; falls back through Windows RSSI then simulation
|
||||
|
||||
**Invariants:**
|
||||
- Frame history buffer never exceeds 100 entries (oldest dropped on push)
|
||||
- Goertzel breathing estimate requires 3x SNR above noise to be reported
|
||||
- Source type is determined once at startup and does not change during runtime
|
||||
|
||||
---
|
||||
|
||||
### 2. Model Management Context
|
||||
|
||||
**Responsibility:** Discover `.rvf` model files from `data/models/`, load weights into memory for inference, manage the active model lifecycle, and support LoRA profile activation.
|
||||
|
||||
```
|
||||
+------------------------------------------------------------+
|
||||
| Model Management Context |
|
||||
+------------------------------------------------------------+
|
||||
| |
|
||||
| +----------------+ +----------------+ |
|
||||
| | Model Scanner | | RVF Reader | |
|
||||
| | (data/models/ | | (parse .rvf | |
|
||||
| | *.rvf enum) | | manifest) | |
|
||||
| +-------+--------+ +-------+--------+ |
|
||||
| | | |
|
||||
| +----------+----------+ |
|
||||
| v |
|
||||
| +-------------------+ |
|
||||
| | Model Registry | |
|
||||
| | (Vec<ModelInfo>) | |
|
||||
| +--------+----------+ |
|
||||
| v |
|
||||
| +-------------------+ |
|
||||
| | Model Loader | |
|
||||
| | (RvfReader -> |---> LoadedModelState |
|
||||
| | weights, | |
|
||||
| | LoRA profiles) | |
|
||||
| +--------+----------+ |
|
||||
| v |
|
||||
| +-------------------+ |
|
||||
| | LoRA Activator | |
|
||||
| | (profile switch) | |
|
||||
| +-------------------+ |
|
||||
| |
|
||||
+------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Aggregates:**
|
||||
|
||||
```rust
|
||||
/// Aggregate Root: Runtime state for a loaded RVF model.
|
||||
/// At most one LoadedModelState exists at any time.
|
||||
pub struct LoadedModelState {
|
||||
/// Model identifier (derived from filename without .rvf extension).
|
||||
pub model_id: String,
|
||||
/// Original filename on disk.
|
||||
pub filename: String,
|
||||
/// Version string from the RVF manifest.
|
||||
pub version: String,
|
||||
/// Description from the RVF manifest.
|
||||
pub description: String,
|
||||
/// LoRA profiles available in this model.
|
||||
pub lora_profiles: Vec<String>,
|
||||
/// Currently active LoRA profile (if any).
|
||||
pub active_lora_profile: Option<String>,
|
||||
/// Model weights (f32 parameters).
|
||||
pub weights: Vec<f32>,
|
||||
/// Number of frames processed since load.
|
||||
pub frames_processed: u64,
|
||||
/// Cumulative inference time for avg calculation.
|
||||
pub total_inference_ms: f64,
|
||||
/// When the model was loaded.
|
||||
pub loaded_at: Instant,
|
||||
}
|
||||
```
|
||||
|
||||
**Value Objects:**
|
||||
|
||||
```rust
|
||||
/// Summary information for a model discovered on disk.
|
||||
pub struct ModelInfo {
|
||||
pub id: String,
|
||||
pub filename: String,
|
||||
pub version: String,
|
||||
pub description: String,
|
||||
pub size_bytes: u64,
|
||||
pub created_at: String,
|
||||
pub pck_score: Option<f64>,
|
||||
pub has_quantization: bool,
|
||||
pub lora_profiles: Vec<String>,
|
||||
pub segment_count: usize,
|
||||
}
|
||||
|
||||
/// Information about the currently loaded model with runtime stats.
|
||||
pub struct ActiveModelInfo {
|
||||
pub model_id: String,
|
||||
pub filename: String,
|
||||
pub version: String,
|
||||
pub description: String,
|
||||
pub avg_inference_ms: f64,
|
||||
pub frames_processed: u64,
|
||||
pub pose_source: String, // "model_inference"
|
||||
pub lora_profiles: Vec<String>,
|
||||
pub active_lora_profile: Option<String>,
|
||||
}
|
||||
|
||||
/// Request to load a model by ID.
|
||||
pub struct LoadModelRequest {
|
||||
pub model_id: String,
|
||||
}
|
||||
|
||||
/// Request to activate a LoRA profile.
|
||||
pub struct ActivateLoraRequest {
|
||||
pub model_id: String,
|
||||
pub profile_name: String,
|
||||
}
|
||||
```
|
||||
|
||||
**Domain Services:**
|
||||
- `ModelScanService` -- Scans `data/models/` at startup for `.rvf` files, parses each with `RvfReader` to extract manifest metadata
|
||||
- `ModelLoadService` -- Reads model weights from an RVF container into memory, sets `model_loaded = true`
|
||||
- `LoraActivationService` -- Switches the active LoRA adapter on a loaded model without full reload
|
||||
|
||||
**Invariants:**
|
||||
- Only one model can be loaded at a time; loading a new model implicitly unloads the previous one
|
||||
- A model must be loaded before a LoRA profile can be activated
|
||||
- The `active_lora_profile` must be one of the model's declared `lora_profiles`
|
||||
- Model deletion is refused if the model is currently loaded (must unload first)
|
||||
- `data/models/` directory is created at startup if it does not exist
|
||||
|
||||
---
|
||||
|
||||
### 3. CSI Recording Context
|
||||
|
||||
**Responsibility:** Capture CSI frames to `.csi.jsonl` files during active recording sessions, manage session lifecycle, and provide download/delete operations on stored recordings.
|
||||
|
||||
```
|
||||
+------------------------------------------------------------+
|
||||
| CSI Recording Context |
|
||||
+------------------------------------------------------------+
|
||||
| |
|
||||
| +----------------+ +----------------+ |
|
||||
| | Start/Stop | | Auto-Stop | |
|
||||
| | Controller | | Timer | |
|
||||
| | (REST API) | | (duration_ | |
|
||||
| | | | secs check) | |
|
||||
| +-------+--------+ +-------+--------+ |
|
||||
| | | |
|
||||
| +----------+----------+ |
|
||||
| v |
|
||||
| +-------------------+ |
|
||||
| | Recording State | |
|
||||
| | (session_id, | |
|
||||
| | frame_count, | |
|
||||
| | file_path) | |
|
||||
| +--------+----------+ |
|
||||
| v |
|
||||
| +-------------------+ |
|
||||
| | Frame Writer | |
|
||||
| | (maybe_record_ |---> .csi.jsonl file |
|
||||
| | frame on each | |
|
||||
| | tick) | |
|
||||
| +--------+----------+ |
|
||||
| v |
|
||||
| +-------------------+ |
|
||||
| | Metadata Writer | |
|
||||
| | (.meta.json on | |
|
||||
| | stop) | |
|
||||
| +-------------------+ |
|
||||
| |
|
||||
+------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Aggregates:**
|
||||
|
||||
```rust
|
||||
/// Aggregate Root: Runtime state for the active CSI recording session.
|
||||
/// At most one RecordingState can be active at any time.
|
||||
pub struct RecordingState {
|
||||
/// Whether a recording is currently active.
|
||||
pub active: bool,
|
||||
/// Session ID of the active recording.
|
||||
pub session_id: String,
|
||||
/// Session display name.
|
||||
pub session_name: String,
|
||||
/// Optional label / activity tag (e.g., "walking", "standing").
|
||||
pub label: Option<String>,
|
||||
/// Path to the JSONL file being written.
|
||||
pub file_path: PathBuf,
|
||||
/// Number of frames written so far.
|
||||
pub frame_count: u64,
|
||||
/// When the recording started (monotonic clock).
|
||||
pub start_time: Instant,
|
||||
/// ISO-8601 start timestamp for metadata.
|
||||
pub started_at: String,
|
||||
/// Optional auto-stop duration in seconds.
|
||||
pub duration_secs: Option<u64>,
|
||||
}
|
||||
```
|
||||
|
||||
**Value Objects:**
|
||||
|
||||
```rust
|
||||
/// Metadata for a completed or active recording session.
|
||||
pub struct RecordingSession {
|
||||
pub id: String,
|
||||
pub name: String,
|
||||
pub label: Option<String>,
|
||||
pub started_at: String,
|
||||
pub ended_at: Option<String>,
|
||||
pub frame_count: u64,
|
||||
pub file_size_bytes: u64,
|
||||
pub file_path: String,
|
||||
}
|
||||
|
||||
/// A single recorded CSI frame line (JSONL format).
|
||||
pub struct RecordedFrame {
|
||||
pub timestamp: f64,
|
||||
pub subcarriers: Vec<f64>,
|
||||
pub rssi: f64,
|
||||
pub noise_floor: f64,
|
||||
pub features: serde_json::Value,
|
||||
}
|
||||
|
||||
/// Request to start a new recording session.
|
||||
pub struct StartRecordingRequest {
|
||||
pub session_name: String,
|
||||
pub label: Option<String>,
|
||||
pub duration_secs: Option<u64>,
|
||||
}
|
||||
```
|
||||
|
||||
**Domain Services:**
|
||||
- `RecordingLifecycleService` -- Creates a new `.csi.jsonl` file, generates session ID, manages start/stop transitions
|
||||
- `FrameWriterService` -- Called on each tick via `maybe_record_frame()`, appends a `RecordedFrame` JSON line to the active file
|
||||
- `AutoStopService` -- Checks elapsed time against `duration_secs` on each tick; triggers stop when exceeded
|
||||
- `RecordingScanService` -- Enumerates `data/recordings/` for `.csi.jsonl` files and reads companion `.meta.json` for session metadata
|
||||
|
||||
**Invariants:**
|
||||
- Only one recording session can be active at a time; starting a new recording while one is active returns HTTP 409 Conflict
|
||||
- Recording with `duration_secs` set auto-stops after the specified elapsed time
|
||||
- A `.meta.json` companion file is written when a recording stops, capturing final frame count and duration
|
||||
- `data/recordings/` directory is created at startup if it does not exist
|
||||
- Frame writer acquires a read lock on `AppStateInner` per tick; stop acquires a write lock
|
||||
|
||||
---
|
||||
|
||||
### 4. Training Pipeline Context
|
||||
|
||||
**Responsibility:** Run background training against recorded CSI data, stream epoch-level progress via WebSocket, and export trained models as `.rvf` containers. Supports supervised training, contrastive pretraining (ADR-024), and LoRA fine-tuning.
|
||||
|
||||
```
|
||||
+------------------------------------------------------------+
|
||||
| Training Pipeline Context |
|
||||
+------------------------------------------------------------+
|
||||
| |
|
||||
| +----------------+ +----------------+ |
|
||||
| | Training API | | WebSocket | |
|
||||
| | (start/stop/ | | Progress | |
|
||||
| | status) | | Streamer | |
|
||||
| +-------+--------+ +-------+--------+ |
|
||||
| | ^ |
|
||||
| v | |
|
||||
| +-------------------+ | |
|
||||
| | Training | | |
|
||||
| | Orchestrator +--------+ |
|
||||
| | (tokio::spawn) | broadcast::Sender |
|
||||
| +--------+----------+ |
|
||||
| v |
|
||||
| +-------------------+ |
|
||||
| | Feature | |
|
||||
| | Extractor | |
|
||||
| | (subcarrier var, | |
|
||||
| | Goertzel power, | |
|
||||
| | temporal grad) | |
|
||||
| +--------+----------+ |
|
||||
| v |
|
||||
| +-------------------+ |
|
||||
| | Gradient Descent | |
|
||||
| | Trainer | |
|
||||
| | (batch SGD, |---> TrainingProgress |
|
||||
| | early stopping, | |
|
||||
| | warmup) | |
|
||||
| +--------+----------+ |
|
||||
| v |
|
||||
| +-------------------+ |
|
||||
| | RVF Exporter | |
|
||||
| | (RvfBuilder -> |---> data/models/*.rvf |
|
||||
| | .rvf container) | |
|
||||
| +-------------------+ |
|
||||
| |
|
||||
+------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Aggregates:**
|
||||
|
||||
```rust
|
||||
/// Aggregate Root: Runtime training state stored in AppStateInner.
|
||||
/// At most one training run can be active at any time.
|
||||
pub struct TrainingState {
|
||||
/// Current status snapshot.
|
||||
pub status: TrainingStatus,
|
||||
/// Handle to the background training task (for cancellation).
|
||||
pub task_handle: Option<tokio::task::JoinHandle<()>>,
|
||||
}
|
||||
```
|
||||
|
||||
**Value Objects:**
|
||||
|
||||
```rust
|
||||
/// Current training status (returned by GET /api/v1/train/status).
|
||||
pub struct TrainingStatus {
|
||||
pub active: bool,
|
||||
pub epoch: u32,
|
||||
pub total_epochs: u32,
|
||||
pub train_loss: f64,
|
||||
pub val_pck: f64, // Percentage of Correct Keypoints
|
||||
pub val_oks: f64, // Object Keypoint Similarity
|
||||
pub lr: f64, // current learning rate
|
||||
pub best_pck: f64,
|
||||
pub best_epoch: u32,
|
||||
pub patience_remaining: u32,
|
||||
pub eta_secs: Option<u64>,
|
||||
pub phase: String, // "idle" | "training" | "complete" | "failed"
|
||||
}
|
||||
|
||||
/// Progress update sent over WebSocket to connected UI clients.
|
||||
pub struct TrainingProgress {
|
||||
pub epoch: u32,
|
||||
pub batch: u32,
|
||||
pub total_batches: u32,
|
||||
pub train_loss: f64,
|
||||
pub val_pck: f64,
|
||||
pub val_oks: f64,
|
||||
pub lr: f64,
|
||||
pub phase: String,
|
||||
}
|
||||
|
||||
/// Training configuration submitted with a start request.
|
||||
pub struct TrainingConfig {
|
||||
pub epochs: u32, // default: 100
|
||||
pub batch_size: u32, // default: 8
|
||||
pub learning_rate: f64, // default: 0.001
|
||||
pub weight_decay: f64, // default: 1e-4
|
||||
pub early_stopping_patience: u32, // default: 20
|
||||
pub warmup_epochs: u32, // default: 5
|
||||
pub pretrained_rvf: Option<String>,
|
||||
pub lora_profile: Option<String>,
|
||||
}
|
||||
|
||||
/// Request to start supervised training.
|
||||
pub struct StartTrainingRequest {
|
||||
pub dataset_ids: Vec<String>, // recording session IDs
|
||||
pub config: TrainingConfig,
|
||||
}
|
||||
|
||||
/// Request to start contrastive pretraining (ADR-024).
|
||||
pub struct PretrainRequest {
|
||||
pub dataset_ids: Vec<String>,
|
||||
pub epochs: u32, // default: 50
|
||||
pub lr: f64, // default: 0.001
|
||||
}
|
||||
|
||||
/// Request to start LoRA fine-tuning.
|
||||
pub struct LoraTrainRequest {
|
||||
pub base_model_id: String,
|
||||
pub dataset_ids: Vec<String>,
|
||||
pub profile_name: String,
|
||||
pub rank: u8, // default: 8
|
||||
pub epochs: u32, // default: 30
|
||||
}
|
||||
```
|
||||
|
||||
**Domain Services:**
|
||||
- `TrainingOrchestrationService` -- Spawns a background `tokio::task`, loads recorded frames, runs feature extraction, executes gradient descent with early stopping and warmup
|
||||
- `FeatureExtractionService` -- Computes per-subcarrier sliding-window variance, temporal gradients, Goertzel frequency-domain power across 9 bands, and 3 global scalar features (mean amplitude, std, motion score)
|
||||
- `ProgressBroadcastService` -- Sends `TrainingProgress` messages through a `broadcast::Sender` channel that WebSocket handlers subscribe to
|
||||
- `RvfExportService` -- Uses `RvfBuilder` to write the best checkpoint as a `.rvf` container to `data/models/`
|
||||
|
||||
**Invariants:**
|
||||
- Only one training run can be active at a time; starting training while one is running returns HTTP 409 Conflict
|
||||
- Training requires at least one recording with a minimum frame count before starting
|
||||
- Early stopping halts training after `patience` epochs with no improvement in `val_pck`
|
||||
- Learning rate warmup ramps linearly from 0 to `learning_rate` over `warmup_epochs`
|
||||
- On completion, the best model (by `val_pck`) is automatically exported as `.rvf`
|
||||
- Training status phase transitions: `idle` -> `training` -> `complete` | `failed` -> `idle`
|
||||
- Stopping an active training run aborts the background task via `JoinHandle::abort()` and resets phase to `idle`
|
||||
|
||||
---
|
||||
|
||||
### 5. Visualization Context
|
||||
|
||||
**Responsibility:** Stream sensing data to web UI clients via WebSocket, render Gaussian splat visualizations, display data source transparency indicators, and manage UI mode (full vs. sensing-only).
|
||||
|
||||
```
|
||||
+------------------------------------------------------------+
|
||||
| Visualization Context |
|
||||
+------------------------------------------------------------+
|
||||
| |
|
||||
| +----------------+ +----------------+ |
|
||||
| | WebSocket | | Sensing | |
|
||||
| | Hub | | Service (JS) | |
|
||||
| | (/ws/sensing) | | (client-side | |
|
||||
| | broadcast:: | | reconnect + | |
|
||||
| | Receiver | | sim fallback)| |
|
||||
| +-------+--------+ +-------+--------+ |
|
||||
| | | |
|
||||
| +----------+----------+ |
|
||||
| v |
|
||||
| +----------------------------------------------+ |
|
||||
| | UI Components | |
|
||||
| | | |
|
||||
| | +----------+ +----------+ +----------+ | |
|
||||
| | | Sensing | | Live | | Models | | |
|
||||
| | | Tab | | Demo Tab | | Tab | | |
|
||||
| | | (splats) | | (pose) | | (manage) | | |
|
||||
| | +----------+ +----------+ +----------+ | |
|
||||
| | +----------+ +----------+ | |
|
||||
| | | Recording| | Training | | |
|
||||
| | | Tab | | Tab | | |
|
||||
| | | (capture)| | (train) | | |
|
||||
| | +----------+ +----------+ | |
|
||||
| +----------------------------------------------+ |
|
||||
| |
|
||||
+------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Value Objects:**
|
||||
|
||||
```rust
|
||||
/// Data source indicator shown in the UI (ADR-035).
|
||||
pub enum DataSourceIndicator {
|
||||
LiveEsp32, // Green banner: "LIVE - ESP32"
|
||||
Reconnecting, // Yellow banner: "RECONNECTING..."
|
||||
Simulated, // Red banner: "SIMULATED DATA"
|
||||
}
|
||||
|
||||
/// Pose estimation mode badge (ADR-035).
|
||||
pub enum EstimationMode {
|
||||
SignalDerived, // Green badge: analytical pose from CSI features
|
||||
ModelInference, // Blue badge: neural network inference from loaded RVF
|
||||
}
|
||||
|
||||
/// Render mode for pose visualization (ADR-035).
|
||||
pub enum RenderMode {
|
||||
Skeleton, // Green lines connecting joints + red keypoint dots
|
||||
Keypoints, // Large colored dots with glow and labels
|
||||
Heatmap, // Gaussian radial blobs per keypoint, faint skeleton overlay
|
||||
Dense, // Body region segmentation with colored filled polygons
|
||||
}
|
||||
```
|
||||
|
||||
**Domain Services:**
|
||||
- `WebSocketBroadcastService` -- Subscribes to `broadcast::Sender<String>`, forwards each `SensingUpdate` JSON to all connected WebSocket clients
|
||||
- `SensingServiceJS` -- Client-side JavaScript that manages WebSocket connection, tracks `dataSource` state, falls back to simulation after 5 failed reconnect attempts (~30s delay)
|
||||
- `GaussianSplatRenderer` -- Custom GLSL `ShaderMaterial` rendering point-cloud splats on a 20x20 floor grid, colored by signal intensity
|
||||
- `PoseRenderer` -- Renders skeleton, keypoints, heatmap, or dense body segmentation modes
|
||||
- `BackendDetector` -- Auto-detects whether the full DensePose backend is available; sets `sensingOnlyMode = true` if unreachable
|
||||
|
||||
**Invariants:**
|
||||
- WebSocket sensing service is started on application init, not lazily on tab visit (ADR-043 fix)
|
||||
- Simulation fallback is delayed to 5 failed reconnect attempts (~30 seconds) to avoid premature synthetic data
|
||||
- `pose_source` field is passed through data conversion so the Estimation Mode badge displays correctly
|
||||
- Dashboard and Live Demo tabs read `sensingService.dataSource` at load time -- the service must already be connected
|
||||
|
||||
---
|
||||
|
||||
## Domain Events
|
||||
|
||||
| Event | Published By | Consumed By | Payload |
|
||||
|-------|-------------|-------------|---------|
|
||||
| `ServerStarted` | CSI Ingestion | Visualization | `{ http_port, udp_port, source_type }` |
|
||||
| `CsiFrameIngested` | CSI Ingestion | Recording, Visualization | `{ source, node_id, subcarrier_count, tick }` |
|
||||
| `SensingUpdateBroadcast` | CSI Ingestion | Visualization (WebSocket) | Full `SensingUpdate` JSON |
|
||||
| `ModelLoaded` | Model Management | CSI Ingestion (inference path) | `{ model_id, weight_count, version }` |
|
||||
| `ModelUnloaded` | Model Management | CSI Ingestion | `{ model_id }` |
|
||||
| `LoraProfileActivated` | Model Management | CSI Ingestion | `{ model_id, profile_name }` |
|
||||
| `RecordingStarted` | Recording | Visualization | `{ session_id, session_name, file_path }` |
|
||||
| `RecordingStopped` | Recording | Visualization | `{ session_id, frame_count, duration_secs }` |
|
||||
| `TrainingStarted` | Training Pipeline | Visualization | `{ run_id, config, recording_ids }` |
|
||||
| `TrainingEpochComplete` | Training Pipeline | Visualization (WebSocket) | `{ epoch, total_epochs, train_loss, val_pck, lr }` |
|
||||
| `TrainingComplete` | Training Pipeline | Model Management, Visualization | `{ run_id, final_pck, model_path }` |
|
||||
| `TrainingFailed` | Training Pipeline | Visualization | `{ run_id, error_message }` |
|
||||
| `WebSocketClientConnected` | Visualization | -- | `{ endpoint, client_addr }` |
|
||||
| `WebSocketClientDisconnected` | Visualization | -- | `{ endpoint, client_addr }` |
|
||||
|
||||
In the current implementation, events are realized through two mechanisms:
|
||||
1. **`broadcast::Sender<String>`** for WebSocket fan-out of sensing updates
|
||||
2. **`broadcast::Sender<TrainingProgress>`** for training progress streaming
|
||||
3. **State mutations via RwLock** where other contexts read state changes on their next tick
|
||||
|
||||
---
|
||||
|
||||
## Context Map
|
||||
|
||||
```
|
||||
+-------------------+ +---------------------+
|
||||
| CSI Ingestion |--------->| Visualization |
|
||||
| (produces | publish | (WebSocket |
|
||||
| SensingUpdate) | -------> | consumers) |
|
||||
+--------+----------+ +----------+----------+
|
||||
| |
|
||||
| maybe_record_frame() | reads dataSource
|
||||
v |
|
||||
+-------------------+ |
|
||||
| CSI Recording | |
|
||||
| (hooks into | |
|
||||
| tick loop) | |
|
||||
+--------+----------+ |
|
||||
| |
|
||||
| provides dataset_ids |
|
||||
v |
|
||||
+-------------------+ +----------+----------+
|
||||
| Training Pipeline |--------->| Model Management |
|
||||
| (reads .jsonl, | exports | (loads .rvf for |
|
||||
| trains model) | .rvf --> | inference) |
|
||||
+-------------------+ +----------+----------+
|
||||
|
|
||||
| model weights
|
||||
v
|
||||
+----------+----------+
|
||||
| CSI Ingestion |
|
||||
| (inference path |
|
||||
| uses loaded model)|
|
||||
+----------------------+
|
||||
```
|
||||
|
||||
**Relationships:**
|
||||
|
||||
| Upstream | Downstream | Relationship | Mechanism |
|
||||
|----------|-----------|--------------|-----------|
|
||||
| CSI Ingestion | Visualization | Published Language | `broadcast::Sender<String>` with `SensingUpdate` JSON schema |
|
||||
| CSI Ingestion | CSI Recording | Shared Kernel | `maybe_record_frame()` called from the ingestion tick loop |
|
||||
| CSI Recording | Training Pipeline | Conformist | Training reads `.csi.jsonl` files produced by recording; no negotiation on format |
|
||||
| Training Pipeline | Model Management | Supplier-Consumer | Training exports `.rvf` to `data/models/`; Model Management scans and loads |
|
||||
| Model Management | CSI Ingestion | Shared Kernel | Loaded weights stored in `AppStateInner`; ingestion reads them for inference |
|
||||
| Training Pipeline | Visualization | Published Language | `broadcast::Sender<TrainingProgress>` with progress JSON schema |
|
||||
|
||||
---
|
||||
|
||||
## Anti-Corruption Layers
|
||||
|
||||
### ESP32 Binary Protocol ACL
|
||||
|
||||
The ESP32 sends CSI frames using a compact binary protocol (ADR-018): 20-byte header with magic `0xC5100001`, followed by amplitude and phase arrays. The `Esp32Frame` parser in the ingestion context decodes this binary format into domain value objects (`NodeInfo`, amplitude/phase vectors) before any downstream processing. No other context handles raw UDP bytes.
|
||||
|
||||
### RVF Container ACL
|
||||
|
||||
The `.rvf` container format encapsulates model weights, manifest metadata, vital sign configuration, and optional LoRA adapters. The `RvfReader` and `RvfBuilder` types in the `rvf_container` module provide the anti-corruption layer between the on-disk binary format and the domain types (`ModelInfo`, `LoadedModelState`). The training pipeline writes through `RvfBuilder`; the model management context reads through `RvfReader`.
|
||||
|
||||
### Sensing-Only Mode ACL (Client-Side)
|
||||
|
||||
When the DensePose backend (port 8000) is unreachable, the client-side `BackendDetector` sets `sensingOnlyMode = true`. The `ApiService.request()` method short-circuits all requests to the DensePose backend, returning empty responses instead of `ERR_CONNECTION_REFUSED`. This prevents DensePose-specific concerns from leaking into the sensing UI.
|
||||
|
||||
### JSONL Recording Format ACL
|
||||
|
||||
CSI frames are recorded as newline-delimited JSON (`.csi.jsonl`). The `RecordedFrame` struct defines the schema: `{timestamp, subcarriers, rssi, noise_floor, features}`. The training pipeline reads through this schema, extracting subcarrier arrays for feature computation. If the internal sensing representation changes, only the `maybe_record_frame()` serializer needs updating -- the training pipeline depends only on the `RecordedFrame` contract.
|
||||
|
||||
---
|
||||
|
||||
## REST API Surface
|
||||
|
||||
All endpoints share `AppStateInner` via `Arc<RwLock<AppStateInner>>`.
|
||||
|
||||
### CSI Ingestion & Sensing
|
||||
|
||||
| Method | Path | Context | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| GET | `/api/v1/sensing/latest` | Ingestion | Latest sensing update |
|
||||
| WS | `/ws/sensing` | Visualization | Streaming sensing updates |
|
||||
|
||||
### Model Management
|
||||
|
||||
| Method | Path | Context | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| GET | `/api/v1/models` | Model Mgmt | List all discovered `.rvf` models |
|
||||
| GET | `/api/v1/models/:id` | Model Mgmt | Detailed info for a specific model |
|
||||
| GET | `/api/v1/models/active` | Model Mgmt | Active model with runtime stats |
|
||||
| POST | `/api/v1/models/load` | Model Mgmt | Load model weights into memory |
|
||||
| POST | `/api/v1/models/unload` | Model Mgmt | Unload the active model |
|
||||
| DELETE | `/api/v1/models/:id` | Model Mgmt | Delete a model file from disk |
|
||||
| GET | `/api/v1/models/lora/profiles` | Model Mgmt | List LoRA profiles for active model |
|
||||
| POST | `/api/v1/models/lora/activate` | Model Mgmt | Activate a LoRA adapter |
|
||||
|
||||
### CSI Recording
|
||||
|
||||
| Method | Path | Context | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| POST | `/api/v1/recording/start` | Recording | Start a new recording session |
|
||||
| POST | `/api/v1/recording/stop` | Recording | Stop the active recording |
|
||||
| GET | `/api/v1/recording/list` | Recording | List all recording sessions |
|
||||
| GET | `/api/v1/recording/download/:id` | Recording | Download a `.csi.jsonl` file |
|
||||
| DELETE | `/api/v1/recording/:id` | Recording | Delete a recording |
|
||||
|
||||
### Training Pipeline
|
||||
|
||||
| Method | Path | Context | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| POST | `/api/v1/train/start` | Training | Start supervised training |
|
||||
| POST | `/api/v1/train/stop` | Training | Stop the active training run |
|
||||
| GET | `/api/v1/train/status` | Training | Current training phase and metrics |
|
||||
| POST | `/api/v1/train/pretrain` | Training | Start contrastive pretraining |
|
||||
| POST | `/api/v1/train/lora` | Training | Start LoRA fine-tuning |
|
||||
| WS | `/ws/train/progress` | Training | Streaming training progress |
|
||||
|
||||
---
|
||||
|
||||
## File Layout
|
||||
|
||||
```
|
||||
data/
|
||||
+-- models/ # RVF model files
|
||||
| +-- wifi-densepose-v1.rvf # Trained model container
|
||||
| +-- wifi-densepose-field-v2.rvf # Environment-calibrated model
|
||||
+-- recordings/ # CSI recording sessions
|
||||
+-- walking-20260303_140000.csi.jsonl # Raw CSI frames (JSONL)
|
||||
+-- walking-20260303_140000.csi.meta.json # Session metadata
|
||||
+-- standing-20260303_141500.csi.jsonl
|
||||
+-- standing-20260303_141500.csi.meta.json
|
||||
|
||||
crates/wifi-densepose-sensing-server/
|
||||
+-- src/
|
||||
+-- main.rs # Server entry, CLI args, AppStateInner, sensing loop
|
||||
+-- model_manager.rs # Model Management bounded context
|
||||
+-- recording.rs # CSI Recording bounded context
|
||||
+-- training_api.rs # Training Pipeline bounded context
|
||||
+-- rvf_container.rs # RVF format ACL (RvfReader, RvfBuilder)
|
||||
+-- rvf_pipeline.rs # Progressive loader for model inference
|
||||
+-- vital_signs.rs # Vital sign detection from CSI phase
|
||||
+-- dataset.rs # Dataset loading for training
|
||||
+-- trainer.rs # Core training loop implementation
|
||||
+-- embedding.rs # Contrastive embedding extraction
|
||||
+-- graph_transformer.rs # Graph transformer architecture
|
||||
+-- sona.rs # SONA self-optimizing profile
|
||||
+-- sparse_inference.rs # Sparse inference engine
|
||||
+-- lib.rs # Public module re-exports
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [ADR-019: Sensing-Only UI Mode](../adr/ADR-019-sensing-only-ui-mode.md) -- Decoupled sensing UI, Gaussian splats, Python WebSocket bridge
|
||||
- [ADR-035: Live Sensing UI Accuracy](../adr/ADR-035-live-sensing-ui-accuracy.md) -- Data transparency, Goertzel breathing estimation, signal-responsive pose
|
||||
- [ADR-043: Sensing Server UI API Completion](../adr/ADR-043-sensing-server-ui-api-completion.md) -- Model, recording, training endpoints; single-binary deployment
|
||||
- [RuvSense Domain Model](ruvsense-domain-model.md) -- Upstream signal processing domain (multistatic sensing, coherence, tracking)
|
||||
- [WiFi-Mat Domain Model](wifi-mat-domain-model.md) -- Downstream disaster response domain
|
||||
|
|
@ -0,0 +1,663 @@
|
|||
# Signal Processing Domain Model
|
||||
|
||||
## Domain-Driven Design Specification
|
||||
|
||||
Based on ADR-014 (SOTA Signal Processing) and the `wifi-densepose-signal` crate.
|
||||
|
||||
### Ubiquitous Language
|
||||
|
||||
| Term | Definition |
|
||||
|------|------------|
|
||||
| **CsiFrame** | A single CSI measurement: amplitude + phase per antenna per subcarrier at one timestamp |
|
||||
| **Conjugate Multiplication** | `H_ref[k] * conj(H_target[k])` — cancels CFO/SFO/PDD, isolating environment-induced phase |
|
||||
| **CSI Ratio** | The complex result of conjugate multiplication between two antenna streams |
|
||||
| **Hampel Filter** | Running median +/- scaled MAD outlier detector; resists up to 50% contamination |
|
||||
| **Phase Sanitization** | Pipeline of unwrapping, outlier removal, smoothing, and noise filtering on raw CSI phase |
|
||||
| **Spectrogram** | 2D time-frequency matrix from STFT, standard CNN input for WiFi activity recognition |
|
||||
| **Subcarrier Sensitivity** | Variance ratio (motion var / static var) ranking how responsive a subcarrier is to motion |
|
||||
| **Body Velocity Profile (BVP)** | Doppler-derived velocity x time 2D matrix; domain-independent motion representation |
|
||||
| **Fresnel Zone** | Ellipsoidal region between TX and RX where signal reflection/diffraction occurs |
|
||||
| **Breathing Estimate** | BPM + amplitude + confidence derived from Fresnel zone boundary crossings |
|
||||
| **Motion Score** | Composite (0.0-1.0) from variance, correlation, phase, and optional Doppler components |
|
||||
| **Presence State** | Binary detection result: human present/absent with smoothed confidence |
|
||||
| **Calibration** | Recording baseline variance during a known-empty period for adaptive detection |
|
||||
|
||||
---
|
||||
|
||||
## Bounded Contexts
|
||||
|
||||
### 1. CSI Preprocessing Context
|
||||
|
||||
**Responsibility**: Produce clean, hardware-artifact-free CSI data from raw measurements.
|
||||
|
||||
```
|
||||
+-----------------------------------------------------------+
|
||||
| CSI Preprocessing Context |
|
||||
+-----------------------------------------------------------+
|
||||
| |
|
||||
| +--------------+ +--------------+ +------------+ |
|
||||
| | Conjugate | | Hampel | | Phase | |
|
||||
| | Multiplication| | Filter | | Sanitizer | |
|
||||
| +------+-------+ +------+-------+ +-----+------+ |
|
||||
| | | | |
|
||||
| v v v |
|
||||
| +------+-------+ +------+-------+ +-----+------+ |
|
||||
| | CsiRatio | | HampelResult | | Sanitized | |
|
||||
| | (clean phase)| |(outlier-free)| | Phase | |
|
||||
| +--------------+ +--------------+ +------------+ |
|
||||
| | | | |
|
||||
| +-------------------+------------------+ |
|
||||
| | |
|
||||
| v |
|
||||
| +-------+--------+ |
|
||||
| | CsiProcessor |--> CleanedCsiData |
|
||||
| +----------------+ |
|
||||
| |
|
||||
+-----------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Aggregates**: `CsiProcessor` (Aggregate Root)
|
||||
|
||||
**Value Objects**: `CsiData`, `CsiRatio`, `HampelResult`, `HampelConfig`, `PhaseSanitizerConfig`
|
||||
|
||||
**Domain Services**: `CsiPreprocessor`, `PhaseSanitizer`
|
||||
|
||||
---
|
||||
|
||||
### 2. Feature Extraction Context
|
||||
|
||||
**Responsibility**: Transform clean CSI data into ML-ready feature representations.
|
||||
|
||||
```
|
||||
+-----------------------------------------------------------+
|
||||
| Feature Extraction Context |
|
||||
+-----------------------------------------------------------+
|
||||
| |
|
||||
| +--------------+ +--------------+ +------------+ |
|
||||
| | STFT | | Subcarrier | | Doppler | |
|
||||
| | Spectrogram | | Selection | | BVP Engine | |
|
||||
| +------+-------+ +------+-------+ +-----+------+ |
|
||||
| | | | |
|
||||
| v v v |
|
||||
| +------+-------+ +------+-------+ +-----+------+ |
|
||||
| | Spectrogram | | Subcarrier | | BodyVel | |
|
||||
| | (2D TF) | | Selection | | Profile | |
|
||||
| +--------------+ +--------------+ +------------+ |
|
||||
| | | | |
|
||||
| +-------------------+------------------+ |
|
||||
| | |
|
||||
| v |
|
||||
| +----------+----------+ |
|
||||
| | FeatureExtractor |--> CsiFeatures |
|
||||
| +---------------------+ |
|
||||
| |
|
||||
+-----------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Aggregates**: `FeatureExtractor` (Aggregate Root)
|
||||
|
||||
**Value Objects**: `Spectrogram`, `SubcarrierSelection`, `BodyVelocityProfile`, `CsiFeatures`
|
||||
|
||||
**Domain Services**: `SpectrogramConfig`, `SubcarrierSelectionConfig`, `BvpConfig`
|
||||
|
||||
---
|
||||
|
||||
### 3. Motion Analysis Context
|
||||
|
||||
**Responsibility**: Detect and classify human motion and vital signs from CSI features.
|
||||
|
||||
```
|
||||
+-----------------------------------------------------------+
|
||||
| Motion Analysis Context |
|
||||
+-----------------------------------------------------------+
|
||||
| |
|
||||
| +--------------+ +--------------+ |
|
||||
| | Motion | | Fresnel | |
|
||||
| | Detector | | Breathing | |
|
||||
| +------+-------+ +------+-------+ |
|
||||
| | | |
|
||||
| v v |
|
||||
| +------+-------+ +------+-------+ |
|
||||
| | MotionScore | | Breathing | |
|
||||
| |+ Detection | | Estimate | |
|
||||
| +--------------+ +--------------+ |
|
||||
| | | |
|
||||
| +-------------------+ |
|
||||
| | |
|
||||
| v |
|
||||
| +--------+--------+ |
|
||||
| | HumanDetection |--> PresenceState |
|
||||
| | Result | |
|
||||
| +-----------------+ |
|
||||
| |
|
||||
+-----------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Aggregates**: `MotionDetector` (Aggregate Root)
|
||||
|
||||
**Value Objects**: `MotionScore`, `MotionAnalysis`, `HumanDetectionResult`, `BreathingEstimate`, `FresnelGeometry`
|
||||
|
||||
**Domain Services**: `FresnelBreathingEstimator`
|
||||
|
||||
---
|
||||
|
||||
## Aggregates
|
||||
|
||||
### CsiProcessor (CSI Preprocessing Root)
|
||||
|
||||
```rust
|
||||
pub struct CsiProcessor {
|
||||
config: CsiProcessorConfig,
|
||||
preprocessor: CsiPreprocessor,
|
||||
history: VecDeque<CsiData>,
|
||||
previous_detection_confidence: f64,
|
||||
statistics: ProcessingStatistics,
|
||||
}
|
||||
|
||||
impl CsiProcessor {
|
||||
/// Create with validated configuration
|
||||
pub fn new(config: CsiProcessorConfig) -> Result<Self, CsiProcessorError>;
|
||||
|
||||
/// Full preprocessing pipeline: noise removal -> windowing -> normalization
|
||||
pub fn preprocess(&self, csi_data: &CsiData) -> Result<CsiData, CsiProcessorError>;
|
||||
|
||||
/// Maintain temporal history for downstream feature extraction
|
||||
pub fn add_to_history(&mut self, csi_data: CsiData);
|
||||
|
||||
/// Apply exponential moving average to detection confidence
|
||||
pub fn apply_temporal_smoothing(&mut self, raw_confidence: f64) -> f64;
|
||||
}
|
||||
```
|
||||
|
||||
### FeatureExtractor (Feature Extraction Root)
|
||||
|
||||
```rust
|
||||
pub struct FeatureExtractor {
|
||||
config: FeatureExtractorConfig,
|
||||
}
|
||||
|
||||
impl FeatureExtractor {
|
||||
/// Extract all feature types from a single CsiData snapshot
|
||||
pub fn extract(&self, csi_data: &CsiData) -> CsiFeatures;
|
||||
}
|
||||
```
|
||||
|
||||
### MotionDetector (Motion Analysis Root)
|
||||
|
||||
```rust
|
||||
pub struct MotionDetector {
|
||||
config: MotionDetectorConfig,
|
||||
previous_confidence: f64,
|
||||
motion_history: VecDeque<MotionScore>,
|
||||
baseline_variance: Option<f64>,
|
||||
}
|
||||
|
||||
impl MotionDetector {
|
||||
/// Analyze motion from extracted features
|
||||
pub fn analyze_motion(&self, features: &CsiFeatures) -> MotionAnalysis;
|
||||
|
||||
/// Full detection pipeline: analyze -> score -> smooth -> threshold
|
||||
pub fn detect_human(&mut self, features: &CsiFeatures) -> HumanDetectionResult;
|
||||
|
||||
/// Record baseline variance for adaptive detection
|
||||
pub fn calibrate(&mut self, features: &CsiFeatures);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Value Objects
|
||||
|
||||
### CsiData
|
||||
|
||||
```rust
|
||||
pub struct CsiData {
|
||||
pub timestamp: DateTime<Utc>,
|
||||
pub amplitude: Array2<f64>, // (num_antennas x num_subcarriers)
|
||||
pub phase: Array2<f64>, // (num_antennas x num_subcarriers), radians
|
||||
pub frequency: f64, // center frequency in Hz
|
||||
pub bandwidth: f64, // bandwidth in Hz
|
||||
pub num_subcarriers: usize,
|
||||
pub num_antennas: usize,
|
||||
pub snr: f64, // signal-to-noise ratio in dB
|
||||
pub metadata: CsiMetadata,
|
||||
}
|
||||
```
|
||||
|
||||
### Spectrogram
|
||||
|
||||
```rust
|
||||
pub struct Spectrogram {
|
||||
pub data: Array2<f64>, // (n_freq x n_time) power/magnitude
|
||||
pub n_freq: usize, // frequency bins (window_size/2 + 1)
|
||||
pub n_time: usize, // time frames
|
||||
pub freq_resolution: f64, // Hz per bin
|
||||
pub time_resolution: f64, // seconds per frame
|
||||
}
|
||||
```
|
||||
|
||||
### SubcarrierSelection
|
||||
|
||||
```rust
|
||||
pub struct SubcarrierSelection {
|
||||
pub selected_indices: Vec<usize>, // ranked by sensitivity, descending
|
||||
pub sensitivity_scores: Vec<f64>, // variance ratio for ALL subcarriers
|
||||
pub selected_data: Option<Array2<f64>>, // filtered matrix (optional)
|
||||
}
|
||||
```
|
||||
|
||||
### BodyVelocityProfile
|
||||
|
||||
```rust
|
||||
pub struct BodyVelocityProfile {
|
||||
pub data: Array2<f64>, // (n_velocity_bins x n_time_frames)
|
||||
pub velocity_bins: Vec<f64>, // velocity value for each row (m/s)
|
||||
pub n_time: usize,
|
||||
pub time_resolution: f64, // seconds per frame
|
||||
pub velocity_resolution: f64, // m/s per bin
|
||||
}
|
||||
```
|
||||
|
||||
### BreathingEstimate
|
||||
|
||||
```rust
|
||||
pub struct BreathingEstimate {
|
||||
pub rate_bpm: f64, // breaths per minute
|
||||
pub confidence: f64, // combined confidence (0.0-1.0)
|
||||
pub period_seconds: f64, // estimated breathing period
|
||||
pub autocorrelation_peak: f64, // periodicity quality
|
||||
pub fresnel_confidence: f64, // Fresnel model match
|
||||
pub amplitude_variation: f64, // observed amplitude variation
|
||||
}
|
||||
```
|
||||
|
||||
### MotionScore
|
||||
|
||||
```rust
|
||||
pub struct MotionScore {
|
||||
pub total: f64, // weighted composite (0.0-1.0)
|
||||
pub variance_component: f64,
|
||||
pub correlation_component: f64,
|
||||
pub phase_component: f64,
|
||||
pub doppler_component: Option<f64>,
|
||||
}
|
||||
```
|
||||
|
||||
### HampelResult
|
||||
|
||||
```rust
|
||||
pub struct HampelResult {
|
||||
pub filtered: Vec<f64>, // outliers replaced with local median
|
||||
pub outlier_indices: Vec<usize>,
|
||||
pub medians: Vec<f64>, // local median at each sample
|
||||
pub sigma_estimates: Vec<f64>, // estimated local sigma at each sample
|
||||
}
|
||||
```
|
||||
|
||||
### FresnelGeometry
|
||||
|
||||
```rust
|
||||
pub struct FresnelGeometry {
|
||||
pub d_tx_body: f64, // TX to body distance (meters)
|
||||
pub d_body_rx: f64, // body to RX distance (meters)
|
||||
pub frequency: f64, // carrier frequency (Hz)
|
||||
}
|
||||
|
||||
impl FresnelGeometry {
|
||||
pub fn wavelength(&self) -> f64;
|
||||
pub fn fresnel_radius(&self, n: u32) -> f64;
|
||||
pub fn phase_change(&self, displacement_m: f64) -> f64;
|
||||
pub fn expected_amplitude_variation(&self, displacement_m: f64) -> f64;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Domain Events
|
||||
|
||||
### Preprocessing Events
|
||||
|
||||
```rust
|
||||
pub enum PreprocessingEvent {
|
||||
/// Raw CSI frame cleaned through the full pipeline
|
||||
FrameCleaned {
|
||||
timestamp: DateTime<Utc>,
|
||||
num_antennas: usize,
|
||||
num_subcarriers: usize,
|
||||
noise_filtered: bool,
|
||||
windowed: bool,
|
||||
normalized: bool,
|
||||
},
|
||||
|
||||
/// Outliers detected and replaced by Hampel filter
|
||||
OutliersDetected {
|
||||
subcarrier_indices: Vec<usize>,
|
||||
replacement_values: Vec<f64>,
|
||||
contamination_ratio: f64,
|
||||
},
|
||||
|
||||
/// Phase sanitization completed
|
||||
PhaseSanitized {
|
||||
method: UnwrappingMethod,
|
||||
outliers_removed: usize,
|
||||
smoothing_applied: bool,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Feature Extraction Events
|
||||
|
||||
```rust
|
||||
pub enum FeatureExtractionEvent {
|
||||
/// Spectrogram computed from temporal CSI stream
|
||||
SpectrogramGenerated {
|
||||
n_time: usize,
|
||||
n_freq: usize,
|
||||
window_size: usize,
|
||||
window_fn: WindowFunction,
|
||||
},
|
||||
|
||||
/// Top-K sensitive subcarriers selected
|
||||
SubcarriersSelected {
|
||||
top_k_indices: Vec<usize>,
|
||||
sensitivity_scores: Vec<f64>,
|
||||
min_sensitivity_threshold: f64,
|
||||
},
|
||||
|
||||
/// Body Velocity Profile extracted
|
||||
BvpExtracted {
|
||||
n_velocity_bins: usize,
|
||||
n_time_frames: usize,
|
||||
max_velocity: f64,
|
||||
carrier_frequency: f64,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Motion Analysis Events
|
||||
|
||||
```rust
|
||||
pub enum MotionAnalysisEvent {
|
||||
/// Human motion detected above threshold
|
||||
MotionDetected {
|
||||
score: MotionScore,
|
||||
confidence: f64,
|
||||
threshold: f64,
|
||||
timestamp: DateTime<Utc>,
|
||||
},
|
||||
|
||||
/// Breathing detected via Fresnel zone model
|
||||
BreathingDetected {
|
||||
rate_bpm: f64,
|
||||
amplitude_variation: f64,
|
||||
fresnel_confidence: f64,
|
||||
autocorrelation_peak: f64,
|
||||
},
|
||||
|
||||
/// Presence state changed (entered or left)
|
||||
PresenceChanged {
|
||||
previous: bool,
|
||||
current: bool,
|
||||
smoothed_confidence: f64,
|
||||
timestamp: DateTime<Utc>,
|
||||
},
|
||||
|
||||
/// Detector calibrated with baseline variance
|
||||
BaselineCalibrated {
|
||||
baseline_variance: f64,
|
||||
timestamp: DateTime<Utc>,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Invariants
|
||||
|
||||
### CSI Preprocessing Invariants
|
||||
|
||||
1. **Conjugate multiplication requires >= 2 antenna elements.** `compute_ratio_matrix` returns `CsiRatioError::InsufficientAntennas` if `n_ant < 2`. Without two antennas, there is no pair to cancel common-mode offsets.
|
||||
|
||||
2. **Hampel filter window must be >= 1 (half_window > 0).** A zero-width window cannot compute a local median. Enforced by `HampelError::InvalidWindow`.
|
||||
|
||||
3. **Phase data must be within configured range before sanitization.** Default range is `[-pi, pi]`. Enforced by `PhaseSanitizer::validate_phase_data`.
|
||||
|
||||
4. **Antenna stream lengths must match for conjugate multiplication.** `conjugate_multiply` returns `CsiRatioError::LengthMismatch` if `h_ref.len() != h_target.len()`.
|
||||
|
||||
### Feature Extraction Invariants
|
||||
|
||||
5. **Spectrogram window size must be > 0 and signal must be >= window_size samples.** Enforced by `SpectrogramError::SignalTooShort` and `SpectrogramError::InvalidWindowSize`.
|
||||
|
||||
6. **Subcarrier selection must receive matching subcarrier counts.** Motion and static data must have the same number of columns. Enforced by `SelectionError::SubcarrierCountMismatch`.
|
||||
|
||||
7. **BVP requires >= window_size temporal samples.** Insufficient history prevents STFT computation. Enforced by `BvpError::InsufficientSamples`.
|
||||
|
||||
8. **BVP carrier frequency must be > 0 for wavelength calculation.** Zero frequency would produce a division-by-zero in the Doppler-to-velocity mapping.
|
||||
|
||||
### Motion Analysis Invariants
|
||||
|
||||
9. **Fresnel geometry requires positive distances (d_tx_body > 0, d_body_rx > 0).** Zero or negative distances are physically impossible. Enforced by `FresnelError::InvalidDistance`.
|
||||
|
||||
10. **Fresnel frequency must be positive.** Required for wavelength computation. Enforced by `FresnelError::InvalidFrequency`.
|
||||
|
||||
11. **Breathing estimation requires >= 10 amplitude samples.** Fewer samples cannot support autocorrelation analysis. Enforced by `FresnelError::InsufficientData`.
|
||||
|
||||
12. **Motion detector history does not exceed configured max size.** Oldest entries are evicted via `VecDeque::pop_front` when capacity is reached.
|
||||
|
||||
---
|
||||
|
||||
## Domain Services
|
||||
|
||||
### CsiPreprocessor
|
||||
|
||||
Orchestrates the cleaning pipeline for a single CSI frame.
|
||||
|
||||
```rust
|
||||
pub struct CsiPreprocessor {
|
||||
noise_threshold: f64,
|
||||
}
|
||||
|
||||
impl CsiPreprocessor {
|
||||
/// Remove subcarriers below noise floor (amplitude in dB < threshold)
|
||||
pub fn remove_noise(&self, csi_data: &CsiData) -> Result<CsiData, CsiProcessorError>;
|
||||
|
||||
/// Apply Hamming window to reduce spectral leakage
|
||||
pub fn apply_windowing(&self, csi_data: &CsiData) -> Result<CsiData, CsiProcessorError>;
|
||||
|
||||
/// Normalize amplitude to unit variance
|
||||
pub fn normalize_amplitude(&self, csi_data: &CsiData) -> Result<CsiData, CsiProcessorError>;
|
||||
}
|
||||
```
|
||||
|
||||
### PhaseSanitizer
|
||||
|
||||
Full phase cleaning pipeline: unwrap -> outlier removal -> smoothing -> noise filtering.
|
||||
|
||||
```rust
|
||||
pub struct PhaseSanitizer {
|
||||
config: PhaseSanitizerConfig,
|
||||
statistics: SanitizationStatistics,
|
||||
}
|
||||
|
||||
impl PhaseSanitizer {
|
||||
/// Complete sanitization pipeline (all four stages)
|
||||
pub fn sanitize_phase(
|
||||
&mut self,
|
||||
phase_data: &Array2<f64>,
|
||||
) -> Result<Array2<f64>, PhaseSanitizationError>;
|
||||
}
|
||||
```
|
||||
|
||||
### FresnelBreathingEstimator
|
||||
|
||||
Physics-based breathing detection using Fresnel zone geometry.
|
||||
|
||||
```rust
|
||||
pub struct FresnelBreathingEstimator {
|
||||
geometry: FresnelGeometry,
|
||||
min_displacement: f64, // 3mm default
|
||||
max_displacement: f64, // 15mm default
|
||||
}
|
||||
|
||||
impl FresnelBreathingEstimator {
|
||||
/// Check if amplitude variation matches Fresnel breathing model
|
||||
pub fn breathing_confidence(&self, observed_amplitude_variation: f64) -> f64;
|
||||
|
||||
/// Estimate breathing rate via autocorrelation + Fresnel validation
|
||||
pub fn estimate_breathing_rate(
|
||||
&self,
|
||||
amplitude_signal: &[f64],
|
||||
sample_rate: f64,
|
||||
) -> Result<BreathingEstimate, FresnelError>;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Context Map
|
||||
|
||||
```
|
||||
+--------------------------------------------------------------+
|
||||
| Signal Processing System |
|
||||
+--------------------------------------------------------------+
|
||||
| |
|
||||
| +----------------+ Published +------------------+ |
|
||||
| | CSI | Language | Feature | |
|
||||
| | Preprocessing |------------>| Extraction | |
|
||||
| | Context | CsiData | Context | |
|
||||
| +-------+--------+ +--------+---------+ |
|
||||
| | | |
|
||||
| | Publishes | Publishes |
|
||||
| | CleanedCsiData | CsiFeatures |
|
||||
| v v |
|
||||
| +-------+-------------------------------+---------+ |
|
||||
| | Event Bus (Domain Events) | |
|
||||
| +---------------------------+---------------------+ |
|
||||
| | |
|
||||
| | Subscribes |
|
||||
| v |
|
||||
| +---------+---------+ |
|
||||
| | Motion | |
|
||||
| | Analysis | |
|
||||
| | Context | |
|
||||
| +-------------------+ |
|
||||
| |
|
||||
+---------------------------------------------------------------+
|
||||
| DOWNSTREAM (Customer/Supplier) |
|
||||
| +-----------------+ +------------------+ +--------------+ |
|
||||
| | wifi-densepose | | wifi-densepose | |wifi-densepose| |
|
||||
| | -nn | | -mat | | -train | |
|
||||
| | (consumes | | (consumes | |(consumes | |
|
||||
| | CsiFeatures, | | BreathingEst, | | CsiFeatures) | |
|
||||
| | Spectrogram) | | MotionScore) | | | |
|
||||
| +-----------------+ +------------------+ +--------------+ |
|
||||
+---------------------------------------------------------------+
|
||||
| UPSTREAM (Conformist) |
|
||||
| +-----------------+ +------------------+ |
|
||||
| | wifi-densepose | | wifi-densepose | |
|
||||
| | -core | | -hardware | |
|
||||
| | (CsiFrame | | (ESP32 raw CSI | |
|
||||
| | primitives) | | data ingestion) | |
|
||||
| +-----------------+ +------------------+ |
|
||||
+---------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Relationship Types**:
|
||||
- Preprocessing -> Feature Extraction: **Published Language** (CsiData is the shared contract)
|
||||
- Preprocessing -> Motion Analysis: **Customer/Supplier** (Preprocessing supplies cleaned data)
|
||||
- Feature Extraction -> Motion Analysis: **Customer/Supplier** (Features supplies CsiFeatures)
|
||||
- Signal -> wifi-densepose-nn: **Customer/Supplier** (Signal publishes Spectrogram, BVP)
|
||||
- Signal -> wifi-densepose-mat: **Customer/Supplier** (Signal publishes BreathingEstimate, MotionScore)
|
||||
- Signal <- wifi-densepose-core: **Conformist** (Signal adapts to core CsiFrame types)
|
||||
- Signal <- wifi-densepose-hardware: **Conformist** (Signal adapts to raw ESP32 CSI format)
|
||||
|
||||
---
|
||||
|
||||
## Anti-Corruption Layers
|
||||
|
||||
### Hardware ACL (Upstream)
|
||||
|
||||
Translates raw ESP32 CSI packets into the signal crate's `CsiData` value object, normalizing hardware-specific quirks (LLTF/HT-LTF format differences, antenna mapping, null subcarrier handling).
|
||||
|
||||
```rust
|
||||
/// Normalizes vendor-specific CSI frames to canonical CsiData
|
||||
pub struct HardwareNormalizer {
|
||||
hardware_type: HardwareType,
|
||||
}
|
||||
|
||||
impl HardwareNormalizer {
|
||||
/// Convert raw hardware bytes to canonical CsiData
|
||||
pub fn normalize(
|
||||
&self,
|
||||
raw_csi: &[u8],
|
||||
hardware_type: HardwareType,
|
||||
) -> Result<CanonicalCsiFrame, HardwareNormError>;
|
||||
}
|
||||
|
||||
pub enum HardwareType {
|
||||
Esp32S3,
|
||||
Intel5300,
|
||||
AtherosAr9580,
|
||||
Simulation,
|
||||
}
|
||||
```
|
||||
|
||||
### Neural Network ACL (Downstream)
|
||||
|
||||
Adapts signal processing outputs (Spectrogram, BVP, CsiFeatures) into tensor formats expected by the `wifi-densepose-nn` crate. This boundary prevents neural network model details from leaking into the signal processing domain.
|
||||
|
||||
```rust
|
||||
/// Adapts signal crate types to neural network tensor format
|
||||
pub struct SignalToTensorAdapter;
|
||||
|
||||
impl SignalToTensorAdapter {
|
||||
/// Convert Spectrogram to CNN-ready 2D tensor
|
||||
pub fn spectrogram_to_tensor(spec: &Spectrogram) -> Array2<f32> {
|
||||
spec.data.mapv(|v| v as f32)
|
||||
}
|
||||
|
||||
/// Convert BVP to domain-independent velocity tensor
|
||||
pub fn bvp_to_tensor(bvp: &BodyVelocityProfile) -> Array2<f32> {
|
||||
bvp.data.mapv(|v| v as f32)
|
||||
}
|
||||
|
||||
/// Convert selected subcarrier data to reduced-dimension input
|
||||
pub fn selected_csi_to_tensor(
|
||||
selection: &SubcarrierSelection,
|
||||
data: &Array2<f64>,
|
||||
) -> Result<Array2<f32>, SelectionError> {
|
||||
let extracted = extract_selected(data, selection)?;
|
||||
Ok(extracted.mapv(|v| v as f32))
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### MAT ACL (Downstream)
|
||||
|
||||
Adapts motion analysis outputs for the Mass Casualty Assessment Tool, translating domain-generic motion scores and breathing estimates into disaster-context vital signs.
|
||||
|
||||
```rust
|
||||
/// Adapts signal processing outputs for disaster assessment
|
||||
pub struct SignalToMatAdapter;
|
||||
|
||||
impl SignalToMatAdapter {
|
||||
/// Convert BreathingEstimate to MAT-domain BreathingPattern
|
||||
pub fn to_breathing_pattern(est: &BreathingEstimate) -> BreathingPattern {
|
||||
BreathingPattern {
|
||||
rate_bpm: est.rate_bpm as f32,
|
||||
amplitude: est.amplitude_variation as f32,
|
||||
regularity: est.autocorrelation_peak as f32,
|
||||
pattern_type: classify_breathing_type(est.rate_bpm),
|
||||
}
|
||||
}
|
||||
|
||||
/// Convert MotionScore to MAT-domain presence indicator
|
||||
pub fn to_presence_indicator(score: &MotionScore) -> PresenceIndicator {
|
||||
PresenceIndicator {
|
||||
detected: score.total > 0.3,
|
||||
confidence: score.total,
|
||||
motion_level: classify_motion_level(score),
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue