Matter Closure 闭锁设备集群开发实战基于 connectedhomeip 源码解析 Closure Control 与 Closure Dimension Cluster 的集成方式【免费下载链接】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导读本文面向希望在 Matterconnectedhomeip 项目中为电动窗帘、卷帘门、百叶窗等闭锁Closure设备实现服务端能力的开发者系统讲解 Matter 新引入的 Closure Control闭锁控制与 Closure Dimension闭锁维度两个集群的源码级集成方案。文章以 Closure Control Cluster README 与 Closure Dimension Cluster README 为骨架结合ClosureControlCluster.h、ClosureDimensionCluster.h等源码完整覆盖 Delegate 实现、Feature 配置、集群注册、初始化时序与一致性校验Conformance Validation并给出新旧两套 API 的迁移对照。读完本文你将能够在一个 Matter 应用上从零挂载可用的 Closure 服务端集群并理解其底层运行机制。说明闭锁Closure示例应用在本次仓库快照中尚未落地docs/examples/closure.md 仅包含指向closure-app/**/README的索引占位Closure 相关功能的权威资料集中在src/app/clusters/closure-control-server/与src/app/clusters/closure-dimension-server/两个源码目录中本文即基于这两份 README 及其实现展开。一、Closure 集群在 Matter 体系中的定位Matter 将家居设备的统一数据模型抽象为「端点Endpoint上的集群Cluster」。闭锁设备窗帘、卷帘、百叶窗、车库门等在 Matter 中由两个彼此配合的集群描述Closure Control Cluster闭锁控制集群负责控制闭锁设备的整体行为包括定位Positioning、运动闩锁Motion Latching以及运行状态监控Operational State。它面向一扇逻辑闭锁的整体控制例如把整扇卷帘移到 50%。Closure Dimension Cluster闭锁维度集群负责控制组合式闭锁composed closure中的单一自由度single degree of freedom也称 dimension / axis。例如一扇由帘体升降 叶片翻转两个轴组成的百叶窗每个轴由一个 Dimension 集群实例描述。两者的关系可以理解为Control 是面向设备的顶层控制面Dimension 是面向机械轴的细分控制面。二者共享位置Positioning与运动闩锁Motion Latching等核心概念因此实现模式高度一致。在数据模型层面两个集群的定义均来自 ZAP 模板中的数据模型 XMLclosure-control-cluster.xml 与 closure-dimension-cluster.xml集群语义源头为ClosureControl.adoc规范文档见 XML 中Source字段。二、Closure Control Cluster控制面实现2.1 设计哲学代码驱动Code-Driven替代旧式 CodegenClosureControlCluster.h 开头的头文件注释点明了这一实现的关键取舍这是一个代码驱动的 C 服务端实现其设计目标就是摆脱旧式 codegenZAP 代码生成实现中的紧耦合追求更高的灵活性。与此配套集群通过**委托模式Delegate Pattern**与业务逻辑解耦chip::app::Clusters::ClosureControl::ClosureControlClusterDelegate应用层只需实现该 Delegate 的虚方法即可向集群提供闭锁状态、响应控制命令而无需关心 Matter 消息框架的细节。测试代码 TestClosureControlCluster.cpp 中的MockDelegate展示了 Delegate 需要实现的核心命令入口包括HandleStopCommand()处理 Stop停止命令HandleMoveToCommand(tag, latch, speed)处理 MoveTo移动到目标位置命令参数为TargetPositionEnum目标位置标签、可选的latch闩锁标志与ThreeLevelAutoEnum速度档位HandleCalibrateCommand()处理 Calibrate校准命令IsReadyToMove()查询设备是否可移动例如夹手保护状态下应返回 false。2.2 完整集成四步走根据 Closure Control Cluster README将ClosureControlCluster接入应用的流程分为四步Step 1实现 Delegate创建一个继承ClosureControlClusterDelegate的类并实现其虚方法以处理命令、提供闭锁状态#include app/clusters/closure-control-server/ClosureControlClusterDelegate.h class MyClosureControlDelegate : public chip::app::Clusters::ClosureControl::ClosureControlClusterDelegate { };Step 2用 Builder 风格构建 Config通过ClosureControlCluster::Config配置集群的 FeatureMap、可选属性与初始状态。Config 采用链式With*方法逐项开启 Feature创建集群前配置必须满足一致性要求详见第四节#include app/clusters/closure-control-server/ClosureControlCluster.h using namespace chip::app::Clusters::ClosureControl; auto config ClosureControlCluster::Config(/* endpoint */ 1, gMyDelegate, gTimerDelegate) .WithPositioning() .WithCalibration() // 按需继续开启其他 Feature // WithSpeed(), WithVentilation(), WithPedestrian(), // WithProtection(), WithManuallyOperable(), WithAccess(), // WithInstantaneous()... .WithMotionLatching(chip::BitFlagsLatchControlModesBitmap() .Set(LatchControlModesBitmap::kRemoteLatching) .Set(LatchControlModesBitmap::kRemoteUnlatching)) .WithCountdownTime() .WithInitialMainState(MainStateEnum::kStopped);对照源码 ClosureControlCluster.hConfig的构造参数包含端点号EndpointId、Delegate 引用与 TimerDelegate 引用每个With*方法都会在mFeatureMap中置位对应 FeatureWith*方法开启的 Feature附带配置项WithPositioning()kPositioning定位位置控制WithMotionLatching(BitFlagsLatchControlModesBitmap)kMotionLatching闩锁模式位图如kRemoteLatching远程闩锁、kRemoteUnlatching远程解闩WithSpeed()kSpeed速度控制WithVentilation()kVentilation通风模式WithPedestrian()kPedestrian行人防夹模式WithCalibration()kCalibration校准WithProtection()kProtection保护WithManuallyOperable()kManuallyOperable可手动操作WithAccess()kAccess访问控制WithInstantaneous()kInstantaneous瞬时动作WithCountdownTime(initial)可选属性CountdownTime倒计时时间默认NullNullable类型为可空的ElapsedSWithInitialMainState(mainState)—初始主状态如MainStateEnum::kStoppedWithInitialOverallCurrentState(...)—初始综合当前状态GenericOverallCurrentStateStep 3实例化 Delegate 与集群为每个需要 Closure 能力的端点实例化一个 Delegate 与一个ClosureControlCluster推荐使用RegisteredServerCluster简化注册过程#include app/server-cluster/ServerClusterInterfaceRegistry.h #include lib/support/DefaultTimerDelegate.h // 放在 .cpp 文件中 MyClosureControlDelegate gMyDelegate; chip::support::DefaultTimerDelegate gTimerDelegate; chip::app::RegisteredServerClusterchip::app::Clusters::ClosureControl::ClosureControlCluster gClosureControlCluster(config);Step 4向 CodegenDataModelProvider 注册集群在应用初始化序列中把集群实例注册到CodegenDataModelProvider从而将其挂入 Matter 数据模型与消息处理框架。注册必须发生在服务器启动之前#include data-model-providers/codegen/CodegenDataModelProvider.h void ApplicationInit() { // ... 其他初始化 // 在 server 启动前注册集群 CHIP_ERROR err chip::app::CodegenDataModelProvider::Instance().Registry().Register( gClosureControlCluster.Registration()); VerifyOrDie(err CHIP_NO_ERROR); // ... server 后续才启动 }注册完成后集群的所有 setter/getter 都可以直接通过gClosureControlCluster.Cluster()调用。2.3 新旧两套集成 APIREADME 特别指出出于向后兼容仓库保留了旧式ZAP codegen 模式接口位于 CodegenIntegration.h通过Interface类暴露#include app/clusters/closure-control-server/CodegenIntegration.h using namespace chip::app::Clusters::ClosureControl; MyClosureControlDelegate gMyDelegate; Interface gClosureControlInterface(/* endpoint */ 1, gMyDelegate); CHIP_ERROR ApplicationInit() { ClusterConformance conformance; conformance.FeatureMap().Set(Feature::kPositioning).Set(Feature::kCalibration); ClusterInitParameters initParams; initParams.mMainState MainStateEnum::kStopped; initParams.mLatchControlModes.Set(LatchControlModesBitmap::kRemoteLatching) .Set(LatchControlModesBitmap::kRemoteUnlatching); return gClosureControlInterface.Init(conformance, initParams); }Init()成功后通过gClosureControlInterface.Cluster()访问集群。官方建议迁移到新的直接实例化方式即 2.2 节四步流程以提升性能并减小应用体积footprint。三、Closure Dimension Cluster维度轴面实现3.1 与 Control 集群的对称设计Closure Dimension Cluster 用于控制组合式闭锁的单一轴实现同样采用代码驱动 Delegate 模式chip::app::Clusters::ClosureDimension::ClosureDimensionClusterDelegate其集成流程与 Control 集群几乎一一对应见 ClosureDimensionCluster.h 的Config但With*方法携带了更强的轴语义参数With*方法开启的 Feature附带配置项WithPositioning(resolution, stepValue)kPositioningPercent100ths分辨率与步进值源码默认均为 1WithMotionLatching(latchControlModes)kMotionLatchingLatchControlModesBitmap闩锁模式位图WithUnit(unit, unitRange)kUnitClosureUnitEnum单位与可空的UnitRangeStruct量程WithLimitation(limitRange)kLimitationRangePercent100thsStruct限制范围WithSpeed()kSpeed速度WithTranslation(translationDirection)kTranslationTranslationDirectionEnum平移方向如kDownwardWithRotation(rotationAxis, overflow)kRotationRotationAxisEnum旋转轴与OverflowEnum溢出行为WithModulation(modulationType)kModulationModulationTypeEnum调制类型WithAccess()kAccess访问控制3.2 代码驱动的集成流程Step 1实现 Delegate#include app/clusters/closure-dimension-server/ClosureDimensionClusterDelegate.h class MyClosureDimensionDelegate : public chip::app::Clusters::ClosureDimension::ClosureDimensionClusterDelegate { };Step 2配置 ClusterConformance 与初始化参数#include app/clusters/closure-dimension-server/ClosureDimensionCluster.h chip::app::Clusters::ClosureDimension::ClusterConformance conformance; conformance.FeatureMap().Set(chip::app::Clusters::ClosureDimension::Feature::kPositioning); conformance.FeatureMap().Set(chip::app::Clusters::ClosureDimension::Feature::kMotionLatching); // 按需添加其他 Feature // 可选配置初始化参数启用 translation / rotation / modulation 时需要 chip::app::Clusters::ClosureDimension::ClusterInitParameters initParams; initParams.translationDirection chip::app::Clusters::ClosureDimension::TranslationDirectionEnum::kDownward; // 需要时再设置 initParams.rotationAxis / initParams.modulationTypeStep 3实例化 Delegate 与集群Dimension 集群通过Context结构体一次性携带 delegate、conformance 与 initParams#include app/server-cluster/ServerClusterInterfaceRegistry.h // 放在 .cpp 文件中 MyClosureDimensionDelegate gMyDelegate; chip::app::Clusters::ClosureDimension::ClosureDimensionCluster::Context clusterContext{ .delegate gMyDelegate, .conformance conformance, .initParams initParams }; chip::app::RegisteredServerClusterchip::app::Clusters::ClosureDimension::ClosureDimensionCluster gClosureDimensionCluster( chip::EndpointId{ 2 }, clusterContext);Step 4注册到 CodegenDataModelProvider与 Control 集群完全一致且同样必须在服务器启动前完成#include data-model-providers/codegen/CodegenDataModelProvider.h void ApplicationInit() { // ... 其他初始化 CHIP_ERROR err chip::app::CodegenDataModelProvider::Instance().Registry().Register( gClosureDimensionCluster.Registration()); VerifyOrDie(err CHIP_NO_ERROR); // ... server 启动 }3.3 维度状态与旧接口源码目录中另有 GenericDimensionState.h 提供通用的维度轴状态管理支撑。README 明确说明旧式ClusterLogic与MatterContext类已被移除新实现不再需要它们其余 API 为向后兼容保留仍可通过 CodegenIntegration.h 中的旧式Interface类访问。四、一致性校验Conformance Validation失败即致命两个 README 都以醒目的方式强调同一规则The cluster performs strict conformance validation during construction.Any validation failure is fataland will terminate the application with Invalid Conformance message.即集群在构造阶段执行严格的一致性Conformance校验任何校验失败都是致命的应用将终止并输出 Invalid Conformance 信息。这意味着Config或旧式ClusterConformance中开启的 Feature 组合必须满足 Matter 规范的一致性约束例如启用kMotionLatching时必须同时提供合法的LatchControlModesBitmap启用kTranslation/kRotation/kModulation时必须给出对应的方向、轴或调制类型参数校验发生在服务器启动之前构造/注册阶段因此问题会在启动早期立刻暴露而不是在运行时才产生模糊错误。测试目录下的 TestClosureControlCluster.cpp 与 TestClosureDimensionCluster.cpp 中大量用例通过构造合法/非法配置来验证这一校验逻辑可作为自测与排查的参考。五、初始化时序与迁移指南5.1 推荐的代码驱动时序以 Closure Control README 的 Initialization Sequence 为准服务器启动前Before Server Startup用With*builder 方法构建ClosureControlCluster::Config或 Dimension 集群的Context确定 Feature 与初始状态实例化 Delegate 与集群向CodegenDataModelProvider注册集群。服务器启动后After Startup4. 集群实例上的所有 getter/setter 均可安全直接调用。5.2 从旧式 API 迁移两个 README 都给出了相同的迁移建议推荐用法直接实例化集群RegisteredServerCluster...CodegenDataModelProvider注册获得更优性能与更小 footprint兼容用法继续使用Interface通过CodegenIntegration.h其初始化通过ClusterConformanceClusterInitParameters完成对 Dimension 集群而言迁移时还需注意ClusterLogic与MatterContext已删除不要继续引用。六、总结与源码索引Closure Control 与 Closure Dimension 是 Matter 闭锁设备的两个核心集群connectedhomeip 中的实现采用代码驱动 Delegate 模式强调与业务解耦、构造期严格一致性校验、并保留旧式接口向后兼容。开发者按实现 Delegate → 构建 Config/Conformance → 实例化集群 → 启动前注册四步即可完成接入。关键文件索引均可直接在当前仓库中阅读集群 READMEclosure-control-server/README.md、closure-dimension-server/README.mdControl 集群实现ClosureControlCluster.h、ClosureControlCluster.cpp、ClosureControlClusterDelegate.hDimension 集群实现ClosureDimensionCluster.h、GenericDimensionState.h、closure-dimension-server.h旧接口兼容层closure-control-server/CodegenIntegration.h、closure-dimension-server/CodegenIntegration.h数据模型定义closure-control-cluster.xml、closure-dimension-cluster.xml单元测试TestClosureControlCluster.cpp、TestClosureDimensionCluster.cpp示例索引占位docs/examples/closure.md【免费下载链接】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），仅供参考
Matter Closure 闭锁设备集群开发实战基于 connectedhomeip 源码解析 Closure Control 与 Closure Dimension Cluster 的集成方式【免费下载链接】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导读本文面向希望在 Matterconnectedhomeip 项目中为电动窗帘、卷帘门、百叶窗等闭锁Closure设备实现服务端能力的开发者系统讲解 Matter 新引入的 Closure Control闭锁控制与 Closure Dimension闭锁维度两个集群的源码级集成方案。文章以 Closure Control Cluster README 与 Closure Dimension Cluster README 为骨架结合ClosureControlCluster.h、ClosureDimensionCluster.h等源码完整覆盖 Delegate 实现、Feature 配置、集群注册、初始化时序与一致性校验Conformance Validation并给出新旧两套 API 的迁移对照。读完本文你将能够在一个 Matter 应用上从零挂载可用的 Closure 服务端集群并理解其底层运行机制。说明闭锁Closure示例应用在本次仓库快照中尚未落地docs/examples/closure.md 仅包含指向closure-app/**/README的索引占位Closure 相关功能的权威资料集中在src/app/clusters/closure-control-server/与src/app/clusters/closure-dimension-server/两个源码目录中本文即基于这两份 README 及其实现展开。一、Closure 集群在 Matter 体系中的定位Matter 将家居设备的统一数据模型抽象为「端点Endpoint上的集群Cluster」。闭锁设备窗帘、卷帘、百叶窗、车库门等在 Matter 中由两个彼此配合的集群描述Closure Control Cluster闭锁控制集群负责控制闭锁设备的整体行为包括定位Positioning、运动闩锁Motion Latching以及运行状态监控Operational State。它面向一扇逻辑闭锁的整体控制例如把整扇卷帘移到 50%。Closure Dimension Cluster闭锁维度集群负责控制组合式闭锁composed closure中的单一自由度single degree of freedom也称 dimension / axis。例如一扇由帘体升降 叶片翻转两个轴组成的百叶窗每个轴由一个 Dimension 集群实例描述。两者的关系可以理解为Control 是面向设备的顶层控制面Dimension 是面向机械轴的细分控制面。二者共享位置Positioning与运动闩锁Motion Latching等核心概念因此实现模式高度一致。在数据模型层面两个集群的定义均来自 ZAP 模板中的数据模型 XMLclosure-control-cluster.xml 与 closure-dimension-cluster.xml集群语义源头为ClosureControl.adoc规范文档见 XML 中Source字段。二、Closure Control Cluster控制面实现2.1 设计哲学代码驱动Code-Driven替代旧式 CodegenClosureControlCluster.h 开头的头文件注释点明了这一实现的关键取舍这是一个代码驱动的 C 服务端实现其设计目标就是摆脱旧式 codegenZAP 代码生成实现中的紧耦合追求更高的灵活性。与此配套集群通过**委托模式Delegate Pattern**与业务逻辑解耦chip::app::Clusters::ClosureControl::ClosureControlClusterDelegate应用层只需实现该 Delegate 的虚方法即可向集群提供闭锁状态、响应控制命令而无需关心 Matter 消息框架的细节。测试代码 TestClosureControlCluster.cpp 中的MockDelegate展示了 Delegate 需要实现的核心命令入口包括HandleStopCommand()处理 Stop停止命令HandleMoveToCommand(tag, latch, speed)处理 MoveTo移动到目标位置命令参数为TargetPositionEnum目标位置标签、可选的latch闩锁标志与ThreeLevelAutoEnum速度档位HandleCalibrateCommand()处理 Calibrate校准命令IsReadyToMove()查询设备是否可移动例如夹手保护状态下应返回 false。2.2 完整集成四步走根据 Closure Control Cluster README将ClosureControlCluster接入应用的流程分为四步Step 1实现 Delegate创建一个继承ClosureControlClusterDelegate的类并实现其虚方法以处理命令、提供闭锁状态#include app/clusters/closure-control-server/ClosureControlClusterDelegate.h class MyClosureControlDelegate : public chip::app::Clusters::ClosureControl::ClosureControlClusterDelegate { };Step 2用 Builder 风格构建 Config通过ClosureControlCluster::Config配置集群的 FeatureMap、可选属性与初始状态。Config 采用链式With*方法逐项开启 Feature创建集群前配置必须满足一致性要求详见第四节#include app/clusters/closure-control-server/ClosureControlCluster.h using namespace chip::app::Clusters::ClosureControl; auto config ClosureControlCluster::Config(/* endpoint */ 1, gMyDelegate, gTimerDelegate) .WithPositioning() .WithCalibration() // 按需继续开启其他 Feature // WithSpeed(), WithVentilation(), WithPedestrian(), // WithProtection(), WithManuallyOperable(), WithAccess(), // WithInstantaneous()... .WithMotionLatching(chip::BitFlagsLatchControlModesBitmap() .Set(LatchControlModesBitmap::kRemoteLatching) .Set(LatchControlModesBitmap::kRemoteUnlatching)) .WithCountdownTime() .WithInitialMainState(MainStateEnum::kStopped);对照源码 ClosureControlCluster.hConfig的构造参数包含端点号EndpointId、Delegate 引用与 TimerDelegate 引用每个With*方法都会在mFeatureMap中置位对应 FeatureWith*方法开启的 Feature附带配置项WithPositioning()kPositioning定位位置控制WithMotionLatching(BitFlagsLatchControlModesBitmap)kMotionLatching闩锁模式位图如kRemoteLatching远程闩锁、kRemoteUnlatching远程解闩WithSpeed()kSpeed速度控制WithVentilation()kVentilation通风模式WithPedestrian()kPedestrian行人防夹模式WithCalibration()kCalibration校准WithProtection()kProtection保护WithManuallyOperable()kManuallyOperable可手动操作WithAccess()kAccess访问控制WithInstantaneous()kInstantaneous瞬时动作WithCountdownTime(initial)可选属性CountdownTime倒计时时间默认NullNullable类型为可空的ElapsedSWithInitialMainState(mainState)—初始主状态如MainStateEnum::kStoppedWithInitialOverallCurrentState(...)—初始综合当前状态GenericOverallCurrentStateStep 3实例化 Delegate 与集群为每个需要 Closure 能力的端点实例化一个 Delegate 与一个ClosureControlCluster推荐使用RegisteredServerCluster简化注册过程#include app/server-cluster/ServerClusterInterfaceRegistry.h #include lib/support/DefaultTimerDelegate.h // 放在 .cpp 文件中 MyClosureControlDelegate gMyDelegate; chip::support::DefaultTimerDelegate gTimerDelegate; chip::app::RegisteredServerClusterchip::app::Clusters::ClosureControl::ClosureControlCluster gClosureControlCluster(config);Step 4向 CodegenDataModelProvider 注册集群在应用初始化序列中把集群实例注册到CodegenDataModelProvider从而将其挂入 Matter 数据模型与消息处理框架。注册必须发生在服务器启动之前#include data-model-providers/codegen/CodegenDataModelProvider.h void ApplicationInit() { // ... 其他初始化 // 在 server 启动前注册集群 CHIP_ERROR err chip::app::CodegenDataModelProvider::Instance().Registry().Register( gClosureControlCluster.Registration()); VerifyOrDie(err CHIP_NO_ERROR); // ... server 后续才启动 }注册完成后集群的所有 setter/getter 都可以直接通过gClosureControlCluster.Cluster()调用。2.3 新旧两套集成 APIREADME 特别指出出于向后兼容仓库保留了旧式ZAP codegen 模式接口位于 CodegenIntegration.h通过Interface类暴露#include app/clusters/closure-control-server/CodegenIntegration.h using namespace chip::app::Clusters::ClosureControl; MyClosureControlDelegate gMyDelegate; Interface gClosureControlInterface(/* endpoint */ 1, gMyDelegate); CHIP_ERROR ApplicationInit() { ClusterConformance conformance; conformance.FeatureMap().Set(Feature::kPositioning).Set(Feature::kCalibration); ClusterInitParameters initParams; initParams.mMainState MainStateEnum::kStopped; initParams.mLatchControlModes.Set(LatchControlModesBitmap::kRemoteLatching) .Set(LatchControlModesBitmap::kRemoteUnlatching); return gClosureControlInterface.Init(conformance, initParams); }Init()成功后通过gClosureControlInterface.Cluster()访问集群。官方建议迁移到新的直接实例化方式即 2.2 节四步流程以提升性能并减小应用体积footprint。三、Closure Dimension Cluster维度轴面实现3.1 与 Control 集群的对称设计Closure Dimension Cluster 用于控制组合式闭锁的单一轴实现同样采用代码驱动 Delegate 模式chip::app::Clusters::ClosureDimension::ClosureDimensionClusterDelegate其集成流程与 Control 集群几乎一一对应见 ClosureDimensionCluster.h 的Config但With*方法携带了更强的轴语义参数With*方法开启的 Feature附带配置项WithPositioning(resolution, stepValue)kPositioningPercent100ths分辨率与步进值源码默认均为 1WithMotionLatching(latchControlModes)kMotionLatchingLatchControlModesBitmap闩锁模式位图WithUnit(unit, unitRange)kUnitClosureUnitEnum单位与可空的UnitRangeStruct量程WithLimitation(limitRange)kLimitationRangePercent100thsStruct限制范围WithSpeed()kSpeed速度WithTranslation(translationDirection)kTranslationTranslationDirectionEnum平移方向如kDownwardWithRotation(rotationAxis, overflow)kRotationRotationAxisEnum旋转轴与OverflowEnum溢出行为WithModulation(modulationType)kModulationModulationTypeEnum调制类型WithAccess()kAccess访问控制3.2 代码驱动的集成流程Step 1实现 Delegate#include app/clusters/closure-dimension-server/ClosureDimensionClusterDelegate.h class MyClosureDimensionDelegate : public chip::app::Clusters::ClosureDimension::ClosureDimensionClusterDelegate { };Step 2配置 ClusterConformance 与初始化参数#include app/clusters/closure-dimension-server/ClosureDimensionCluster.h chip::app::Clusters::ClosureDimension::ClusterConformance conformance; conformance.FeatureMap().Set(chip::app::Clusters::ClosureDimension::Feature::kPositioning); conformance.FeatureMap().Set(chip::app::Clusters::ClosureDimension::Feature::kMotionLatching); // 按需添加其他 Feature // 可选配置初始化参数启用 translation / rotation / modulation 时需要 chip::app::Clusters::ClosureDimension::ClusterInitParameters initParams; initParams.translationDirection chip::app::Clusters::ClosureDimension::TranslationDirectionEnum::kDownward; // 需要时再设置 initParams.rotationAxis / initParams.modulationTypeStep 3实例化 Delegate 与集群Dimension 集群通过Context结构体一次性携带 delegate、conformance 与 initParams#include app/server-cluster/ServerClusterInterfaceRegistry.h // 放在 .cpp 文件中 MyClosureDimensionDelegate gMyDelegate; chip::app::Clusters::ClosureDimension::ClosureDimensionCluster::Context clusterContext{ .delegate gMyDelegate, .conformance conformance, .initParams initParams }; chip::app::RegisteredServerClusterchip::app::Clusters::ClosureDimension::ClosureDimensionCluster gClosureDimensionCluster( chip::EndpointId{ 2 }, clusterContext);Step 4注册到 CodegenDataModelProvider与 Control 集群完全一致且同样必须在服务器启动前完成#include data-model-providers/codegen/CodegenDataModelProvider.h void ApplicationInit() { // ... 其他初始化 CHIP_ERROR err chip::app::CodegenDataModelProvider::Instance().Registry().Register( gClosureDimensionCluster.Registration()); VerifyOrDie(err CHIP_NO_ERROR); // ... server 启动 }3.3 维度状态与旧接口源码目录中另有 GenericDimensionState.h 提供通用的维度轴状态管理支撑。README 明确说明旧式ClusterLogic与MatterContext类已被移除新实现不再需要它们其余 API 为向后兼容保留仍可通过 CodegenIntegration.h 中的旧式Interface类访问。四、一致性校验Conformance Validation失败即致命两个 README 都以醒目的方式强调同一规则The cluster performs strict conformance validation during construction.Any validation failure is fataland will terminate the application with Invalid Conformance message.即集群在构造阶段执行严格的一致性Conformance校验任何校验失败都是致命的应用将终止并输出 Invalid Conformance 信息。这意味着Config或旧式ClusterConformance中开启的 Feature 组合必须满足 Matter 规范的一致性约束例如启用kMotionLatching时必须同时提供合法的LatchControlModesBitmap启用kTranslation/kRotation/kModulation时必须给出对应的方向、轴或调制类型参数校验发生在服务器启动之前构造/注册阶段因此问题会在启动早期立刻暴露而不是在运行时才产生模糊错误。测试目录下的 TestClosureControlCluster.cpp 与 TestClosureDimensionCluster.cpp 中大量用例通过构造合法/非法配置来验证这一校验逻辑可作为自测与排查的参考。五、初始化时序与迁移指南5.1 推荐的代码驱动时序以 Closure Control README 的 Initialization Sequence 为准服务器启动前Before Server Startup用With*builder 方法构建ClosureControlCluster::Config或 Dimension 集群的Context确定 Feature 与初始状态实例化 Delegate 与集群向CodegenDataModelProvider注册集群。服务器启动后After Startup4. 集群实例上的所有 getter/setter 均可安全直接调用。5.2 从旧式 API 迁移两个 README 都给出了相同的迁移建议推荐用法直接实例化集群RegisteredServerCluster...CodegenDataModelProvider注册获得更优性能与更小 footprint兼容用法继续使用Interface通过CodegenIntegration.h其初始化通过ClusterConformanceClusterInitParameters完成对 Dimension 集群而言迁移时还需注意ClusterLogic与MatterContext已删除不要继续引用。六、总结与源码索引Closure Control 与 Closure Dimension 是 Matter 闭锁设备的两个核心集群connectedhomeip 中的实现采用代码驱动 Delegate 模式强调与业务解耦、构造期严格一致性校验、并保留旧式接口向后兼容。开发者按实现 Delegate → 构建 Config/Conformance → 实例化集群 → 启动前注册四步即可完成接入。关键文件索引均可直接在当前仓库中阅读集群 READMEclosure-control-server/README.md、closure-dimension-server/README.mdControl 集群实现ClosureControlCluster.h、ClosureControlCluster.cpp、ClosureControlClusterDelegate.hDimension 集群实现ClosureDimensionCluster.h、GenericDimensionState.h、closure-dimension-server.h旧接口兼容层closure-control-server/CodegenIntegration.h、closure-dimension-server/CodegenIntegration.h数据模型定义closure-control-cluster.xml、closure-dimension-cluster.xml单元测试TestClosureControlCluster.cpp、TestClosureDimensionCluster.cpp示例索引占位docs/examples/closure.md【免费下载链接】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），仅供参考
