# 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