7511814976
Document esp-ctl install, standalone tool symlinks, HMAC auth setup, watch daemon setup, and CMakeLists.txt REQUIRES caveat.
190 lines
4.8 KiB
Markdown
190 lines
4.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
cd ~/git/esp32-hacking/get-started/csi_recv_router
|
|
idf.py set-target esp32
|
|
```
|
|
|
|
### 3. Configure WiFi and UDP Target
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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`.
|
|
|
|
```bash
|
|
ls /dev/ttyUSB* /dev/ttyACM*
|
|
```
|
|
|
|
### Flash Firmware
|
|
|
|
```bash
|
|
idf.py -p /dev/ttyUSB0 flash
|
|
```
|
|
|
|
### Monitor Serial Output
|
|
|
|
```bash
|
|
idf.py -p /dev/ttyUSB0 monitor
|
|
```
|
|
|
|
Exit monitor with `Ctrl+]`.
|
|
|
|
### Flash + Monitor (combined)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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` |
|