# Usage Guide

## Firmware Variants

This repo contains three firmware approaches for CSI data collection:

| Firmware | Directory | Output | Use Case |
|----------|-----------|--------|----------|
| **csi_recv_router** | `get-started/csi_recv_router/` | UDP to Pi | **Production** - deployed on 3 sensors |
| **csi_recv** | `get-started/csi_recv/` | Serial console | Development/debugging |
| **csi_send** | `get-started/csi_send/` | N/A (transmit only) | Paired with csi_recv |

## csi_recv_router (Deployed Firmware)

### How It Works

1. ESP32 connects to WiFi router as a station
2. Pings the gateway at 100 Hz (10ms interval)
3. Each ping response triggers a CSI callback
4. CSI data is formatted as CSV and sent via UDP

### Data Flow

```
Router ←── ping ──→ ESP32 ──── UDP ──→ Pi (192.168.129.11:5500)
         (100 Hz)         (CSI_DATA)
```

### CSI Data Format (ESP32)

```
CSI_DATA,<seq>,<mac>,<rssi>,<rate>,<sig_mode>,<mcs>,<cwb>,<smoothing>,
<not_sounding>,<aggregation>,<stbc>,<fec_coding>,<sgi>,<noise_floor>,
<ampdu_cnt>,<channel>,<secondary_channel>,<timestamp>,<ant>,<sig_len>,
<rx_state>,<len>,<first_word_invalid>,"[csi_values]"
```

| Field | Type | Description |
|-------|------|-------------|
| seq | int | Packet sequence number (increments from 0) |
| mac | MAC | Gateway MAC address |
| rssi | int8 | Received signal strength (dBm) |
| rate | uint8 | PHY rate |
| sig_mode | uint8 | 0=non-HT, 1=HT, 3=VHT |
| mcs | uint8 | Modulation and coding scheme |
| cwb | uint8 | Channel bandwidth (0=20MHz, 1=40MHz) |
| smoothing | uint8 | Channel estimate smoothing |
| not_sounding | uint8 | Not sounding frame |
| aggregation | uint8 | AMPDU aggregation |
| stbc | uint8 | Space-time block coding |
| fec_coding | uint8 | FEC coding (0=BCC, 1=LDPC) |
| sgi | uint8 | Short guard interval |
| noise_floor | int8 | Noise floor (dBm) |
| ampdu_cnt | uint8 | AMPDU sub-frame count |
| channel | uint8 | Primary channel number |
| secondary_channel | uint8 | Secondary channel offset |
| timestamp | uint32 | Local timestamp (microseconds) |
| ant | uint8 | Antenna number |
| sig_len | uint16 | Signal length |
| rx_state | uint32 | RX state (0 = valid) |
| len | int | CSI data length (bytes) |
| first_word_invalid | bool | First 4 bytes invalid flag |
| csi_values | int8[] | Raw CSI I/Q values (interleaved) |

### CSI Values Interpretation

The `csi_values` array contains interleaved I/Q pairs per subcarrier:

```
[I0, Q0, I1, Q1, I2, Q2, ...]
```

- Each pair represents one OFDM subcarrier
- Amplitude: `sqrt(I^2 + Q^2)`
- Phase: `atan2(Q, I)`
- Typical length: 128 bytes (64 subcarriers x 2 values) for HT20

## csi_recv vs csi_recv_router Comparison

| Aspect | csi_recv | csi_recv_router |
|--------|----------|-----------------|
| **WiFi mode** | STA, no AP connection | STA, connects to router |
| **CSI source** | ESP-NOW packets from csi_send | Ping responses from gateway |
| **Output** | Serial (`ets_printf`) | UDP socket |
| **Requires** | Paired csi_send device | WiFi router only |
| **Promiscuous mode** | Yes | No |
| **MAC filtering** | Fixed `1a:00:00:00:00:00` | Gateway BSSID |
| **WiFi credentials** | Not needed | Required (menuconfig) |
| **CSI config (ESP32)** | All LTF types enabled | LLTF only (router compat) |
| **Gain compensation** | Logged to serial | Applied to UDP data |
| **Sequence counter** | From ESP-NOW payload (`rx_id`) | Local counter (`s_count`) |
| **Network** | Standalone (no router needed) | Depends on router |
| **Deployment** | Lab/testing | Production |

### Key Differences in CSI Config (ESP32 target)

| Setting | csi_recv | csi_recv_router |
|---------|----------|-----------------|
| `lltf_en` | true | true |
| `htltf_en` | **true** | **false** |
| `stbc_htltf2_en` | **true** | **false** |
| `manu_scale` | **false** | **true** |
| `shift` | **false** | **true** |

The router firmware uses only LLTF for broader router compatibility. The ESP-NOW firmware enables all LTF types since it controls both endpoints.

## CSI Configuration Reference

### sdkconfig.defaults

#### WiFi Settings

| Config | Value | Description |
|--------|-------|-------------|
| `CONFIG_ESP32_WIFI_CSI_ENABLED` | `y` | **Required.** Enables CSI extraction from received frames |
| `CONFIG_ESP32_WIFI_AMPDU_TX_ENABLED` | (empty) | Disables TX aggregation. Aggregated frames combine CSI, reducing quality |
| `CONFIG_ESP32_WIFI_AMPDU_RX_ENABLED` | (empty) | Disables RX aggregation (csi_recv_router only) |
| `CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM` | `128` | Number of dynamic RX buffers. Higher = fewer drops at high CSI rates. Default is 32 |
| `CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM` | `32` | Number of dynamic TX buffers |

#### Performance Settings

| Config | Value | Description |
|--------|-------|-------------|
| `CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ` | `240` | Max CPU clock. Ensures CSI callback and UDP send complete within 10ms |
| `CONFIG_COMPILER_OPTIMIZATION_PERF` | `y` | `-O2` optimization. Faster CSI processing |
| `CONFIG_FREERTOS_HZ` | `1000` | 1ms tick resolution. Required for 100 Hz ping timer accuracy |

#### System Settings

| Config | Value | Description |
|--------|-------|-------------|
| `CONFIG_ESP_TASK_WDT_TIMEOUT_S` | `30` | Watchdog timeout. Extended from default 5s to avoid false resets during WiFi reconnect |
| `CONFIG_ESP_CONSOLE_UART_BAUDRATE` | `921600` | Fast serial for debug output |
| `CONFIG_ESPTOOLPY_MONITOR_BAUD` | `921600` | Monitor baud rate (must match console) |

### Kconfig.projbuild (Custom Settings)

| Config | Default | Range | Description |
|--------|---------|-------|-------------|
| `CONFIG_CSI_UDP_TARGET_IP` | `192.168.129.11` | Any IPv4 | Destination IP for UDP CSI packets |
| `CONFIG_CSI_UDP_TARGET_PORT` | `5500` | 1024-65535 | Destination UDP port |

### wifi_csi_config_t (Code-Level Settings)

#### ESP32 (Xtensa)

| Field | csi_recv_router | Description |
|-------|----------------|-------------|
| `lltf_en` | `true` | Enable Legacy Long Training Field. Most compatible with routers |
| `htltf_en` | `false` | HT-LTF. Only in HT (802.11n) frames. Disabled for router compat |
| `stbc_htltf2_en` | `false` | STBC HT-LTF2. Only with STBC encoding |
| `ltf_merge_en` | `true` | Merge multiple LTF into one CSI report |
| `channel_filter_en` | `true` | Apply channel estimation filter |
| `manu_scale` | `true` | Manual amplitude scaling |
| `shift` | `true` | Bit shift for value range |

### Compile-Time Defines (app_main.c)

| Define | Value | Description |
|--------|-------|-------------|
| `CONFIG_SEND_FREQUENCY` | `100` | Ping rate in Hz (10ms interval) |
| `CONFIG_FORCE_GAIN` | `0` | Force AGC/FFT gain to baseline (disabled) |
| `CONFIG_GAIN_CONTROL` | `1` (auto) | Enable gain compensation (ESP32-S3, C3, C5, C6, C61) |

## Remote Management

### Commands (esp-cmd)

Send commands to individual devices over UDP port 5501:

```bash
esp-cmd <host> STATUS        # Uptime, heap, RSSI, tx_power, rate, version
esp-cmd <host> IDENTIFY      # LED solid 5s
esp-cmd <host> RATE <10-100> # Set ping rate (NVS saved)
esp-cmd <host> POWER <2-20>  # Set TX power dBm (NVS saved)
esp-cmd <host> OTA <url>     # Trigger OTA update (prefer esp-ota)
esp-cmd <host> REBOOT        # Restart device
```

### Fleet Management (esp-fleet)

Send commands to all sensors in parallel:

```bash
esp-fleet status             # Query all devices
esp-fleet identify           # Blink all LEDs
esp-fleet rate 50            # Set rate on all
esp-fleet reboot             # Reboot all
esp-fleet ota                # OTA update all (sequential)
esp-fleet ota /path/to/fw    # OTA with custom firmware
```

## OTA Updates

### Overview

Firmware updates are delivered over WiFi using ESP-IDF's `esp_https_ota` with a dual OTA partition layout. The device downloads a new binary from an HTTP server on the Pi, writes it to the inactive OTA slot, and reboots.

### Partition Layout

| Partition | Offset | Size | Purpose |
|-----------|--------|------|---------|
| nvs | 0x9000 | 16 KB | NVS config storage |
| otadata | 0xd000 | 8 KB | OTA boot selection |
| phy_init | 0xf000 | 4 KB | PHY calibration |
| ota_0 | 0x10000 | 1920 KB | App slot A |
| ota_1 | 0x1F0000 | 1920 KB | App slot B |

### Using esp-ota

The `esp-ota` tool handles the full OTA workflow:

```bash
esp-ota amber-maple.local               # Default build path
esp-ota amber-maple.local -f custom.bin # Custom firmware
esp-ota amber-maple.local --no-wait     # Don't verify reboot
```

**What it does:**

1. Verifies the device is alive (`STATUS`)
2. Starts a temporary HTTP server on port 8070
3. Sends `OTA http://<pi-ip>:8070/<firmware>.bin` to the device
4. Waits for the device to download, flash, reboot
5. Verifies the device responds with the new version

### Rollback

The bootloader supports automatic rollback on failed updates:

1. New firmware is written to the inactive OTA slot
2. Device reboots into the new firmware in `PENDING_VERIFY` state
3. If the firmware boots successfully (WiFi connects, mDNS starts, command listener ready), it marks itself as valid
4. If the firmware crashes or hangs, the 30s watchdog triggers a reboot and the bootloader rolls back to the previous slot

### First-Time Setup

The initial flash **must be done via USB** because switching from a single-app to a dual-OTA partition table requires erasing the entire flash. After the first USB flash, all subsequent updates can be done via OTA.

```bash
idf.py -p /dev/ttyUSB0 flash   # First time: USB required
esp-ota amber-maple.local       # All subsequent updates: OTA
```

## Receiving CSI Data on the Pi

Listen on UDP port 5500:

```bash
# Quick test
nc -lu 5500

# Save to file
nc -lu 5500 > csi_capture.csv

# With socat (more reliable)
socat UDP-RECV:5500 STDOUT
```

## Python Visualization Tools

### get-started/tools/

```bash
pip install -r get-started/tools/requirements.txt
python get-started/tools/csi_data_read_parse.py
```

Requires serial connection (not UDP). Use for development with `csi_recv` firmware.

### esp-radar/console_test/tools/

```bash
pip install -r esp-radar/console_test/tools/requirements.txt
python esp-radar/console_test/tools/esp_csi_tool.py
python esp-radar/console_test/tools/esp_csi_tool_gui.py
```

CLI and GUI tools for CSI analysis with presence detection algorithms.