Umber
/
ESP32
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Move README.md to root and update with comprehensive project documentation

This commit is contained in:
Robert McMahon 2025-12-27 19:47:20 -08:00
parent c58e70a658
commit 78bc0effc4
3 changed files with 168 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

167
README.md Normal file
View File

@ -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 <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:
```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.

2
dependencies.lock
View File

@ -17,5 +17,5 @@ direct_dependencies:
- espressif/led_strip - espressif/led_strip
- idf - idf
manifest_hash: cfead66889b7175cc6aa9a766fd00dc94649d6800986f3fcc4645dc58723ed39 manifest_hash: cfead66889b7175cc6aa9a766fd00dc94649d6800986f3fcc4645dc58723ed39
target: esp32s3 target: esp32c5
version: 2.0.0 version: 2.0.0

60
doc/README.md
View File

@ -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.