窗帘 Cluster（WindowCovering）

Cluster ID: 0x0102  |  所在 Endpoint: 通常在 Endpoint 1（功能端点）

WindowCovering 是 Matter 中控制窗帘类设备的核心 Cluster，适用于电动卷帘、百叶窗、窗帘轨道、遮阳篷、投影幕布等所有需要「升降」或「倾斜」控制的设备。 它定义了窗帘的运动控制命令、位置反馈属性，以及设备类型与安全状态的完整描述。

命令（Commands）

WindowCovering Cluster 共有 7 个命令。基础三件套（UpOrOpen / DownOrClose / StopMotion）是所有窗帘设备都支持的， 后四个精确定位命令需要设备启用对应的 Feature 组合。 点击下方表格中的命令 ID 可跳转到对应的详细说明。

UpOrOpen — 升起 / 打开（0x00）

将窗帘向「全开」方向运动。对卷帘来说是向上收起，对窗帘轨道来说是向两侧拉开。 不需要任何参数，设备收到后立即开始运动，直到到达全开位置或收到 StopMotion 命令。

↑ 返回命令列表

DownOrClose — 降下 / 关闭（0x01）

将窗帘向「全关」方向运动。对卷帘来说是向下展开，对窗帘轨道来说是向中间合拢。 不需要任何参数，设备收到后立即运动到全关位置。

↑ 返回命令列表

StopMotion — 停止运动（0x02）

立即停止窗帘所有轴的运动（升降和倾斜）。不需要参数。 停止后 OperationalStatus 的所有运动位归零。

↑ 返回命令列表

GoToLiftValue — 升降到绝对值（0x04）

将窗帘升降到指定的绝对位置值。这个值对应设备内部的物理单位（如电机步数）， 范围由 InstalledOpenLimitLift 和 InstalledClosedLimitLift 决定。

↑ 返回命令列表

GoToLiftPercentage — 升降到百分比（0x05）

将窗帘升降到指定的百分比位置。这是最常用的精确控制命令。 参数使用 percent100ths（百分之一的百分比，范围 0–10000），0 = 全开，10000 = 全关。

↑ 返回命令列表

GoToTiltValue — 倾斜到绝对值（0x07）

将百叶窗叶片倾斜到指定的绝对位置值。仅支持带倾斜功能的百叶窗类设备。

↑ 返回命令列表

GoToTiltPercentage — 倾斜到百分比（0x08）

将百叶窗叶片倾斜到指定的百分比位置。与升降百分比逻辑一致， 0 = 叶片完全打开（平行于窗面），10000 = 叶片完全关闭（垂直于窗面）。

↑ 返回命令列表

属性详解

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

类型与配置（0x0000, 0x000D, 0x0007, 0x0017）

描述窗帘设备的物理类型、产品分类以及当前的配置和运行模式。

Type 枚举值

EndProductType 枚举值

ConfigStatus 位图

Mode 位图

↑ 返回属性列表

升降位置（0x0001–0x0011）

描述窗帘升降轴的当前位置、目标位置和行程极限。所有升降属性需要设备支持 LF（Lift） 特性。

↑ 返回属性列表

倾斜位置（0x0002–0x0013）

描述窗帘倾斜轴（百叶窗叶片角度）的当前位置、目标位置和行程极限。所有倾斜属性需要设备支持 TL（Tilt） 特性。

↑ 返回属性列表

运行状态（0x000A, 0x001A）

描述窗帘当前的运动方向和安全异常状态。

OperationalStatus 位图

SafetyStatus 位图

↑ 返回属性列表

Feature 位图

WindowCovering Cluster 通过 FeatureMap（0xFFFC）声明设备支持哪些能力。Feature 的组合决定了哪些命令和属性可用：

示例数据

一个支持升降 + 位置感知的电动卷帘在 30% 位置（接近全开）时的 WindowCovering Cluster 读取结果：

{
  // --- 类型与配置 ---
  "0x0000": 0,              // Type = Rollershade（卷帘）
  "0x000D": 0,              // EndProductType = RollerShade
  "0x0007": 0x09,           // ConfigStatus = Operational + LiftPositionAware
  "0x0017": 0x00,           // Mode = 正常运行（所有位为 0）

  // --- 升降位置 ---
  "0x000E": 3000,           // CurrentPositionLiftPercent100ths = 30.00%
  "0x0008": 30,             // CurrentPositionLiftPercentage = 30%
  "0x000B": 3000,           // TargetPositionLiftPercent100ths = 30.00%（目标与当前一致，已停止）
  "0x0010": 0,              // InstalledOpenLimitLift = 0（全开位置）
  "0x0011": 10000,          // InstalledClosedLimitLift = 10000（全关位置）

  // --- 运行状态 ---
  "0x000A": 0x00,           // OperationalStatus = 所有轴已停止
  "0x001A": 0x0000          // SafetyStatus = 无异常
}

常见场景