username/esp32-hacking
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity

docs: Update README for v1.7 with current features and CI
Some checks failed
Lint & Security / C/C++ Static Analysis (push) Failing after 3s
Details
Lint & Security / Security Flaw Analysis (push) Failing after 2s
Details
Lint & Security / Secret Scanning (push) Failing after 1s
Details
Lint & Security / Shell Script Analysis (push) Failing after 1s
Details

Browse Source
This commit is contained in:
user
2026-02-05 11:38:08 +01:00
parent 8265f96f3b
commit 28db1f9fe3
1 changed files with 101 additions and 213 deletions
Download Patch File Download Diff File Expand all files Collapse all files

314
README.md
View File

@@ -1,244 +1,132 @@
# ESP32 Firmware Hacking
# ESP32 CSI Sensing Firmware
Resources for customizing ESP32 CSI 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/ # Basic CSI examples (CURRENTLY USED)
│ ├── csi_recv_router/ # <-- OUR FIRMWARE (modified for UDP)
│ ├── csi_recv/ # Basic receiver (serial output)
│ ├── csi_send/ # CSI transmitter
│ └── tools/ # Python CSI parsing tools
├── esp-radar/ # Advanced presence detection
│ ├── console_test/ # Interactive CSI testing console
│ └── connect_rainmaker/ # IoT cloud integration
├── esp-crab/ # Dual-antenna experiments
│ ├── master_recv/ # Master receiver
│ ├── slave_recv/ # Slave receiver
│ └── slave_send/ # Slave transmitter
└── README.md # This file
├── 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
```
## Current Firmware
## Commands
**Source:** `get-started/csi_recv_router/`
**Origin:** Espressif esp-csi example, modified for UDP output
**Deployed on:** 3x ESP32-DevKitC V1
Send via UDP to port 5501. See `docs/CHEATSHEET.md` for full reference.
### What It Does
1. Connects to WiFi router as station
2. Pings gateway at 100 Hz to generate CSI frames
3. On each CSI callback, formats data as text
4. Sends via UDP to Pi (port 5500)
| 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 |
### Key Settings (sdkconfig.defaults)
## Data Formats
| Setting | Value | Purpose |
|---------|-------|---------|
| `CONFIG_ESP32_WIFI_CSI_ENABLED` | y | Enable CSI extraction |
| `CONFIG_ESP32_WIFI_AMPDU_TX_ENABLED` | (empty) | Disable TX aggregation |
| `CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM` | 128 | Large RX buffer |
| `CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ` | 240 | Max CPU speed |
| `CONFIG_FREERTOS_HZ` | 1000 | 1ms tick resolution |
| `CONFIG_ESP_TASK_WDT_TIMEOUT_S` | 30 | Watchdog timeout |
| `CONFIG_COMPILER_OPTIMIZATION_PERF` | y | Performance optimization |
### Custom Config (Kconfig.projbuild)
| Config | Description |
|--------|-------------|
| `CONFIG_CSI_UDP_TARGET_IP` | Pi's IP address (192.168.129.11) |
| `CONFIG_CSI_UDP_TARGET_PORT` | UDP port (5500) |
### CSI Data Format
**CSI Data:**
```
CSI_DATA,<seq>,<mac>,<rssi>,<rate>,<sig_mode>,<mcs>,<cwb>,<smoothing>,
<not_sounding>,<aggregation>,<stbc>,<fec_coding>,<sgi>,<noise_floor>,
<ampdu_cnt>,<channel>,<secondary_channel>,<timestamp>,<ant>,<sig_len>,
<rx_state>,<len>,<first_word_invalid>,"[csi_values]"
CSI_DATA,<hostname>,<seq>,<mac>,<rssi>,...,"[amplitudes]"
```
### Build & Flash
```bash
source ~/esp/esp-idf/export.sh
cd ~/esp/esp-csi/examples/get-started/csi_recv_router
idf.py menuconfig # Change WiFi SSID/password, UDP target IP
idf.py build
idf.py -p /dev/ttyUSB0 flash
idf.py -p /dev/ttyUSB0 monitor # View serial output
**Compact Mode:**
```
F:<hostname>,<rms>,<std>,<max>,<max_idx>,<energy>
```
## Firmware Modification Ideas
### 1. Remote Commands (UDP bidirectional)
Add a UDP listener on the ESP32 to receive commands from the Pi.
```c
// Commands to implement:
// REBOOT - restart ESP32
// IDENTIFY - blink onboard LED for 5 seconds
// STATUS - reply with uptime, free heap, RSSI, chip temp
// RATE <n> - change ping/CSI rate (packets per second)
// OTA <url> - trigger OTA firmware update
**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
```
**Complexity:** Low
**Impact:** High - enables remote management without USB
### 2. Adaptive Sampling Rate
Reduce packet rate when no presence detected, increase on motion.
```c
// Idle: 10 pkt/s (saves power, bandwidth)
// Active: 100 pkt/s (full resolution)
// Trigger: wander threshold on-device
**BLE:**
```
BLE_DATA,<hostname>,<mac>,<rssi>,<name>
```
**Complexity:** Medium (needs on-device wander calculation)
**Impact:** Medium - reduces Pi CPU load by ~90% when idle
## Pi-Side Tools
### 3. On-Device CSI Processing
Install from [esp-ctl](https://git.mymx.me/username/esp-ctl):
Pre-compute amplitude on ESP32, send only metrics.
| 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 |
```c
// Instead of raw CSI (128 int16 values per packet = 256 bytes):
// Send: "METRICS,<seq>,<rssi>,<wander>,<jitter>,<amplitude_mean>"
// ~50 bytes per packet instead of ~500
## 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
```
**Complexity:** Medium
**Impact:** High - 80% bandwidth reduction
## CI/CD
### 4. LED Status Indicator
Use onboard LED (GPIO2 on most DevKitC) for status.
```c
// Off: No WiFi connection
// Slow blink: Connected, no CSI activity
// Fast blink: Sending CSI data
// Solid: Identify mode (triggered by command)
```
**Complexity:** Low
**Impact:** Low - quality of life
### 5. BLE Scanning
ESP32 has Bluetooth. Scan for nearby BLE devices.
```c
// Periodically scan for BLE advertisements
// Report: MAC, RSSI, device name
// Use for: phone/wearable proximity detection
// Complements CSI: confirms person is home (phone detected)
```
**Complexity:** Medium
**Impact:** High - adds a second detection method
### 6. OTA (Over-The-Air) Updates
Flash new firmware via WiFi without USB.
```c
// ESP-IDF has built-in OTA support
// Pi serves firmware binary via HTTP
// ESP32 downloads and flashes
// Requires dual OTA partition scheme
```
**Complexity:** Medium (partition table change needed)
**Impact:** High - no more USB flashing
### 7. ESP-NOW Mesh
Direct ESP32-to-ESP32 communication without router.
```c
// Active CSI: ESP32-A sends, ESP32-B measures CSI
// More reliable than passive router beacon monitoring
// Can work even if WiFi router goes down
```
**Complexity:** High (requires re-architecting firmware)
**Impact:** High - better CSI quality
### 8. Temperature Reporting
ESP32 has internal temperature sensor.
```c
// Read chip temperature
// Send with CSI data or as separate status packet
// Useful for monitoring device health
```
**Complexity:** Low
**Impact:** Low - monitoring
### 9. mDNS Auto-Discovery
Announce device on network, no need for static IPs.
```c
// Register as: <device-name>.local
// Pi discovers sensors automatically
// No manual IP configuration needed
```
**Complexity:** Low
**Impact:** Medium - easier deployment
### 10. Watchdog + Auto-Recovery
Better error handling and self-healing.
```c
// Monitor WiFi connection, reconnect on drop
// Monitor UDP send failures
// Track heap fragmentation
// Reboot if stuck for >60 seconds
```
**Complexity:** Low
**Impact:** Medium - reliability
## Priority Order (Recommended)
| Priority | Feature | Why |
|----------|---------|-----|
| 1 | Remote commands | Remote reboot + identify = essential |
| 2 | LED status | Easy win, helps debugging |
| 3 | OTA updates | Stop walking to each sensor with USB |
| 4 | Adaptive rate | Save CPU/power when idle |
| 5 | mDNS | Easier deployment |
| 6 | BLE scanning | Second detection method |
| 7 | On-device processing | Bandwidth optimization |
| 8 | Temperature | Nice to have |
| 9 | ESP-NOW mesh | Major rewrite, big payoff |
| 10 | Watchdog improvements | Production hardening |
## ESP-CSI Tools
### Python CSI Parser (get-started/tools/)
- `csi_data_read_parse.py` - PyQt5 GUI for live CSI visualization
- Shows amplitude and phase plots in real-time
### ESP Radar Console (esp-radar/console_test/)
- Interactive console for testing CSI features
- Includes `esp_csi_tool.py` CLI and GUI tools
- Built-in presence detection algorithms
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 Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/)
- [ESP-IDF Documentation](https://docs.espressif.com/projects/esp-idf/en/latest/)
- [ESP-CSI Repository](https://github.com/espressif/esp-csi)
- [ESP32 WiFi CSI API](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_wifi.html)
- [ESP-NOW Protocol](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_now.html)
- [ESP32 OTA Updates](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/ota.html)
- [wifi-sensing docs](https://git.mymx.me/username/wifi-sensing) — Protocol & architecture documentation