Matter（connectedhomeip）ESP32 All Clusters Minimal App 从编译到集群控制实战指南

MatterconnectedhomeipESP32 All Clusters Minimal App 从编译到集群控制实战指南【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip导读本文以 examples/all-clusters-minimal-app/esp32/README.md 为骨架系统讲解 Matter 开源 SDK 中面向 ESP32 平台的 All Clusters Minimal 示例应用如何搭建 ESP-IDF 与 Matter 编译环境、如何构建烧录、如何通过 chip-tool 下发 OnOff / LevelControl 集群命令并结合main.cpp、AppTask.cpp、DeviceCallbacks.cpp、Kconfig.projbuild等源码说明命令在设备端的实际执行路径与 LED 状态反馈机制。读完本文你将掌握在 ESP32 系列开发板上跑通一个 Matter 设备端示例并完成集群控制闭环的完整方法。一、示例应用概述All Clusters Minimal App 是 Matter SDK 提供的一个原型示例应用用于验证两类核心能力设备配网Commissioning设备通过 Matter 的配网流程加入 Fabric获得网络凭据并完成安全会话建立集群控制Cluster Control配网完成后由 Controller如 chip-tool向设备端下发集群命令驱动设备上的物理外设LED、屏幕等产生可观察的变化。在 ESP32 平台下该示例对应仓库路径为 examples/all-clusters-minimal-app/esp32工程名在 CMakeLists.txt 中定义为chip-all-clusters-minimal-app。与功能更全的 all-clusters-app 相比Minimal 意味着按需裁剪集群与硬件抽象便于快速验证核心链路。该示例在启动阶段通过app_main()完成以下初始化见 main/main.cpp初始化 NVS 与默认事件循环若启用CONFIG_ENABLE_CHIP_SHELL则注册设备端调试 Shell初始化 Wi-Fi 协议栈ESP32Utils::InitWiFiStack通过CHIPDeviceManager初始化设备管理器注册设备认证凭据默认为示例 DAC或CONFIG_ENABLE_ESP32_FACTORY_DATA_PROVIDER启用工厂数据通过Esp32AppServer::Init()启动 ZCL 数据模型与 CHIP App Server最后创建 AppTask 事件循环。二、环境准备ESP-IDF 与 Matter 环境搭建开始构建前需要一次性完成 ESP-IDF 与 Matter 两套环境。官方指南位于环境搭建docs/platforms/esp32/setup_idf_chip.md构建与配网docs/platforms/esp32/build_app_and_commission.md2.1 安装 ESP-IDF本示例基于 ESP-IDFv5.5.1构建验证克隆并安装git clone -b v5.5.1 --recursive --depth 1 --shallow-submodule https://github.com/espressif/esp-idf.git cd esp-idf ./install.sh若已有旧版 ESP-IDF 工具链可按如下方式升级到 v5.5.1cd path/to/esp-idf git fetch --depth 1 origin v5.5.1 git reset --hard FETCH_HEAD git submodule update --depth 1 --recursive --init git clean -ffdx ./install.sh2.2 Bootstrap Matter 环境在仓库根目录执行以下命令脚本会下载 GN、ninja 并配置构建/测试所需的 Python 环境source scripts/bootstrap.sh -p all,esp32Matter 环境过期时重复执行上述命令即可更新。说明ESP32 平台需要 xtensa-esp32-elfESP32 系列或 riscv-esp32-elfESP32C3 等 RISC-V 芯片工具链ESP-IDF 安装脚本会自动处理VSCode devcontainer 已预装这些组件。三、构建、烧录与监控3.1 激活环境变量打开新终端后依次激活两套环境# 1. ESP-IDF 工具链 cd path/to/esp-idf source export.sh # 2. Matter 环境必须在 export.sh 之后执行 cd path/to/connectedhomeip source scripts/activate.sh # 3. 推荐开启 ccache 加速 IDF 构建 export IDF_CCACHE_ENABLE13.2 设置目标芯片并构建# 进入示例目录 cd examples/all-clusters-minimal-app/esp32 # 设置目标芯片按实际硬件选择 idf.py set-target esp32 # 或 esp32c3 / esp32c6 / esp32s3 / esp32h2 等 # 构建 idf.py build3.3 默认配置与自定义配置默认构建直接使用 sdkconfig.defaults其关键默认项包括配置项默认值作用CONFIG_BT_ENABLED/CONFIG_BT_NIMBLE_ENABLEDy启用 BLE配网通道CONFIG_PARTITION_TABLE_CUSTOMy使用 partitions.csv 自定义分区表内含 ota_0 / ota_1 双 OTA 分区CONFIG_DEVICE_VENDOR_ID0xFFF1Matter 厂商 IDCONFIG_DEVICE_PRODUCT_ID0x8001产品 IDCONFIG_ENABLE_CHIP_SHELLy启用设备端调试 ShellCONFIG_ESPTOOLPY_FLASHSIZE4MB烧录镜像大小CONFIG_LWIP_IPV6_NUM_ADDRESSES6提高 IPv6 地址容量若需为特定开发板构建如 M5Stack可指定 SDKCONFIG_DEFAULTSrm sdkconfig idf.py -D SDKCONFIG_DEFAULTSsdkconfig_m5stack.defaults build示例目录中提供了sdkconfig_c3devkit.defaults、sdkconfig_m5stack.defaults、sdkconfig_m5stack_rpc.defaults等多套板级配置。自定义参数则可运行idf.py menuconfig调整。3.4 烧录与串口监控# 擦除整片 flash首次强烈建议 idf.py -p /dev/ttyUSB0 erase_flash # 烧录并打开监控Linux 下端口如 /dev/ttyUSB0macOS 下如 /dev/tty.usbserial-101 idf.py -p /dev/ttyUSB0 flash monitor退出监控按Ctrl]按CtrltCtrlh可查看监控命令菜单。若设备枚举失败可能需要安装 VCP 驱动。四、集群控制Cluster Control配网完成后可用 chip-tool 作为 Client 向设备端Server发送 Matter 命令。命令格式为运行编译产物传入目标集群名、目标命令名以及端点 ID。Client 发送单个命令包后即退出。4.1 OnOff 集群$ ./out/debug/chip-tool onoff on NODE ID ENDPOINTNODE ID设备被配网时分配的节点 ID如12345ENDPOINT目标端点 ID本示例 OnOff Server 位于端点 1、2。除on外OnOff 集群同样支持off、toggle等标准命令。从源码看本示例同时通过设备端 Shell 暴露了本地触达能力main/ShellCommands.cpp 注册了OnOff on/off/toggle endpoint-id子命令便于在没有 Controller 时直接通过串口调试。4.2 LevelControl 集群Usage: $ ./out/debug/chip-tool levelcontrol move-to-level Level10 TransitionTime0 OptionMask0 OptionOverride0 NODE ID ENDPOINTmove-to-level命令携带四个参数参数示例值含义Level10目标亮度等级0-254TransitionTime0过渡时间单位由集群规范定义0 表示立即切换OptionMask0选项掩码OptionOverride0选项覆盖位4.3 命令在设备端的执行链路命令到达设备后属性变化会触发设备回调。以 main/DeviceCallbacks.cpp 为例PostAttributeChangeCallback依据集群 ID 分发Clusters::OnOff::Id走OnOnOffPostAttributeChangeCallbackClusters::LevelControl::Id走OnLevelControlAttributeChangeCallbackClusters::Identify::Id走 Identify 回调OnOnOffPostAttributeChangeCallback将端点 1/2 的 OnOff 状态映射到statusLED1/statusLED2LEDWidget::SetOnLevelControlAttributeChangeCallback读取CurrentLevel属性后调用SetBrightness调整亮度当 OnOff 状态为关时亮度强制归零若启用CONFIG_LED_TYPE_RMTOnColorControlAttributeChangeCallback还支持 ColorControl 集群的CurrentHue/CurrentSaturation属性见 DeviceCallbacks.cpp。此外Identify 集群注册了gIdentify0/gIdentify1两个端点的实例OnIdentifyTriggerEffect会在kBlink效果时驱动statusLED1.Blink(500ms)DeviceCallbacks.cpp用于配网时在物理设备上定位目标。五、LED 状态反馈与 GPIO 配置本示例的核心演示点是Controller 下发的 OnOff / LevelControl 命令会实时反映到开发板的 LED 上。各板型的表现与配置如下开发板LED 反馈方式默认状态 GPIOSTATUS_LED_GPIO_NUMESP32-DevKitC需外接 LED 至状态 GPIO2板载蓝色 LED1ESP32-WROVER-KIT_V4.1需外接 LED 至状态 GPIO26ESP32C3-DevKitM板载 LED 直接显示命令效果8M5Stack屏幕上的虚拟绿色 LED40各板型默认 GPIO 值定义在 main/Kconfig.projbuildconfig STATUS_LED_GPIO_NUM int range 0 40 default 2 if DEVICE_TYPE_ESP32_DEVKITC # Use LED1 (blue LED) as status LED on DevKitC default 8 if DEVICE_TYPE_ESP32_C3_DEVKITM || ... default 26 if DEVICE_TYPE_ESP32_WROVER_KIT default 40 if DEVICE_TYPE_M5STACK在源码中使用时通过CONFIG_STATUS_LED_GPIO_NUM引用见 main/AppTask.cppstatusLED1.Init(static_castgpio_num_t(CONFIG_STATUS_LED_GPIO_NUM)); // 第二个 LED 未映射到物理引脚仅映射到带屏幕设备的虚拟 LED statusLED2.Init(GPIO_NUM_MAX); bluetoothLED.Init(); wifiLED.Init(); pairingWindowLED.Init();各 LED 语义statusLED1端点 1 的 OnOff / LevelControl 状态反馈statusLED2端点 2 的状态反馈虚拟bluetoothLED配网会话建立/结束时点亮/熄灭见 main.cpp 中AppCallbacks对OnCommissioningSessionStarted/OnCommissioningSessionStopped的处理wifiLEDIPv4 连通性指示DeviceCallbacks.cpppairingWindowLED配网窗口开关指示。设备类型DEVICE_TYPE_*与配网模式Rendezvous ModeSoft-AP / BLE / On-Network均可通过idf.py menuconfig在 Demo 菜单下选择见 Kconfig.projbuild。设备类型选择同时决定HAVE_DISPLAY与 TFT 屏类型配置。六、配网Commissioning与多板型支持6.1 构建独立 chip-tool以 ESP32 示例作为 Server可选用 Python 控制器或独立 chip-tool 作为 Client。独立 chip-tool 的构建方式cd path/to/connectedhomeip scripts/examples/gn_build_example.sh examples/chip-tool out/debug6.2 配网命令Wi-Fi 设备ESP32 / ESP32C3 / ESP32S3 / ESP32C6$ out/debug/chip-tool pairing ble-wifi 12345 MY_SSID MY_PASSWORD 20202021 3840Thread 设备ESP32H2先启动 OpenThread Border Router 获取 active operational dataset再执行$ ./out/debug/chip-tool pairing ble-thread 12345 hex:operational-dataset 20202021 3840以太网设备ESP32-Ethernet-Kit$ out/debug/chip-tool pairing onnetwork 12345 202020216.3 配网参数说明参数值说明Node ID12345可自定义任意节点 IDDiscriminator3840测试用 discriminatorSetup Pin Code20202021测试用 setup pin code如需更换 discriminator 与 setup pin code可启用 ESP32 工厂数据提供器CONFIG_ENABLE_ESP32_FACTORY_DATA_PROVIDER。该配置在 main.cpp 中生效启用后通过SetCommissionableDataProvider/SetDeviceAttestationCredentialsProvider注入ESP32FactoryDataProvider否则回退到示例 DACExamples::GetExampleDACProvider()。6.4 芯片支持范围依据 docs/platforms/esp32/build_app_and_commission.mdMatter 示例应用面向 ESP32-DevKitC、ESP32-WROVER-KIT_V4.1、M5Stack、ESP32C3-DevKitM、ESP32-Ethernet-Kit 与 ESP32S3ESP32H2 / ESP32C6 仅验证了 lighting-app、lit-icd-app 与 all-clusters-app。注意 M5Stack Core 2 的显示屏在 tft 组件中不受支持其余功能不受影响。七、进阶扩展OTA 与 RPC 控制台示例 README 同时指向两条进阶能力完整指南见 docs/platforms/esp32/ota.md 与 docs/platforms/esp32/rpc_console.md。7.1 Matter OTA启用CONFIG_CHIP_OTA_IMAGE_BUILD即可在build目录生成project name-ota.bin配合 OTA Provider 应用下发升级用CONFIG_DEVICE_SOFTWARE_VERSION与CONFIG_DEVICE_SOFTWARE_VERSION_NUMBER设置版本号启用CONFIG_ENABLE_OTA_REQUESTOR使设备具备 OTA 请求方能力配网后可通过 chip-tool 读写default-otaproviders列表再在设备控制台执行matter ota query触发查询。本示例的 partitions.csv 预置了ota_0/ota_1两个 1900K 的 OTA 应用分区与otadata分区为 OTA 升级做好了分区布局准备。7.2 RPC 控制台与设备追踪复用sdkconfig_m5stack_rpc.defaults配置或通过 menuconfig 启用 Pigweed RPC 库同时关闭 CHIP Shell、按板型配置 UART 引脚构建并安装 examples/common/pigweed/rpc_console 后运行chip-console --device /dev/ttyUSB0即可通过 RPC 下发rpcs.chip.rpc.WiFi.Connect(ssid..., secret...)等调用可用于远程调试与控制。八、总结All Clusters Minimal App 是快速上手 Matter ESP32 的最佳切入点之一它用最精简的集群集合OnOff、LevelControl、Identify、ColorControl 等覆盖了构建 → 烧录 → 配网 → 集群控制 → 外设反馈的完整开发闭环。其关键源码位置汇总如下关注点文件应用入口与初始化examples/all-clusters-minimal-app/esp32/main/main.cpp任务与 LED 初始化examples/all-clusters-minimal-app/esp32/main/AppTask.cpp集群属性回调与 LED 映射examples/all-clusters-minimal-app/esp32/main/DeviceCallbacks.cpp设备端 Shell 命令examples/all-clusters-minimal-app/esp32/main/ShellCommands.cpp板型与 GPIO 配置examples/all-clusters-minimal-app/esp32/main/Kconfig.projbuild构建默认配置examples/all-clusters-minimal-app/esp32/sdkconfig.defaultsOTA 分区布局examples/all-clusters-minimal-app/esp32/partitions.csv建议的下一步实践路径先以默认配置在 ESP32-DevKitC 或 ESP32C3-DevKitM 上跑通本章命令随后尝试menuconfig切换设备类型与配网模式最后结合 OTA 与 RPC 控制台深入设备端开发。【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考