diff --git a/README.md b/README.md new file mode 100644 index 0000000..825585e --- /dev/null +++ b/README.md @@ -0,0 +1,167 @@ +# 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 + +### Building + +```bash +# 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 +``` + +## Console Commands + +### WiFi Commands +- `wifi connect [password]` - Connect to WiFi network +- `wifi scan` - Scan for available networks +- `wifi status` - Show WiFi connection status +- `wifi mode ` - Set WiFi mode +- `wifi power ` - Set transmit power + +### IP Configuration +- `ip addr` - Show current IP configuration +- `ip set ` - 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 ] [--port ] [--len ] [--burst ]` - 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 ` - 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: + +```bash +# Flash and configure multiple devices +python3 esp32_deploy.py \ + --ssid "YourSSID" \ + --password "password" \ + --target-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. + +## 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](doc/QUICK_START.md) +- [Quick Reference](doc/QUICK_REFERENCE.md) +- [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. diff --git a/dependencies.lock b/dependencies.lock index 37f7b68..7e51cc5 100644 --- a/dependencies.lock +++ b/dependencies.lock @@ -17,5 +17,5 @@ direct_dependencies: - espressif/led_strip - idf manifest_hash: cfead66889b7175cc6aa9a766fd00dc94649d6800986f3fcc4645dc58723ed39 -target: esp32s3 +target: esp32c5 version: 2.0.0 diff --git a/doc/README.md b/doc/README.md deleted file mode 100644 index 2fb7dff..0000000 --- a/doc/README.md +++ /dev/null @@ -1,60 +0,0 @@ -# esp32-iperf (ESP-IDF 6.x) - -Minimal ESP32/ESP32-S3 iPerf firmware with **station mode** and optional **static IP**. -Tested on **ESP-IDF 6.0** (dev snapshot). - -## Repo layout - -| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S2 | ESP32-S3 | Linux | -| ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | -------- | ----- | - -# Hello World Example - -Starts a FreeRTOS task to print "Hello World". - -(See the README.md file in the upper level 'examples' directory for more information about examples.) - -## How to use example - -Follow detailed instructions provided specifically for this example. - -Select the instructions depending on Espressif chip installed on your development board: - -- [ESP32 Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/stable/get-started/index.html) -- [ESP32-S2 Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/get-started/index.html) - - -## Example folder contents - -The project **hello_world** contains one source file in C language [hello_world_main.c](main/hello_world_main.c). The file is located in folder [main](main). - -ESP-IDF projects are built using CMake. The project build configuration is contained in `CMakeLists.txt` files that provide set of directives and instructions describing the project's source files and targets (executable, library, or both). - -Below is short explanation of remaining files in the project folder. - -``` -├── CMakeLists.txt -├── pytest_hello_world.py Python script used for automated testing -├── main -│ ├── CMakeLists.txt -│ └── hello_world_main.c -└── README.md This is the file you are currently reading -``` - -For more information on structure and contents of ESP-IDF projects, please refer to Section [Build System](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html) of the ESP-IDF Programming Guide. - -## Troubleshooting - -* Program upload failure - - * Hardware connection is not correct: run `idf.py -p PORT monitor`, and reboot your board to see if there are any output logs. - * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. - -## Technical support and feedback - -Please use the following feedback channels: - -* For technical queries, go to the [esp32.com](https://esp32.com/) forum -* For a feature request or bug report, create a [GitHub issue](https://github.com/espressif/esp-idf/issues) - -We will get back to you as soon as possible.