70f37ad6dc
Add csi_count, uptime_s, WiFi reconnect, SCANRATE, PROBERATE to completed items. Document ESP32 promiscuous mode limitation (breaks CSI).
209 lines
7.3 KiB
Markdown
209 lines
7.3 KiB
Markdown
# Cheatsheet
|
|
|
|
## Environment Setup
|
|
|
|
```bash
|
|
source ~/esp/esp-idf/export.sh # Activate ESP-IDF (every shell)
|
|
```
|
|
|
|
## Build & Flash
|
|
|
|
```bash
|
|
cd ~/git/esp32-hacking/get-started/csi_recv_router
|
|
|
|
idf.py set-target esp32 # Set chip target
|
|
idf.py menuconfig # Configure WiFi/UDP settings
|
|
idf.py build # Compile firmware
|
|
idf.py -p /dev/ttyUSB0 -b 460800 flash # Flash to device (460800 baud)
|
|
idf.py -p /dev/ttyUSB0 monitor # Serial monitor (Ctrl+] to exit)
|
|
idf.py -p /dev/ttyUSB0 -b 460800 flash monitor # Flash + monitor combined
|
|
idf.py fullclean # Clean build directory
|
|
idf.py reconfigure # Re-fetch managed components
|
|
```
|
|
|
|
## Deployed Sensors
|
|
|
|
| Name | IP | mDNS | Location |
|
|
|------|-----|------|----------|
|
|
| muddy-storm | 192.168.129.29 | muddy-storm.local | Living Room |
|
|
| amber-maple | 192.168.129.30 | amber-maple.local | Office |
|
|
| hollow-acorn | 192.168.129.31 | hollow-acorn.local | Kitchen |
|
|
|
|
**Target:** `192.168.129.11:5500` (Pi) | **Cmd port:** `5501`
|
|
|
|
## Remote Management (esp-cmd)
|
|
|
|
```bash
|
|
esp-cmd <host> STATUS # Uptime, heap, RSSI, rate, version, adaptive, motion, csi_count
|
|
esp-cmd <host> IDENTIFY # LED solid 5s (find the device)
|
|
esp-cmd <host> RATE 50 # Set ping rate to 50 Hz (disables adaptive)
|
|
esp-cmd <host> POWER 15 # Set TX power to 15 dBm (NVS saved)
|
|
esp-cmd <host> ADAPTIVE ON # Enable adaptive sampling (NVS saved)
|
|
esp-cmd <host> ADAPTIVE OFF # Disable adaptive sampling
|
|
esp-cmd <host> THRESHOLD 0.005 # Set motion sensitivity (NVS saved)
|
|
esp-cmd <host> OTA http://pi:8070/fw # Trigger OTA update (use esp-ota instead)
|
|
esp-cmd <host> HOSTNAME mydevice # Set hostname (NVS saved, mDNS updated)
|
|
esp-cmd <host> SCANRATE 60 # BLE scan restart interval (5-300s)
|
|
esp-cmd <host> PROBERATE 5 # Probe dedup cooldown (1-300s)
|
|
esp-cmd <host> REBOOT # Restart device
|
|
```
|
|
|
|
Host can be an IP or mDNS name (`amber-maple.local`).
|
|
|
|
```bash
|
|
esp-cmd amber-maple.local STATUS # Single device via mDNS
|
|
esp-cmd 192.168.129.29 IDENTIFY # Single device via IP
|
|
```
|
|
|
|
## Fleet Management (esp-fleet)
|
|
|
|
```bash
|
|
esp-fleet status # Query all sensors at once
|
|
esp-fleet identify # Blink all LEDs
|
|
esp-fleet rate 50 # Set rate on all devices
|
|
esp-fleet reboot # Reboot entire fleet
|
|
esp-fleet ota # OTA update all (sequential)
|
|
esp-fleet ota /path/to/firmware.bin # OTA with custom firmware
|
|
```
|
|
|
|
## OTA Updates (esp-ota)
|
|
|
|
```bash
|
|
esp-ota amber-maple.local # OTA with default build
|
|
esp-ota amber-maple.local -f fw.bin # OTA with custom firmware
|
|
esp-ota amber-maple.local --no-wait # Fire and forget
|
|
```
|
|
|
|
**First flash after enabling OTA requires USB** (partition table change).
|
|
After that, all updates are OTA.
|
|
|
|
### OTA Flow
|
|
|
|
1. Verifies device is alive via STATUS
|
|
2. Starts temp HTTP server on Pi (port 8070)
|
|
3. Sends `OTA http://<pi>:8070/<fw>.bin` via UDP
|
|
4. Device downloads, flashes, reboots
|
|
5. Verifies device responds post-reboot
|
|
|
|
### Rollback
|
|
|
|
If new firmware crashes or hangs, the 30s watchdog reboots and bootloader
|
|
automatically rolls back to the previous firmware.
|
|
|
|
## Adaptive Sampling
|
|
|
|
When enabled, the device automatically adjusts ping rate based on CSI wander:
|
|
|
|
- **Motion detected** (wander > threshold): 100 pkt/s
|
|
- **Idle** (wander < threshold for 3s): 10 pkt/s
|
|
- Rate changes send `EVENT,<hostname>,motion=<0|1> rate=<hz> wander=<value>` via UDP
|
|
|
|
```bash
|
|
esp-cmd amber-maple.local ADAPTIVE ON # Enable
|
|
esp-cmd amber-maple.local THRESHOLD 0.005 # Tune sensitivity
|
|
# Lower threshold = more sensitive, higher = less sensitive
|
|
# Good starting range: 0.001 - 0.01
|
|
```
|
|
|
|
### LED States
|
|
|
|
| LED | Meaning |
|
|
|-----|---------|
|
|
| Off | Not connected to WiFi |
|
|
| Slow blink (1 Hz) | Connected, no CSI activity |
|
|
| Fast blink (5 Hz) | CSI data flowing |
|
|
| Solid (5s) | IDENTIFY command active |
|
|
| Double blink | OTA in progress |
|
|
|
|
## Sensor Discovery
|
|
|
|
```bash
|
|
esp-ctl discover # Find all sensors via mDNS
|
|
esp-ctl discover -t 5 # Longer browse (5s timeout)
|
|
esp-ctl status --discover # Status using discovered fleet
|
|
esp-ctl target --discover # Query targets via discovery
|
|
```
|
|
|
|
Requires firmware with `_esp-csi._udp` mDNS service (v1.1+).
|
|
|
|
## Test CSI Reception
|
|
|
|
```bash
|
|
nc -lu 5500 # Listen for CSI packets
|
|
socat UDP-RECV:5500 STDOUT # Alternative listener
|
|
nc -lu 5500 | head -1 # See one packet
|
|
nc -lu 5500 | wc -l # Count packets/sec (Ctrl+C)
|
|
esp-ctl listen -f probe -n 5 # Capture 5 probe requests (ESP32-C6+ only)
|
|
esp-ctl listen -f alert # Monitor deauth/disassoc alerts (ESP32-C6+ only)
|
|
```
|
|
|
|
## Firmware Variants
|
|
|
|
| Firmware | Dir | Output | Needs |
|
|
|----------|-----|--------|-------|
|
|
| csi_recv_router | `get-started/csi_recv_router/` | UDP | WiFi router |
|
|
| csi_recv | `get-started/csi_recv/` | Serial | csi_send device |
|
|
| csi_send | `get-started/csi_send/` | N/A | csi_recv device |
|
|
|
|
## Key Config (menuconfig)
|
|
|
|
| Path | Setting |
|
|
|------|---------|
|
|
| Example Connection Configuration → SSID | WiFi network name |
|
|
| Example Connection Configuration → Password | WiFi password |
|
|
| CSI UDP Configuration → IP | `192.168.129.11` |
|
|
| CSI UDP Configuration → Port | `5500` |
|
|
| CSI UDP Configuration → Cmd port | `5501` |
|
|
| CSI UDP Configuration → Hostname | mDNS name (e.g., `amber-maple`) |
|
|
|
|
## USB Flash Notes
|
|
|
|
- **Use 460800 baud** (`-b 460800`) — 921600 causes connection failures on some boards
|
|
- Hostname can be changed at runtime via `esp-ctl cmd <host> HOSTNAME <name>`
|
|
- First flash after enabling OTA partitions must be via USB
|
|
|
|
## Data Packet Formats
|
|
|
|
All data packets include sensor hostname after the type tag:
|
|
|
|
```
|
|
CSI_DATA,<hostname>,seq,mac,rssi,rate,...,len,first_word,"[I,Q,...]"
|
|
BLE_DATA,<hostname>,mac,rssi,pub|rnd,name
|
|
EVENT,<hostname>,motion=0|1 rate=<hz> wander=<value>
|
|
ALERT_DATA,<hostname>,deauth|disassoc,sender_mac,target_mac,rssi
|
|
PROBE_DATA,<hostname>,mac,rssi,ssid
|
|
```
|
|
|
|
**Note:** On original ESP32, promiscuous mode (ALERT_DATA, PROBE_DATA) is disabled
|
|
because it breaks CSI data collection at the driver level. These packet types are
|
|
only generated on ESP32-C6 and newer chips.
|
|
|
|
## Source Paths
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `get-started/csi_recv_router/main/app_main.c` | Main firmware source |
|
|
| `get-started/csi_recv_router/main/Kconfig.projbuild` | UDP/cmd port config |
|
|
| `tools/esp-cmd` | Pi-side management CLI |
|
|
| `tools/esp-ota` | Pi-side OTA update tool |
|
|
| `tools/esp-fleet` | Fleet-wide command tool |
|
|
| `get-started/csi_recv_router/sdkconfig.defaults` | SDK defaults |
|
|
| `get-started/csi_recv_router/main/idf_component.yml` | Dependencies |
|
|
| `get-started/csi_recv_router/CMakeLists.txt` | Build config |
|
|
|
|
## ESP-IDF Paths
|
|
|
|
| Path | Contents |
|
|
|------|----------|
|
|
| `~/esp/esp-idf/` | ESP-IDF v5.5.2 |
|
|
| `~/esp/esp-csi/` | Original esp-csi examples |
|
|
| `~/.espressif/tools/` | Xtensa toolchain |
|
|
|
|
## USB Serial
|
|
|
|
```bash
|
|
ls /dev/ttyUSB* /dev/ttyACM* # Find connected devices
|
|
dmesg | tail # Check USB detection
|
|
sudo usermod -aG dialout $USER # Fix permissions (re-login)
|
|
```
|