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 ## Directory Structure
``` ```
esp32-hacking/ esp32-hacking/
├── get-started/ # Basic CSI examples (CURRENTLY USED) ├── get-started/csi_recv_router/ # Main firmware (v1.7)
│ ├── csi_recv_router/ # <-- OUR FIRMWARE (modified for UDP) │ ├── main/app_main.c # Single-file firmware (~2000 lines)
│ ├── csi_recv/ # Basic receiver (serial output) │ ├── sdkconfig.defaults # Build defaults
│ ├── csi_send/ # CSI transmitter │ └── partitions.csv # Dual OTA partition table
│ └── tools/ # Python CSI parsing tools ├── docs/
├── esp-radar/ # Advanced presence detection │ ├── CHEATSHEET.md # Command reference
│ ├── console_test/ # Interactive CSI testing console │ ├── INSTALL.md # Build & flash guide
│ └── connect_rainmaker/ # IoT cloud integration │ └── USAGE.md # Comprehensive usage
├── esp-crab/ # Dual-antenna experiments ├── tools/ # Helper scripts
│ ├── master_recv/ # Master receiver ├── esp-radar/ # Advanced presence detection examples
│ ├── slave_recv/ # Slave receiver ├── esp-crab/ # Dual-antenna experiments
│ └── slave_send/ # Slave transmitter ├── ROADMAP.md # Version milestones
└── README.md # This file └── TASKS.md # Current work tracking
``` ```
## Current Firmware ## Commands
**Source:** `get-started/csi_recv_router/` Send via UDP to port 5501. See `docs/CHEATSHEET.md` for full reference.
**Origin:** Espressif esp-csi example, modified for UDP output
**Deployed on:** 3x ESP32-DevKitC V1
### What It Does | Command | Description |
1. Connects to WiFi router as station |---------|-------------|
2. Pings gateway at 100 Hz to generate CSI frames | `STATUS` | Device info, config, heap, temp, CSI stats |
3. On each CSI callback, formats data as text | `RATE <10-100>` | Set CSI packet rate (disables adaptive) |
4. Sends via UDP to Pi (port 5500) | `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 | **CSI Data:**
|---------|-------|---------|
| `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,<seq>,<mac>,<rssi>,<rate>,<sig_mode>,<mcs>,<cwb>,<smoothing>, CSI_DATA,<hostname>,<seq>,<mac>,<rssi>,...,"[amplitudes]"
<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]"
``` ```
### Build & Flash **Compact Mode:**
```bash ```
source ~/esp/esp-idf/export.sh F:<hostname>,<rms>,<std>,<max>,<max_idx>,<energy>
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
``` ```
## Firmware Modification Ideas **Events:**
```
### 1. Remote Commands (UDP bidirectional) EVENT,<hostname>,motion=1 rate=100 wander=0.0234
EVENT,<hostname>,presence=1 score=0.0832
Add a UDP listener on the ESP32 to receive commands from the Pi. EVENT,<hostname>,calibrate=done packets=1000 nsub=52
```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
``` ```
**Complexity:** Low **BLE:**
**Impact:** High - enables remote management without USB ```
BLE_DATA,<hostname>,<mac>,<rssi>,<name>
### 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
``` ```
**Complexity:** Medium (needs on-device wander calculation) ## Pi-Side Tools
**Impact:** Medium - reduces Pi CPU load by ~90% when idle
### 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 ## NVS Configuration
// Instead of raw CSI (128 int16 values per packet = 256 bytes):
// Send: "METRICS,<seq>,<rssi>,<wander>,<jitter>,<amplitude_mean>" 22 keys persisted in flash:
// ~50 bytes per packet instead of ~500
```
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 ## CI/CD
**Impact:** High - 80% bandwidth reduction
### 4. LED Status Indicator Gitea Actions workflow (`.gitea/workflows/lint.yml`):
- **cppcheck** — C static analysis
Use onboard LED (GPIO2 on most DevKitC) for status. - **flawfinder** — Security flaw detection
- **gitleaks** — Secret scanning
```c - **shellcheck** — Shell script linting
// 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
## References ## 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) - [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) - [wifi-sensing docs](https://git.mymx.me/username/wifi-sensing) — Protocol & architecture documentation
- [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)