Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit fcb93cc

Browse files
claudeclaude
committed
feat: Implement ADR-014 SOTA signal processing (6 algorithms, 83 tests)
Add six research-grade signal processing algorithms to wifi-densepose-signal: - Conjugate Multiplication: CFO/SFO cancellation via antenna ratio (SpotFi) - Hampel Filter: Robust median/MAD outlier detection (50% contamination resistant) - Fresnel Zone Model: Physics-based breathing detection from chest displacement - CSI Spectrogram: STFT time-frequency generation with 4 window functions - Subcarrier Selection: Variance-ratio ranking for top-K motion-sensitive subcarriers - Body Velocity Profile: Domain-independent Doppler velocity mapping (Widar 3.0) All 313 workspace tests pass, 0 failures. Updated README with new capabilities. https://claude.ai/code/session_01Ki7pvEZtJDvqJkmyn6B714
1 parent 63c3d0f commit fcb93cc

9 files changed

Lines changed: 1868 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ A high-performance Rust port is available in `/rust-port/wifi-densepose-rs/`:
6464
| Memory Usage | ~500MB | ~100MB |
6565
| WASM Support | ❌ | ✅ |
6666
| Binary Size | N/A | ~10MB |
67-
| Test Coverage | 100% | 107 tests |
67+
| Test Coverage | 100% | 313 tests |
6868

6969
**Quick Start (Rust):**
7070
```bash
@@ -83,6 +83,19 @@ Mathematical correctness validated:
8383
- ✅ Correlation: 1.0 for identical signals
8484
- ✅ Phase coherence: 1.0 for coherent signals
8585

86+
### SOTA Signal Processing (ADR-014)
87+
88+
Six research-grade algorithms implemented in the `wifi-densepose-signal` crate:
89+
90+
| Algorithm | Purpose | Reference |
91+
|-----------|---------|-----------|
92+
| **Conjugate Multiplication** | Cancels CFO/SFO from raw CSI phase via antenna ratio | SpotFi (SIGCOMM 2015) |
93+
| **Hampel Filter** | Robust outlier removal using median/MAD (resists 50% contamination) | Hampel (1974) |
94+
| **Fresnel Zone Model** | Physics-based breathing detection from chest displacement | FarSense (MobiCom 2019) |
95+
| **CSI Spectrogram** | STFT time-frequency matrices for CNN-based activity recognition | Standard since 2018 |
96+
| **Subcarrier Selection** | Variance-ratio ranking to pick top-K motion-sensitive subcarriers | WiDance (MobiCom 2017) |
97+
| **Body Velocity Profile** | Domain-independent velocity x time representation from Doppler | Widar 3.0 (MobiSys 2019) |
98+
8699
See [Rust Port Documentation](/rust-port/wifi-densepose-rs/docs/) for ADRs and DDD patterns.
87100

88101
## 🚨 WiFi-Mat: Disaster Response Module

‎docs/adr/ADR-014-sota-signal-processing.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# ADR-014: SOTA Signal Processing Algorithms for WiFi Sensing
2+
3+
## Status
4+
Accepted
5+
6+
## Context
7+
8+
The existing signal processing pipeline (ADR-002) provides foundational CSI processing:
9+
phase unwrapping, FFT-based feature extraction, and variance-based motion detection.
10+
However, the academic state-of-the-art in WiFi sensing (2020-2025) has advanced
11+
significantly beyond these basics. To achieve research-grade accuracy, we need
12+
algorithms grounded in the physics of WiFi signal propagation and human body interaction.
13+
14+
### Current Gaps vs SOTA
15+
16+
| Capability | Current | SOTA Reference |
17+
|-----------|---------|----------------|
18+
| Phase cleaning | Z-score outlier + unwrapping | Conjugate multiplication (SpotFi 2015, IndoTrack 2017) |
19+
| Outlier detection | Z-score | Hampel filter (robust median-based) |
20+
| Breathing detection | Zero-crossing frequency | Fresnel zone model (FarSense 2019, Wi-Sleep 2021) |
21+
| Signal representation | Raw amplitude/phase | CSI spectrogram (time-frequency 2D matrix) |
22+
| Subcarrier usage | All subcarriers equally | Sensitivity-based selection (variance ratio) |
23+
| Motion profiling | Single motion score | Body Velocity Profile / BVP (Widar 3.0 2019) |
24+
25+
## Decision
26+
27+
Implement six SOTA algorithms in the `wifi-densepose-signal` crate as new modules,
28+
each with deterministic tests and no mock data.
29+
30+
### 1. Conjugate Multiplication (CSI Ratio Model)
31+
32+
**What:** Multiply CSI from antenna pair (i,j) as `H_i * conj(H_j)` to cancel
33+
carrier frequency offset (CFO), sampling frequency offset (SFO), and packet
34+
detection delay — all of which corrupt raw phase measurements.
35+
36+
**Why:** Raw CSI phase from commodity hardware (ESP32, Intel 5300) includes
37+
random offsets that change per packet. Conjugate multiplication preserves only
38+
the phase difference caused by the environment (human motion), not the hardware.
39+
40+
**Math:** `CSI_ratio[k] = H_1[k] * conj(H_2[k])` where k is subcarrier index.
41+
The resulting phase `angle(CSI_ratio[k])` reflects only path differences between
42+
the two antenna elements.
43+
44+
**Reference:** SpotFi (SIGCOMM 2015), IndoTrack (MobiCom 2017)
45+
46+
### 2. Hampel Filter
47+
48+
**What:** Replace outliers using running median ± scaled MAD (Median Absolute
49+
Deviation), which is robust to the outliers themselves (unlike mean/std Z-score).
50+
51+
**Why:** WiFi CSI has burst interference, multipath spikes, and hardware glitches
52+
that create outliers. Z-score outlier detection uses mean/std, which are themselves
53+
corrupted by the outliers (masking effect). Hampel filter uses median/MAD, which
54+
resist up to 50% contamination.
55+
56+
**Math:** For window around sample i: `median = med(x[i-w..i+w])`,
57+
`MAD = med(|x[j] - median|)`, `σ_est = 1.4826 * MAD`.
58+
If `|x[i] - median| > t * σ_est`, replace x[i] with median.
59+
60+
**Reference:** Standard DSP technique, used in WiGest (2015), WiDance (2017)
61+
62+
### 3. Fresnel Zone Breathing Model
63+
64+
**What:** Model WiFi signal variation as a function of human chest displacement
65+
crossing Fresnel zone boundaries. The chest moves ~5-10mm during breathing,
66+
which at 5 GHz (λ=60mm) is a significant fraction of the Fresnel zone width.
67+
68+
**Why:** Zero-crossing counting works for strong signals but fails in multipath-rich
69+
environments. The Fresnel model predicts *where* in the signal cycle a breathing
70+
motion should appear based on the TX-RX-body geometry, enabling detection even
71+
with weak signals.
72+
73+
**Math:** Fresnel zone radius at point P: `F_n = sqrt(n * λ * d1 * d2 / (d1 + d2))`.
74+
Signal variation: `ΔΦ = 2π * 2Δd / λ` where Δd is chest displacement.
75+
Expected breathing amplitude: `A = |sin(ΔΦ/2)|`.
76+
77+
**Reference:** FarSense (MobiCom 2019), Wi-Sleep (UbiComp 2021)
78+
79+
### 4. CSI Spectrogram
80+
81+
**What:** Construct a 2D time-frequency matrix by applying sliding-window FFT
82+
(STFT) to the temporal CSI amplitude stream per subcarrier. This reveals how
83+
the frequency content of body motion changes over time.
84+
85+
**Why:** Spectrograms are the standard input to CNN-based activity recognition.
86+
A breathing person shows a ~0.2-0.4 Hz band, walking shows 1-2 Hz, and
87+
stationary environment shows only noise. The 2D structure allows spatial
88+
pattern recognition that 1D features miss.
89+
90+
**Math:** `S[t,f] = |Σ_n x[n] * w[n-t] * exp(-j2πfn)|²`
91+
92+
**Reference:** Used in virtually all CNN-based WiFi sensing papers since 2018
93+
94+
### 5. Subcarrier Sensitivity Selection
95+
96+
**What:** Rank subcarriers by their sensitivity to human motion (variance ratio
97+
between motion and static periods) and select only the top-K for further processing.
98+
99+
**Why:** Not all subcarriers respond equally to body motion. Some are in
100+
multipath nulls, some carry mainly noise. Using all subcarriers dilutes the signal.
101+
Selecting the 10-20 most sensitive subcarriers improves SNR by 6-10 dB.
102+
103+
**Math:** `sensitivity[k] = var_motion(amp[k]) / (var_static(amp[k]) + ε)`.
104+
Select top-K subcarriers by sensitivity score.
105+
106+
**Reference:** WiDance (MobiCom 2017), WiGest (SenSys 2015)
107+
108+
### 6. Body Velocity Profile (BVP)
109+
110+
**What:** Extract velocity distribution of body parts from Doppler shifts across
111+
subcarriers. BVP is a 2D representation (velocity × time) that encodes how
112+
different body parts move at different speeds.
113+
114+
**Why:** BVP is domain-independent — the same velocity profile appears regardless
115+
of room layout, furniture, or AP placement. This makes it the basis for
116+
cross-environment gesture and activity recognition.
117+
118+
**Math:** Apply DFT across time for each subcarrier, then aggregate across
119+
subcarriers: `BVP[v,t] = Σ_k |STFT_k[v,t]|` where v maps to velocity via
120+
`v = f_doppler * λ / 2`.
121+
122+
**Reference:** Widar 3.0 (MobiSys 2019), WiDar (MobiSys 2017)
123+
124+
## Implementation
125+
126+
All algorithms implemented in `wifi-densepose-signal/src/` as new modules:
127+
- `csi_ratio.rs` — Conjugate multiplication
128+
- `hampel.rs` — Hampel filter
129+
- `fresnel.rs` — Fresnel zone breathing model
130+
- `spectrogram.rs` — CSI spectrogram generation
131+
- `subcarrier_selection.rs` — Sensitivity-based selection
132+
- `bvp.rs` — Body Velocity Profile extraction
133+
134+
Each module has:
135+
- Deterministic unit tests with known input/output
136+
- No random data, no mocks
137+
- Documentation with references to source papers
138+
- Integration with existing `CsiData` types
139+
140+
## Consequences
141+
142+
### Positive
143+
- Research-grade signal processing matching 2019-2023 publications
144+
- Physics-grounded algorithms (Fresnel zones, Doppler) not just heuristics
145+
- Cross-environment robustness via BVP and CSI ratio
146+
- CNN-ready features via spectrograms
147+
- Improved SNR via subcarrier selection
148+
149+
### Negative
150+
- Increased computational cost (STFT, complex multiplication per frame)
151+
- Fresnel model requires TX-RX distance estimate (geometry input)
152+
- BVP requires sufficient temporal history (>1 second at 100+ Hz sampling)
153+
154+
## References
155+
- SpotFi: Decimeter Level Localization Using WiFi (SIGCOMM 2015)
156+
- IndoTrack: Device-Free Indoor Human Tracking (MobiCom 2017)
157+
- FarSense: Pushing the Range Limit of WiFi-based Respiration Sensing (MobiCom 2019)
158+
- Widar 3.0: Zero-Effort Cross-Domain Gesture Recognition (MobiSys 2019)
159+
- Wi-Sleep: Contactless Sleep Staging (UbiComp 2021)
160+
- DensePose from WiFi (arXiv 2022, CMU)

0 commit comments

Comments
 (0)