Matter darwin-framework-tool 使用指南基于 Apple 框架的 Matter 调试与控制工具【免费下载链接】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本文以 connectedhomeipMatter SDK仓库中的 darwin-framework-tool 示例应用为主题系统讲解该工具的构建、设备配对Commissioning、Matter 命令发送、交互式模式以及 OTA 软件更新调试等核心能力。darwin-framework-tool 是一款面向 macOS 开发者、直接基于 Apple 官方Matter.framework即MTR*Objective-C API编写的命令行工具可用于在开发阶段对任意 Matter 服务端设备进行配对、读取属性、发送命令与测试 OTA 流程。读完本文你将掌握从源码构建该工具、通过 IP 配对设备、查询 cluster/命令/属性帮助信息以及驱动 OTA Provider 端行为的具体操作方案。工具概述darwin-framework-tool 是 examples/darwin-framework-tool 目录下的一个示例应用其作用是通过 Matter 向一台 Matter 服务端server发送消息。与仓库中基于 C 编写的 chip-tool 不同它使用 Apple 的Matter.framework公开 APIMTRDevice、MTRDeviceController、MTRSetupPayload等因此是了解如何在自家 macOS/iOS 应用中以 Apple 官方框架操作 Matter的最直接参考实现。源代码入口main.mm 中通过registerCommandsBdx、registerCommandsPairing、registerCommandsDiscover、registerCommandsInteractive、registerClusterOtaSoftwareUpdateProviderInteractive、registerClusters等一系列注册函数将配对、发现、交互、OTA 与集群命令统一挂载到一个命令分发器上执行。构建产物编译后得到一个名为darwin-framework-tool的命令行可执行文件所有交互都通过命令行参数完成。平台限制由于依赖 Apple 的Matter.framework、CoreBluetooth.framework、Network.framework等系统框架见 BUILD.gn该工具仅在 macOS 上构建与运行。重要前置条件darwin-framework-tool 必须使用 Apple 开发者签名证书进行签名code signing相关要求可参阅 docs/guides/BUILDING.md 中关于构建前置条件Prerequisites的部分以及 Apple 官方 Code Signing 文档。构建示例应用构建前请先按 docs/guides/BUILDING.md 完成通用构建前置条件准备安装 Xcode、执行source scripts/activate.sh初始化 GN/ninja 与 Python 环境。构建命令十分直接使用仓库提供的 GN 构建脚本scripts/examples/gn_build_example.sh examples/darwin-framework-tool SOME-PATH/执行完成后可执行文件将输出到SOME-PATH/darwin-framework-tool。从构建脚本 BUILD.gn 可以补充了解以下构建细节构建目标为executable(darwin-framework-tool)源码集合包含main.mm、commands/common/CHIPCommandBridge.mm、commands/pairing/PairingCommandBridge.mm、commands/provider/OTASoftwareUpdateInteractive.mm等。可通过 GN 参数控制构建行为chip_codesign默认false置为true时启用代码签名//build/codesign:codesign目标。enable_leak_checking默认在非 ASan 且目标系统为 macOS 时启用!is_asan target_os mac用于在应用退出前自动做内存泄漏检查对应源码中的 debug/LeakChecker.mm。enable_provisional_features启用后定义MTR_ENABLE_PROVISIONAL1开放临时/草案集群接口。若启用交互模式config_use_interactive_mode构建系统会额外引入 editline 库并编译commands/interactive/InteractiveCommands.mm。使用客户端配对设备要对设备发送命令必须先让设备与 darwin-framework-tool 完成配对commissioning。当前版本的 darwin-framework-tool 一次只能记住一台已配对设备。其配置状态保存在/tmp/chip_tool_config.ini中当遇到因陈旧配置导致的异常时删除/tmp下的该文件及其他.ini文件通常可以解决问题。通过 IP 配对设备下面的命令会使用给定的 IP 地址、discriminator 和 setup code 与设备完成配对darwin-framework-tool pairing ethernet {NODE_ID_TO_ASSIGN} 20202021 3840 {IP_ADDRESS}其中{NODE_ID_TO_ASSIGN}为该设备分配的节点 IDnode id必须是十进制数字或带0x前缀的十六进制数字。20202021默认的 setup code即手动配对码。3840设备的 discriminator。{IP_ADDRESS}设备在 IP 网络中的地址。从 PairingCommandBridge.h 的源码结构可以看到pairing命令族背后支持多种配对模式PairingMode与组网类型CommissioningType配对模式说明关键参数pairing code使用手动配对码onboarding payload配对payload、dcl-hostname、dcl-port、use-dcl等pairing ble通过 BLE 配对使用 PIN 码与 discriminatorsetup-pin-code0~134217727、discriminator0~4096pairing ethernetCode模式通过 IP 网络使用 setup code 配对见上文示例pairing already-discovered对已发现的设备按下标配对payload、index组网类型CommissioningType则决定配对时是否顺带配置网络None仅建立 PASEPasscode Authenticated Session。WithoutNetwork完成配对但不配置网络。WithWiFi配对并配置 WiFi需提供ssid与password参数。WithThread配对并配置 Thread需提供operationalDataset参数。此外配对命令还支持若干可选参数例如country-code用于设置 Basic Information 集群 Location 属性的国家/地区代码。use-device-attestation-delegate置 1 时使用一个始终要求收到认证结果通知的设备认证委托对应 PairingCommandBridge.mm 中的NoOpAttestationDelegate默认false。device-attestation-failsafe-time设置调用设备认证委托前需要延长的 failsafe 时间。dcl-hostname/dcl-port/dcl-disable-https/dcl-disable-https-validation/use-dcl控制是否从 DCLDistributed Compliance Ledger服务获取并展示条款与条件Terms and Conditions信息。底层实现上配对流程由 PairingCommandBridge.mm 驱动构造MTRSetupPayload然后调用MTRDeviceController的setupCommissioningSessionWithPayload:newNodeID:建立配网会话整个过程通过MTRDeviceControllerDelegate回调返回结果命令默认等待时长为 120 秒见GetWaitDuration()。忘记当前已配对设备若需要解除当前已配对设备的关联运行darwin-framework-tool pairing unpair从源码看Unpair()会读取设备的 Operational Credentials 集群中的当前 fabric index然后调用removeFabricWithParams:将该 fabric 移除从而完成解绑。使用客户端发送 Matter 命令配对完成后即可向设备发送 Matter 命令。调用方式是传入目标集群名cluster name、命令名command name以及端点 IDendpoint iddarwin-framework-tool onoff on 1其中onoff目标集群名。on目标命令名。1endpoint id取值范围必须为 1 到 240。客户端会发送单个命令包然后退出。这一单次命令 退出的执行模型由 CHIPCommandBridge.mm 中的Run()流程保证执行命令 → 等待结果StartWaiting(GetWaitDuration())→ 关闭控制器栈 → 清理资源。获取支持的集群列表不带任何参数直接运行可执行文件即可列出全部支持的集群darwin-framework-tool示例输出Usage: ./darwin-framework-tool cluster_name command_name [param1 param2 ...] ------------------------------------------------------------------------------------- | Clusters: | ------------------------------------------------------------------------------------- | * basic | | * colorcontrol | | * doorlock | | * groups | | * identify | | * levelcontrol | | * onoff | | * pairing | | * payload | | * scenes | | * temperaturemeasurement | -------------------------------------------------------------------------------------该列表由 main.mm 中注册的命令模块汇总生成除了上述集群外实际编译进工具的还包括bdx、discover、interactive、memory、storage、configuration以及 OTA 相关命令组。获取某个集群支持的命令列表传入目标集群名即可列出该集群支持的全部命令darwin-framework-tool onoff获取某个集群支持的属性列表传入目标集群名和read命令名即可查看该集群可读取的属性darwin-framework-tool onoff read获取某个命令的参数列表传入目标集群名和目标命令名即可查看该命令所需的参数darwin-framework-tool onoff on使用交互式模式darwin-framework-tool 还提供交互式interactive模式方便在同一个会话内连续执行多条命令避免反复启动进程。启动命令如下darwin-framework-tool interactive start进入交互式模式后输入help即可查看当前可用的命令。从 InteractiveCommands.mm 的源码实现可以看到交互式模式基于 editline 库提供行编辑与历史记录功能同时支持以下快捷键命令提示符为快捷键作用Ctrl^重启 Matter 协议栈restartCtrl_停止协议栈stopCtrlZ挂起/恢复控制器suspend/resumeCtrlG触发重新订阅trigger-resubscriptionCtrl触发exit(0)退出quit()或quit退出交互式模式命令历史记录会写入/tmp/darwin_framework_tool_history。此外交互式模式还支持interactive server子命令它通过 WebSocket 服务器接收命令并按 JSON 结构返回结果包括results与logs字段这一机制为自动化测试场景提供了命令级接口。使用 OTA 软件更新应用OTA Software Update AppOTA 软件更新命令只能在交互式模式下使用。进入交互式模式后会出现额外的otasoftwareupdateapp命令运行otasoftwareupdateapp即可查看该命令下可用的子命令其作用是让 darwin-framework-tool 以 OTA Provider 身份参与 OTA 测试。设置 OTA 候选镜像列表通过otasoftwareupdateapp candidate-file-path可指定一个 JSON 文件作为候选镜像列表。JSON 结构如下{ deviceSoftwareVersionModel: [ { vendorId: 65521, productId: 32769, softwareVersion: 10, softwareVersionString: 1.0.0, cDVersionNumber: 18, softwareVersionValid: true, minApplicableSoftwareVersion: 0, maxApplicableSoftwareVersion: 100, otaURL: /Users/josh/Desktop/OTACandidates/ota_v10.bin } ] }各字段含义如下vendorId/productId候选镜像适用的厂商 ID 与产品 ID。softwareVersion软件版本号数值。softwareVersionString软件版本字符串。cDVersionNumber认证声明Certification Declaration版本号。softwareVersionValid该软件版本是否有效。minApplicableSoftwareVersion/maxApplicableSoftwareVersion适用该镜像的最低/最高软件版本范围。otaURLOTA 镜像文件在本机的路径本地文件路径。从 OTASoftwareUpdateInteractive.mm 的实现看candidate-file-path的处理流程是使用 jsoncpp 解析 JSON读取deviceSoftwareVersionModel数组要求该键必须存在且为数组否则报错。对每个候选镜像读取其 OTA 文件头最多读取 1024 字节通过MTROTAHeader解析。逐一校验候选声明中的vendorId、productId、softwareVersion、softwareVersionString、minApplicableSoftwareVersion、maxApplicableSoftwareVersion与 OTA 文件头是否一致任何一项不匹配都会导致CHIP_ERROR_INVALID_ARGUMENT。设置 Provider 端的用户同意状态darwin-framework-tool 允许在 Provider 端设置用户同意consent状态命令如下otasoftwareupdateapp set-consent-status [granted, obtaining, denied]默认情况下consent 会被设置为unknown此时由请求方requestor决定是否同意如果请求方无法给出同意则更新会被拒绝。源码中的取值映射为granted→OTAProviderUserGranted、obtaining→OTAProviderUserObtaining、denied→OTAProviderUserDenied。除了set-consent-statusotasoftwareupdateapp还支持设置 OTA 查询应答状态如0Update Available、1Busy、2Not Available、ApplyUpdate 动作应答0Proceed、1Await Next Action、2Discontinue、user-consent-needed、延迟动作时间delayed-action-time与 timed invoke 超时timed-invoke-timeout-ms等参数可用于模拟 Provider 在各种场景下的应答行为。小结darwin-framework-tool 是 Matter SDK 中面向 Apple 生态的瑞士军刀式调试工具它既是使用 AppleMatter.framework官方 API 编写 Matter 控制器的参考范例也是一套可直接投入开发调试的完备命令行客户端。通过本文介绍的构建命令、pairing ethernet配对流程、onoff on 1式的集群命令调用、interactive start交互式会话以及 OTA Provider 调试命令开发者可以快速完成从构建工具 → 配对设备 → 发送命令 → 调试 OTA的完整闭环。需要深入了解命令注册机制、配对参数细节或 OTA 处理逻辑时可继续阅读 main.mm、PairingCommandBridge.h 与 OTASoftwareUpdateInteractive.mm 等源码文件。【免费下载链接】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），仅供参考