ESP32 iPerf Traffic Generator

High-performance UDP traffic generator firmware for ESP32 devices with interactive console interface, GPS synchronization, and WiFi monitoring capabilities.

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
• 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:

# 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

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

# 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

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
• monitor stop - Stop monitor mode
• monitor channel <channel> - Set monitor channel
• monitor status - Show monitor status

For detailed command documentation, see doc/QUICK_REFERENCE.md.

Mass Deployment

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

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

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

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
│   └── board_config.h    # Hardware pin definitions
├── components/
│   ├── app_console/      # Console command implementations
│   ├── iperf/            # iPerf traffic generator core
│   ├── wifi_controller/  # WiFi management and monitor mode
│   ├── wifi_cfg/         # WiFi and IP configuration storage
│   ├── gps_sync/         # GPS PPS and NMEA parsing
│   ├── status_led/       # LED status indication
│   └── ...
├── esp32_deploy.py       # Mass deployment script
├── gen_udev_rules.py     # USB port mapping utility
└── doc/                  # Additional documentation

Documentation

• Quick Start Guide
• Quick Reference
• Deployment Guide
• Mass Deployment
• GDB Debugging Guide (ESP32-C5)

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.