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

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

【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32

MatterCommissionTest 是 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.yml：CI 编译配置（指定PartitionScheme=huge_app，并要求开启CONFIG_ESP_MATTER_ENABLE_DATA_MODEL）

支持的芯片目标

SoC	Wi-Fi	Thread	BLE 配网	状态
ESP32	✅	❌	❌	完全支持
ESP32-S2	✅	❌	❌	完全支持
ESP32-S3	✅	❌	✅	完全支持
ESP32-C3	✅	❌	✅	完全支持
ESP32-C5	❌	✅	✅	支持（仅 Thread）
ESP32-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 凭据）

软件环境准备

前置条件

1. 安装 Arduino IDE（建议 2.0 或更高版本）
2. 安装支持 Matter 的 ESP32 Arduino Core（即本仓库对应的核心版本）
3. 安装 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 空间。

编译与烧录步骤

1. 在 Arduino IDE 中打开MatterCommissionTest.inosketch（位于 libraries/Matter/examples/MatterCommissionTest/）。
2. 从Tools > Board菜单选择你的 ESP32 开发板。
3. 从Tools > Partition Scheme菜单选择"Huge APP (3MB No OTA/1MB SPIFFS)"。该分区方案对应ci.yml中的fqbn_append: PartitionScheme=huge_app，因为 Matter 协议栈体积较大，需要大 APP 分区。
4. 在Tools菜单中启用"Erase All Flash Before Sketch Upload"选项（首次烧录或芯片上残留旧 Matter 配网信息时尤其重要，避免配网状态冲突）。
5. 通过 USB 将 ESP32 开发板连接到电脑。
6. 点击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?data=MT%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()取消配网，随后循环重新开始。

使用设备：持续测试循环

测试循环流程

设备按以下四阶段周而复始地运行：

1. 配网阶段（Commissioning Phase）：设备等待 Matter 配网，并在 Serial Monitor 中显示手动配对码与 QR 码 URL。
2. 已配网阶段（Commissioned Phase）：配网成功后，设备接入 Matter 网络并处于可用状态（作为一盏 On/Off 灯）。
3. 自动取消配网（Automatic Decommissioning）：30 秒后设备自动取消配网。
4. 重复（Repeat）：循环重新开始，便于你多次测试配网过程。

智能家居平台接入

使用支持 Matter 的智能家居中枢（如 Apple HomePod、Google Nest Hub 或 Amazon Echo）在每个测试周期内对设备进行配网。

Apple Home

1. 打开 iOS 设备上的"家庭"App
2. 点击"+" > "添加配件"
3. 扫描 Serial Monitor 中显示的 QR 码，或
4. 点击"我没有或无法扫描代码"，手动输入配对码
5. 按提示完成设置
6. 设备将以 On/Off 灯的形式出现在"家庭"App 中
7. 30 秒后设备自动取消配网，测试循环重新开始

Amazon Alexa

1. 打开 Alexa App
2. 依次点击 More > Add Device > Matter
3. 选择"Scan QR code"或"Enter code manually"
4. 完成设置流程
5. 灯设备将出现在 Alexa App 中
6. 30 秒后设备自动取消配网，测试循环重新开始

Google Home

1. 打开 Google Home App
2. 点击"+" > Set up device > New device
3. 选择"Matter device"
4. 扫描 QR 码或输入手动配对码
5. 按提示完成设置
6. 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(); }

其职责可拆解为三步：

1. 按需连接 Wi-Fi：仅当芯片不支持 BLE 配网（!CONFIG_ENABLE_CHIPOBLE）时执行，轮询等待WiFi.status() == WL_CONNECTED。
2. 初始化端点：全局对象MatterOnOffLight OnOffLight;调用OnOffLight.begin()创建 On/Off 灯端点。MatterOnOffLight端点类定义在 libraries/Matter/src/MatterEndpoints/ 目录下，与 Matter 标准 On/Off 灯 Cluster 对应。
3. 启动 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