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 配网CommissioningCYW30739 设备通过低功耗蓝牙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.xWSLWindows 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 --rootexamples/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_passcodematter_discriminatormatter_pake_iteration_countmatter_pake_salt$ cd ~/connectedhomeip $ scripts/examples/gn_build_example.sh examples/light-switch-app/infineon/cyw30739 out/cyw30739-light-switch \ matter_passcode20202021 \ matter_discriminator3840 \ matter_pake_iteration_count1000 \ matter_pake_saltU1BBS0UyUCBLZXkgU2FsdA这些参数直接决定配网阶段的安全性passcode 用于 PAKE 口令验证discriminator 用于 BLE 广播过滤PAKE 迭代次数与盐值影响密钥推导强度。示例默认的 passcode 为20202021、discriminator 为3840与下文 CHIPTool 配网命令中的参数一一对应。Device Information设备信息示例支持通过以下参数覆盖默认设备信息matter_vendor_namematter_vendor_idmatter_product_namematter_product_idmatter_serial_numbermatter_hardware_versionmatter_hardware_version_string$ cd ~/connectedhomeip $ scripts/examples/gn_build_example.sh examples/light-switch-app/infineon/cyw30739 out/cyw30739-light-switch \ matter_vendor_nameInfineon \ matter_vendor_id0x1388 \ matter_product_nameTEST_PRODUCT \ matter_product_id0x0001 \ matter_serial_numberTEST_SN \ matter_hardware_version30739 \ matter_hardware_version_string30739默认值可在 args.gni 中查看其默认matter_product_id为0x0005、matter_product_name为CYW30739 Light-Switch App示例的 vendor ID 默认指向0x1388Infineon 测试 VID。DAC / DAC Key / PAI 证书 / Certificate Declaration示例默认使用 development开发证书、密钥与 CDCertification Declaration。生产构建可通过以下参数替换matter_att_certmatter_att_cert_passwordmatter_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_passwordpassword \ 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 应自带已预置的工厂数据。为了确保其最优使用请通过以下参数配置 Optigause_provisioned_optigaoptiga_dac_object_idoptiga_dac_key_object_idoptiga_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_id0xe0e0 \ optiga_dac_key_object_id0xe0f0 \ optiga_pai_cert_object_id0xe0e8开发者必须将上述 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本地控制操作开关设备自身 LED1switch 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 384020202021与3840即默认的 passcode 与 discriminator若构建时覆盖了这些值此处需保持一致。第二步写入 ACLAccess Control Listchip-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为例依次执行以下命令配置组密钥、组映射与 ACLchip-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 设备上分别写入相同的 GroupKeySetID 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 自身的节点 IDchip-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/ToggleLevelControl Cluster 支持 MoveToLevel亮度调节Identify Cluster 支持属性读取。会话恢复若命令响应超时CHIP_ERROR_TIMEOUTOnInvokeCommandFailure会尝试重建 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 中默认开启。【免费下载链接】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），仅供参考