Matter CYW30739 Light Switch 示例完整指南：环境搭建、构建烧录与绑定控制实战-创锋一号

Matter CYW30739 Light Switch 示例完整指南：环境搭建、构建烧录与绑定控制实战

【免费下载链接】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

本篇指南以 Matter 开源参考实现（connectedhomeip）仓库中的 CYW30739 Light Switch 示例为核心，完整讲解如何在 Infineon CYW30739 平台上构建、烧录并运行一个基于 Matter 与 ModusToolbox SDK 的开关设备。你将掌握 ModusToolbox 环境配置、GN/Ninja 构建流程、工厂数据（Factory Data）覆盖、恢复模式烧录，以及通过 CHIPTool 完成 BLE + Thread 配网、绑定（Binding）配置、单播与组播命令控制的完整实战方案。文中所有命令与参数均来自 CYW30739 Light Switch README，并结合仓库源码补充实现细节。

示例简介与整体架构

CYW30739 light switch 示例演示了一个基于 Matter 和 Infineon ModusToolbox SDK 构建的开/关（on-off）开关设备。该设备可以接入 OpenThread 网络，并被 Matter 控制器（如 CHIPTool）控制，其核心工作流程如下：

BLE 配网（Commissioning）：CYW30739 设备通过低功耗蓝牙（BLE）广播，与 Matter 控制器执行 Rendezvous 流程，双方交换安全信息。
Thread 入网：配网过程中，控制器将目标 Thread 网络的 active dataset 以及 CASE 凭据下发给设备，设备由此加入 OpenThread 网络。
绑定与控制：配网成功后，控制器通过写入 Binding Cluster 建立设备与目标灯具（如另一块运行 lighting-app 的 CYW30739 设备）之间的绑定关系，此后开关设备即可通过单播（unicast）或组播（group）方式向目标发送 On/Off/Toggle 命令。

该示例的工程组织如下：BUILD.gn 声明了light_switch_app目标，其源码由src/AppShellCommands.cpp、src/AppTask.cpp、src/BindingHandler.cpp、src/ButtonHandler.cpp、src/LightSwitch.cpp、src/ZclCallbacks.cpp组成；args.gni 中配置了默认产品信息（matter_product_id = "0x0005"）并开启了 groupcast 支持（chip_config_enable_groupcast = true）。

安装 ModusToolbox 软件

示例基于 Infineon 的 ModusToolbox 软件构建。请按照官方《ModusToolbox Installation Guide》下载并安装 ModusToolbox（注意：安装指南为外部链接，本文不展开其内容）。

ModusToolbox tools package

按照安装指南完成安装后，ModusToolbox 工具包应自动安装在默认位置（不同操作系统默认位置不同，以安装指南为准）。如果你需要将工具包安装到自定义位置，必须设置环境变量CY_TOOLS_PATHS，指向ModusToolbox/tools_x.x目录：

export CY_TOOLS_PATHS="/path/to/ModusToolbox/tools_x.x"

WSL（Windows Subsystem for Linux）注意事项

如果你使用 WSL，请务必安装ModusToolbox for Linux版本。直接在 WSL 命令行中调用 Windows 版本工具会导致构建过程中的路径解析失败。

拉取仓库、同步子模块与 Bootstrap

在构建示例之前，需要先检出 Matter 仓库并同步子模块，然后执行 bootstrap 初始化构建环境：

$ cd ~/connectedhomeip $ scripts/checkout_submodules.py --platform infineon $ bash scripts/bootstrap.sh -p all,infineon

其中--platform infineon会同步 Infineon 平台所需的子模块与 SDK 依赖；bootstrap.sh -p all,infineon负责安装 Python 依赖并准备编译工具链。

构建示例应用

仓库提供了两种构建方式：

方式一：使用官方封装脚本（推荐）

$ cd ~/connectedhomeip $ scripts/examples/gn_build_example.sh examples/light-switch-app/infineon/cyw30739 out/cyw30739-light-switch

方式二：直接使用 GN/Ninja

$ cd ~/connectedhomeip $ source scripts/activate.sh $ gn gen --root=examples/light-switch-app/infineon/cyw30739 out/cyw30739-light-switch $ ninja -C out/cyw30739-light-switch [light_switch_app-BOARD_NAME]

关于目标名称light_switch_app-BOARD_NAME：从 BUILD.gn 可以看到，示例会针对matter_wpan_sdk_board_list中的每一块板卡生成一个目标，当前支持的板卡为CYW30739B2-P5-EVK-01、CYW30739B2-P5-EVK-02、CYW30739B2-P5-EVK-03。因此完整的 ninja 目标名形如light_switch_app-CYW30739B2-P5-EVK-01。

如需删除生成的可执行文件、库与目标文件，可直接删除输出目录：

$ cd ~/connectedhomeip $ rm -rf out/cyw30739-light-switch

工厂数据（Factory Data）配置

生产构建时，制造商通常需要覆盖默认的工厂数据。CYW30739 示例通过 GN 参数提供了一套完整的覆盖机制，分为四类。

Commissionable Data（配网数据）

Infineon CYW30739 示例默认使用测试用的 passcode、discriminator 与 PAKE 参数。生产构建应通过以下参数覆盖：

matter_passcode
matter_discriminator
matter_pake_iteration_count
matter_pake_salt

$ cd ~/connectedhomeip $ scripts/examples/gn_build_example.sh examples/light-switch-app/infineon/cyw30739 out/cyw30739-light-switch \ 'matter_passcode=20202021' \ 'matter_discriminator=3840' \ 'matter_pake_iteration_count=1000' \ 'matter_pake_salt="U1BBS0UyUCBLZXkgU2FsdA=="'

这些参数直接决定配网阶段的安全性：passcode 用于 PAKE 口令验证，discriminator 用于 BLE 广播过滤，PAKE 迭代次数与盐值影响密钥推导强度。示例默认的 passcode 为20202021、discriminator 为3840，与下文 CHIPTool 配网命令中的参数一一对应。

Device Information（设备信息）

示例支持通过以下参数覆盖默认设备信息：

matter_vendor_name
matter_vendor_id
matter_product_name
matter_product_id
matter_serial_number
matter_hardware_version
matter_hardware_version_string

$ cd ~/connectedhomeip $ scripts/examples/gn_build_example.sh examples/light-switch-app/infineon/cyw30739 out/cyw30739-light-switch \ 'matter_vendor_name="Infineon"' \ 'matter_vendor_id="0x1388"' \ 'matter_product_name="TEST_PRODUCT"' \ 'matter_product_id="0x0001"' \ 'matter_serial_number="TEST_SN"' \ 'matter_hardware_version=30739' \ 'matter_hardware_version_string="30739"'

默认值可在 args.gni 中查看，其默认matter_product_id为0x0005、matter_product_name为"CYW30739 Light-Switch App"；示例的 vendor ID 默认指向0x1388（Infineon 测试 VID）。

DAC / DAC Key / PAI 证书 / Certificate Declaration

示例默认使用 development（开发）证书、密钥与 CD（Certification Declaration）。生产构建可通过以下参数替换：

matter_att_cert
matter_att_cert_password
matter_cd

$ cd ~/connectedhomeip $ scripts/examples/gn_build_example.sh examples/light-switch-app/infineon/cyw30739 out/cyw30739-light-switch \ 'matter_att_cert="/path/to/att_cert.p12"' \ 'matter_att_cert_password="password"' \ 'matter_cd="/path/to/cd.der"'

其中matter_att_cert为包含 DAC 私钥与证书的 PKCS#12 文件（matter_att_cert_password为该文件的密码），matter_cd为证书声明 DER 文件。示例默认的开发 DAC 位于 examples/platform/infineon/credentials/development/attestation/Matter-Development-DAC-1388-0005.p12（见 args.gni）。

使用预置的 Optiga Trust M 安全芯片

对于支持 Optiga Trust M 的板卡，CYW30739 默认会将工厂数据预置到 Optiga Trust M 中，便于开发调试。而量产板上的 Optiga Trust M 应自带已预置的工厂数据。为了确保其最优使用，请通过以下参数配置 Optiga：

use_provisioned_optiga
optiga_dac_object_id
optiga_dac_key_object_id
optiga_pai_cert_object_id

$ cd ~/connectedhomeip $ scripts/examples/gn_build_example.sh examples/light-switch-app/infineon/cyw30739 out/cyw30739-light-switch \ 'optiga_dac_object_id="0xe0e0"' \ 'optiga_dac_key_object_id="0xe0f0"' \ 'optiga_pai_cert_object_id="0xe0e8"'

开发者必须将上述 object ID 设置为与 Optiga 预置流程中实际使用的配置值一致，否则设备将无法从安全芯片中正确加载证书与密钥。

烧录应用（Flashing）

进入恢复模式（Recovery Mode）

运行烧录脚本前，需要先将 CYW30739 板卡置于恢复模式：

按住板上的RECOVERY按钮；
同时按住RESET按钮；
释放RESET按钮；
等待一秒钟后，释放RECOVERY按钮。

运行烧录脚本

构建完成后，输出目录中会生成形如light_switch_app-BOARD_NAME.flash.py的烧录脚本（BOARD_NAME对应实际板卡名），在命令行中执行：

$ cd ~/connectedhomeip $ out/cyw30739-light-switch/light_switch_app-BOARD_NAME.flash.py --port <port>

其中<port>为连接板卡的串口/调试端口。

运行完整示例

前置条件

OpenThread Border Router：假设你已配置并运行了一个 OpenThread border router。若尚未配置，请参考仓库内指南 docs/platforms/openthread/openthread_border_router_pi.md，其中说明了如何在树莓派上搭建 border router。
第二块 CYW30739 设备：本示例需要另一块运行lighting app（灯具）示例的 CYW30739 设备，并已配网加入同一个 OpenThread 网络，作为开关命令的目标设备。

板载交互与 App Shell 命令

当 CYW30739 设备运行 light switch 示例时：

按下 USER 按钮：向绑定的灯具发送 Toggle 命令（源码实现在 ButtonHandler.cpp，单击触发LightSwitch::InitiateActionSwitch(LightSwitch::Action::Toggle)，长按则触发工厂复位）。
LED1：指示当前按钮/开关状态。
OnOff Cluster：以下为应用 shell 命令（注册逻辑见 AppShellCommands.cpp）：

本地控制（操作开关设备自身 LED1）

switch local on : 点亮 light-switch 设备 LED1 switch local off : 熄灭 light-switch 设备 LED1 switch local toggle : 翻转 light-switch 设备 LED1

单播控制（向绑定的灯具发送命令）

switch onoff on : 向绑定设备发送单播 On 命令 switch onoff off : 向绑定设备发送单播 Off 命令 switch onoff toggle : 向绑定设备发送单播 Toggle 命令

组播控制（向绑定的组发送命令）

switch groups onoff on : 向绑定组发送 On 组命令 switch groups onoff off : 向绑定组发送 Off 组命令 switch groups onoff toggle : 向绑定组发送 Toggle 组命令

从 AppShellCommands.cpp 还可以看到一组调试命令，可辅助验证绑定配置：

switch debug table : 打印绑定表 switch debug bleadv start|stop : 启动/停止 BLE 广播 switch debug bind_group [fabric] [group] [cluster] : 手动写入组绑定 switch debug bind_unicast [fabric] [node] [endpoint] [cluster] : 手动写入单播绑定 switch debug brightness [0-254] : 修改亮度（Level Control）

使用 CHIPTool 配置单播绑定

第一步：BLE + Thread 配网

chip-tool pairing ble-thread 1 hex:<operationalDataset> 20202021 3840

20202021与3840即默认的 passcode 与 discriminator（若构建时覆盖了这些值，此处需保持一致）。

第二步：写入 ACL（Access Control List）

chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [<chip-tool-node-id>], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": [<light-switch-node-id>], "targets": [{"cluster": 6, "endpoint": 1, "deviceType": null}]}]' <lighting-node-id> 0

第三步：写入 Binding 表

chip-tool binding write binding '[{"fabricIndex": 1, "node": <lighting-node-id>, "endpoint": 1, "cluster": 6}]' <light-switch-node-id> 1

其中 cluster 6 为 OnOff Cluster。以下为配网成功后lighting-node-id = 1、light-switch-node-id = 2时的完整示例：

chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": [2], "targets": [{"cluster": 6, "endpoint": 1, "deviceType": null}]}]' 1 0 chip-tool binding write binding '[{"fabricIndex": 1, "node": 1, "endpoint": 1, "cluster": 6}]' 2 1

使用 CHIPTool 配置组播（Groups）绑定

第一步：配网

chip-tool pairing ble-thread 1 hex:<operationalDataset> 20202021 3840

配网成功后，仍以 lighting 设备（node 1）与 light-switch 设备（node 2）为例，依次执行以下命令配置组密钥、组映射与 ACL：

chip-tool groupkeymanagement key-set-write '{"groupKeySetID": 417, "groupKeySecurityPolicy": 0, "epochKey0":"a0a1a2a3a4a5a6a7a8a9aaabacadaeaf", "epochStartTime0": 1110000,"epochKey1":"b0b1b2b3b4b5b6b7b8b9babbbcbdbebf", "epochStartTime1":1110001,"epochKey2":"c0c1c2c3c4c5c6c7c8c9cacbcccdcecf", "epochStartTime2": 1110002 }' 1 0 chip-tool groupkeymanagement write group-key-map '[{"groupId": 257, "groupKeySetID": 417, "fabricIndex": 1}]' 1 0 chip-tool groups add-group 257 demo 1 1 chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": null, "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 3, "subjects": [257], "targets": null}]' 1 0 chip-tool groupkeymanagement key-set-write '{"groupKeySetID": 417, "groupKeySecurityPolicy": 0, "epochKey0":"a0a1a2a3a4a5a6a7a8a9aaabacadaeaf", "epochStartTime0": 1110000,"epochKey1":"b0b1b2b3b4b5b6b7b8b9babbbcbdbebf", "epochStartTime1":1110001,"epochKey2":"c0c1c2c3c4c5c6c7c8c9cacbcccdcecf", "epochStartTime2": 1110002 }' 2 0 chip-tool groupkeymanagement write group-key-map '[{"groupId": 257, "groupKeySetID": 417, "fabricIndex": 1}]' 2 0 chip-tool groups add-group 257 demo 2 1 chip-tool binding write binding '[{"fabricIndex": 1, "group": 257}]' 2 1

上述流程在 lighting 设备与 light-switch 设备上分别写入相同的 GroupKeySet（ID 417）与 group-key-map，将 group 257 映射到该密钥集，并将 257 加入名为demo的组。ACL 中"authMode": 3, "subjects": [257]表示允许组 257 以 Manage 权限访问。

配网成功后，也可以使用测试命令TestGroupDemoConfig快速完成组配置：

chip-tool tests TestGroupDemoConfig --nodeId <light-switch-node-id> chip-tool tests TestGroupDemoConfig --nodeId <lighting-node-id> chip-tool binding write binding '[{"fabricIndex": 1, "group": 257}]' <light-switch-node-id> 1

以light-switch-node-id = 2、lighting-node-id = 1为例：

chip-tool tests TestGroupDemoConfig --nodeId 2 chip-tool tests TestGroupDemoConfig --nodeId 1 chip-tool binding write binding '[{"fabricIndex": 1, "group": 257}]' 2 1

同时支持单播与组播

如需同时支持单播与组播命令，可执行上述组配置命令，并将最后一条 binding 命令替换为同时包含组绑定与单播绑定的条目：

chip-tool binding write binding '[{"fabricIndex": 1, "group": 257},{"fabricIndex": 1, "node": <lighting-node-id>, "endpoint": 1, "cluster":6} ]' <light-switch-node-id> 1

获取 chip-tool 的 Node ID

配网完成后，可通过读取 ACL 表获取 chip-tool 自身的节点 ID：

chip-tool accesscontrol read acl <nodeid> 0

源码级原理：绑定（Binding）机制如何工作

示例的绑定机制是理解整个控制链路的钥匙。从 BindingHandler.cpp 可以还原出完整调用链：

初始化：BindingHandler::Init()通过DeviceLayer::PlatformMgr().ScheduleWork调度InitInternal，内部调用Binding::Manager::GetInstance().Init(...)完成绑定管理器初始化，并注册LightSwitchChangedHandler与LightSwitchContextReleaseHandler回调（见 BindingHandler.cpp）。
动作分发：用户按下按钮或执行 shell 命令后，LightSwitch::InitiateActionSwitch构造BindingData（包含 EndpointId、ClusterId、CommandId、IsGroup），调度SwitchWorkerHandler调用NotifyBoundClusterChanged（见 LightSwitch.cpp）。
绑定表查询与命令发送：LightSwitchChangedHandler根据绑定条目类型分派：单播绑定（MATTER_UNICAST_BINDING）通过Controller::InvokeCommandRequest建立 CASE 安全会话后向目标节点发送命令；组播绑定（MATTER_MULTICAST_BINDING）通过Controller::InvokeGroupCommandRequest向组发送命令（见 BindingHandler.cpp）。其中 OnOff Cluster 支持 On/Off/Toggle，LevelControl Cluster 支持 MoveToLevel（亮度调节），Identify Cluster 支持属性读取。
会话恢复：若命令响应超时（CHIP_ERROR_TIMEOUT），OnInvokeCommandFailure会尝试重建 CASE 会话并重传命令（见 BindingHandler.cpp），提升网络切换场景下的控制可靠性。

这也解释了上文 CHIPTool 配置中为何需要同时写入 ACL（授权开关设备访问 OnOff Cluster）与 Binding 表（记录目标节点/组与集群关系）：ACL 决定“能不能发”，Binding 决定“发给谁、发什么”。

常见问题排查要点

WSL 下构建失败（路径解析错误）：确认安装的是 ModusToolbox for Linux 而非 Windows 版本，并正确设置CY_TOOLS_PATHS。
烧录前未进入恢复模式：务必按顺序执行 RECOVERY/RESET 的组合操作，否则flash.py可能无法识别设备。
配网失败：确认 CHIPTool 的ble-thread命令中的 passcode/discriminator 与构建时设置的matter_passcode/matter_discriminator一致（默认20202021/3840）。
绑定后命令无响应：确认已写入 ACL（使用chip-tool accesscontrol read acl <nodeid> 0核查），并确认目标灯具已加入同一 Thread 网络；同时可通过switch debug table查看开关设备的绑定表是否正确写入。
组播不可用：组播控制依赖 Group Key Management 与 group-key-map 的正确配置，且示例需以chip_config_enable_groupcast = true构建（该选项在 args.gni 中默认开启）。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析