connectedhomeip 中的 ZAP 工具入门用 GUI 配置 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/connectedhomeipZAPZigbee Cluster Preparation是 Matter 设备开发中用于编辑.zap端点配置文件的核心 GUI 工具开发者在图形界面中勾选设备支持的端点、设备类型、集群及其属性/命令/事件保存后的.zap文件会在构建阶段驱动 ZAP 编译器生成 Ember 层代码并最终编译进固件。本文以docs/zap_and_codegen/zap_intro.md为主线结合 connectedhomeipMatter SDK仓库中的实际脚本与配置完整讲解 ZAP 工具的启动方式、界面操作、集群属性配置细节以及.matter可读文件、一致性校验与代码生成的配套流程读完即可上手编辑并评审任意 Matter 示例应用的端点配置。ZAP 在 Matter 开发中的角色Matter原 Project CHIP设备的端点组成endpoint composition由.zap文件描述它涵盖设备上的所有端点endpoint每个端点上挂载的集群cluster与设备类型device type每个集群启用的特性features、属性attributes、命令commands与事件events。.zap文件本身并不能直接运行它需要与集群定义文件cluster definitions一起交给ZAP 编译器编译器生成一层Ember 层ember layer该层代码在构建过程中自动生成并编译进固件负责在收到特定命令、读写属性时做对应的处理并为集群属性分配存储内存。这一数据流对应仓库中的实际链路ZAP 工具写入.zap文件编译器见scripts/tools/zap/下的执行脚本读取src/app/zap-templates/zcl/zcl.json集群定义与数据类型的默认描述文件与src/app/zap-templates/app-templates.json生成模板最终产出 Ember 代码。与.zap配套仓库还维护同名的.matter文件——它是.zap内容的人类可读版本以接近 IDL类似 protobuf / Android AIDL的语法呈现专用于代码评审。例如 examples/chef/devices/ 下的*.matter文件首行即注明This IDL was generated automatically by ZAP.并逐条列出枚举、结构体与集群定义供评审人员逐行核对端点配置是否正确。快速上手打开并浏览一个.zap文件启动 ZAP 图形界面在仓库根目录执行./scripts/tools/zap/run_zaptool.sh filename其中filename是待打开的.zap文件路径例如示例应用的examples/all-clusters-app/all-clusters-app.zap该文件会被run_zaptool.sh自动识别并使用带测试扩展的zcl-with-test-extensions.json。脚本启动时会自动附带正确的模板与集群描述参数无需手工拼写。关于 ZAP 可执行文件的定位run_zaptool.sh 支持以下方式按优先级从高到低ZAP_DEVELOPMENT_PATH指向 ZAP 源码开发目录会执行zap_bootstrap.sh引导依赖并以node src-script/zap-start.js启动ZAP_INSTALL_PATH指向解压后的 ZAP 发布包目录macOS 下为zap.app/Contents/MacOS/zapLinux 下为zap可执行文件默认回退直接使用PATH中的zap命令在已引导的构建环境中即如此也可以用--zap ZAP参数显式指定可执行文件。打开文件后在工具中选择Matter 格式即可进入主界面。左侧端点区界面左侧展示设备的端点配置包括端点列表如Endpoint-0、Endpoint-1、Endpoint-2、Endpoint-65534等、ADD ENDPOINT按钮以及每个端点旁的编辑铅笔图标。右侧是 Matter 工作区提供Generate、Regenerate、Options、Extensions、Notifications、Preview、Tutorial、Settings等操作入口。编辑端点设备类型与修订号点击端点旁的编辑按钮铅笔图标会打开一个对话框可在其中修改该端点的设备类型device types及其修订号revision。此处有两个字段不要修改Profile ID它标识该 ZAP 端点是 Matter 端点profile 标识来自 Zigbee 时代的遗留概念Matter 中应保持默认值Network这是仅适用于 Zigbee 产品的属性对 Matter 无意义。编辑集群启用与配置要编辑某个端点上的集群先在左侧选中该端点随后将目标集群的enable下拉框设置为server点击该集群旁的齿轮图标进入集群详细配置界面。集群配置详解Attributes 各列含义进入集群配置后.zap文件会列出该集群的全部可用属性。属性表格的列设置如下这是.zap配置中最核心的部分直接决定设备实际暴露的数据模型列名含义与配置要点Enabled打开即表示在设备上启用该属性。Attribute ID来自 Matter 规范的属性 ID。Attribute来自规范的属性名称。Required标记为yes表示该属性是强制的。注意部分属性会在启用某些特性features或其它属性后变为强制这种变化不会在 UI 中反映需要设备厂商自行保证符合规范。Client/Server对 Matter 而言所有属性都应设为serverMatter 设备端不通过该表格配置 client 侧属性。Mfg code仅适用于厂商自定义manufacturer-specific属性。Storage option决定 Ember 是否为该属性分配存储直接使用 Ember 层的集群设为RAM使用 override 层、自行管理存储的集群设为external。Matter SDK 会依据集群实现和 Matter zap 配置文档自动设置正确的值除非有明确理由否则建议保持默认值不变。Type来自规范的数据类型。Default与规范中定义的默认值不同它表示当属性由 Ember 层RAM 存储实现时希望的起始值。为什么 Storage option 不宜乱改Storage option的正确取值与底层实现强绑定。仓库中的集群实现分两类直接基于 Ember 层的集群属性状态由 Ember 在 RAM 中管理对应RAM基于 override 层、自带存储实现的集群属性读写由应用代码接管对应external。因此默认值实际由 SDK 按集群实现逐一审定随意覆盖可能导致属性无存储空间或与实现冲突。Matter zap 配置文档对每个集群的取值有系统说明改动前应查阅对应集群的源码实现可参考src/app/clusters/下各集群目录确认其存储模型。Attribute Reporting 与 EventsAttribute Reporting属性上报配置不适用于 Matter保持未使用该能力为 Zigbee 遗留设计Matter 的订阅/上报由交互模型在运行时管理无需在.zap中静态配置Events事件页签同样不适用于 Matter保持未使用。Commands勾选需要支持的命令在 Commands 页签中勾选希望支持的请求命令Request command若勾选了某个请求命令其对应的**响应命令Response command**也必须一并勾选否则生成出的处理逻辑不完整。用.matter文件评审端点配置.matter文件是从.zap生成的人类可读 IDL主要设计目标有二可读结构类似 protobuf / AIDL便于评审人员逐行审查Matter 专属只包含 Matter 相关数据.zap本身兼容 Zigbee含大量通用字段。当前.matter文件在应用级代码生成时由.zap文件自动生成。需要单独生成时使用scripts/tools/zap/generate.py ${ZAP_FILE_PATH}该脚本会使用模板src/app/zap-templates/matter-idl.json生成与.zap对应的.matter文件。建议生成后检查内容是否符合预期并可执行 Lint 校验matter-idl-lint ${MATTER_FILE_PATH}若.matter内容有误应回头修正.zap文件.matter只是.zap内容的呈现。仓库中.matter的解析与代码生成实现位于 scripts/py_matter_idl 与 scripts/codegen.py二者是 SDK 从可读 IDL转向新一代代码生成技术栈的实验基础——该方案相比 ZAP 依赖更少、生成更快、模板更灵活且输入可审计。保证规范一致性Conformance 检查由于 Required 列不会随特性/其它属性的启用而动态变化设备厂商必须自行保证端点配置符合 Matter 规范。SDK 提供了一致性检查测试TC_DeviceConformance.pysrc/python_testing/TC_DeviceConformance.py它以 Python 测试的形式运行内部调用check_conformance遍历设备数据模型比对 CSA 数据模型中的强制属性、设备类型从属关系与集群/数据类型定义输出不合规项。在docs/testing的 CI 测试框架下它支持--PICS src/app/tests/suites/certification/ci-pics-values等参数接入认证级测试套件。建议在修改.zap后运行设备组成device composition相关测试确认所选组合符合规范。从.zap到固件代码生成链路一瞥构建期自动生成在示例应用中.zap文件在构建阶段被自动消费GN/CMake 规则见 src/app/chip_data_model.gni 与 src/app/chip_data_model.cmake在编译时调用generate.py/codegen.py生成服务器侧处理数据集群回调、属性 RAM 分配等随后与固件一起编译。这就是docs/zap_and_codegen/code_generation.md中编译期代码生成的落地方式。全量再生成与定向生成仓库提供两类再生成入口全量再生成较慢需数分钟./scripts/tools/zap_regen_all.py只重生成测试相关代码YAML 测试开发时更快例如./scripts/tools/zap_regen_all.py --type tests ./scripts/tools/zap_regen_all.py --type tests --tests chip-tool单个应用只需再生成.matter文件应用侧唯一需要更新的产物./scripts/tools/zap/generate.py \ examples/bridge-app/bridge-common/bridge-app.zap按-t/--templates传入其它模板、并以-o/--output-dir指定输出目录可生成更多类型的产物。推荐的日常更新流程# 1. 用 ZAP GUI 编辑 .zap 文件或直接修改 .zap ./scripts/tools/zap/run_zaptool.sh $PATH_TO_ZAP_FILE # 2. 重新生成 .matter 文件注意.matter 生成不使用 output 目录 ./scripts/tools/zap/generate.py $PATH_TO_ZAP_FILE随后重新构建应用并建议运行设备组成一致性测试如TC_DeviceConformance验证规范符合性。小结ZAP 是 Matter 设备数据模型配置的总闸run_zaptool.sh负责拉起带正确模板与集群描述的 GUI左侧端点区管理端点与设备类型集群配置页签中的 Attributes 表格Enabled / Required / Storage option / Default 等列、Commands 勾选共同决定设备暴露的能力边界配置结果以.zap为单一事实来源经构建期 ZAP 编译器生成 Ember 层固件代码同时产出.matter供评审再由TC_DeviceConformance.py等一致性测试兜底规范符合性。掌握了这套编辑.zap→ 生成.matter→ 重建与校验的闭环即可在 Matter SDK 中高效配置并评审任何设备的端点组成。【免费下载链接】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），仅供参考 
长河君 · 2026/9/18 14:37:47 · 阅读 1.2k connectedhomeip 中的 ZAP 工具入门：用 GUI 配置 Matter 设备端点与集群并驱动代码生成
connectedhomeip 中的 ZAP 工具入门用 GUI 配置 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/connectedhomeipZAPZigbee Cluster Preparation是 Matter 设备开发中用于编辑.zap端点配置文件的核心 GUI 工具开发者在图形界面中勾选设备支持的端点、设备类型、集群及其属性/命令/事件保存后的.zap文件会在构建阶段驱动 ZAP 编译器生成 Ember 层代码并最终编译进固件。本文以docs/zap_and_codegen/zap_intro.md为主线结合 connectedhomeipMatter SDK仓库中的实际脚本与配置完整讲解 ZAP 工具的启动方式、界面操作、集群属性配置细节以及.matter可读文件、一致性校验与代码生成的配套流程读完即可上手编辑并评审任意 Matter 示例应用的端点配置。ZAP 在 Matter 开发中的角色Matter原 Project CHIP设备的端点组成endpoint composition由.zap文件描述它涵盖设备上的所有端点endpoint每个端点上挂载的集群cluster与设备类型device type每个集群启用的特性features、属性attributes、命令commands与事件events。.zap文件本身并不能直接运行它需要与集群定义文件cluster definitions一起交给ZAP 编译器编译器生成一层Ember 层ember layer该层代码在构建过程中自动生成并编译进固件负责在收到特定命令、读写属性时做对应的处理并为集群属性分配存储内存。这一数据流对应仓库中的实际链路ZAP 工具写入.zap文件编译器见scripts/tools/zap/下的执行脚本读取src/app/zap-templates/zcl/zcl.json集群定义与数据类型的默认描述文件与src/app/zap-templates/app-templates.json生成模板最终产出 Ember 代码。与.zap配套仓库还维护同名的.matter文件——它是.zap内容的人类可读版本以接近 IDL类似 protobuf / Android AIDL的语法呈现专用于代码评审。例如 examples/chef/devices/ 下的*.matter文件首行即注明This IDL was generated automatically by ZAP.并逐条列出枚举、结构体与集群定义供评审人员逐行核对端点配置是否正确。快速上手打开并浏览一个.zap文件启动 ZAP 图形界面在仓库根目录执行./scripts/tools/zap/run_zaptool.sh filename其中filename是待打开的.zap文件路径例如示例应用的examples/all-clusters-app/all-clusters-app.zap该文件会被run_zaptool.sh自动识别并使用带测试扩展的zcl-with-test-extensions.json。脚本启动时会自动附带正确的模板与集群描述参数无需手工拼写。关于 ZAP 可执行文件的定位run_zaptool.sh 支持以下方式按优先级从高到低ZAP_DEVELOPMENT_PATH指向 ZAP 源码开发目录会执行zap_bootstrap.sh引导依赖并以node src-script/zap-start.js启动ZAP_INSTALL_PATH指向解压后的 ZAP 发布包目录macOS 下为zap.app/Contents/MacOS/zapLinux 下为zap可执行文件默认回退直接使用PATH中的zap命令在已引导的构建环境中即如此也可以用--zap ZAP参数显式指定可执行文件。打开文件后在工具中选择Matter 格式即可进入主界面。左侧端点区界面左侧展示设备的端点配置包括端点列表如Endpoint-0、Endpoint-1、Endpoint-2、Endpoint-65534等、ADD ENDPOINT按钮以及每个端点旁的编辑铅笔图标。右侧是 Matter 工作区提供Generate、Regenerate、Options、Extensions、Notifications、Preview、Tutorial、Settings等操作入口。编辑端点设备类型与修订号点击端点旁的编辑按钮铅笔图标会打开一个对话框可在其中修改该端点的设备类型device types及其修订号revision。此处有两个字段不要修改Profile ID它标识该 ZAP 端点是 Matter 端点profile 标识来自 Zigbee 时代的遗留概念Matter 中应保持默认值Network这是仅适用于 Zigbee 产品的属性对 Matter 无意义。编辑集群启用与配置要编辑某个端点上的集群先在左侧选中该端点随后将目标集群的enable下拉框设置为server点击该集群旁的齿轮图标进入集群详细配置界面。集群配置详解Attributes 各列含义进入集群配置后.zap文件会列出该集群的全部可用属性。属性表格的列设置如下这是.zap配置中最核心的部分直接决定设备实际暴露的数据模型列名含义与配置要点Enabled打开即表示在设备上启用该属性。Attribute ID来自 Matter 规范的属性 ID。Attribute来自规范的属性名称。Required标记为yes表示该属性是强制的。注意部分属性会在启用某些特性features或其它属性后变为强制这种变化不会在 UI 中反映需要设备厂商自行保证符合规范。Client/Server对 Matter 而言所有属性都应设为serverMatter 设备端不通过该表格配置 client 侧属性。Mfg code仅适用于厂商自定义manufacturer-specific属性。Storage option决定 Ember 是否为该属性分配存储直接使用 Ember 层的集群设为RAM使用 override 层、自行管理存储的集群设为external。Matter SDK 会依据集群实现和 Matter zap 配置文档自动设置正确的值除非有明确理由否则建议保持默认值不变。Type来自规范的数据类型。Default与规范中定义的默认值不同它表示当属性由 Ember 层RAM 存储实现时希望的起始值。为什么 Storage option 不宜乱改Storage option的正确取值与底层实现强绑定。仓库中的集群实现分两类直接基于 Ember 层的集群属性状态由 Ember 在 RAM 中管理对应RAM基于 override 层、自带存储实现的集群属性读写由应用代码接管对应external。因此默认值实际由 SDK 按集群实现逐一审定随意覆盖可能导致属性无存储空间或与实现冲突。Matter zap 配置文档对每个集群的取值有系统说明改动前应查阅对应集群的源码实现可参考src/app/clusters/下各集群目录确认其存储模型。Attribute Reporting 与 EventsAttribute Reporting属性上报配置不适用于 Matter保持未使用该能力为 Zigbee 遗留设计Matter 的订阅/上报由交互模型在运行时管理无需在.zap中静态配置Events事件页签同样不适用于 Matter保持未使用。Commands勾选需要支持的命令在 Commands 页签中勾选希望支持的请求命令Request command若勾选了某个请求命令其对应的**响应命令Response command**也必须一并勾选否则生成出的处理逻辑不完整。用.matter文件评审端点配置.matter文件是从.zap生成的人类可读 IDL主要设计目标有二可读结构类似 protobuf / AIDL便于评审人员逐行审查Matter 专属只包含 Matter 相关数据.zap本身兼容 Zigbee含大量通用字段。当前.matter文件在应用级代码生成时由.zap文件自动生成。需要单独生成时使用scripts/tools/zap/generate.py ${ZAP_FILE_PATH}该脚本会使用模板src/app/zap-templates/matter-idl.json生成与.zap对应的.matter文件。建议生成后检查内容是否符合预期并可执行 Lint 校验matter-idl-lint ${MATTER_FILE_PATH}若.matter内容有误应回头修正.zap文件.matter只是.zap内容的呈现。仓库中.matter的解析与代码生成实现位于 scripts/py_matter_idl 与 scripts/codegen.py二者是 SDK 从可读 IDL转向新一代代码生成技术栈的实验基础——该方案相比 ZAP 依赖更少、生成更快、模板更灵活且输入可审计。保证规范一致性Conformance 检查由于 Required 列不会随特性/其它属性的启用而动态变化设备厂商必须自行保证端点配置符合 Matter 规范。SDK 提供了一致性检查测试TC_DeviceConformance.pysrc/python_testing/TC_DeviceConformance.py它以 Python 测试的形式运行内部调用check_conformance遍历设备数据模型比对 CSA 数据模型中的强制属性、设备类型从属关系与集群/数据类型定义输出不合规项。在docs/testing的 CI 测试框架下它支持--PICS src/app/tests/suites/certification/ci-pics-values等参数接入认证级测试套件。建议在修改.zap后运行设备组成device composition相关测试确认所选组合符合规范。从.zap到固件代码生成链路一瞥构建期自动生成在示例应用中.zap文件在构建阶段被自动消费GN/CMake 规则见 src/app/chip_data_model.gni 与 src/app/chip_data_model.cmake在编译时调用generate.py/codegen.py生成服务器侧处理数据集群回调、属性 RAM 分配等随后与固件一起编译。这就是docs/zap_and_codegen/code_generation.md中编译期代码生成的落地方式。全量再生成与定向生成仓库提供两类再生成入口全量再生成较慢需数分钟./scripts/tools/zap_regen_all.py只重生成测试相关代码YAML 测试开发时更快例如./scripts/tools/zap_regen_all.py --type tests ./scripts/tools/zap_regen_all.py --type tests --tests chip-tool单个应用只需再生成.matter文件应用侧唯一需要更新的产物./scripts/tools/zap/generate.py \ examples/bridge-app/bridge-common/bridge-app.zap按-t/--templates传入其它模板、并以-o/--output-dir指定输出目录可生成更多类型的产物。推荐的日常更新流程# 1. 用 ZAP GUI 编辑 .zap 文件或直接修改 .zap ./scripts/tools/zap/run_zaptool.sh $PATH_TO_ZAP_FILE # 2. 重新生成 .matter 文件注意.matter 生成不使用 output 目录 ./scripts/tools/zap/generate.py $PATH_TO_ZAP_FILE随后重新构建应用并建议运行设备组成一致性测试如TC_DeviceConformance验证规范符合性。小结ZAP 是 Matter 设备数据模型配置的总闸run_zaptool.sh负责拉起带正确模板与集群描述的 GUI左侧端点区管理端点与设备类型集群配置页签中的 Attributes 表格Enabled / Required / Storage option / Default 等列、Commands 勾选共同决定设备暴露的能力边界配置结果以.zap为单一事实来源经构建期 ZAP 编译器生成 Ember 层固件代码同时产出.matter供评审再由TC_DeviceConformance.py等一致性测试兜底规范符合性。掌握了这套编辑.zap→ 生成.matter→ 重建与校验的闭环即可在 Matter SDK 中高效配置并评审任何设备的端点组成。【免费下载链接】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），仅供参考