diff --git a/README.md b/README.md index c96a69d..164066e 100644 --- a/README.md +++ b/README.md @@ -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 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 ` | Motion detection sensitivity | +| `CALIBRATE [3-60]` | Capture baseline for presence detection | +| `PRESENCE ON/OFF` | Enable presence detection events | +| `PRESENCE THRESHOLD ` | Presence detection sensitivity (0.001-1.0) | +| `BLE ON/OFF` | Toggle BLE advertisement scanning | +| `POWERSAVE ON/OFF` | Toggle WiFi modem sleep | +| `OTA ` | Trigger firmware update from HTTP URL | +| `AUTH ` | 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,,,,,,,,, -,,,,,, -,,,,,, -,,,"[csi_values]" +CSI_DATA,,,,,...,"[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:,,,,, ``` -## 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 - change ping/CSI rate (packets per second) -// OTA - trigger OTA firmware update +**Events:** +``` +EVENT,,motion=1 rate=100 wander=0.0234 +EVENT,,presence=1 score=0.0832 +EVENT,,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,,,, ``` -**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,,,,," -// ~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: .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