feat(iperf_menu): Add iperf_menu component (#467)

* feat(iperf): Add iperf menu component for use with CLI

* update readme

* readme: update

* wip

* Update components/iperf_menu/include/iperf_menu.hpp

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* minor update

* flesh out docs and clean up menu / APIs

* Update components/iperf_menu/include/iperf_menu.hpp

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update components/iperf_menu/include/iperf_menu.hpp

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* fix minor bug

* fix sp

* update readme and make various methods const

* overload with tcp command for reference

* properly display client destination address

* remove unnecessary yaml

* fix bug in refactor and turn on perf. optimizations for demo

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: finger563

.github/workflows/build.yml

@@ -107,6 +107,11 @@ jobs:
           target: esp32s3
         - path: 'components/interrupt/example'
           target: esp32s3
+        - path: 'components/iperf_menu/example'
+          target: esp32s3
+          # NOTE: we must use custom command here because this component depends
+          # on espressif/iperf, so we can't disable the component manager
+          command: idf.py build
         - path: 'components/joystick/example'
           target: esp32
         - path: 'components/kts1622/example'

.github/workflows/upload_components.yml

@@ -71,6 +71,7 @@ jobs:
             components/icm42607
             components/input_drivers
             components/interrupt
+            components/iperf_menu
             components/joystick
             components/kts1622
             components/led

components/iperf_menu/CMakeLists.txt

@@ -0,0 +1,3 @@
+idf_component_register(
+  INCLUDE_DIRS "include"
+  PRIV_REQUIRES format cli iperf)

components/iperf_menu/README.md

@@ -0,0 +1,78 @@
+# Iperf Menu Component
+[![Badge](https://components.espressif.com/components/espp/wifi/badge.svg)](https://components.espressif.com/components/espp/iperf_menu)
+
+The `iperf_menu` component simply provides a menu for the `espressif/iperf`
+component, enabling you to easily use the `iperf` network performance testing
+tool on your ESP device using the `cli` component.
+
+<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
+**Table of Contents**
+
+- [Iperf Menu Component](#iperf-menu-component)
+  - [Menu Functions:](#menu-functions)
+  - [Example](#example)
+
+<!-- markdown-toc end -->
+
+## Menu Functions:
+
+The `iperf_menu` component provides a simple command-line interface (CLI) for
+interacting with the `iperf` tool. The available commands are:
+
+```console
+iperf> help
+Commands available:
+ - help
+	This help message
+ - exit
+	Quit the session
+ - udp
+	Get the current UDP mode setting.
+ - udp <udp>
+	Set the UDP mode for iperf tests.
+ - tcp
+	Get the current TCP mode setting.
+ - tcp <tcp>
+	Set the TCP mode for iperf tests.
+ - ipv6
+	Get the current IPv6 setting.
+ - ipv6 <ipv6>
+	Set the IPv6 mode for iperf tests.
+ - interval
+	Get the current reporting interval setting.
+ - interval <interval>
+	Set the reporting interval for iperf tests.
+ - time
+	Get the current time (duration) setting.
+ - time <time>
+	Set the time for iperf tests.
+ - format
+	Get the current formatting setting (kibits/sec or mbits/sec).
+ - format <format>
+	Set the output format for iperf tests.
+ - length
+	Get the current buffer length setting.
+ - length <length>
+	Set the buffer length for iperf tests.
+ - abort
+	Abort the current iperf test if running. This will stop the test and print a message.
+ - client <host>
+	Run an iperf client, connecting to the specified host, using the default port.
+ - client <host> <port>
+	Run an iperf client, connecting to the specified host and port.
+ - client <host> <port> <bandwidth>
+	Run an iperf client, connecting to the specified host and port. Uses the passed length as the buffer length for data transmission.
+ - server
+	Run an iperf server, listening on the default port.
+ - server <port>
+	Run an iperf server, listening on the specified port.
+ - example
+	(menu)
+```
+
+![CleanShot 2025-07-07 at 15 29 33](https://github.com/user-attachments/assets/da0f1b47-3db5-4ec4-8673-f8a61fa736e3)
+
+## Example
+
+The [example](./example) shows the use of the `espp::IperfMenu` (using WiFi station). 
+

components/iperf_menu/example/CMakeLists.txt

@@ -0,0 +1,21 @@
+# The following lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.20)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+
+# add the component directories that we want to use
+set(EXTRA_COMPONENT_DIRS
+  "../../../components/"
+)
+
+set(
+  COMPONENTS
+  "main esptool_py wifi iperf_menu task format"
+  CACHE STRING
+  "List of components to include"
+  )
+
+project(iperf_menu_example)
+
+set(CMAKE_CXX_STANDARD 20)

components/iperf_menu/example/README.md

@@ -0,0 +1,130 @@
+# Iperf Menu Example
+
+This example shows the use of the `espp::IperfMenu` component to measure the
+throughput of a network (WiFi / ethernet) connection between an ESP chip and
+another device running iperf.
+
+<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
+**Table of Contents**
+
+- [Iperf Menu Example](#iperf-menu-example)
+  - [How to use example](#how-to-use-example)
+    - [Build and Flash](#build-and-flash)
+    - [Configuration](#configuration)
+    - [Example Output](#example-output)
+
+<!-- markdown-toc end -->
+
+![CleanShot 2025-07-07 at 13 27 54](https://github.com/user-attachments/assets/3eedd8e3-b864-4385-9b7b-46d573480e90)
+
+This supports:
+
+- client operation
+- server operation
+- ipv4/ipv6
+
+## How to use example
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT flash monitor
+```
+
+(Replace PORT with the name of the serial port to use.)
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+### Configuration
+
+This example uses WiFi (specifically WiFi STA), so you should use the `wifi`
+command line interface (CLI) menu that the example outputs over the serial
+monitor to configure the WiFi network.
+
+Once you're connected, you can use the `iperf` menu to select the operation mode
+(client or server) and set the parameters for the test.
+
+### Example Output
+
+![CleanShot 2025-07-07 at 14 27 02@2x](https://github.com/user-attachments/assets/9053320f-40c6-45b6-9224-9f2c16ca7960)
+
+![CleanShot 2025-07-07 at 13 27 54](https://github.com/user-attachments/assets/3eedd8e3-b864-4385-9b7b-46d573480e90)
+
+
+```console
+I (399) main_task: Calling app_main()
+[iperf_example/I][0.015]: Starting example...
+I (429) pp: pp rom version: e7ae62f
+I (429) net80211: net80211 rom version: e7ae62f
+I (439) wifi:wifi driver task: 3fcb05cc, prio:23, stack:6656, core=0
+I (449) wifi:wifi firmware version: 79fa3f41ba
+I (449) wifi:wifi certification version: v7.0
+I (449) wifi:config NVS flash: enabled
+I (449) wifi:config nano formatting: disabled
+I (449) wifi:Init data frame dynamic rx buffer num: 32
+I (449) wifi:Init static rx mgmt buffer num: 5
+I (449) wifi:Init management short buffer num: 32
+I (449) wifi:Init dynamic tx buffer num: 32
+I (449) wifi:Init static tx FG buffer num: 2
+I (449) wifi:Init static rx buffer size: 1600
+I (449) wifi:Init static rx buffer num: 10
+I (449) wifi:Init dynamic rx buffer num: 32
+I (449) wifi_init: rx ba win: 6
+I (449) wifi_init: accept mbox: 6
+I (449) wifi_init: tcpip mbox: 32
+I (449) wifi_init: udp mbox: 6
+I (449) wifi_init: tcp mbox: 6
+I (449) wifi_init: tcp tx win: 5760
+I (449) wifi_init: tcp rx win: 5760
+I (449) wifi_init: tcp mss: 1440
+I (449) wifi_init: WiFi IRAM OP enabled
+I (449) wifi_init: WiFi RX IRAM OP enabled
+[WifiSta/D][0.069]: SSID is empty, trying to load saved WiFi configuration
+[WifiSta/I][0.070]: Loaded saved WiFi configuration: SSID = 'HouseOfBoo'
+I (459) phy_init: phy_version 700,8582a7fd,Feb 10 2025,20:13:11
+I (489) wifi:mode : sta (f4:12:fa:5a:85:90)
+I (489) wifi:enable tsf
+I (499) wifi:new:<6,0>, old:<1,0>, ap:<255,255>, sta:<6,0>, prof:1, snd_ch_cfg:0x0
+I (499) wifi:state: init -> auth (0xb0)
+example> I (529) wifi:state: auth -> assoc (0x0)
+I (539) wifi:state: assoc -> run (0x10)
+I (659) wifi:connected with HouseOfBoo, aid = 1, channel 6, BW20, bssid = 3c:28:6d:bf:ed:ad
+I (669) wifi:security: WPA2-PSK, phy: bgn, rssi: -63
+I (669) wifi:pm start, type: 1
+
+I (669) wifi:dp: 1, bi: 102400, li: 3, scale listen interval from 307200 us to 307200 us
+I (669) wifi:set rx beacon pti, rx_bcn_pti: 0, bcn_timeout: 25000, mt_pti: 0, mt_time: 10000
+I (679) wifi:dp: 2, bi: 102400, li: 4, scale listen interval from 307200 us to 409600 us
+I (679) wifi:AP's beacon interval = 102400 us, DTIM period = 2
+I (689) wifi:<ba-add>idx:0 (ifx:0, 3c:28:6d:bf:ed:ad), tid:6, ssn:3, winSize:64
+I (1399) wifi:<ba-add>idx:1 (ifx:0, 3c:28:6d:bf:ed:ad), tid:0, ssn:0, winSize:64
+I (1889) esp_netif_handlers: sta ip: 192.168.86.32, mask: 255.255.255.0, gw: 192.168.86.1
+[WifiSta/I][1.502]: got ip: 192.168.86.32
+[iperf_example/I][1.503]: got IP: 192.168.86.32
+
+example>
+example> iperf
+iperf> client_tcp 192.168.86.21 5001 0 10
+Using iperf config: iperf_cfg_t client {  host: 358000832,  dest port: 5001,  source port: 5001,  protocol: TCP,  duration: 30,  bandwidth: -1,  buffer_size: 0 }
+iperf> I (23009) iperf: Successfully connected
+
+Interval       Bandwidth
+ 0.0-10.0 sec  6784.00 Kbits/sec
+10.0-20.0 sec  5964.80 Kbits/sec
+20.0-30.0 sec  4377.60 Kbits/sec
+ 0.0-30.0 sec  5708.80 Kbits/sec
+I (53029) iperf: TCP Socket client is closed.
+I (53029) iperf: iperf exit
+
+iperf> client_udp 192.168.86.21 5001 0 1
+Using iperf config: iperf_cfg_t client {  host: 358000832,  dest port: 5001,  source port: 5001,  protocol: UDP,  duration: 30,  bandwidth: -1,  buffer_size: 0 }
+iperf> I (101369) iperf: Socket created, sending to 358000832:5001
+
+Interval       Bandwidth
+ 0.0- 1.0 sec  8130.94 Kbits/sec
+ 1.0- 2.0 sec  7315.55 Kbits/sec
+```

components/iperf_menu/example/main/CMakeLists.txt

@@ -0,0 +1,2 @@
+idf_component_register(SRC_DIRS "."
+                       INCLUDE_DIRS ".")

components/iperf_menu/example/main/iperf_menu_example.cpp

@@ -0,0 +1,76 @@
+#include <chrono>
+#include <vector>
+
+#include "sdkconfig.h"
+
+#if CONFIG_ESP32_WIFI_NVS_ENABLED
+#include "nvs_flash.h"
+#endif
+
+#include "logger.hpp"
+#include "task.hpp"
+#include "wifi_sta.hpp"
+
+#if defined(CONFIG_COMPILER_CXX_EXCEPTIONS)
+#include "cli.hpp"
+#include "iperf_menu.hpp"
+#include "wifi_sta_menu.hpp"
+#endif
+
+using namespace std::chrono_literals;
+
+extern "C" void app_main(void) {
+  espp::Logger logger({.tag = "iperf_example", .level = espp::Logger::Verbosity::INFO});
+  logger.info("Starting example...");
+
+#if CONFIG_ESP32_WIFI_NVS_ENABLED
+  // Initialize NVS
+  esp_err_t ret = nvs_flash_init();
+  if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
+    ESP_ERROR_CHECK(nvs_flash_erase());
+    ret = nvs_flash_init();
+  }
+  ESP_ERROR_CHECK(ret);
+#endif
+
+#if CONFIG_COMPILER_CXX_EXCEPTIONS || defined(_DOXYGEN_)
+  {
+    //! [iperf menu example]
+    espp::WifiSta wifi_sta({.ssid = "",               // CONFIG_ESP_WIFI_SSID,
+                            .password = "",           // CONFIG_ESP_WIFI_PASSWORD,
+                            .num_connect_retries = 5, // CONFIG_ESP_MAXIMUM_RETRY,
+                            .on_connected = nullptr,
+                            .on_disconnected = nullptr,
+                            .on_got_ip =
+                                [&](ip_event_got_ip_t *eventdata) {
+                                  logger.info("got IP: {}.{}.{}.{}",
+                                              IP2STR(&eventdata->ip_info.ip));
+                                },
+                            .log_level = espp::Logger::Verbosity::DEBUG});
+    auto sta_menu = espp::WifiStaMenu(wifi_sta);
+
+    auto iperf_menu = espp::IperfMenu();
+
+    // Now make the cli and start it
+    auto root_menu = std::make_unique<cli::Menu>("example");
+    root_menu->Insert(sta_menu.get());
+    root_menu->Insert(iperf_menu.get());
+    cli::Cli cli(std::move(root_menu));
+    cli::SetColor();
+    cli.ExitAction([](auto &out) { out << "Goodbye and thanks for all the fish.\n"; });
+
+    espp::Cli input(cli);
+    input.SetInputHistorySize(10);
+    input.Start();
+    //! [iperf menu example]
+  }
+#else
+  logger.error("C++ exceptions are not enabled. Please enable them in the menuconfig.");
+#endif // CONFIG_COMPILER_CXX_EXCEPTIONS || defined(_DOXYGEN_)
+
+  logger.info("Example complete!");
+
+  while (true) {
+    std::this_thread::sleep_for(1s);
+  }
+}

components/iperf_menu/example/partitions.csv

@@ -0,0 +1,5 @@
+# ESP-IDF Partition Table
+# Name,   Type, SubType, Offset,  Size, Flags
+nvs,      data, nvs,     0x9000,  0x6000,
+phy_init, data, phy,     0xf000,  0x1000,
+factory,  app,  factory, 0x10000, 2000K,

components/iperf_menu/example/sdkconfig.defaults

@@ -0,0 +1,33 @@
+# NOTE: because this uses iperf, we have to use a larger min flash size
+CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
+
+# CONFIG_ESP32_WIFI_NVS_ENABLED=n
+
+CONFIG_PARTITION_TABLE_CUSTOM=y
+CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv"
+CONFIG_PARTITION_TABLE_FILENAME="partitions.csv"
+CONFIG_PARTITION_TABLE_OFFSET=0x8000
+CONFIG_PARTITION_TABLE_MD5=y
+
+# Common ESP-related
+#
+CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE=4096
+CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192
+
+# the cli library requires exceptions right now...
+CONFIG_COMPILER_CXX_EXCEPTIONS=y
+
+# for the example:
+CONFIG_FREERTOS_UNICORE=n
+CONFIG_FREERTOS_HZ=1000
+
+CONFIG_ESP_INT_WDT=n
+CONFIG_ESP_TASK_WDT_EN=n
+
+CONFIG_LWIP_ETHARP_TRUST_IP_MAC=n
+CONFIG_LWIP_IRAM_OPTIMIZATION=y
+CONFIG_LWIP_TCPIP_TASK_PRIO=23
+
+CONFIG_IPERF_TRAFFIC_TASK_PRIORITY=23
+CONFIG_IPERF_REPORT_TASK_PRIORITY=24
+CONFIG_COMPILER_OPTIMIZATION_PERF=y