Matter Cluster: Level Control Cluster
LevelControl Cluster的作用？
该集群提供了一个接口，用于控制可设置为某个级别的设备特性，例如灯光的亮度、门的关闭程度或加热器的功率输出。
Cluster ID
| Hierarchy | Role | Scope | PICS Code |
|---|---|---|---|
| Base | Application | Endpoint | LVL |
| ID | Hierachy | Name | Conformance |
|---|---|---|---|
| 0x0008 | Base | Level Control | |
| 0x001c | Derived | Pulse Width Modulation | P |
注意：Pulse Width Modulation cluster是临时性的
Features
| Bit | Code | Feature | Default | Conformance | Summary |
|---|---|---|---|---|---|
| 0 | OO | OnOff | 1 | O | Dependency with the On/Off cluster |
| 1 | LT | Lighting | 0 | O | Behavior that supports lighting applications |
| 2 | FQ | Frequency | 0 | P | Supports frequency attributes and behavior |
On/Off Feature
对于许多应用程序，LevelControl cluster与 On/Off cluster之间需要密切的关系。本节介绍实现此服务器集群以及实施 On/Off 服务器集群的终端节点所需的依赖项。在 FeatureMap 中的 On/Off 功能位存在之前，此集群与 On/Off 集群之间存在依赖关系。
On/Off cluster的 OnOff 属性和 Level Control cluster的 CurrentLevel 属性本质上是独立的变量，因为它们位于不同的群集上。但是，当两个集群都在同一终端节点上实现时，它们之间可能会引入依赖关系。
- Effect of On/Off Commands on the CurrentLevel attribute（On/Off 命令对 CurrentLevel 属性的影响）
OnLevel 属性决定了 On/Off cluster的命令是否对 CurrentLevel 属性产生永久影响。如果定义了此属性（即已实现且不等于 null），则它们确实具有永久效果，否则则不具有。由于淡入淡出/淡入淡出，总是存在临时效果。
收到 On/Off cluster的各种命令时，对 Level Control cluster的影响，例如，与 Level Control 关联时， On/Off 命令的效果表中所述。在此表以及整个群集规范中，“level”表示 CurrentLevel 属性的值。
| Command | Action On Receipt |
|---|---|
| On | 临时存储 CurrentLevel。将 CurrentLevel 设置为设备允许的最小级别。在 OnOffTransitionTime 时间段内，将 CurrentLevel 更改为 OnLevel，如果未定义 OnLevel，则更改为存储的级别。 |
| Off | 临时存储 CurrentLevel。将 CurrentLevel 更改为设备在 OnOffTransitionTime 时间段内允许的最小级别。如果未定义 OnLevel，则将 CurrentLevel 设置为存储的级别。 |
| Toggle | 如果 OnOff 属性的值为 FALSE，则按照 On 命令继续。否则，按照 Off 命令继续 |
上表中描述的目的是，在转换完成后，应恢复在发出任何 On、Off 或 Toggle 命令之前生效的 CurrentLevel。如果收到这些命令中的另一个，则在转换完成之前，应保留并恢复最初存储的 CurrentLevel。
- Effect of Level Control Commands on the OnOff Attribute（级别控制命令对 OnOff 属性的影响）
Level Control 群集中提供了两组命令。它们是相同的，除了第一组（MoveToLevel、Move 和 Step 命令）不应影响 OnOff 属性，而第二组（“with On/Off”变体）应影响。
第一组用于保持 CurrentLevel 和 OnOff 属性之间的独立性，因此更改 CurrentLevel 不会影响 OnOff 属性。例如，这表示带有单独静音按钮的音量控制的行为，或者 “turn to set level and press to turn on on / off” 调光器。
第二组用于链接 CurrentLevel 和 OnOff 属性。当级别降低到最小值时， OnOff 属性会自动变为 FALSE，当级别增加到最小值以上时， OnOff 属性会自动变为 TRUE。例如，这表示没有独立开/关开关的调光器的行为。
对于 Stop 命令，包含 StopWithOnOff 只是为了对称，以便轻松选择一组或另一组命令 – 两个 Stop 命令是相同的，因为对 On/Off 的依赖性是由正在停止的原始命令决定的。
- Effect of Level Control Commands Depends on OnOff
在引入 Options 属性之前，如果同一端点上 On/Off 集群的 OnOff 属性为 FALSE，则除那些以 ‘with On/Off’ 为后缀的命令外，所有命令都无效。即使 On/Off （OO） 功能集位设置为零，这仍然是正确的。要允许此类命令运行，请参阅下面的 Options 属性。
Attributes
| ID | Name | Type | Contraint | Quality | Default | Access | Conformance |
|---|---|---|---|---|---|---|---|
| 0x0000 | CurrentLevel | uint8 | MinLevel to MaxLevel | SNX | null | R V | M |
| 0x0001 | RemainingTime | uint16 | all | 0 | R V | LT | |
| 0x0002 | MinLevel | uint8 | 1 to MaxLevel | 1 | R V | [LT] | |
| 0x0002 | MinLevel | uint8 | 0 to MaxLevel | 0 | R V | [!LT] | |
| 0x0003 | MaxLevel | uint8 | MinLevel to 254 | 254 | R V | O | |
| 0x0004 | CurrentFrequency | uint16 | MinFrequency to MaxFrequency | PS | 0 | R V | FQ |
| 0x0005 | MinFrequency | uint16 | 0 to MaxFrequency | 0 | R V | FQ | |
| 0x0006 | MaxFrequency | uint16 | min Minfrequency | 0 | R V | FQ | |
| 0x0010 | OnOffTransitionTime | uint16 | all | 0 | RW VO | O | |
| 0x0011 | OnLevel | uint8 | MinLevel to MaxLevel | X | null | RW VO | M |
| 0x0012 | OnTransitionTime | uint16 | all | X | null | RW VO | O |
| 0x0013 | OffTransitionTime | uint16 | all | X | null | RW VO | O |
| 0x0014 | DefaultMoveRate | uint8 | all | X | MS | RW VO | O |
| 0x000f | Options | OptionsBitmap | desc | 0 | RW VO | M | |
| 0x4000 | StartUpCurrentLevel | uint8 | desc | XN | MS | RW VM | LT |
- CurrentLevel Attribute（当前亮度/级别）
该属性暗示着设备当前级别。级别的含义取决于设备。
对于灯类，取值范围：1254，即亮度范围，通常映射为1%100%，算法如下：
1 | level = (value - MinLevel) /(MaxLevel - MinLevel) * 100 |
例如：value = 200，映射为：79%
- RemainingTime Attribute
该属性暗示着持续时间直到current命令执行完毕，它以 1/10 秒为单位。
- MinLevel Attribute（最小亮度，默认为1，不能为0）
该属性暗示着当前级别可以设置的最小值。
- MaxLevel Attribute（最大亮度，默认为254）
该属性暗示着当前级别可以设置的最大值
- CurrentFrequency Attribute
该属性暗示着设备处于当前级别时的频率。当前频率的值为0，表示是未知的。
- MinFrequency Attribute
该属性暗示着当前频率可以设置的最小值。最小频率属性的值应该小于或等于最大频率属性的值。
- MaxFrequency Attribute
该属性暗示着当前频率可以设置的最小值。最大频率属性的值应该大于或等于最小属性的值。
- Options Attribute
此属性应指示设备的选定选项。
选项属性是一个位图，它决定了某些集群命令的默认行为。每个依赖于选项属性的命令都应首先构造一个临时的选项位图，该位图在命令处理期间有效。临时选项位图具有与选项属性相同的格式和含义，但包括可能被命令字段覆盖的任何位。
- OnOffTransitionTime Attribute
此属性应指示当同一个Endpoint上的 OnOff 集群收到On或 Off命令时，移动到目标级别或从目标级别移出所需的时间。以 1/10 秒为单位。
- OnLevel Attribute（设备开启时的默认亮度）
此属性应指示当同一Endpoint上的 OnOff 集群的 OnOff 属性设置为 TRUE 时， CurrentLevel 属性被设置的值，这是处理 OnOff 集群命令的结果。如果未实现 OnLevel 属性，或将其设置为空值，则它不起作用。有关更多详细信息，请参阅开/关命令对 CurrentLevel 属性的影响。
- OnTrasitionTime Attribute
此属性应指示当同一 Endpoint 上的 OnOff 集群收到 On 命令时，将当前级别从最低级别移至最高级别所需的时间。它以 1/10 秒为单位指定。如果未实现此属性，或包含空值，则应使用 OnOffTransitionTime。
- OffTransitionTime Attribute
此属性应指示当同一 Endpoint上 的 OnOff 集群收到 Off 命令时，将当前级别从最高级别移至最低级别所需的时间。它以 1/10 秒为单位指定。如果未实现此属性，或包含空值，则应使用 OnOffTransitionTime。
- DefaultMoveRate Attribute
当收到带有空值速率参数的移动命令时，此属性应指示移动速率（以单位/秒为单位）。
- StartUpCurrentLevel Attribute
此属性应指示设备通电时所需的启动级别，并且此级别应反映在 CurrentLevel 属性中。StartUpCurrentLevel 属性的值如下所列：
| Value | Action on power up |
|---|---|
| 0 | 将 CurrentLevel 属性设置为设备允许的最小值 |
| null | 将 CurrentLevel 属性设置为它之前的值 |
| other values | 将CurrentLevel 属性设置为输入的值 |
此行为不适用于与 OTA 相关的重启。OTA 重启后，CurrentLevel 属性应返回到重启前的值。
Commands
| ID | Name | Direction | Respone | Access | Conformance |
|---|---|---|---|---|---|
| 0x00 | MoveToLevel | client –> server | Y | O | M |
| 0x01 | Move | client –> server | Y | O | M |
| 0x02 | Step | client –> server | Y | O | M |
| 0x03 | Stop | client –> server | Y | O | M |
| 0x04 | MoveToLevelWithOnOff | client –> server | Y | O | M |
| 0x05 | MoveWithOnOff | client –> server | Y | O | M |
| 0x06 | StepWithOnOff | client –> server | Y | O | M |
| 0x07 | StopWithOnOff | client –> server | Y | O | M |
| 0x08 | MoveToClosestFrequecny | client –> server | Y | O | M |
- MoveToLevel Command
收到此命令后，设备应从其当前级别移至级别字段中指定的值。“级别”的含义取决于设备 - 例如，对于灯来说，它可能表示亮度级别。
移动应尽可能在技术上可行，即不是阶跃函数，并且移动到新级别所需的时间应等于 TransitionTime 字段的值（以十分之一秒为单位），或尽可能接近该值。
如果 TransitionTime 字段的值为 null，则移动到新级别所需的时间应由 OnOffTransitionTime 属性决定。如果不存在 OnOffTransitionTime（可选属性），则设备应尽快移动到新级别。
- Move Command
收到此命令后，设备应首先创建并处理临时选项位图，如 MoveToLevel 命令中所述。
收到此命令后，设备应从其当前级别开始以连续的方式向上或向下移动，如下所述：
| MoveMode | Action on Receipt |
|---|---|
| Up | 按照速率字段中给出的速率增加设备的级别。如果级别达到设备允许的最大值，则停止。 |
| Down | 按照“速率”字段中指定的速率降低设备的级别。如果级别达到设备允许的最低水平，则停止。 |
- Step Command
收到此命令后，设备应首先创建并处理临时选项位图，如 MoveToLevel 命令中所述。
收到此命令后，设备应从其当前级别向上或向下移动，如下所述：
| StepMode | Action on Receipt |
|---|---|
| Up | 按 StepSize 单位增加 CurrentLevel，或直到达到设备允许的最大级别（如果在此过程中已达到）。在后一种情况下，过渡时间应按比例减少。 |
| Down | 将 CurrentLevel 降低 StepSize 单位，或直到达到设备允许的最低级别（如果在此过程中已达到）。在后一种情况下，过渡时间应按比例减少。 |
- Stop Command
收到此命令后，设备应首先创建并处理临时选项位图，如 MoveToLevel 命令中所述。
收到此命令后，当前正在执行的任何 MoveToLevel、Move 或 Step 命令（及其“带开/关”变体）都应终止。收到 Stop 命令后，CurrentLevel 的值应保留为原值，RemainingTime 应设置为零。
此命令在命令列表中有两个条目，一个用于 MoveToLevel、Move 和 Step 命令，另一个用于它们的“带 On/Off”对应项。这只是为了对称，以便轻松选择一组或另一组命令 - Stop 命令是相同的，因为 On/Off 的依赖性由要停止的原始命令决定。
- MoveToClosestFrequecny Command
收到此命令后，设备应将其当前频率更改为请求的频率，或更改为其可以生成的最接近的频率。如果设备无法接近该频率，则应返回默认响应，错误代码为 CONSTRAINT_ERROR。确定请求的频率是否可以近似为支持的频率是制造商特定的决定。
- With On/Off Commands
MoveToLevelWithOnOff、MoveWithOnOff 和 StepWithOnOff 命令分别与 MoveToLevel、Move 和 Step 命令具有相同的数据字段。