ESP32 Arduino Matter 配网测试指南：MatterCommissionTest 示例深度解析

ESP32 Arduino Matter 配网测试指南MatterCommissionTest 示例深度解析【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32MatterCommissionTest 是 ESP32 Arduino Core 中用于验证 Matter 配网Commissioning全流程的自动化测试示例设备上电后作为 On/Off 灯节点等待接入 Matter 网络配网成功后等待 30 秒自动取消配网Decommission随后进入下一轮配网循环可反复验证配网工作流。本文基于 libraries/Matter/examples/MatterCommissionTest/README.md 与仓库源码完整讲解其支持目标、配置步骤、烧录方法、预期输出、各智能家居平台接入流程与源码级实现原理帮助你快速搭建一套可重复执行的 Matter 配网测试环境。示例概述与核心能力该示例通过一个 On/Off 灯端点On/Off Light Endpoint演示 ESP32 SoC 的 Matter 配网功能覆盖从未配网 → 配网成功 → 30 秒后自动取消配网 → 重新进入配网等待的完整闭环核心特性如下基于 Matter 协议实现的 On/Off 灯设备同时支持 Wi-Fi 与 Thread*两种底层网络连接方式通过 QR 码或手动配对码Manual Pairing Code完成 Matter 配网配网成功 30 秒后自动取消配网实现持续测试循环可接入 Apple HomeKit、Amazon Alexa 与 Google Home 等主流智能家居生态作为验证 Matter 配网工作流的轻量测试工具*Thread 支持需要以 Arduino 作为 ESP-IDF Component 的方式编译工程详见下文底层网络与编译方式小节。示例位于仓库 libraries/Matter/examples/MatterCommissionTest/ 目录由三个文件构成MatterCommissionTest.ino示例主程序README.md使用说明ci.ymlCI 编译配置指定PartitionSchemehuge_app并要求开启CONFIG_ESP_MATTER_ENABLE_DATA_MODEL支持的芯片目标SoCWi-FiThreadBLE 配网状态ESP32✅❌❌完全支持ESP32-S2✅❌❌完全支持ESP32-S3✅❌✅完全支持ESP32-C3✅❌✅完全支持ESP32-C5❌✅✅支持仅 ThreadESP32-C6✅❌✅完全支持ESP32-H2❌✅✅支持仅 Thread配网方式与网络能力说明ESP32 与 ESP32-S2不支持通过低功耗蓝牙BLE配网必须在 sketch 代码中直接提供 Wi-Fi 凭据使设备手动接入网络。ESP32-C6虽然芯片本身支持 Thread但当前仓库中预编译的 ESP32 Arduino Matter 库仅启用了 Wi-Fi。若需要配置为仅 Thread 运行必须以 Arduino 作为 IDF Component 构建工程并禁用 Matter Wi-Fi 站点station功能。ESP32-C5虽然芯片支持 2.4 GHz 与 5 GHz Wi-Fi但当前预编译库仅启用了 Thread。若要配置为 Wi-Fi 运行同样需要以 Arduino 作为 ESP-IDF Component 构建工程并关闭 Thread 网络仅保留 Wi-Fi station。这些能力判定在源码中均有对应实现。例如 libraries/Matter/src/Matter.cpp 中的isBLECommissioningEnabled()会同时检查 SoC 硬件能力SOC_BLE_SUPPORTED与软件配置CONFIG_ENABLE_CHIPOBLE后才返回是否支持 BLE 配网isThreadEnabled()则检查CONFIG_ENABLE_MATTER_OVER_THREAD || CHIP_DEVICE_CONFIG_ENABLE_THREAD宏。硬件要求一块 ESP32 兼容开发板请对照上表选择并确认所选芯片的配网方式BLE 配网或手动 Wi-Fi 凭据软件环境准备前置条件安装 Arduino IDE建议 2.0 或更高版本安装支持 Matter 的 ESP32 Arduino Core即本仓库对应的核心版本安装 ESP32 Arduino 库Matter必选Matter 协议栈封装库Wi-Fi仅 ESP32 与 ESP32-S2 需要其余芯片通过 Matter CHIPoBLE 自动建立 IP 网络无需手动连接 Wi-Fi配置项上传 sketch 前需要修改一处配置——Wi-Fi 凭据当不使用 BLE 配网时必须填写尤其对 ESP32 / ESP32-S2 为强制项const char *ssid your-ssid; // 修改为你的 Wi-Fi SSID const char *password your-password; // 修改为你的 Wi-Fi 密码在 MatterCommissionTest.ino 中这两项定义被#if !CONFIG_ENABLE_CHIPOBLE条件编译包裹只有未启用 CHIPoBLE即芯片不支持 BLE 配网时才需要编译进 Wi-Fi 连接代码从而为支持 BLE 配网的芯片节省 Flash 空间。编译与烧录步骤在 Arduino IDE 中打开MatterCommissionTest.inosketch位于 libraries/Matter/examples/MatterCommissionTest/。从Tools Board菜单选择你的 ESP32 开发板。从Tools Partition Scheme菜单选择Huge APP (3MB No OTA/1MB SPIFFS)。该分区方案对应ci.yml中的fqbn_append: PartitionSchemehuge_app因为 Matter 协议栈体积较大需要大 APP 分区。在Tools菜单中启用Erase All Flash Before Sketch Upload选项首次烧录或芯片上残留旧 Matter 配网信息时尤其重要避免配网状态冲突。通过 USB 将 ESP32 开发板连接到电脑。点击Upload按钮编译并烧录 sketch。预期串口输出sketch 运行后打开 Serial Monitor 并将波特率设为115200。只有 ESP32 与 ESP32-S2 会打印 Wi-Fi 连接过程信息其他目标芯片会使用 Matter CHIPoBLE 自动完成 IP 网络建立。典型输出如下Connecting to your-wifi-ssid ....... Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. Initiate the device discovery in your Matter environment. Commission it to your Matter hub with the manual pairing code or QR code Manual pairing code: 34970112332 QR code URL: https://project-chip.github.io/connectedhomeip/qrcode.html?dataMT%3A6FCJ142C00KA0648G00 Matter Fabric not commissioned yet. Waiting for commissioning. Matter Fabric not commissioned yet. Waiting for commissioning. ... Matter Node is commissioned and connected to the network. Decommissioning in 30 seconds. Matter Node is decommissioned. Commissioning widget shall start over. Matter Node is not commissioned yet. Initiate the device discovery in your Matter environment. ...输出中的关键信息Manual pairing code手动配对码可在不支持扫码时手动输入QR code URL二维码数据链接可打开后扫码完成配网配网成功后打印Matter Node is commissioned and connected to the network.随后 30 秒倒计时后自动取消配网进入下一轮循环。串口输出的源码来源上述输出与 MatterCommissionTest.ino 的loop()逻辑一一对应void loop() { if (!Matter.isDeviceCommissioned()) { Serial.println(Matter Node is not commissioned yet.); Serial.println(Initiate the device discovery in your Matter environment.); Serial.println(Commission it to your Matter hub with the manual pairing code or QR code); Serial.printf(Manual pairing code: %s\r\n, Matter.getManualPairingCode().c_str()); Serial.printf(QR code URL: %s\r\n, Matter.getOnboardingQRCodeUrl().c_str()); while (!Matter.isDeviceCommissioned()) { delay(5000); Serial.println(Matter Fabric not commissioned yet. Waiting for commissioning.); } } Serial.println(Matter Node is commissioned and connected to the network.); Serial.println( Decommissioning in 30 seconds. ); delay(30000); Matter.decommission(); Serial.println(Matter Node is decommissioned. Commissioning widget shall start over.); }loop()的执行流程为先判断是否已配网isDeviceCommissioned()未配网时打印配对码并每 5 秒轮询一次等待配网配网完成后打印确认信息延迟 30 秒后调用Matter.decommission()取消配网随后循环重新开始。使用设备持续测试循环测试循环流程设备按以下四阶段周而复始地运行配网阶段Commissioning Phase设备等待 Matter 配网并在 Serial Monitor 中显示手动配对码与 QR 码 URL。已配网阶段Commissioned Phase配网成功后设备接入 Matter 网络并处于可用状态作为一盏 On/Off 灯。自动取消配网Automatic Decommissioning30 秒后设备自动取消配网。重复Repeat循环重新开始便于你多次测试配网过程。智能家居平台接入使用支持 Matter 的智能家居中枢如 Apple HomePod、Google Nest Hub 或 Amazon Echo在每个测试周期内对设备进行配网。Apple Home打开 iOS 设备上的家庭App点击 添加配件扫描 Serial Monitor 中显示的 QR 码或点击我没有或无法扫描代码手动输入配对码按提示完成设置设备将以 On/Off 灯的形式出现在家庭App 中30 秒后设备自动取消配网测试循环重新开始Amazon Alexa打开 Alexa App依次点击 More Add Device Matter选择Scan QR code或Enter code manually完成设置流程灯设备将出现在 Alexa App 中30 秒后设备自动取消配网测试循环重新开始Google Home打开 Google Home App点击 Set up device New device选择Matter device扫描 QR 码或输入手动配对码按提示完成设置30 秒后设备自动取消配网测试循环重新开始代码结构剖析setup()初始化 Wi-Fi、Matter 端点与协议栈void setup() { Serial.begin(115200); #if !CONFIG_ENABLE_CHIPOBLE // 手动连接 Wi-Fi仅 ESP32 / ESP32-S2 Serial.print(Connecting to ); Serial.println(ssid); WiFi.begin(ssid, password); while (WiFi.status() ! WL_CONNECTED) { delay(500); Serial.print(.); } Serial.println(\r\nWiFi connected); Serial.println(IP address: ); Serial.println(WiFi.localIP()); delay(500); #endif // 初始化至少一个 Matter EndPoint OnOffLight.begin(); // Matter 启动——必须在所有 EndPoint 初始化完成之后调用 Matter.begin(); }其职责可拆解为三步按需连接 Wi-Fi仅当芯片不支持 BLE 配网!CONFIG_ENABLE_CHIPOBLE时执行轮询等待WiFi.status() WL_CONNECTED。初始化端点全局对象MatterOnOffLight OnOffLight;调用OnOffLight.begin()创建 On/Off 灯端点。MatterOnOffLight端点类定义在 libraries/Matter/src/MatterEndpoints/ 目录下与 Matter 标准 On/Off 灯 Cluster 对应。启动 Matter 协议栈Matter.begin()必须在所有端点初始化完成后调用。从 libraries/Matter/src/Matter.cpp 的实现可以看到它内部会校验生命周期状态必须先创建端点才能启动、检查 BLE 配网所需的蓝牙内存是否被释放、在CONFIG_ENABLE_MATTER_OVER_THREAD时设置 OpenThread 平台配置radio mode、nvs 分区等最终调用esp_matter::start(app_event_cb)启动 Matter 核心并在启动前后分别应用设备身份identity配置。loop()配网状态机与自动取消配网loop()已在上文完整给出核心 API 的底层语义如下Matter.isDeviceCommissioned()返回当前设备是否已加入某个 Matter Fabric。源码实现为chip::Server::GetInstance().GetFabricTable().FabricCount() 0即只要设备已加入任一 Fabric 即视为已配网。Matter.getManualPairingCode()/Matter.getOnboardingQRCodeUrl()在 libraries/Matter/src/MatterIdentity.cpp 中实现二者均在Matter.begin()之后才可用源码会在未启动协议栈时打印告警并返回空串配对码在协议栈启动后生成。Matter.decommission()实现为esp_matter::factory_reset()即执行 Matter 层级的工厂复位清空 Fabric 信息使设备恢复到可重新配网的状态从而支撑30 秒一轮的连续测试循环。故障排查配网时设备不可见确认 Wi-Fi 或 Thread 连接已正确配置。配网失败可等待当前周期取消配网后进入下一轮再试另一种方式是擦除 SoC Flash 中的残留配网信息——在 Arduino IDE 中通过Tools Erase All Flash Before Sketch Upload: Enabled启用擦除或直接用命令esptool.py --port PORT erase_flash擦除整片 Flash。无串口输出检查波特率是否为 115200并确认 USB 连接正常。设备不断取消配网这是预期行为——设备在配网成功 30 秒后自动取消配网以支持持续测试循环。底层网络与编译方式补充预编译的 Matter Arduino 库在底层网络上有所取舍当前版本 Wi-Fi 与 Thread 二选一预编译若需变更默认网络类型需以 Arduino 作为 ESP-IDF Component 的方式构建工程在支持 Thread 的芯片如 ESP32-C6/H2上启用 Thread构建工程并启用CONFIG_ENABLE_MATTER_OVER_THREAD同时关闭 Matter Wi-Fi station 功能。在 ESP32-C5 上启用 Wi-Fi构建工程并关闭 Thread 网络仅保留 Wi-Fi station。这种构建方式与仓库中 idf_component_examples/ 下的示例工程结构一致可在 ESP-IDF 组件体系中引用 Arduino Core 并自行配置 sdkconfig 选项。相关 Matter 整体架构与配置说明可参考仓库文档 docs/en/matter/ 目录下的 Matter 系列文档。许可证本示例基于 Apache License, Version 2.0 许可发布与仓库整体 LICENSE 一致见 LICENSE.md。【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考