esp32-hacking/docs/INSTALL.md

Build & Flash Guide

Prerequisites

Component	Version	Location
ESP-IDF	v5.5.2	~/esp/esp-idf/
esp-csi	latest	~/esp/esp-csi/ (reference only)
Xtensa toolchain	(bundled)	~/.espressif/tools/
Python	3.13+	ESP-IDF venv

Note: Only ESP32 (Xtensa) target is installed. For ESP32-C3/C5/C6, run ~/esp/esp-idf/install.sh with the appropriate target first.

Setup

1. Activate ESP-IDF Environment

source ~/esp/esp-idf/export.sh

This must be run in every new shell session. It adds idf.py and the toolchain to PATH.

2. Set Target Chip

cd ~/git/esp32-hacking/get-started/csi_recv_router
idf.py set-target esp32

3. Configure WiFi and UDP Target

idf.py menuconfig

Navigate to:

• Example Connection Configuration → Set WiFi SSID and password
• CSI UDP Configuration → Set target IP and port

Setting	Default	Description
WiFi SSID	(none)	Your router's SSID
WiFi Password	(none)	Your router's password
UDP Target IP	192.168.129.11	Pi's IP address
UDP Target Port	5500	Listening port on Pi

Build

cd ~/git/esp32-hacking/get-started/csi_recv_router
idf.py build

Build output goes to build/ (excluded by .gitignore). External component esp_csi_gain_ctrl is fetched automatically to managed_components/.

Note on CMakeLists.txt: The main component uses no explicit REQUIRES — ESP-IDF auto-includes all components (including mbedtls for HMAC auth). Adding REQUIRES <component> overrides this and breaks the build unless all dependencies are listed.

Flash

Connect ESP32

Plug ESP32-DevKitC into USB. The serial port appears as /dev/ttyUSB0 or /dev/ttyACM0.

ls /dev/ttyUSB* /dev/ttyACM*

Flash Firmware

idf.py -p /dev/ttyUSB0 flash

Monitor Serial Output

idf.py -p /dev/ttyUSB0 monitor

Exit monitor with Ctrl+].

Flash + Monitor (combined)

idf.py -p /dev/ttyUSB0 flash monitor

Pi-Side Tools

Prerequisites

Component	Version	Install
Python	3.10+	System
esp-ctl	0.1.0	pip install -e ~/git/esp-ctl
requests	≥2.28	(esp-ctl dependency)
pyyaml	≥6.0	(esp-ctl dependency)

Install esp-ctl

cd ~/git/esp-ctl
pip install --break-system-packages -e .

# Optional extras
pip install --break-system-packages -e '.[serial]'    # pyserial for serial monitor
pip install --break-system-packages -e '.[discover]'   # zeroconf for mDNS discovery

Standalone Tools (esp32-hacking)

Symlinked to ~/.local/bin/:

Tool	Source	Purpose
esp-cmd	tools/esp-cmd	Single device commands
esp-fleet	tools/esp-fleet	Fleet-wide commands
esp-ota	tools/esp-ota	OTA firmware update

All three import esp_ctl.auth.sign_command for HMAC auth support — esp-ctl must be installed.

ln -sf ~/git/esp32-hacking/tools/esp-cmd ~/.local/bin/
ln -sf ~/git/esp32-hacking/tools/esp-fleet ~/.local/bin/
ln -sf ~/git/esp32-hacking/tools/esp-ota ~/.local/bin/

HMAC Auth Setup

# Set secret on device
esp-ctl cmd amber-maple.local "AUTH mysecretkey123"

# Add to environment so all tools auto-sign
echo 'export ESP_CMD_SECRET="mysecretkey123"' >> ~/.bashrc.secrets
source ~/.bashrc.secrets

Watch Daemon Setup

# Download OUI database (one-time)
esp-ctl oui --update

# Edit config
vim ~/.config/esp-ctl/watch.yaml

# Run daemon (listens on :5500, enriches + stores probes/BLE/alerts)
esp-ctl watch

Deployed Devices

Name	IP	Location	Notes
muddy-storm	192.168.129.29	Living Room
amber-maple	192.168.129.30	Office
hollow-acorn	192.168.129.31	Kitchen

All devices run csi_recv_router firmware, sending CSI data to 192.168.129.11:5500.

Building Other Firmware Variants

Same process, different directory:

# ESP-NOW receiver (serial output)
cd ~/git/esp32-hacking/get-started/csi_recv
idf.py set-target esp32 && idf.py build

# ESP-NOW transmitter
cd ~/git/esp32-hacking/get-started/csi_send
idf.py set-target esp32 && idf.py build

# Radar console (presence detection)
cd ~/git/esp32-hacking/esp-radar/console_test
idf.py set-target esp32 && idf.py build

Troubleshooting

Problem	Solution
idf.py: command not found	Run source ~/esp/esp-idf/export.sh
/dev/ttyUSB0 not found	Plug in ESP32, check dmesg | tail
Permission denied on serial	sudo usermod -aG dialout $USER, then re-login
Build fails on dependencies	idf.py reconfigure to re-fetch components
WiFi not connecting	Check SSID/password in idf.py menuconfig