# 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 STATUS # Uptime, heap, RSSI, rate, version, adaptive, motion esp-cmd IDENTIFY # LED solid 5s (find the device) esp-cmd RATE 50 # Set ping rate to 50 Hz (disables adaptive) esp-cmd POWER 15 # Set TX power to 15 dBm (NVS saved) esp-cmd ADAPTIVE ON # Enable adaptive sampling (NVS saved) esp-cmd ADAPTIVE OFF # Disable adaptive sampling esp-cmd THRESHOLD 0.005 # Set motion sensitivity (NVS saved) esp-cmd OTA http://pi:8070/fw # Trigger OTA update (use esp-ota instead) esp-cmd 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://:8070/.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,,motion=<0|1> rate= wander=` 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 | ## 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) ``` ## 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 - Each device needs its own build with its hostname set in menuconfig - 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,,seq,mac,rssi,rate,...,len,first_word,"[I,Q,...]" BLE_DATA,,mac,rssi,pub|rnd,name EVENT,,motion=0|1 rate= wander= ALERT_DATA,,deauth|disassoc,sender_mac,target_mac,rssi ``` ## 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) ```