esp32-hacking/docs/CHEATSHEET.md

Cheatsheet

Environment Setup

source ~/esp/esp-idf/export.sh          # Activate ESP-IDF (every shell)

Build & Flash

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)

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

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)

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)

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

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

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

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

ls /dev/ttyUSB* /dev/ttyACM*            # Find connected devices
dmesg | tail                             # Check USB detection
sudo usermod -aG dialout $USER           # Fix permissions (re-login)