亮度控制 Cluster（LevelControl）

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

LevelControl 提供了对设备「可调级别」的完整控制能力 —— 最典型的场景是灯的亮度调节，但也适用于风扇转速、窗帘开合度等任何可以用数值表示「程度」的设备。 它定义了两组命令：一组不影响 OnOff 状态，另一组会联动 OnOff Cluster 的开关状态。

命令（Commands）

LevelControl 提供两组命令：基本组（0x00~0x03）和 WithOnOff 组（0x04~0x07）。 两组命令的参数完全一样，区别在于 WithOnOff 组会联动 OnOff Cluster 的开关状态。 此外还有一个频率控制命令（0x08），仅在设备支持 Frequency feature 时可用。

MoveToLevel —— 移动到指定亮度（0x00）

将 CurrentLevel 从当前值平滑过渡到指定的目标亮度。这是最常用的命令 —— App 上的亮度滑块松手时就是发这个命令。 不会影响 OnOff 状态，即使目标亮度是 0 也不会关灯。

↑ 返回命令列表

Move —— 持续移动亮度（0x01）

让 CurrentLevel 以指定速率持续向上或向下变化，直到达到 MinLevel/MaxLevel 或收到 Stop 命令。 适合长按按钮持续调光的场景。

↑ 返回命令列表

Step —— 按步进值调整亮度（0x02）

将 CurrentLevel 按指定步进值向上或向下调整一档。适合短按按钮「调亮一格」「调暗一格」的场景。

↑ 返回命令列表

Stop —— 停止移动（0x03）

停止正在进行的 Move 或 Step 过渡。CurrentLevel 会保持在收到 Stop 命令时的值。

↑ 返回命令列表

MoveToLevelWithOnOff —— 移动到指定亮度（联动开关）（0x04）

功能与 MoveToLevel 完全相同，区别在于会联动 OnOff Cluster：目标亮度为 0 时自动关灯（OnOff 变为 Off），目标亮度大于 0 时自动开灯（OnOff 变为 On）。 App 调光时应优先使用这个命令，确保亮度和开关状态始终一致。

↑ 返回命令列表

MoveWithOnOff —— 持续移动亮度（联动开关）（0x05）

功能与 Move 相同，但移动过程中会联动 OnOff 状态。参数与 Move 一致。

↑ 返回命令列表

StepWithOnOff —— 按步进值调整亮度（联动开关）（0x06）

功能与 Step 相同，但步进过程中会联动 OnOff 状态。参数与 Step 一致。

↑ 返回命令列表

StopWithOnOff —— 停止移动（联动开关）（0x07）

功能与 Stop 相同，但联动 OnOff 状态。参数与 Stop 一致。

↑ 返回命令列表

MoveToClosestFrequency —— 移动到最近频率（0x08）

将 CurrentFrequency 移动到设备支持的最接近目标频率的值。仅在设备支持 Frequency feature 时可用，日常灯控开发中很少用到。

↑ 返回命令列表

属性详解

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

当前状态（0x00 – 0x03）

描述设备当前的亮度级别和允许的范围。这是 App 展示亮度状态最直接的数据来源。

↑ 返回属性列表

频率控制（0x04 – 0x06）

描述设备的频率控制能力。仅在设备支持 Frequency feature（Feature Map Bit 2）时才有这些属性。

↑ 返回属性列表

过渡与开关联动（0x0F – 0x14）

控制亮度变化的过渡行为，以及 OnOff Cluster 开灯/关灯时如何影响亮度。 这组属性直接决定了用户体验 —— 灯是突然亮/灭还是平滑过渡。

↑ 返回属性列表

启动行为（0x4000）

控制设备重新上电后的初始亮度。

StartUpCurrentLevel 特殊值

↑ 返回属性列表

枚举与位图

MoveModeEnum

Move 和 MoveWithOnOff 命令中的 MoveMode 参数使用此枚举，指定亮度移动方向。

StepModeEnum

Step 和 StepWithOnOff 命令中的 StepMode 参数使用此枚举，指定步进方向。

OptionsBitmap

Options 属性以及所有命令中 OptionsMask / OptionsOverride 参数使用此位图。 它控制命令在特定条件下是否执行。

Feature Map

LevelControl 通过 Feature Map 声明设备支持的可选能力。

示例数据

一个典型可调光灯具的 LevelControl Cluster 读取结果：

{
  // --- 当前状态 ---
  "0x0": 127,                // CurrentLevel = 127（约 50% 亮度）
  "0x1": 0,                  // RemainingTime = 0（无进行中的过渡）
  "0x2": 1,                  // MinLevel = 1（最低可用级别）
  "0x3": 254,                // MaxLevel = 254（最高可用级别）

  // --- 过渡与开关联动 ---
  "0xF": 0,                  // Options = 0（无特殊选项）
  "0x10": 10,                // OnOffTransitionTime = 10（1 秒过渡）
  "0x11": null,              // OnLevel = null（On 时恢复之前亮度）
  "0x12": null,              // OnTransitionTime = null（使用 OnOffTransitionTime）
  "0x13": null,              // OffTransitionTime = null（使用 OnOffTransitionTime）
  "0x14": 50,                // DefaultMoveRate = 50（每秒变化 50 个单位）

  // --- 启动行为 ---
  "0x4000": null              // StartUpCurrentLevel = null（上电恢复断电前亮度）
}

常见场景

场景 1：App 调光

1. 读取 MinLevel (0x02) 和 MaxLevel (0x03)，映射到滑块 0%~100%
2. 用户拖动滑块时，将百分比换算为目标亮度值
3. 发送 MoveToLevelWithOnOff (0x04)（推荐使用 WithOnOff 版本，保证开关状态一致）
4. 订阅 CurrentLevel (0x00) 的变化，实时更新 UI 显示

场景 2：记忆亮度开关灯

1. 设置 OnLevel (0x11) 为 null —— 让设备记忆上次关灯前的亮度
2. 用户点击「开灯」→ OnOff Cluster 发 On 命令 → 灯自动恢复到上次的亮度
3. 用户点击「关灯」→ OnOff Cluster 发 Off 命令 → 亮度渐暗到 0
4. 可选：设置 OnTransitionTime (0x12) 和 OffTransitionTime (0x13) 控制过渡速度

场景 3：断电恢复设置

1. 设置 StartUpCurrentLevel (0x4000)：null = 恢复断电前亮度，0x00 = 最低亮度，具体值 = 固定亮度
2. 同时设置 OnOff Cluster 的 StartUpOnOff，确保开关状态和亮度配合正确
3. 典型配置：StartUpCurrentLevel=null + StartUpOnOff=RestorePrevious → 完整恢复断电前状态

场景 4：物理按钮调光（长按 + 短按）

1. 短按 → 发送 StepWithOnOff (0x06)，每次增减固定步进值（如 25）
2. 长按按下 → 发送 MoveWithOnOff (0x05)，持续变化
3. 长按松手 → 发送 StopWithOnOff (0x07)，停在当前亮度