阀门控制 Cluster（ValveConfigurationAndControl）

Cluster ID: 0x0081 | 所在 Endpoint: 通常在 Valve Endpoint（阀门功能端点）

ValveConfigurationAndControl 是 Matter 中控制阀门设备的核心 Cluster，适用于水阀、燃气阀、灌溉阀等需要「开/关/定时/开度调节」能力的场景。它定义了阀门的开关命令、持续时间控制、当前/目标状态、开度百分比、故障检测和事件上报等全部能力。与简单的 OnOff 开关不同，阀门 Cluster 内置了定时自动关阀和精确开度控制，更适合需要安全保护的流体控制场景。

Feature 驱动的能力差异

ValveConfigurationAndControl 的能力取决于两个 Feature： TimeSync（TS） 启用基于 UTC 时间戳的自动关阀能力， Level（LVL） 启用百分比开度控制（0~100%）。一个简单的水阀可能只支持全开/全关，而一个灌溉控制阀可能同时支持定时和开度调节。开发前先读取 FeatureMap (0xFFFC)，确认设备支持哪些能力，再决定 UI 布局。

命令（Commands）

ValveConfigurationAndControl Cluster 共有 2 个命令：Open 和 Close。 Open 命令支持可选的持续时间和目标开度参数，Close 命令无参数直接关阀。点击下方表格中的命令 ID 可跳转到对应的详细说明。

ID	名称	说明	所需特性
`0x00`	Open	打开阀门（可指定持续时间和开度）	无
`0x01`	Close	关闭阀门	无

Open —— 打开阀门（0x00）

打开阀门。可以通过可选参数指定开阀持续时间和目标开度。如果不传任何参数，阀门按 DefaultOpenDuration 的时间全开。如果阀门已经打开，再次发送 Open 命令会更新持续时间和目标开度。

参数	类型	是否必选	说明
OpenDuration	elapsed-s / null	可选	开阀持续时间，单位秒。`null` 表示使用 DefaultOpenDuration 的值。省略时也使用默认值
TargetLevel	percent	可选（需 LVL）	目标开度百分比，1~100。省略时全开（100%）。需要 LVL Feature

安全提示：DefaultOpenDuration

如果 DefaultOpenDuration 为 null 且 Open 命令也未指定 OpenDuration，阀门将无限期保持打开状态，直到收到 Close 命令。对于水阀和燃气阀，建议始终设置 DefaultOpenDuration 作为安全兜底，防止网络断连后阀门长期开启导致水漫或气泄。

使用场景

用户在 App 上点击「打开水阀」按钮，发送 Open 命令，阀门打开。花园灌溉系统发送 Open(OpenDuration=1800)，阀门开启 30 分钟后自动关闭。智能暖通系统发送 Open(TargetLevel=50)，阀门打开到 50% 开度，精确控制热水流量。

↑ 返回命令列表

Close —— 关闭阀门（0x01）

关闭阀门。没有任何参数。执行成功后，TargetState 变为 Closed (0)，阀门开始执行关闭动作。如果阀门正在定时开启中，Close 命令会取消定时并立即关阀。

使用场景

用户手动关闭水阀、水浸传感器检测到漏水后自动化规则触发紧急关阀、燃气报警器联动关闭燃气阀门时调用。

↑ 返回命令列表

属性详解

ValveConfigurationAndControl Cluster 的属性按功能分为四组。点击下方汇总表中的属性 ID 可跳转到对应的详细说明。

ID	名称	类型	分组	说明
`0x0000`	OpenDuration	elapsed-s / null	定时参数	当前开阀持续时间（秒）
`0x0001`	DefaultOpenDuration	elapsed-s / null	定时参数	默认开阀持续时间（秒）
`0x0002`	AutoCloseTime	epoch-us / null	定时参数	自动关阀的 UTC 时间戳
`0x0003`	RemainingDuration	elapsed-s / null	定时参数	剩余开阀时间（秒）
`0x0004`	CurrentState	ValveStateEnum / null	阀门状态	当前阀门状态
`0x0005`	TargetState	ValveStateEnum / null	阀门状态	目标阀门状态
`0x0006`	CurrentLevel	percent / null	开度控制	当前开度百分比
`0x0007`	TargetLevel	percent / null	开度控制	目标开度百分比
`0x0008`	DefaultOpenLevel	percent	开度控制	Open 命令未带 TargetLevel 时使用的默认开度
`0x000A`	LevelStep	uint8	开度控制	开度调节步长
`0x0009`	ValveFault	ValveFaultBitmap	故障状态	阀门故障位图

定时参数（0x0000 ~ 0x0003）

控制阀门的开启持续时间和自动关闭机制。这是阀门 Cluster 区别于简单 OnOff 开关的关键能力 —— 内置定时保护，防止阀门意外长期开启。

ID	名称	类型	说明
`0x0000`	OpenDuration 开阀持续时间	elapsed-s / null	本次开阀的持续时间，单位秒。由 Open 命令设置。`null` 表示无限期开启（直到收到 Close 命令）。阀门关闭后此值变为 `null`
`0x0001`	DefaultOpenDuration 默认开阀时间	elapsed-s / null	当 Open 命令未指定 OpenDuration 时使用的默认值，单位秒。可读写。`null` 表示无默认时间（Open 不带参数时将无限期开启）。建议设置一个合理的安全值
`0x0002`	AutoCloseTime 自动关阀时间	epoch-us / null	阀门将自动关闭的 UTC 时间戳，单位微秒。由设备根据 OpenDuration 和开阀时间自动计算。`null` 表示无自动关闭计划。需要 TS Feature
`0x0003`	RemainingDuration 剩余开阀时间	elapsed-s / null	距离自动关阀还剩多少秒。设备自动维护，倒计时归零后阀门关闭。`null` 表示无定时或阀门已关闭

定时参数之间的关系

DefaultOpenDuration 是预设值，OpenDuration 是本次实际生效值， RemainingDuration 是实时倒计时，AutoCloseTime 是绝对时间点。 Open 命令不带参数时，OpenDuration = DefaultOpenDuration；带参数时，OpenDuration = 命令参数值。 App 界面通常显示 RemainingDuration 作为倒计时。

↑ 返回属性列表

阀门状态（0x0004 ~ 0x0005）

描述阀门当前的开关状态和目标状态。阀门动作需要时间（电机驱动），所以 CurrentState 和 TargetState 可能不一致 —— 阀门正在动作时 CurrentState 为 Transitioning。

ID	名称	类型	说明
`0x0004`	CurrentState 当前状态	ValveStateEnum / null	阀门当前的实际状态。Nullable —— `null` 表示设备无法确定当前状态（如刚上电、无位置传感器）
`0x0005`	TargetState 目标状态	ValveStateEnum / null	阀门的目标状态。发送 Open 命令后变为 `Open (1)`，发送 Close 后变为 `Closed (0)`。Nullable —— `null` 表示无待执行的目标

状态转换流程

发送 Open 命令后：TargetState 立即变为 Open，CurrentState 变为 Transitioning，阀门电机开始动作。到位后 CurrentState 变为 Open。 Close 命令同理。App 界面应根据 CurrentState 显示实时状态，当值为 Transitioning 时可显示加载动画。

↑ 返回属性列表

开度控制（0x0006 ~ 0x0008, 0x000A）

控制阀门的精确开度百分比。需要设备支持 Level（LVL） Feature。不支持 LVL 的阀门只有全开/全关两种状态。

ID	名称	类型	说明
`0x0006`	CurrentLevel 当前开度	percent / null	阀门当前的实际开度百分比，0~100。`0` = 全关，`100` = 全开。Nullable —— `null` 表示无法确定当前开度。需要 LVL Feature
`0x0007`	TargetLevel 目标开度	percent / null	阀门的目标开度百分比，1~100。由 Open 命令的 TargetLevel 参数设置。Nullable —— `null` 表示无待执行的目标开度。需要 LVL Feature
`0x0008`	DefaultOpenLevel 默认开度	percent	Open 命令未携带 TargetLevel 参数时，阀门使用的默认目标开度，1~100。默认值 `100`（全开）。需要 LVL Feature，可选属性
`0x000A`	LevelStep 开度步长	uint8	阀门开度可调节的最小步长，1~50。例如为 `10` 时只能设置 10%、20%…… 默认值 `1`。需要 LVL Feature，可选属性

开度与状态的关系

CurrentLevel = 0 等价于 CurrentState = Closed， CurrentLevel > 0 等价于 CurrentState = Open。对于支持 LVL 的设备，App 可以用滑块控件让用户精确设置开度， Open 命令的 TargetLevel 参数值即对应滑块位置。

↑ 返回属性列表

故障状态（0x0009）

记录阀门的故障信息。ValveFault 是一个位图属性，多个故障可以同时存在。

ID	名称	类型	说明
`0x0009`	ValveFault 阀门故障	ValveFaultBitmap	阀门故障位图，每个位代表一种故障类型。`0` = 无故障。详见下方 ValveFaultBitmap 章节

↑ 返回属性列表

枚举与位图

ValveStateEnum（阀门状态枚举）

用于 CurrentState 和 TargetState 属性，描述阀门的开关状态。

Closed 关闭 —— 阀门完全关闭，无流体通过

Open 打开 —— 阀门已打开（全开或部分开启）

Transitioning 过渡中 —— 阀门正在执行开启或关闭动作（电机运转中）

ValveFaultBitmap（阀门故障位图）

ValveFault (0x0009) 属性的位图定义。每个位代表一种故障类型，多个位可以同时置位。当任意位从 0 变为 1 时，设备会上报 ValveFault 事件。

Bit 0

GeneralFault 通用故障 —— 未归类的一般性硬件或软件问题

Bit 1

Blocked 阻塞 —— 阀门机械卡住，无法正常开启或关闭

Bit 2

Leaking 泄漏 —— 阀门关闭状态下仍检测到流体通过

Bit 3

NotConnected 未连接 —— 阀门执行器与控制器之间通信断开

Bit 4

ShortCircuit 短路 —— 阀门电机或驱动电路发生短路

Bit 5

CurrentExceeded 过流 —— 阀门电机电流超出安全范围

故障位图读取示例

ValveFault = 0x00（十进制 0）= 无故障，一切正常。
ValveFault = 0x06（十进制 6）= Bit 1 + Bit 2 = 阀门卡住且有泄漏 —— 需要立即检修。
ValveFault = 0x30（十进制 48）= Bit 4 + Bit 5 = 电路短路且过流 —— 可能是电机损坏，需要断电检查。

Feature 位图

ValveConfigurationAndControl Cluster 通过 FeatureMap（0xFFFC）声明设备支持哪些高级能力：

Bit 0

TS（TimeSync）时间同步 —— 启用 AutoCloseTime 属性，设备可基于 UTC 时间戳精确计算自动关阀时刻。需要设备接入 Time Synchronization Cluster

Bit 1

LVL（Level）开度控制 —— 启用 CurrentLevel、TargetLevel 属性和 Open 命令的 TargetLevel 参数，支持 0~100% 精确开度调节

Feature 组合示例

一个简单的水阀（开/关）：FeatureMap = 0x00，只支持全开全关和基于秒数的定时。
一个灌溉控制阀：FeatureMap = 0x03（TS + LVL），支持精确开度调节和基于 UTC 时间的自动关阀。
一个带时间同步的燃气阀：FeatureMap = 0x01（仅 TS），只能全开全关，但支持 UTC 时间戳的精确定时。

事件（Events）

ValveConfigurationAndControl Cluster 定义了 2 个事件，分别用于阀门状态变化通知和故障上报。

ID	名称	优先级	数据字段	说明
`0x00`	ValveStateChanged	INFO	ValveState (ValveStateEnum), ValveLevel (percent)	阀门状态或开度发生变化时触发
`0x01`	ValveFault	WARNING	ValveFault (ValveFaultBitmap)	阀门故障位图发生变化时触发（新增或清除故障）

事件订阅建议

ValveStateChanged 事件包含变化后的状态和开度值，App 订阅后可实时更新界面，无需轮询 CurrentState 和 CurrentLevel 属性。 ValveFault 事件在故障出现或消除时都会触发，携带最新的完整故障位图。对于水阀和燃气阀，建议始终订阅 ValveFault 事件并在收到 Leaking（泄漏）故障时立即告警。

示例数据

一个支持 Level（LVL）特性的智能水阀在 75% 开度运行中的 ValveConfigurationAndControl Cluster 读取结果：

{
  // --- 定时参数 ---
  "0x0000": 1800,            // OpenDuration = 1800 秒（本次开阀 30 分钟）
  "0x0001": 3600,            // DefaultOpenDuration = 3600 秒（默认每次开阀 1 小时）
  "0x0002": null,            // AutoCloseTime = null（未设置自动关阀时间点）
  "0x0003": 1200,            // RemainingDuration = 1200 秒（还剩 20 分钟关阀）

  // --- 阀门状态 ---
  "0x0004": 1,               // CurrentState = Open（当前已打开）
  "0x0005": 1,               // TargetState = Open（目标也是打开）

  // --- 开度控制（LVL Feature）---
  "0x0006": 75,              // CurrentLevel = 75%（当前开度 75%）
  "0x0007": 75,              // TargetLevel = 75%（目标开度 75%）
  "0x0008": 100,             // DefaultOpenLevel = 100%（Open 命令不带开度时默认全开）
  "0x000A": 1,               // LevelStep = 1%（开度调节步长）

  // --- 故障状态 ---
  "0x0009": 0                // ValveFault = 0（无故障）
}

开发提示

最简单的阀门可能只有 OpenDuration、DefaultOpenDuration、RemainingDuration、CurrentState、TargetState 和 ValveFault 这几个核心属性。 CurrentLevel / TargetLevel 需要 LVL Feature，AutoCloseTime 需要 TS Feature。读取前先检查 FeatureMap (0xFFFC)，对不支持的属性发起读取会返回 UNSUPPORTED_ATTRIBUTE。

常见场景

场景 1：花园灌溉定时浇水

查看步骤

写入 DefaultOpenDuration (0x0001) = 1800，预设每次浇水 30 分钟
自动化规则在早晨 6 点触发，发送 Open (0x00) 命令（不带参数，使用默认时间）
阀门打开，CurrentState 变为 Open (1)，RemainingDuration 开始从 1800 倒计时
App 订阅 RemainingDuration (0x0003)，界面显示「还剩 XX 分钟自动关闭」
30 分钟后阀门自动关闭，CurrentState 变为 Closed (0)
如果需要中途取消浇水，发送 Close (0x01) 命令立即关阀
订阅 ValveFault 事件，当检测到 Blocked (Bit 1) 时提醒用户清理阀门

场景 2：水浸传感器联动紧急关阀

查看步骤

水浸传感器（BooleanState Cluster）检测到漏水，StateValue 变为 true
自动化规则触发，向水阀发送 Close (0x01) 命令紧急关阀
读取 CurrentState (0x0004) 确认阀门已关闭（Closed = 0）
如果 CurrentState 为 Transitioning (2)，等待几秒后再次确认
检查 ValveFault (0x0009) 位图中的 Leaking (Bit 2) 位 —— 如果阀门关闭后仍检测到泄漏，说明阀门密封失效，需要人工干预
向用户推送告警通知：「检测到漏水，已自动关闭水阀。请检查现场。」
漏水解除后，用户手动发送 Open 命令恢复供水