# 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` |