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