628b84f4f3
- Add build & flash workflow (docs/INSTALL.md) - Add CSI config reference and firmware comparison (docs/USAGE.md) - Add quick reference cheatsheet (docs/CHEATSHEET.md) - Add dependencies.lock to .gitignore (env-specific) - Update TASKS.md with completed items and build notes - Verified firmware builds on ESP-IDF v6.1.0 / aarch64
3.4 KiB
Build & Flash Guide
Prerequisites
| Component | Version | Location |
|---|---|---|
| ESP-IDF | v6.1.0 | ~/esp/esp-idf/ |
| esp-csi | latest | ~/esp/esp-csi/ (reference only) |
| Xtensa toolchain | GCC 15.2.0 | ~/.espressif/tools/ |
| Python | 3.13+ | ESP-IDF venv |
Note: No RISC-V toolchain installed. Only ESP32 (Xtensa) targets are supported. 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/.
ESP-IDF v6.1 Workaround
The esp_csi_gain_ctrl component (v0.1.4) only ships prebuilt libraries up to ESP-IDF v6.0. On ESP-IDF v6.1+, the build fails with a missing .a file. Fix by symlinking:
cd managed_components/espressif__esp_csi_gain_ctrl
ln -s 6.0 6.1
This is needed after every idf.py fullclean or component re-fetch. The v6.0 library is ABI-compatible with v6.1.
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
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 |