颜色控制 Cluster（ColorControl）

Cluster ID: 0x0300  |  所在 Endpoint: 通常在 Endpoint 1（功能端点，与 OnOff / LevelControl 同端点）

ColorControl 是 Matter 灯具设备的颜色控制核心 Cluster，支持通过三种颜色模型控制灯光颜色： Hue/Saturation（色相/饱和度）、XY 色坐标（CIE 1931）、Color Temperature（色温，单位 Mireds）。 此外还支持 Enhanced Hue（16-bit 高精度色相）和 Color Loop（自动循环变色）等高级功能。

Feature 能力（Feature Map）

ColorControl 通过 Feature Map 声明设备支持哪些颜色控制能力。不同能力决定了可用的命令和属性集合。 读取 ColorCapabilities (0x400A) 可以获取设备支持的能力位图。

命令（Commands）

ColorControl 定义了 19 个命令，按颜色模型分为五组：Hue/Saturation 控制、XY 色坐标控制、色温控制、Enhanced Hue 控制、Color Loop 控制。 点击下方表格中的命令 ID 可跳转到对应的详细说明。

所有命令都支持 OptionsMask 和 OptionsOverride 参数，用于临时覆盖 Options (0x000F) 属性中的 ExecuteIfOff 标志位。

MoveToHue —— 移动到指定色相（0x00）

将灯光色相平滑过渡到目标值。Hue 取值 0~254，映射到 0°~360° 色环。Direction 参数控制色环上的过渡方向。

↑ 返回命令列表

MoveHue —— 持续移动色相（0x01）

以恒定速率持续移动色相值，直到收到 StopMoveStep 或色相到达自然边界。

↑ 返回命令列表

StepHue —— 色相步进（0x02）

将色相增加或减少一个指定的步长值。

↑ 返回命令列表

MoveToSaturation —— 移动到指定饱和度（0x03）

将灯光饱和度平滑过渡到目标值。Saturation 取值 0~254，0 为无色（白光），254 为最高饱和度。

↑ 返回命令列表

MoveSaturation —— 持续移动饱和度（0x04）

以恒定速率持续移动饱和度值，直到收到 StopMoveStep。参数结构同 MoveHue。

↑ 返回命令列表

StepSaturation —— 饱和度步进（0x05）

将饱和度增加或减少一个指定的步长值。参数结构同 StepHue。

↑ 返回命令列表

MoveToHueAndSaturation —— 同时设置色相和饱和度（0x06）

一次命令同时设置色相和饱和度，比分开发送两个命令更高效，过渡更平滑。

↑ 返回命令列表

MoveToColor —— 移动到指定 XY 色坐标（0x07）

将灯光颜色过渡到指定的 CIE 1931 XY 色坐标。X 和 Y 取值 0~0xFEFF，映射到 0.0~1.0 的色度坐标。

↑ 返回命令列表

MoveColor —— 持续移动 XY 色坐标（0x08）

以恒定速率在 XY 色度平面上持续移动。

↑ 返回命令列表

StepColor —— XY 色坐标步进（0x09）

将 X 和 Y 坐标各增加/减少一个步长值。

↑ 返回命令列表

MoveToColorTemperature —— 移动到指定色温（0x0A）

将灯光色温平滑过渡到目标值。目标值会被裁剪到 [ColorTempPhysicalMinMireds, ColorTempPhysicalMaxMireds] 范围内。 这是色温灯最常用的命令。

↑ 返回命令列表

MoveColorTemperature —— 持续移动色温（0x4B）

以恒定速率持续移动色温值，并可指定移动的上下限范围。

↑ 返回命令列表

StepColorTemperature —— 色温步进（0x4C）

将色温增加或减少一个指定的步长值，并可指定步进的上下限范围。

↑ 返回命令列表

EnhancedMoveToHue —— 移动到指定 Enhanced Hue（0x40）

与 MoveToHue 类似，但使用 16-bit Enhanced Hue（0~0xFFFF），精度是标准 Hue 的 256 倍。 适用于需要精细颜色控制的场景。

↑ 返回命令列表

EnhancedMoveHue —— 持续移动 Enhanced Hue（0x41）

以恒定速率持续移动 Enhanced Hue 值。参数结构类似 MoveHue，但 Rate 为 uint16。

↑ 返回命令列表

EnhancedStepHue —— Enhanced Hue 步进（0x42）

将 Enhanced Hue 增加或减少一个指定的步长值。参数结构类似 StepHue，但 StepSize 为 uint16。

↑ 返回命令列表

EnhancedMoveToHueAndSaturation —— 同时设置 Enhanced Hue 和 Saturation（0x43）

一次命令同时设置 16-bit Enhanced Hue 和 8-bit Saturation。

↑ 返回命令列表

ColorLoopSet —— 配置 Color Loop（0x44）

配置并激活/关闭 Color Loop（自动循环变色）。通过 UpdateFlags 位图控制本次命令要更新哪些参数。 激活后，灯光会按设定的时间周期在色环上自动循环。

↑ 返回命令列表

StopMoveStep —— 停止过渡（0x47）

立即停止当前正在进行的 Move 或 Step 颜色过渡。灯光保持在当前颜色状态。 适用于所有颜色模型（HS、XY、CT）。

↑ 返回命令列表

属性详解

ColorControl Cluster 共有 52 个属性，按功能分为六组。点击下方汇总表中的属性 ID 可跳转到对应的详细说明。

当前颜色状态

反映灯光当前的颜色参数，是 App UI 展示和状态同步的核心数据源。

↑ 返回属性列表

颜色模式与选项

标识设备当前使用的颜色控制模型以及命令执行选项。

ColorMode 枚举值

EnhancedColorMode 枚举值

↑ 返回属性列表

Enhanced Hue 与 Color Loop

高精度色相控制和自动循环变色的状态属性。

↑ 返回属性列表

能力与色温范围

描述设备支持的颜色控制能力和色温物理范围。开发时必须先读取这些属性来确定可用的控制方式。

ColorCapabilities 位图

↑ 返回属性列表

漂移补偿与灯具信息

描述灯具的颜色漂移补偿机制和原色（Primary）数量。大多数 App 开发无需关注这些属性。

DriftCompensation 枚举值

↑ 返回属性列表

原色坐标（Primary 1~6）

灯具最多可以声明 6 组原色（Primary），每组包含 CIE XY 坐标和强度值。这些属性描述灯具 LED 的物理色域， 通常由固件设置，App 开发一般不需要读取。

↑ 返回属性列表

白点与色点

描述灯具的白点坐标和 RGB 三色点坐标，用于色彩校准。这些属性可写，通常由高级校准工具使用， App 开发一般不需要关注。

↑ 返回属性列表

命令参数枚举值速查

以下枚举类型在多个命令的参数中复用。

DirectionEnum（色相过渡方向）

MoveModeEnum（持续移动模式）

StepModeEnum（步进方向）

ColorLoopActionEnum（循环动作）

ColorLoopDirectionEnum（循环方向）

UpdateFlags 位图（ColorLoopSet 命令参数）

标准示例

以下是一个支持全能力（HS + XY + CT + EHUE + CL）的全彩灯的典型属性数据示例：

{
  // --- 当前颜色状态 ---
  "0x0000": 127,         // CurrentHue = 127（约 180°，青色附近）
  "0x0001": 200,         // CurrentSaturation = 200（高饱和度）
  "0x0003": 24939,       // CurrentX = 24939（CIE x ≈ 0.3805）
  "0x0004": 24701,       // CurrentY = 24701（CIE y ≈ 0.3769）
  "0x0007": 370,         // ColorTemperatureMireds = 370（≈ 2703K 暖白）
  "0x0002": 0,           // RemainingTime = 0（无过渡进行中）

  // --- 颜色模式 ---
  "0x0008": 2,           // ColorMode = ColorTemperature（当前用色温控制）
  "0x4001": 2,           // EnhancedColorMode = ColorTemperature
  "0x000F": 0,           // Options = 0（不启用 ExecuteIfOff）

  // --- Enhanced Hue & Color Loop ---
  "0x4000": 0,           // EnhancedCurrentHue = 0
  "0x4002": 0,           // ColorLoopActive = 0（未激活循环）
  "0x4003": 0,           // ColorLoopDirection = Decrement
  "0x4004": 25,          // ColorLoopTime = 25 秒
  "0x4005": 0,           // ColorLoopStartEnhancedHue = 0
  "0x4006": 0,           // ColorLoopStoredEnhancedHue = 0

  // --- 能力与色温范围 ---
  "0x400A": 31,          // ColorCapabilities = 0x1F（支持全部五种能力）
  "0x400B": 153,         // ColorTempPhysicalMinMireds = 153（≈ 6536K）
  "0x400C": 500,         // ColorTempPhysicalMaxMireds = 500（≈ 2000K）
  "0x400D": 153,         // CoupleColorTempToLevelMinMireds = 153
  "0x4010": 370          // StartUpColorTemperatureMireds = 370（开机暖白）
}

常见场景

场景 1：色温滑条调节

1. 读取 ColorCapabilities (0x400A)，确认 Bit 4（CT）为 1
2. 读取 ColorTempPhysicalMinMireds (0x400B) 和 ColorTempPhysicalMaxMireds (0x400C) 确定滑条范围
3. 用户拖动滑条时，将 Kelvin 转换为 Mireds：mireds = 1000000 / kelvin
4. 发送 MoveToColorTemperature (0x0A)，TransitionTime 设为 5（0.5 秒过渡）
5. 订阅 ColorTemperatureMireds (0x0007) 确认设备已到达目标色温

场景 2：色盘选色（Hue/Saturation）

1. 读取 ColorCapabilities (0x400A)，确认 Bit 0（HS）为 1
2. 用户在色盘上选择一个点，获取角度和半径
3. 角度 → Hue：hue = angle * 254 / 360
4. 半径 → Saturation：saturation = radius * 254 / maxRadius
5. 发送 MoveToHueAndSaturation (0x06) 一次设置两个值
6. 订阅 CurrentHue (0x0000) 和 CurrentSaturation (0x0001) 确认结果

场景 3：灯光控制页面初始化

1. 读取 ColorCapabilities (0x400A) —— 决定 UI 上展示哪些控制组件（色盘、色温滑条等）
2. 读取 EnhancedColorMode (0x4001) —— 确定当前是哪种颜色模式，高亮对应的 UI Tab
3. 根据模式读取对应属性：色温模式读 ColorTemperatureMireds，HS 模式读 CurrentHue + CurrentSaturation
4. 如支持 CT，读取 ColorTempPhysicalMinMireds / MaxMireds 设置滑条范围
5. 订阅所有相关属性的变化，保持 UI 与设备状态同步

场景 4：氛围灯 / 派对模式（Color Loop）

1. 读取 ColorCapabilities (0x400A)，确认 Bit 2（CL）为 1
2. 发送 ColorLoopSet (0x44)：UpdateFlags = 0x0F，Action = 2（从当前色开始），Direction = 1（递增），Time = 30（30 秒一圈）
3. 读取 ColorLoopActive (0x4002) 确认循环已激活
4. 关闭时再次发送 ColorLoopSet，Action = 0（Deactivate）