# ESP32 Firmware Hacking

Resources for customizing ESP32 CSI firmware.

## 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
```

## Current Firmware

**Source:** `get-started/csi_recv_router/`
**Origin:** Espressif esp-csi example, modified for UDP output
**Deployed on:** 3x ESP32-DevKitC V1

### 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)

### Key Settings (sdkconfig.defaults)

| 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,<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]"
```

### 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
```

## 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
```

**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
```

**Complexity:** Medium (needs on-device wander calculation)
**Impact:** Medium - reduces Pi CPU load by ~90% when idle

### 3. On-Device CSI Processing

Pre-compute amplitude on ESP32, send only metrics.

```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
```

**Complexity:** Medium
**Impact:** High - 80% bandwidth reduction

### 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

## References

- [ESP-IDF Programming Guide](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)
