ESP32/README.md

# ESP32 Wi-Fi Telemetry Capture / iPerf Load Generator

High-performance Wi-Fi monitor and iperf 2 based traffic generator firmware for ESP32 devices with interactive console interface, GPS synchronization, and Wi-Fi telemetry capture (MCS, RSSI, frame stats, collapse detection, and more).

**Version:** 2.1.0
**ESP-IDF:** 6.0+

## Features

- **UDP Traffic Generation**: Precise packet pacing (PPS) with drift-free timers
- **Interactive Console**: Full REPL interface with command history and tab completion
- **WiFi Management**: Station mode with static IP support, DHCP, and monitor mode
- **GPS Synchronization**: PPS signal support and NMEA parsing for timestamp synchronization
- **Persistent Configuration**: NVS storage for WiFi credentials, IP settings, and iPerf parameters
- **SD Card**: Telemetry storage (fiwi-telemetry), HTTP file download (port 8080), serial transfer, broadcast beacon for laptop discovery
- **Status LED**: Visual feedback for connection state and system status
- **Mass Deployment**: Python scripts for flashing and configuring multiple devices

## Supported Targets

- ESP32
- ESP32-S3
- ESP32-C5
- ESP32-C3, ESP32-C6 (may require testing)

## Quick Start

### Prerequisites

- ESP-IDF v6.0 or later
- Python 3.7+ (for deployment scripts)
- USB serial connection to ESP32 device

### ESP-IDF Setup

Add this function to your `~/.bashrc` or `~/.zshrc` to activate ESP-IDF v6:

```bash
# ESP-IDF v6 activator
get_idf() {
  export IDF_PATH="$HOME/Code/esp32/esp-idf-v6"
  export IDF_PYTHON_ENV_PATH="$HOME/.espressif/python_env/idf6.0_py3.11_env"
  export IDF_TOOLS_PYTHON="$IDF_PYTHON_ENV_PATH/bin/python"
  export PATH="$IDF_PYTHON_ENV_PATH/bin:$PATH"
  export PYTHONNOUSERSITE=1
  . "$IDF_PATH/export.sh"
  hash -r
  echo "ESP-IDF : $(idf.py --version 2>/dev/null)"
  echo "python  : $(python --version)"
  echo "idf.py  : $(command -v idf.py)"
}
```

After adding the function, reload your shell configuration and run `get_idf` to activate the ESP-IDF environment.

### Building

**Note:** All `idf.py` commands require the ESP-IDF environment to be activated first by running `get_idf`.

```bash
# Activate ESP-IDF environment (required before all idf.py commands)
get_idf

# Set target (e.g., esp32c5, esp32s3, esp32)
idf.py set-target esp32c5

# Configure (optional)
idf.py menuconfig

# Build
idf.py build

# Flash and monitor
idf.py -p /dev/ttyUSB0 flash monitor
```

### Initial Configuration

After flashing, connect to the console at 115200 baud. Use the interactive commands:

```bash
# Connect to WiFi
wifi connect "YourSSID" "password"

# Set static IP (optional)
ip set 192.168.1.100 255.255.255.0 192.168.1.1

# Configure iPerf parameters
iperf set --client 192.168.1.10 --port 5001 --len 1470 --burst 1

# Save configuration to NVS
iperf save

# Start iPerf traffic
iperf start

# Check status
iperf status

# Wi‑Fi telemetry (monitor mode writes to fiwi-telemetry on SD; disconnects WiFi)
monitor start 6
sdcard status
sdcard read fiwi-telemetry
```

## Console Commands

### WiFi Commands
- `wifi connect <ssid> [password]` - Connect to WiFi network
- `wifi scan` - Scan for available networks
- `wifi status` - Show WiFi connection status
- `wifi mode <sta|ap>` - Set WiFi mode
- `wifi power <dbm>` - Set transmit power

### IP Configuration
- `ip addr` - Show current IP configuration
- `ip set <ip> <mask> <gateway>` - Set static IP
- `ip dhcp` - Enable DHCP

### iPerf Commands
- `iperf start` - Start traffic generation
- `iperf stop` - Stop traffic generation
- `iperf status` - Show current status and statistics
- `iperf set [--client <ip>] [--port <port>] [--len <bytes>] [--burst <count>]` - Configure parameters
- `iperf save` - Save configuration to NVS
- `iperf reload` - Reload configuration from NVS
- `iperf clear` - Clear saved configuration

### System Commands
- `reset` - Software reset
- `version` - Show firmware and IDF version
- `system info` - Show system information
- `system heap` - Show free heap memory

### GPS Commands (if GPS enabled)
- `gps status` - Show GPS synchronization status

### Monitor Mode
- `monitor start [channel]` - Start WiFi monitor mode (writes MCS telemetry to `fiwi-telemetry` on SD every 10s)
- `monitor stop` - Stop monitor mode
- `monitor channel <channel>` - Set monitor channel
- `monitor status` - Show monitor status

### SD Card Commands
Telemetry from monitor mode is stored in `fiwi-telemetry` (NDJSON, appended each flush). Use SD commands to inspect or transfer it.

- `sdcard status` - Show CD, mounted, capacity, and fiwi-telemetry file info
- `sdcard list [path]` - List files (path optional, default root)
- `sdcard read <file>` - Read and print file (e.g. `sdcard read fiwi-telemetry`)
- `sdcard write <file> <text>` - Write text to file
- `sdcard send <file>` - Stream file over serial (use `tools/sdcard_recv.py`)
- `sdcard delete <file>` - Delete a file

**Example (telemetry capture):**
```text
monitor start 6
sdcard status
sdcard list
sdcard read fiwi-telemetry
```

For detailed command documentation, see [Quick Reference](doc/QUICK_REFERENCE.md).

## Mass Deployment

Use the `esp32_deploy.py` script for deploying to multiple devices:

```bash
# Flash and configure multiple devices
python3 esp32_deploy.py \
  --ssid "YourSSID" \
  --password "password" \
  --start-ip 192.168.1.50 \
  --netmask 255.255.255.0 \
  --gateway 192.168.1.1 \
  --iperf-dest-ip 192.168.1.10 \
  --iperf-port 5001
```

See [Deployment Guide](doc/DEPLOYMENT_GUIDE.md) for complete deployment instructions.

### USB Port Mapping (`gen_udev_rules.py`)

When deploying to multiple ESP32 devices, Linux assigns `/dev/ttyUSB*` ports that can change between reboots or when devices are reconnected. The `gen_udev_rules.py` script creates stable symbolic links (e.g., `/dev/esp_port_01`, `/dev/esp_port_02`) based on each device's USB physical topology (`ID_PATH`), ensuring consistent port identification across system reboots.

**Features:**
- Uses `ID_PATH` for stable device identification (not just port numbers)
- Creates predictable symlinks: `/dev/esp_port_01`, `/dev/esp_port_02`, etc.
- Supports full scan (generate from scratch) or incremental updates (append new devices)
- Sorts devices by physical USB topology for consistent ordering

**Usage:**

```bash
# Generate complete rules file from scratch
python3 gen_udev_rules.py --full

# Append only new devices to existing rules (default mode)
python3 gen_udev_rules.py --append

# Dry run to preview changes
python3 gen_udev_rules.py --append --dry-run
```

After generating rules, install them:
```bash
sudo cp 99-esp32-stable.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger
```

The deployment script (`esp32_deploy.py`) can use these stable symlinks when `--map-ports` is used, or devices can be referenced directly by their `esp_port_XX` names.

## Project Structure

```
├── main/                  # Main application code
│   ├── main.c            # Entry point and console initialization
│   ├── broadcast_beacon.c/h  # UDP broadcast for laptop discovery
│   └── board_config.h    # Hardware pin definitions
├── components/
│   ├── app_console/      # Console command implementations
│   │   ├── cmd_wifi.c    # WiFi commands (connect, scan, status, mode, power)
│   │   ├── cmd_ip.c      # IP configuration (addr, set, dhcp)
│   │   ├── cmd_iperf.c   # iPerf commands (start, stop, status, set, save, reload, clear)
│   │   ├── cmd_monitor.c # Monitor mode (start, stop, channel, status)
│   │   ├── cmd_sdcard.c  # SD card commands (status, list, read, write, send, delete)
│   │   ├── cmd_gps.c     # GPS commands (status)
│   │   ├── cmd_system.c  # System commands (reset, version, info, heap)
│   │   ├── cmd_ping.c    # Ping command
│   │   └── cmd_nvs.c     # NVS management commands
│   ├── iperf/            # iPerf traffic generator core
│   ├── wifi_controller/  # WiFi management and monitor mode
│   ├── wifi_monitor/     # 802.11 frame capture and collapse detection
│   ├── wifi_cfg/         # WiFi and IP configuration storage
│   ├── gps_sync/         # GPS PPS and NMEA parsing
│   ├── status_led/       # LED status indication
│   ├── sd_card/          # SD card SPI mount and file I/O
│   ├── sdcard_http/      # HTTP server for SD file download (port 8080)
│   ├── mcs_telemetry/    # MCS/RSSI telemetry -> fiwi-telemetry
│   ├── csi_log/          # CSI logging (when CSI enabled)
│   └── csi_manager/      # CSI configuration (when CSI enabled)
├── tools/
│   ├── beacon_listen.py  # Listen for beacons, download fiwi-telemetry
│   └── sdcard_recv.py    # Receive file over serial from device
├── esp32_deploy.py       # Mass deployment script
├── gen_udev_rules.py     # USB port mapping utility
└── doc/                  # Additional documentation
```

## Documentation

- [Quick Start Guide](doc/QUICK_START.md)
- [Quick Reference](doc/QUICK_REFERENCE.md)
- [SD Card Wiring](doc/SD_CARD_WIRING.md) - Hardware, file transfer, beacon discovery
- [Telemetry Capture](doc/TELEMETRY_CAPTURE.md) - Enable and capture fiwi-telemetry
- [Deployment Guide](doc/DEPLOYMENT_GUIDE.md)
- [Mass Deployment](doc/MASS_DEPLOY.md)
- [GDB Debugging Guide (ESP32-C5)](doc/ESP32-C5_GDB_Debugging_Guide.md)

## License

Copyright (c) 2025 Umber Networks & Robert McMahon
All rights reserved.

See individual source files for full license details.

## Contributing

This is a project-specific firmware. For issues or feature requests, please contact the maintainers.