ESP32-S3 Edge Intelligence (ADR-039) — alpha firmware + next improvements

[ruvnet]

WiFi-DensePose uses WiFi Channel State Information (CSI) to estimate human pose — no cameras required. The ADR-039 Edge Intelligence feature moves signal processing directly onto the ESP32-S3 microcontroller, enabling real-time presence detection, vital signs monitoring (breathing and heart rate), and fall detection at the network edge. This alpha release provides the complete firmware with a tiered processing pipeline that runs on the ESP32-S3's dual cores.

---

ESP32-S3 Edge Intelligence — Alpha Release

Release: v0.3.0-alpha-esp32
ADR: ADR-039

---

Quick Start

1. Flash the firmware

Download binaries from the release page, then:

python -m esptool --chip esp32s3 --port COM7 --baud 460800 \
  write_flash --flash_mode dio --flash_size 4MB \
  0x0 bootloader.bin \
  0x8000 partition-table.bin \
  0x10000 esp32-csi-node.bin

2. Provision WiFi credentials

python scripts/provision.py --port COM7 \
  --ssid "YOUR_SSID" --password "YOUR_PASSWORD" \
  --target-ip 192.168.1.20

3. Enable edge processing

Edge processing defaults to Tier 2 (full pipeline). To change:

Option A — Rebuild with Kconfig (compile-time):

idf.py menuconfig
# Navigate to: Edge Intelligence (ADR-039) → Edge processing tier

Option B — NVS override (runtime, no reflash):

python scripts/provision.py --port COM7 --edge-tier 2

4. Receive vitals data

When Tier 2 is enabled, the ESP32 sends a 32-byte vitals packet (magic 0xC5110002) to the same UDP target at 1 Hz:

Field	Bytes	Description
magic	0-3	0xC5110002 (distinguishes from CSI 0xC5110001)
node_id	4	Node identifier
flags	5	Bit0=presence, Bit1=fall, Bit2=motion
breathing_rate	6-7	BPM × 100 (fixed-point)
heartrate	8-11	BPM × 10000 (fixed-point)
rssi	12	Latest RSSI
n_persons	13	Detected person count
motion_energy	16-19	Phase variance (f32)
presence_score	20-23	Detection score (f32)
timestamp_ms	24-27	Milliseconds since boot

Start the sensing server to receive both CSI and vitals:

cd rust-port/wifi-densepose-rs
cargo run -p wifi-densepose-sensing-server -- --http-port 3000 --source esp32
# GET /api/v1/edge-vitals — latest vitals from ESP32

---

What's Implemented

• Lock-free SPSC ring buffer (Core 0 to Core 1)
• Tier 1: Phase unwrap, Welford running stats, top-K subcarrier selection
• Tier 2: Presence detection (adaptive 3-sigma calibration from 1200 ambient frames)
• Tier 2: Vital signs — breathing (0.1-0.5 Hz) and heart rate (0.8-2.0 Hz) via biquad IIR bandpass
• Tier 2: Zero-crossing BPM estimation (replaced energy heuristic)
• Tier 2: Fall detection (phase acceleration threshold)
• Tier 2: Multi-person vitals (up to 4 persons via subcarrier group clustering)
• Vitals UDP packet (32 bytes, 1 Hz, magic 0xC5110002)
• Delta compression (XOR + RLE, magic 0xC5110003, 30-50% bandwidth reduction)
• NVS/Kconfig configurable (7 parameters including power duty cycle)
• OTA firmware update (HTTP server on port 8032 with rollback support)
• Power management (WiFi modem sleep + light sleep duty cycling)
• Aggregator vitals parsing (sensing-server decodes 0xC5110002, WebSocket broadcast, REST endpoint)
• provision.py edge config (6 new CLI args: --edge-tier, --pres-thresh, --fall-thresh, --vital-window, --vital-interval, --subk-count)
• GitHub Actions firmware CI (Docker build, 900 KB size gate, flash integrity checks)
• Full backward compatibility (tier=0 = raw passthrough)

Remaining Improvements

High Priority

• CI QEMU ESP32-S3 smoke test — ESP32-S3 (LX7) not yet supported by QEMU; monitoring Espressif updates

Future (Tier 3)

• On-device ML inference — TFLite Micro or ESP-NN for gesture classification
• AETHER embeddings — contrastive CSI feature extraction (ADR-024) on ESP32-S3
• MERIDIAN domain adaptation — environment fingerprinting for cross-room generalization (ADR-027)
• Mesh vitals — aggregate vitals from multiple ESP32 nodes for room-level monitoring

---

Build Verification

Docker: espressif/idf:v5.4
Binary: 820 KB (900 KB gate — 20% headroom)
Source: 7 files (main.c, csi_collector.c, stream_sender.c, nvs_config.c, edge_processing.c, ota_update.c, power_mgmt.c)
Rust:   cargo check passes (sensing-server with vitals parser)

Known Limitations

1. Vital signs accuracy: BPM estimation uses zero-crossing on bandpass-filtered phase. Accuracy is best with a single stationary subject within 3m of the ESP32.
2. QEMU: ESP32-S3 (LX7) is not supported by QEMU. Boot testing requires real hardware.
3. Fall detection: Phase acceleration heuristic may false-positive in environments with moving doors/pets.
4. Binary size: 820 KB leaves ~80 KB for Tier 3 ML models — tight for full TFLite inference.

Testing Feedback

If you try this alpha, please report:

• Does the firmware boot and connect to WiFi? (check serial monitor at 115200 baud)
• With edge_tier=2, do you see vitals packets on the aggregator?
• In a quiet room with one person, are the breathing/heart rate estimates plausible?
• Any crashes or watchdog resets?

cc @ruvnet