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

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

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