企业官网建设流程全解析

Matter 1.5 升级完整指南：如何落地 19 类新设备类型与 13 个新集群（connectedhomeip）

【免费下载链接】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）SDK 现已内置完整的 Matter 1.5 数据模型：19 类新设备类型、13 个净增集群、联合 Fabric 管理与 Label 集群重构。本文按"为什么升级→改了什么→怎么迁移→怎么排坑"的顺序，给出价值判断、1.4 与 1.5 的结构性差异清单、三步迁移路径和 4 个高频坑，帮助团队独立判断并完成版本升级。

为什么现在升级：业务与技术的双重价值判断

业务侧的机会：Matter 1.5 新增的 19 类设备类型（data_model/1.5/device_types/）恰好覆盖此前 Matter 无法表达的高价值品类：

• 摄像头与门禁音频：Camera、FloodlightCamera、SnapshotCamera、CameraController，以及 Doorbell、VideoDoorbell、AudioDoorbell、Chime、Intercom 共 9 类
• 能源计量：ElectricalMeter、ElectricalUtilityMeter、ElectricalEnergyTariff、MeterReferencePoint，配合 CommodityMetering、CommodityTariff、CommodityPrice 集群，首次支持电表/燃气表级场景
• 执行器与灌溉：Closure、ClosureController、ClosurePanel、IrrigationSystem、SoilSensor

不做 1.5 的直接后果是：新品类无法通过认证进入主流生态，存量产品线（如照明、门锁）虽不受阻塞，但会逐步失去与新版控制端、网关的协同能力。

技术侧的回报：

• 设备类型总数从 74 类增至93 类，集群从 112 个增至125 个，一次升级即可覆盖未来两代产品线
• 新增 JointFabricAdministratorCluster，支持跨 Fabric 的联合管理，多生态分发不再需要私有扩展
• 1.5 首次引入 data_model/1.5/globals/（Enums、Structs、TypeDefs 等 5 类共享定义），类型一致性由规格文件保证，减少各厂商私有枚举的分裂

Matter 1.4 与 1.5 的结构性变化对照表

对 data_model/1.4/ 与 data_model/1.5/ 两个目录逐文件比对，结构性变化集中在 5 处：

三步升级路径：从兼容性评估到代码再生成

阶段一：环境准备与基线差异确认

• 目标：拿到干净的 1.5 数据模型，明确本项目受影响的集群与设备类型清单
• 关键动作：克隆仓库、初始化子模块，用官方 diff 脚本生成 1.4→1.5 变更摘要

git clone https://gitcode.com/GitHub_Trending/co/connectedhomeip cd connectedhomeip && ./scripts/checkout_submodules.py ./scripts/spec_xml/spec_revision_diff_summary.py --help

• 完成标准：diff 摘要输出存档，产品所需的新集群/新设备类型与代码中需改动的文件一一对应

阶段二：更新 ZAP 配置并重新生成代码

• 目标：让 .zap/.matter 模板引用 1.5 数据模型，重新生成访问器
• 关键动作：修改模板中的集群与设备类型声明（含旧名→新名替换），在 examples/all-clusters-app/ 全量示例上验证生成无误，再回写产品工程；摄像头场景可参考 examples/camera-app/
• 完成标准：目标平台构建通过，无未解析集群引用

source scripts/activate.sh ./scripts/build examples/all-clusters-app/linux/x64

阶段三：验证与测试基线切换

• 目标：确认固件与 IDM 测试使用同一规格版本
• 关键动作：运行数据模型解析单元测试，确认SpecificationVersion声明与 data_model/1.5/ 对齐；测试基础设施会从端点 0 的 BasicInformation 集群读取规格版本并自动选择对应基线（见 data_model/README.md）
• 完成标准：TestSpec* 单元测试全部通过；升级前后关键指标（配网耗时、集群读写正确率）留档对比

python3 src/python_testing/TestSpecParsingSupport.py python3 src/python_testing/TestSpecParsingDeviceType.py

高频坑位：四个升级问题的排查与解法

问题 1：旧集群名称引用残留

• 现象：代码生成报未知集群，或联合 Fabric 相关编译失败
• 解法：1.5 将 JointFabricPKICluster 更名为 JointFabricAdministratorCluster，Label 三子集群重构为 Label/FixedLabel/UserLabel，Proxy 相关 3 个集群移除。用新定义 data_model/1.5/clusters/ 建立映射表后全局替换

问题 2：IDM 测试用了错误基线

• 现象：测试按 1.4 的 XML 校验固件，新增集群被误判缺失
• 解法：确认SpecificationDefinedRevisions.h（src/app/）已指向 1.5，固件端点 0 的 SpecificationVersion 属性同步更新，测试框架据此自动切到 1.5 基线

问题 3：手工修改 data_model 下的 XML

• 现象：本地改动与上游 DMTT 更新冲突，PR 反复失败
• 解法：规格 XML 是机器生成的，禁止手改；需要临时覆盖访问权限等定义时，使用声明式覆盖文件 data_model/errata_future.yaml，机制说明见 docs/guides/data_model_errata.md

问题 4：升级后新品类"只认不实现"

• 现象：声明了 ElectricalMeter 等设备类型，但对应集群无服务端实现，认证卡壳
• 解法：只声明产品实际支持的子集；需要实现新集群时，按 docs/guides/writing_clusters.md 编写，并对照 docs/testing/integration_tests.md 补齐测试用例

资源索引：源码、文档与测试规范路径

• 1.5 数据模型定义：data_model/1.5/clusters/、data_model/1.5/device_types/
• 集群参考实现：src/app/clusters/
• 全量集群示例应用：examples/all-clusters-app/；摄像头示例：examples/camera-app/
• SDK 升级说明：docs/upgrading.md
• ZAP 与代码生成：docs/zap_and_codegen/code_generation.md
• 数据模型 Errata 机制：docs/guides/data_model_errata.md
• 数据模型维护说明：data_model/README.md
• 集成测试规范：docs/testing/integration_tests.md

收尾建议

建议在一个发布周期（2–3 个月）内完成数据模型与测试基线切换：摄像头、计量、窗帘类产品线优先立项，联合 Fabric 作为独立评估项；升级前完成旧集群名称映射与 diff 摘要归档，可避免约半数的返工。

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