|
| 1 | +# Edge Intelligence Modules — WiFi-DensePose |
| 2 | + |
| 3 | +> 60 WASM modules that run directly on an ESP32 sensor. No internet needed, no cloud fees, instant response. Each module is a tiny file (5-30 KB) that reads WiFi signal data and makes decisions locally in under 10 ms. |
| 4 | +
|
| 5 | +## Quick Start |
| 6 | + |
| 7 | +```bash |
| 8 | +# Build all modules for ESP32 |
| 9 | +cd rust-port/wifi-densepose-rs/crates/wifi-densepose-wasm-edge |
| 10 | +cargo build --target wasm32-unknown-unknown --release |
| 11 | + |
| 12 | +# Run all 632 tests |
| 13 | +cargo test --features std |
| 14 | + |
| 15 | +# Upload a module to your ESP32 |
| 16 | +python scripts/wasm_upload.py --port COM7 --module target/wasm32-unknown-unknown/release/module_name.wasm |
| 17 | +``` |
| 18 | + |
| 19 | +## Module Categories |
| 20 | + |
| 21 | +| | Category | Modules | Tests | Documentation | |
| 22 | +|---|----------|---------|-------|---------------| |
| 23 | +| | **Core** | 7 | 81 | [core.md](core.md) | |
| 24 | +| | **Medical & Health** | 5 | 38 | [medical.md](medical.md) | |
| 25 | +| | **Security & Safety** | 6 | 42 | [security.md](security.md) | |
| 26 | +| | **Smart Building** | 5 | 38 | [building.md](building.md) | |
| 27 | +| | **Retail & Hospitality** | 5 | 38 | [retail.md](retail.md) | |
| 28 | +| | **Industrial** | 5 | 38 | [industrial.md](industrial.md) | |
| 29 | +| | **Exotic & Research** | 10 | ~60 | [exotic.md](exotic.md) | |
| 30 | +| | **Signal Intelligence** | 6 | 54 | [signal-intelligence.md](signal-intelligence.md) | |
| 31 | +| | **Adaptive Learning** | 4 | 42 | [adaptive-learning.md](adaptive-learning.md) | |
| 32 | +| | **Spatial & Temporal** | 6 | 56 | [spatial-temporal.md](spatial-temporal.md) | |
| 33 | +| | **AI Security** | 2 | 20 | [ai-security.md](ai-security.md) | |
| 34 | +| | **Quantum & Autonomous** | 4 | 30 | [autonomous.md](autonomous.md) | |
| 35 | +| | **Total** | **65** | **632** | | |
| 36 | + |
| 37 | +## How It Works |
| 38 | + |
| 39 | +1. **WiFi signals bounce off people and objects** in a room, creating a unique pattern |
| 40 | +2. **The ESP32 chip reads these patterns** as Channel State Information (CSI) — 52 numbers that describe how each WiFi channel changed |
| 41 | +3. **WASM modules analyze the patterns** to detect specific things: someone fell, a room is occupied, breathing rate changed |
| 42 | +4. **Events are emitted locally** — no cloud round-trip, response time under 10 ms |
| 43 | + |
| 44 | +## Architecture |
| 45 | + |
| 46 | +``` |
| 47 | +WiFi Router ──── radio waves ────→ ESP32-S3 Sensor |
| 48 | + │ |
| 49 | + ▼ |
| 50 | + ┌──────────────┐ |
| 51 | + │ Tier 0-2 │ C firmware: phase unwrap, |
| 52 | + │ DSP Engine │ stats, top-K selection |
| 53 | + └──────┬───────┘ |
| 54 | + │ CSI frame (52 subcarriers) |
| 55 | + ▼ |
| 56 | + ┌──────────────┐ |
| 57 | + │ WASM3 │ Tiny interpreter |
| 58 | + │ Runtime │ (60 KB overhead) |
| 59 | + └──────┬───────┘ |
| 60 | + │ |
| 61 | + ┌───────────┼───────────┐ |
| 62 | + ▼ ▼ ▼ |
| 63 | + ┌──────────┐ ┌──────────┐ ┌──────────┐ |
| 64 | + │ Module A │ │ Module B │ │ Module C │ |
| 65 | + │ (5-30KB) │ │ (5-30KB) │ │ (5-30KB) │ |
| 66 | + └────┬─────┘ └────┬─────┘ └────┬─────┘ |
| 67 | + │ │ │ |
| 68 | + └───────────┼───────────┘ |
| 69 | + ▼ |
| 70 | + Events + Alerts |
| 71 | + (UDP to aggregator or local) |
| 72 | +``` |
| 73 | + |
| 74 | +## Host API |
| 75 | + |
| 76 | +Every module talks to the ESP32 through 12 functions: |
| 77 | + |
| 78 | +| Function | Returns | Description | |
| 79 | +|----------|---------|-------------| |
| 80 | +| `csi_get_phase(i)` | `f32` | WiFi signal phase angle for subcarrier `i` | |
| 81 | +| `csi_get_amplitude(i)` | `f32` | Signal strength for subcarrier `i` | |
| 82 | +| `csi_get_variance(i)` | `f32` | How much subcarrier `i` fluctuates | |
| 83 | +| `csi_get_bpm_breathing()` | `f32` | Breathing rate (BPM) | |
| 84 | +| `csi_get_bpm_heartrate()` | `f32` | Heart rate (BPM) | |
| 85 | +| `csi_get_presence()` | `i32` | Is anyone there? (0/1) | |
| 86 | +| `csi_get_motion_energy()` | `f32` | Overall movement level | |
| 87 | +| `csi_get_n_persons()` | `i32` | Estimated number of people | |
| 88 | +| `csi_get_timestamp()` | `i32` | Current timestamp (ms) | |
| 89 | +| `csi_emit_event(id, val)` | — | Send a detection result to the host | |
| 90 | +| `csi_log(ptr, len)` | — | Log a message to serial console | |
| 91 | +| `csi_get_phase_history(buf, max)` | `i32` | Past phase values for trend analysis | |
| 92 | + |
| 93 | +## Event ID Registry |
| 94 | + |
| 95 | +| Range | Category | Example Events | |
| 96 | +|-------|----------|---------------| |
| 97 | +| 0-99 | Core | Gesture detected, coherence score, anomaly | |
| 98 | +| 100-199 | Medical | Apnea, bradycardia, tachycardia, seizure | |
| 99 | +| 200-299 | Security | Intrusion, perimeter breach, loitering, panic | |
| 100 | +| 300-399 | Smart Building | Zone occupied, HVAC, lighting, elevator, meeting | |
| 101 | +| 400-499 | Retail | Queue length, dwell zone, customer flow, turnover | |
| 102 | +| 500-599 | Industrial | Proximity warning, confined space, vibration | |
| 103 | +| 600-699 | Exotic | Sleep stage, emotion, gesture language, rain | |
| 104 | +| 700-729 | Signal Intelligence | Attention, coherence gate, compression, recovery | |
| 105 | +| 730-759 | Adaptive Learning | Gesture learned, attractor, adaptation, EWC | |
| 106 | +| 760-789 | Spatial Reasoning | Influence, HNSW match, spike tracking | |
| 107 | +| 790-819 | Temporal Analysis | Pattern, LTL violation, GOAP goal | |
| 108 | +| 820-849 | AI Security | Replay attack, injection, jamming, behavior | |
| 109 | +| 850-879 | Quantum-Inspired | Entanglement, decoherence, hypothesis | |
| 110 | +| 880-899 | Autonomous | Inference, rule fired, mesh reconfigure | |
| 111 | + |
| 112 | +## Module Development |
| 113 | + |
| 114 | +### Adding a New Module |
| 115 | + |
| 116 | +1. Create `src/your_module.rs` following the pattern: |
| 117 | + ```rust |
| 118 | + #![cfg_attr(not(feature = "std"), no_std)] |
| 119 | + #[cfg(not(feature = "std"))] |
| 120 | + use libm::fabsf; |
| 121 | + |
| 122 | + pub struct YourModule { /* fixed-size fields only */ } |
| 123 | + |
| 124 | + impl YourModule { |
| 125 | + pub const fn new() -> Self { /* ... */ } |
| 126 | + pub fn process_frame(&mut self, /* inputs */) -> &[(i32, f32)] { /* ... */ } |
| 127 | + } |
| 128 | + ``` |
| 129 | + |
| 130 | +2. Add `pub mod your_module;` to `lib.rs` |
| 131 | +3. Add event constants to `event_types` in `lib.rs` |
| 132 | +4. Add tests with `#[cfg(test)] mod tests { ... }` |
| 133 | +5. Run `cargo test --features std` |
| 134 | + |
| 135 | +### Constraints |
| 136 | + |
| 137 | +- **No heap allocation**: Use fixed-size arrays, not `Vec` or `String` |
| 138 | +- **No `std`**: Use `libm` for math functions |
| 139 | +- **Budget tiers**: L (<2ms), S (<5ms), H (<10ms) per frame |
| 140 | +- **Binary size**: Each module should be 5-30 KB as WASM |
| 141 | + |
| 142 | +## References |
| 143 | + |
| 144 | +- [ADR-039](../adr/ADR-039-esp32-edge-intelligence.md) — Edge processing tiers |
| 145 | +- [ADR-040](../adr/ADR-040-wasm-programmable-sensing.md) — WASM runtime design |
| 146 | +- [ADR-041](../adr/ADR-041-wasm-module-collection.md) — Full module specification |
| 147 | +- [Source code](../../rust-port/wifi-densepose-rs/crates/wifi-densepose-wasm-edge/src/) |
0 commit comments