1. 项目概述：为什么我们需要一个专属的吞吐量测试工具？

最近在折腾Seeed Studio的XIAO ESP32-C5这块板子，它最大的亮点就是集成了支持Wi-Fi 6和蓝牙5.0的ESP32-C5芯片。对于物联网开发者来说，Wi-Fi性能，尤其是吞吐量，是评估设备联网能力、数据传输效率和整体项目可行性的核心指标。官方数据很漂亮，但“纸上得来终觉浅”，实际环境中的表现如何？天线设计、固件配置、网络环境，任何一个环节都可能成为瓶颈。

市面上通用的测速工具，比如 iperf ，功能强大，但用在资源受限的嵌入式设备上，往往显得“笨重”。你需要搭建服务器、配置复杂的参数，对于快速验证、批量测试或者集成到自动化流程中并不友好。更重要的是，这些通用工具很难针对特定硬件（如XIAO ESP32-C5的PCB天线特性）或特定应用场景（如低功耗模式下的间歇性数据传输）进行定制化测试。

因此，我决定动手为XIAO ESP32-C5量身打造一个轻量级、高精度的Wi-Fi吞吐量测试工具。这个工具的目标很明确：第一，要能真实、便捷地反映这块板子在各种状态下的网络性能上限；第二，要能融入开发流程，作为硬件选型、天线调试、固件优化的量化依据；第三，代码要清晰、模块化，方便其他开发者复用和扩展。这不仅仅是跑个分，更是深入理解ESP32-C5网络栈和优化项目设计的过程。

2. 工具整体设计与核心思路拆解

2.1 核心需求与方案选型

我们的核心需求是测量XIAO ESP32-C5的Wi-Fi吞吐量，这通常指在特定时间段内成功传输的数据总量，单位是Mbps或MB/s。测试需要分为两个角色： 服务器端（Server） 和 客户端（Client） 。服务器负责接收数据并计算速率，客户端负责发送数据。

方案选型上，我们放弃了在MCU上移植完整 iperf 的想法，因为它过于庞大。我们选择基于ESP-IDF提供的 lwIP （轻量级IP协议栈）和 sockets 接口，自建一个最精简的TCP吞吐量测试程序。TCP协议能保证数据可靠传输，测出的结果更贴近实际应用场景（如文件上传、OTA升级）的表现。为什么不用UDP？UDP虽然开销小，但无法反映网络拥塞控制、重传机制对实际吞吐量的影响，结果可能虚高且不稳定。

工具将设计为双模式：通过编译宏或运行时参数，同一套代码可分别编译为服务器固件或客户端固件。服务器启动后监听指定端口，客户端连接后，双方协商测试参数（如测试时长、数据块大小），然后客户端开始疯狂发送数据，服务器接收并统计。

2.2 系统架构与关键模块

整个工具可以划分为以下几个关键模块：

  1. Wi-Fi连接管理模块 ：负责连接指定的Wi-Fi网络（AP）。这是测试的前提，代码需要处理连接、断开、重连等事件，并确保在测试开始前网络已就绪。
  2. TCP服务器模块 ：实现一个简单的TCP服务器，绑定IP和端口，监听客户端连接。接受连接后，进入测试逻辑。
  3. TCP客户端模块 ：实现TCP客户端，解析服务器地址，发起连接，连接成功后进入测试逻辑。
  4. 测试协议模块 ：这是核心。定义客户端与服务器之间简单的控制协议。例如，连接建立后，客户端先发送一个包含 测试时长 和 数据块大小 的协议头，服务器确认后，回复一个开始信号，随后正式数据流才开始。这避免了TCP连接缓冲区的干扰，确保计时准确。
  5. 数据吞吐引擎模块 ：负责实际的数据发送和接收。发送端循环构造数据块并调用 send() ；接收端循环调用 recv() 并累加字节数。需要高精度计时器（如 esp_timer ）来记录精确的测试时间。
  6. 统计与输出模块 ：计算平均吞吐量、瞬时速率，并将结果通过串口打印出来，格式清晰，便于记录和分析。

注意：在嵌入式环境中，要特别注意任务堆栈大小。数据发送/接收循环是性能关键路径，应放在高优先级的任务中执行，并避免在循环内进行耗时的打印操作，以免影响吞吐量测量准确性。

3. 核心细节解析与实操要点

3.1 Wi-Fi连接的最佳实践与稳定性保障

吞吐量测试对网络稳定性要求极高。一个波动大的连接会导致结果毫无参考价值。在ESP-IDF中配置Wi-Fi，有几个关键点：

配置阶段： 

// 初始化底层TCP/IP栈和事件循环
ESP_ERROR_CHECK(esp_netif_init());
ESP_ERROR_CHECK(esp_event_loop_create_default());

// 创建Station模式的网络接口
esp_netif_t *sta_netif = esp_netif_create_default_wifi_sta();
assert(sta_netif);

// Wi-Fi初始化配置
wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
ESP_ERROR_CHECK(esp_wifi_init(&cfg));

// 注册Wi-Fi事件处理函数，用于处理连接、断开等事件
ESP_ERROR_CHECK(esp_event_handler_instance_register(WIFI_EVENT, ESP_EVENT_ANY_ID, &wifi_event_handler, NULL, NULL));
ESP_ERROR_CHECK(esp_event_handler_instance_register(IP_EVENT, IP_EVENT_STA_GOT_IP, &got_ip_event_handler, NULL, NULL));

// 设置Station模式配置
wifi_config_t wifi_config = {
    .sta = {
        .ssid = CONFIG_WIFI_SSID, // 从menuconfig或代码中读取
        .password = CONFIG_WIFI_PASSWORD,
        .threshold.authmode = WIFI_AUTH_WPA2_PSK, // 最低认证模式
        .pmf_cfg = {
            .capable = true,
            .required = false // 根据AP要求调整
        },
    },
};
ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA));
ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_STA, &wifi_config));
ESP_ERROR_CHECK(esp_wifi_start());

实操心得：

  • 电源与天线 ：XIAO ESP32-C5板载天线性能受周围金属物体影响大。测试时，务必让设备远离大型金属机箱、显示器背板等。如果条件允许，可以外接一个IPEX接口的优质天线进行对比测试，这能帮你判断板载天线设计是否成为瓶颈。
  • 信道选择 ：使用Wi-Fi分析仪APP，找一个相对空闲的信道（如1, 6, 11）进行测试，避免同频干扰。最好将测试用的路由器AP也固定在这个信道。
  • PMF（保护管理帧） ：对于较新的路由器，可能需要启用PMF。如果连接不稳定，可以尝试将 pmf_cfg.required 设为 true 。但有些老旧AP不支持，这时设为 false 兼容性更好。
  • 连接等待 ：代码中必须有健全的状态机等待 IP_EVENT_STA_GOT_IP 事件，确保获取到有效IP地址后再启动测试任务。

3.2 高精度吞吐量测量机制

测量吞吐量的原理很简单：(总接收字节数 * 8) / 测试时间。但魔鬼在细节中。

计时器选择 ：不要使用 vTaskDelay 或 gettimeofday ，精度不够。ESP32提供了高精度定时器 esp_timer ，它可以提供微秒级的时间戳。

#include “esp_timer.h”
int64_t start_time, end_time;
start_time = esp_timer_get_time();
// ... 执行测试 ...
end_time = esp_timer_get_time();
double duration_seconds = (double)(end_time - start_time) / 1000000.0;
double throughput_mbps = (total_bytes * 8.0) / duration_seconds / 1000000.0;

数据块与缓冲区 ：

  • 发送端 ：预先分配一个大小可配置（如1KB, 4KB, 16KB）的发送缓冲区，并用伪随机数据填充。每次循环调用 send(socket, buffer, buffer_size, 0) 。 send 的返回值是实际发出的字节数， 必须检查 。在TCP中，它可能小于请求的缓冲区大小，这是因为套接字发送缓冲区已满。这时需要适当延迟（如 vTaskDelay(1) ）或等待可写事件。
  • 接收端 ：同样分配一个足够大的缓冲区循环接收。 recv 的返回值可能小于缓冲区大小，这是正常现象。累加所有 recv 返回的正数值，直到测试时间结束或连接关闭。
  • TCP_NODELAY ：为了减少小数据包的延迟，默认的Nagle算法可能会缓冲数据。对于吞吐量测试，我们希望数据立即发送，可以在建立连接后设置 setsockopt(sock, IPPROTO_TCP, TCP_NODELAY, &enable, sizeof(int)) 。

测试协议设计 ： 为了避免TCP三次握手和慢启动阶段的数据影响统计，我们设计一个简单的握手协议。

  1. 客户端连接服务器。
  2. 客户端发送一个固定大小的“测试配置”结构体（包含 test_duration_sec 和 block_size ）。
  3. 服务器接收并解析配置，回复一个“ACK”字节。
  4. 客户端收到ACK后，等待1秒（让网络平静），然后获取当前时间戳作为 start_time ，并开始疯狂发送数据。
  5. 服务器在收到第一个数据包时，记录自己的 start_time ，然后开始接收统计。
  6. 客户端在达到配置的测试时间后，立即停止发送，并发送一个特殊的“结束标记”短报文。
  7. 服务器收到“结束标记”后，记录 end_time ，计算吞吐量并打印结果，然后关闭连接。

这样能确保双方计时基本同步，且剔除了握手和启动阶段的影响。

4. 实操过程与核心环节实现

4.1 开发环境搭建与项目配置

首先，确保你的开发环境已就绪。我们需要ESP-IDF v5.1或更高版本，以完整支持ESP32-C5。

  1. 安装ESP-IDF ：按照乐鑫官方指南安装ESP-IDF框架。对于XIAO系列，Seeed Studio也提供了详细的入门教程，通常推荐使用VSCode的ESP-IDF扩展，这是最便捷的方式。
  2. 创建项目 ：使用 idf.py create-project xiao_esp32c5_throughput_tester 创建一个新项目，或者直接在我的GitHub仓库（此处假设有，实际写作时可替换为“可以参考附带的示例代码”）中获取基础框架。
  3. 配置项目 ：运行 idf.py menuconfig 进行关键配置：
    • Component config -> ESP32C5-specific ：确保芯片支持已启用。
    • Component config -> LWIP -> TCP ：可以适当增加 TCP_WND （TCP窗口大小）和 TCP_SND_BUF （发送缓冲区大小），例如从默认的5744增加到8760，这有助于提升单连接吞吐量。但注意，增加过多会占用更多内存。
    • Component config -> Wi-Fi ：检查Wi-Fi相关配置，如 Wi-Fi station task stack size ，如果测试任务复杂，可以稍微调大，例如从3072增加到4096。
    • Example Configuration （或你自己的配置菜单）：添加用于设置 WIFI_SSID 、 WIFI_PASSWORD 、 SERVER_IP （客户端模式需要）、 TEST_DURATION 、 BLOCK_SIZE 等参数的选项。这样无需修改代码即可灵活配置。

4.2 服务器端代码实现详解

服务器端的主要任务是监听、接受连接、协商协议、接收数据并统计。

监听与接受连接： 

// 创建TCP socket
int listen_sock = socket(AF_INET, SOCK_STREAM, IPPROTO_IP);
// 设置地址重用，方便调试
int opt = 1;
setsockopt(listen_sock, SOL_SOCKET, SO_REUSEADDR, &opt, sizeof(opt));

// 绑定地址和端口（INADDR_ANY表示本机所有IP）
struct sockaddr_in server_addr;
server_addr.sin_family = AF_INET;
server_addr.sin_port = htons(CONFIG_SERVER_PORT);
server_addr.sin_addr.s_addr = htonl(INADDR_ANY);
bind(listen_sock, (struct sockaddr *)&server_addr, sizeof(server_addr));

// 开始监听
listen(listen_sock, 1); // 等待队列长度为1，我们一次只测一个客户端

// 等待客户端连接
struct sockaddr_in client_addr;
socklen_t addr_len = sizeof(client_addr);
int client_sock = accept(listen_sock, (struct sockaddr *)&client_addr, &addr_len);
ESP_LOGI(TAG, “Client connected from %s”, inet_ntoa(client_addr.sin_addr));

协议协商与数据接收循环： 

// 1. 接收测试配置
test_config_t config;
recv(client_sock, &config, sizeof(config), 0);
ESP_LOGI(TAG, “Test config: duration=%d sec, block size=%d bytes”, config.duration, config.block_size);

// 2. 回复ACK
send(client_sock, “A”, 1, 0);

// 3. 准备接收数据
char *recv_buffer = malloc(config.block_size);
size_t total_bytes = 0;
bool test_started = false;
int64_t start_time = 0, end_time = 0;

while (1) {
    int len = recv(client_sock, recv_buffer, config.block_size, 0);
    if (len > 0) {
        if (!test_started) {
            // 收到第一个数据包，开始计时
            start_time = esp_timer_get_time();
            test_started = true;
        }
        total_bytes += len;
    } else if (len == 0) {
        // 连接正常关闭
        break;
    } else {
        // recv 错误
        ESP_LOGE(TAG, “recv error: errno=%d”, errno);
        break;
    }
    // 检查是否收到结束标记（可以设计为一个特定的小数据包）
    // 这里简化处理：由客户端在固定时间后关闭连接，我们通过计算时间判断结束。
}
end_time = esp_timer_get_time();
// 计算并打印吞吐量...
free(recv_buffer);
close(client_sock);

4.3 客户端代码实现详解

客户端负责发起连接、发送配置、等待确认、然后全力发送数据。

连接与发送循环： 

// 创建socket并连接服务器
int sock = socket(AF_INET, SOCK_STREAM, IPPROTO_IP);
struct sockaddr_in server_addr;
server_addr.sin_family = AF_INET;
server_addr.sin_port = htons(CONFIG_SERVER_PORT);
inet_pton(AF_INET, CONFIG_SERVER_IP, &server_addr.sin_addr);
connect(sock, (struct sockaddr *)&server_addr, sizeof(server_addr));

// 发送测试配置
test_config_t config = {.duration = CONFIG_TEST_DURATION, .block_size = CONFIG_BLOCK_SIZE};
send(sock, &config, sizeof(config), 0);

// 等待服务器ACK
char ack;
recv(sock, &ack, 1, 0);
if (ack != ‘A’) {
    ESP_LOGE(TAG, “Protocol error”);
    close(sock);
    return;
}

// 准备发送缓冲区
char *send_buffer = malloc(config.block_size);
// 填充一些非零数据，避免被压缩
for (int i = 0; i < config.block_size; i++) {
    send_buffer[i] = (char)(i % 256);
}

// 设置TCP_NODELAY
int enable = 1;
setsockopt(sock, IPPROTO_TCP, TCP_NODELAY, &enable, sizeof(enable));

// 等待一秒后开始
vTaskDelay(pdMS_TO_TICKS(1000));
int64_t start_time = esp_timer_get_time();
int64_t deadline = start_time + (config.duration * 1000000);
size_t total_sent = 0;

while (esp_timer_get_time() < deadline) {
    int sent = send(sock, send_buffer, config.block_size, 0);
    if (sent > 0) {
        total_sent += sent;
    } else if (sent < 0) {
        // 处理错误，例如连接中断
        break;
    }
    // 如果sent < config.block_size，说明TCP发送缓冲区满了
    // 在实际高强度测试中，这种情况频繁发生，是限制吞吐量的关键。
    // 可以稍作延迟，但为了测极限，我们选择快速循环再次调用send。
}
// 测试结束，可以选择发送一个结束标记，然后关闭socket
// send(sock, “END”, 3, 0);
close(sock);
free(send_buffer);
// 计算并打印客户端视角的发送速率...

4.4 编译、烧录与双机测试

  1. 编译服务器固件 ：在 menuconfig 中，设置设备为服务器模式（可以定义一个宏如 CONFIG_DEVICE_ROLE_SERVER=y ），配置Wi-Fi信息。然后编译： idf.py build 。
  2. 烧录到设备A ：将服务器固件烧录到第一块XIAO ESP32-C5（设备A）。通过串口监视器，查看其获取到的IP地址，例如 192.168.1.100 。
  3. 编译客户端固件 ：修改配置，设置为客户端模式，并填入服务器IP地址 192.168.1.100 。编译客户端固件。
  4. 烧录到设备B ：将客户端固件烧录到第二块XIAO ESP32-C5（设备B）。
  5. 搭建测试环境 ：将设备A和设备B放置在距离路由器相同且较近的位置，减少信号衰减的影响。确保它们连接到同一个5GHz Wi-Fi网络（ESP32-C5支持Wi-Fi 6，但需路由器支持）。如果测试2.4GHz，需明确配置。
  6. 执行测试 ：先启动设备A（服务器），看到“Server listening on port 5001”的日志。再启动设备B（客户端），它会自动连接并开始测试。观察双方串口日志输出的吞吐量结果。

5. 常见问题与排查技巧实录

在实际测试中，你肯定会遇到各种预期之外的情况。下面是我在多次测试中踩过的坑和总结的排查思路。

5.1 吞吐量远低于理论值

这是最常见的问题。理论值可能高达上百Mbps，但实测只有几十甚至几Mbps。

  • 排查思路1：检查Wi-Fi连接速率 。在服务器或客户端代码中，可以在连接Wi-Fi后，定期调用 esp_wifi_sta_get_ap_info(&ap_info) 来获取 ap_info.rssi （信号强度）和 ap_info.rx_rate / ap_info.tx_rate （协商速率）。如果协商速率很低（比如只有72Mbps），那吞吐量上限就被卡死了。解决方法：确保设备靠近路由器，避开干扰信道，路由器开启Wi-Fi 5/6模式。
  • 排查思路2：发送端被“卡住” 。在客户端的发送循环中，如果 send 函数频繁返回小于缓冲区大小的值（甚至返回 EAGAIN 错误），说明TCP发送缓冲区已满，数据在本地堆积，无法及时发到网络。这往往是吞吐量的主要瓶颈。你可以：
    • 增加 TCP_SND_BUF 大小（在menuconfig的LWIP配置中）。
    • 在代码中动态设置更大的socket发送缓冲区： setsockopt(sock, SOL_SOCKET, SO_SNDBUF, &send_buf_size, sizeof(send_buf_size)); 。
    • 但注意，缓冲区不是越大越好，过大会增加延迟。可以尝试不同的块大小（ BLOCK_SIZE ），例如从1K调到16K，找到最佳点。
  • 排查思路3：任务优先级与系统调度 。确保你的数据发送/接收任务运行在足够高的优先级上（如 configMAX_PRIORITIES-1 ）。避免在测试任务中进行串口打印等阻塞操作，可以将统计信息缓存起来，测试结束后再打印。
  • 排查思路4：电源问题 。USB供电不足可能导致芯片降频或Wi-Fi功率受限。尝试使用质量好的USB线和电源适配器，或者通过XIAO的VIN引脚提供稳定的5V供电。

5.2 测试结果波动巨大，每次差异大

这通常与环境干扰或统计方法有关。

  • 固定变量 ：确保测试环境相对静止，设备位置不变，关闭其他大量占用带宽的设备（如正在下载的电脑、手机）。
  • 延长测试时间 ：将单次测试时长从10秒增加到30秒或60秒，取平均值，可以平滑短期波动。
  • 多次测试取中位数 ：进行5-10次测试，去掉最高和最低值，取中间几次的平均值，结果会更稳定。
  • 检查计时精度 ：确保使用 esp_timer_get_time() ，并且计时起点和终点界定准确（如前述的协议握手方法）。

5.3 连接建立失败或测试中途断开

  • 防火墙/路由器设置 ：确保测试使用的端口（如5001）在服务器端设备的防火墙和路由器上没有被阻止。
  • Wi-Fi断连 ：监控Wi-Fi事件。如果信号太弱，ESP32可能会断线重连。确保 Wi-Fi station 任务堆栈足够，并在代码中处理 WIFI_EVENT_STA_DISCONNECTED 事件，尝试自动重连。但在吞吐量测试期间重连会导致测试失败，所以稳定连接是前提。
  • 内存不足 ：如果 BLOCK_SIZE 设置过大，或者同时分配多个缓冲区，可能导致堆内存不足。监控ESP-IDF的堆内存使用情况 heap_caps_get_free_size(MALLOC_CAP_DEFAULT) ，确保有足够余量。

5.4 服务器与客户端结果不一致

这是正常现象，通常客户端统计的“发送量”会略高于服务器统计的“接收量”。因为：

  1. TCP协议开销 ：客户端发送的数据包含了TCP/IP头，而服务器应用层 recv 到的只是净荷数据。
  2. 网络丢包与重传 ：客户端发送出去的数据包，可能在网络中丢失，客户端TCP栈会重传。客户端统计了重传的数据，而服务器只计算第一次成功接收的。
  3. 计时误差 ：虽然我们尽力同步，但微小的计时误差在高速传输下会被放大。

通常，我们以 服务器端的结果为准 ，因为它反映了实际成功交付到应用层的数据量。两者差值如果过大（比如超过5%），则需要排查网络丢包问题。

5.5 进阶测试场景与工具扩展

基础吞吐量测试跑通后，这个工具可以进一步扩展，用于更深入的性能分析：

  • 双向同时测试 ：修改协议，支持全双工测试，即客户端和服务器同时收发数据，模拟更真实的交互场景。
  • 多连接测试 ：创建多个并发的TCP连接，测试设备在多任务下的总吞吐量和处理能力。
  • 不同功率模式测试 ：在 menuconfig 中调整Wi-Fi的电源模式（如 WIFI_PS_MIN_MODEM ， WIFI_PS_NONE ），测试功耗与性能的权衡。 WIFI_PS_NONE （不休眠）性能最好，但最耗电。
  • UDP吞吐量测试 ：作为对比，可以实现UDP版本。UDP没有重传和拥塞控制，测出的主要是物理层和驱动层的极限速率，通常比TCP结果高，但不可靠。
  • 集成到CI/CD ：将测试脚本化，设备上电自动连接、测试、输出结果，并通过串口或网络上报给主机进行自动化分析和记录。

通过这个自制的吞吐量测试工具，你不仅能得到几个冰冷的数字，更能深入理解ESP32-C5在网络栈处理、缓冲区管理、任务调度等方面的行为，为你的物联网产品选择最合适的网络参数和优化方向打下坚实基础。

Logo
AI硬件创业社区

智能硬件社区聚焦AI智能硬件技术生态，汇聚嵌入式AI、物联网硬件开发者，打造交流分享平台，同步全国赛事资讯、开展 OPC 核心人才招募，助力技术落地与开发者成长。

更多推荐

如何高效解决数据导出难题：NocoDB终极实战指南

你是否曾为数据库数据导出格式单一、操作复杂而烦恼？NocoDB作为一款开源免费的Airtable替代方案，提供了强大的数据导出功能，让你在3分钟内掌握专业级数据导出技巧。本文将为你深入解析NocoDB的CSV和JSON导出功能，通过实战配置和高级技巧，彻底解决数据迁移、备份与共享的痛点。## 数据导出痛点与NocoDB解决方案### 常见数据导出难题- **格式限制**：传统工具仅支持基

avatar AI硬件创业社区

终极解决方案：无VR设备也能畅玩《半条命：Alyx》的完整指南

还在为没有昂贵的VR设备而无法体验《半条命：Alyx》这款VR独占大作而烦恼吗？HLA-NoVR模组为你提供了完美的解决方案！这个革命性的非VR转换模组通过精妙的脚本设计，将原本依赖VR设备的交互体验完美转换为键盘鼠标操作，让普通PC玩家也能享受到这款经典游戏的完整魅力。HLA-NoVR是目前最简单易用且功能最全面的非VR模组，让你无需VR设备就能体验《半条命：Alyx》的全部内容。## 🎮

avatar AI硬件创业社区

ComfyUI-WanVideoWrapper：5分钟掌握AI视频生成全流程

在AI视频生成技术飞速发展的今天，ComfyUI-WanVideoWrapper为创作者提供了一个强大而直观的解决方案。这个开源项目将WanVideo模型的先进功能与ComfyUI的可视化工作流完美结合，让你能够轻松实现从文本到视频、从图像到视频的创意转换。无论你是数字艺术爱好者还是专业内容创作者，都能在这里找到适合自己的AI视频生成工具。## 快速开始：安装与配置### 环境要求开始之

avatar AI硬件创业社区