ESP32 CSI Sensing Firmware
Custom ESP32 firmware for WiFi Channel State Information (CSI) sensing with presence detection, BLE scanning, and remote management.
Version: 1.7 Deployed on: 3x ESP32-DevKitC V1 (muddy-storm, amber-maple, hollow-acorn)
Features
| Feature | Description |
|---|---|
| CSI Streaming | UDP packets at 10-100 Hz with per-subcarrier amplitude data |
| Presence Detection | Baseline calibration + normalized Euclidean distance scoring |
| Adaptive Sampling | Auto-adjusts rate: 10 Hz idle → 100 Hz on motion |
| BLE Scanning | Periodic advertisement scanning with RSSI tracking |
| OTA Updates | WiFi firmware updates with rollback protection |
| HMAC Auth | Optional command authentication (HMAC-SHA256) |
| Power Management | DFS (240/80 MHz) + WiFi modem sleep |
| Security Monitoring | Deauth flood detection, probe request capture |
Quick Start
# Build firmware
source ~/esp/esp-idf/export.sh
cd get-started/csi_recv_router
idf.py build
# Flash via USB
idf.py -p /dev/ttyUSB0 flash monitor
# Or OTA update (after initial flash)
esp-ota <hostname> build/csi_recv_router.bin
Directory Structure
esp32-hacking/
├── get-started/csi_recv_router/ # Main firmware (v1.7)
│ ├── main/app_main.c # Single-file firmware (~2000 lines)
│ ├── sdkconfig.defaults # Build defaults
│ └── partitions.csv # Dual OTA partition table
├── docs/
│ ├── CHEATSHEET.md # Command reference
│ ├── INSTALL.md # Build & flash guide
│ └── USAGE.md # Comprehensive usage
├── tools/ # Helper scripts
├── esp-radar/ # Advanced presence detection examples
├── esp-crab/ # Dual-antenna experiments
├── ROADMAP.md # Version milestones
└── TASKS.md # Current work tracking
Commands
Send via UDP to port 5501. See docs/CHEATSHEET.md for full reference.
| Command | Description |
|---|---|
STATUS |
Device info, config, heap, temp, CSI stats |
RATE <10-100> |
Set CSI packet rate (disables adaptive) |
ADAPTIVE ON/OFF |
Toggle motion-based rate adjustment |
THRESHOLD <val> |
Motion detection sensitivity |
CALIBRATE [3-60] |
Capture baseline for presence detection |
PRESENCE ON/OFF |
Enable presence detection events |
PRESENCE THRESHOLD <val> |
Presence detection sensitivity (0.001-1.0) |
BLE ON/OFF |
Toggle BLE advertisement scanning |
POWERSAVE ON/OFF |
Toggle WiFi modem sleep |
OTA <url> |
Trigger firmware update from HTTP URL |
AUTH <secret/OFF> |
Set/disable HMAC authentication |
REBOOT |
Restart device |
Data Formats
CSI Data:
CSI_DATA,<hostname>,<seq>,<mac>,<rssi>,...,"[amplitudes]"
Compact Mode:
F:<hostname>,<rms>,<std>,<max>,<max_idx>,<energy>
Events:
EVENT,<hostname>,motion=1 rate=100 wander=0.0234
EVENT,<hostname>,presence=1 score=0.0832
EVENT,<hostname>,calibrate=done packets=1000 nsub=52
BLE:
BLE_DATA,<hostname>,<mac>,<rssi>,<name>
Pi-Side Tools
Install from esp-ctl:
| Tool | Purpose |
|---|---|
esp-cmd |
Send commands to single sensor |
esp-ctl |
Listen, watch daemon, OSINT queries, BLE tracking |
esp-fleet |
Fleet management (status, command broadcast) |
esp-ota |
OTA firmware updates |
NVS Configuration
22 keys persisted in flash:
send_rate, tx_power, adaptive, threshold, ble_scan, target_ip, target_port,
hostname, boot_count, csi_mode, hybrid_n, auth_secret, flood_thresh,
flood_window, scan_rate, probe_rate, powersave, presence, pr_thresh,
bl_nsub, bl_amps
CI/CD
Gitea Actions workflow (.gitea/workflows/lint.yml):
- cppcheck — C static analysis
- flawfinder — Security flaw detection
- gitleaks — Secret scanning
- shellcheck — Shell script linting
References
- ESP-IDF Documentation
- ESP-CSI Repository
- wifi-sensing docs — Protocol & architecture documentation