在 ESP32 上自动化 Wi-Fi 配网测试

# 在 ESP32 上自动化 Wi-Fi 配置测试 来源：https://groundrun.io/blog/automating-wi-fi-setup-testing-on-the-esp32/ 客户拿到新的 Wi-Fi 联网产品后做的第一件事就是完成 Wi-Fi 配置，所以它必须足够可靠，无论产品其他部分如何变化都要每次都成功。 这件事我们可以借助 Groundrun 系统来完成。让我们开始搭建。 ## 搭建 首先我们需要将硬件接入测试环路，方式与之前对 ESP32 进行 OTA 更新测试（https://groundrun.io/blog/we-broke-an-over-the-air-update-on-the-esp32-on-purpose/）时相同。这次测试我们使用的是来自 Espressif（https://www.espressif.com/）的 ESP32-C6（https://www.espressif.com/en/products/socs/esp32-c6）开发板。借助 Groundrun，把它接入测试环路非常简单：我们只需要这样做： Android 手机，Groundrun 测试台，ESP32-C6 开发板——一块 ESP32-C6 开发板和一部 Android 手机，都通过 USB 连接到 Groundrun 测试台。 1. 通过 USB 将 ESP32-C6 开发板连接到 Groundrun 测试台。 2. 通过 USB 将一部 Android 手机连接到同一台 Groundrun 测试台。 就这样。 ## Wi-Fi 配网 在联网设备上配置 Wi-Fi 网络有多种方式，而 ESP32（https://www.espressif.com/en/products/socs/esp32）系列支持其中多种： - **蓝牙。**手机通过蓝牙低功耗（BLE）与开发板配对，并直接将网络名称和密码发送给它。 - **Soft AP。**开发板启动自己的临时 Wi-Fi 网络，手机加入该网络并发送真实的凭据，随后开发板切换到正式网络。 - **Wi-Fi 强制门户（Captive Portal）。**同样是 Soft AP 网络，但手机会被直接重定向到一个网页来输入凭据，就像酒店或机场的 Wi-Fi 登录页面一样。无需安装任何 App。 - **SmartConfig。**这是 Espressif 自有的技术，在 ESP32 上以 ESPTouch v2 运行，内置于他们的 ESP-IDF SDK（https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_smartconfig.html）中。手机保持连接在家庭网络上，并以编码数据包流的形式广播凭据；尚未连接任何网络的开发板通过监听模式接收这些数据包。 - **WPS（Wi-Fi Protected Setup）。**Wi-Fi 联盟的行业标准。按下路由器上的按钮，开发板即可自动加入网络，直接与路由器协商凭据。 我们的目标是对这五种方式全部进行测试。 > 手机保持连接在家庭网络上，并以编码数据包流的形式广播凭据；尚未连接任何网络的开发板通过监听模式接收这些数据包。 ## 智能手机 App 通常情况下，你已经有一个现成的智能手机 App。在我们的案例中，我们需要一个简单的东西，仅用于演示如何连接 Wi-Fi，因此我们让 Claude 开发了一个快速的 App。它只需要在正确的时机为每种方法发送正确的字节数据，仅此而已。App 不需要好看，而它确实也不好看。 > App 不需要好看，而它确实也不好看。 App 的主界面：纯白背景上排列着五个紫色按钮，每种 Wi-Fi 配网方式一个，分别标注为 BLE 配置、BLE + 二维码配置、SmartConfig、SoftAP 配置和强制门户。App 主界面，每种机制对应一个按钮。 ## 固件 对于现有的联网产品，固件早已写好。在我们的案例中，我们需要遵循让 AI 开发工具理解固件的最佳实践（参见如何在联网产品开发中开始使用 AI 编码代理（https://groundrun.io/blog/how-to-start-using-ai-agents-in-connected-product-development/)）。 我们让 Claude 为我们开发固件代码。Groundrun 系统在这里帮了大忙，它提供了处理 ESP32 固件所需的技能，最终我们得到了实现上述每一种 Wi-Fi 配网机制的代码文件。 由于 Claude Code 可以访问测试台及其硬件，它可以独立完成这项工作。我们只需提供计划、目标和停止条件，它就知道该朝什么方向努力以及何时停止。 最终的固件代码如下（这是 WPS 机制的实现）： ```c void app_main(void) { ESP_ERROR_CHECK(nvs_flash_init()); ESP_ERROR_CHECK(esp_netif_init()); ESP_ERROR_CHECK(esp_event_loop_create_default()); esp_netif_t *sta_netif = esp_netif_create_default_wifi_sta(); assert(sta_netif); wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT(); ESP_ERROR_CHECK(esp_wifi_init(&cfg)); ESP_ERROR_CHECK(esp_event_handler_register(WIFI_EVENT, ESP_EVENT_ANY_ID, &wifi_event_handler, NULL)); ESP_ERROR_CHECK(esp_event_handler_register(IP_EVENT, IP_EVENT_STA_GOT_IP, &got_ip_event_handler, NULL)); ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA)); /* 在启动驱动程序之前，先读取 esp_wifi 自身配置存储中已有的 * Wi-Fi 凭据（WIFI_STORAGE_FLASH，默认值，由 NVS 支撑）。 * 刚做过批量擦除的板子上没有凭据；而已经完成过一次 WPS 并重启 * 过的板子上则有。 */ wifi_config_t stored_config; memset(&stored_config, 0, sizeof(stored_config)); esp_err_t get_config_err = esp_wifi_get_config(WIFI_IF_STA, &stored_config); bool has_stored_creds = (get_config_err == ESP_OK) && (stored_config.sta.ssid[0] != '\0'); ESP_ERROR_CHECK(esp_wifi_start()); if (has_stored_creds) { esp_wifi_connect(); } else { start_wps(); } } ``` ## 搭建用户流程 这里的用户流程很简单：用户打开 App，输入 Wi-Fi 密码，ESP32 加入网络。具体细节因方式而异，因此五种方式各自有一条独立的流程路径，在 Groundrun 的流程构建器中逐步编写出来。 Claude 借助 Groundrun 的技能集完成了这些映射，每条流程都是 Claude Code 可以自行再次运行的。 ## 运行测试 现在一切就绪，我们可以运行 Wi-Fi 配置流程了——既可以在 Groundrun 协调器中交互式运行，也可以作为持续集成（CI）回归测试运行。 每次代码变更我们都会运行回归测试：无论系统中做了什么改动，这部分都必须保持稳固。 一次自动化回归运行，显示强制门户配置、WPS 配置、蓝牙配置、SmartConfig 配置和 SoftAP 配置均为绿色对勾，旁边是更新相关的场景。回归测试套件，五种 Wi-Fi 配置方法全部通过，与同一流水线中运行的更新场景并列。 这些回归运行还包含了我们在故意破坏 ESP32 的 OTA 更新（https://groundrun.io/blog/we-broke-an-over-the-air-update-on-the-esp32-on-purpose/)）一文中讨论过的 OTA 更新测试。 ## 耗时 每次 CI 运行都会自动计时，协调器会分别记录每个步骤，这样我们就可以按耗时环节进行拆解分析：烧录固件、安装并启动 App、运行配网机制本身，以及等待板子确认已加入网络。 Flash + 启动、App 安装/启动、AP 设置、机制、等待确认、拆除，各阶段耗时图。图中还显示了蓝牙配置平均耗时 101 秒，蓝牙方式 124 秒，Soft AP 63 秒，强制门户 74 秒，SmartConfig 45 秒，WPS 方式耗时未显示。各方法按阶段拆分的平均场景耗时。 图表显示，除 SmartConfig 外，各方法的烧录和启动耗时基本相同，约 22 到 24 秒。SmartConfig 还需要烧录第二块开发板用于监听其广播，使该阶段耗时达到 37 秒。除此之外，机制阶段的耗时在各方法之间差异很大，值得单独进行比较。 0s 到 90s 的刻度，蓝牙配置 53 秒，Soft AP 77 秒，强制门户 38 秒，SmartConfig 11 秒，WPS 6 秒。仅机制步骤的平均耗时。 单独看机制步骤的耗时，Soft AP 的机制耗时几乎是 WPS 的十三倍，这与它需要系统对话框和多屏流程的特点相符。SmartConfig 和 WPS 都在 15 秒以内，明显低于蓝牙、Soft AP 和强制门户。 ## 特殊现象 将五种方式并排测试后，我们发现了它们之间的真实差异。 强制门户是五种中最棘手的。手机显示的登录页面只保持打开几秒钟，而这个页面何时关闭完全由手机自身的操作系统决定。整个表单必须在这个时间窗口内填写完成并提交，否则凭据永远无法到达开发板。 蓝牙和 Soft AP 在手机加入开发板网络之前都会触发一个系统弹窗，而手机在扫描开发板时，这个弹窗可能需要几秒钟才能出现。我们的测试会等待这个弹窗。 WPS 完全不需要 App。一旦有人按下按钮，路由器和开发板就会直接交换凭据。 在我们的测试中，SmartConfig 的运行速度明显慢于其他四种方式，偶尔会慢得多，而且偶尔会出现无法归结到单一原因的罕见失败。 测试 WPS 也意味着我们自己要充当路由器的角色。测试台会启动自己的临时 Wi-Fi 网络，并固定在 2.4 GHz 频段（因为开发板的无线电支持不到 5 GHz），每次运行结束后再将其拆除。 ## 结论 任何支持 Wi-Fi 的联网产品，用户做的第一件事都是配置 Wi-Fi，因此它必须是系统中最稳固的机制。 Groundrun 系统让我们能够在硬件在环的情况下，为此机制搭建用户流程和自动化测试。 --- 了解 Groundrun 如何在硬件在环场景下运行，请查看平台概览（https://groundrun.io/platform/)）。