133 lines
4.3 KiB
Markdown
133 lines
4.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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](https://git.mymx.me/username/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](https://docs.espressif.com/projects/esp-idf/en/latest/)
|
|
- [ESP-CSI Repository](https://github.com/espressif/esp-csi)
|
|
- [wifi-sensing docs](https://git.mymx.me/username/wifi-sensing) — Protocol & architecture documentation
|