YOGYUI

Matter Specification - Level Control Cluster 본문

홈네트워크(IoT)/Matter

Matter Specification - Level Control Cluster

요겨 2023. 3. 25. 09:24
반응형

Matter :: Level Control Cluster

This cluster provides an interface for controlling a characteristic of a device that can be set to a level, for example the brightness of a light, the degree of closure of a door, or the power output of a heater.
밝기 변경 가능한 조명, 출력 조정 가능한 히터 등 단계별로 제어 가능한 디바이스를 위한 클러스터
PWM 제어를 위한 주파수(frequency) 어트리뷰트도 존재하나, 아직 정식으로 릴리즈되지는 않았다 (1.0 기준)

1. Classification

Hierarchy Role PICS Code Primary Transaction
Base Application LVL Type 1 (client → server)

2. Identifier

Identifier Hierarchy Name
0x0008 Base Level
0x0008 Derived Level Control for Lighting
0x001C Derived Pulse Width Modulation

※ Pulse width modulation cluster is provisonal

3. Features

3.1. Bit 0: On/Off

Bit Code Feature Def Description
0 OO On/Off 1 Matter Application Clusters Dependency with the On/Off cluster
더보기

For many applications, a close relationship between this cluster and the On/Off cluster is needed.
This section describes the dependencies that are required when an endpoint that implements this server cluster and also implements the On/Off server cluster. Before the On/Off feature bit in the FeatureMap existed, there was a dependency between this cluster and the On/Off cluster.

The OnOff attribute of the On/Off cluster and the CurrentLevel attribute of the Level Control cluster are intrinsically independent variables, as they are on different clusters. However, when both clusters are implemented on the same endpoint, dependencies MAY be introduced between them. Facilities are provided to introduce dependencies if required.

[Effect of On/Off Commands on the CurrentLevel Attribute]

The attribute OnLevel (see OnLevel Attribute) determines whether commands of the On/Off cluster have a permanent effect on the CurrentLevel attribute or not. If this attribute is defined (i.e., implemented and not equal to null) they do have a permanent effect, otherwise they do not. There is always a temporary effect, due to fading up / down.
The effect on the Level Control cluster on receipt of the various commands of the On/Off cluster are as detailed in Actions on Receipt for On/Off Commands, when Associated with Level Control. In this table, and throughout this cluster specification, 'level' means the value of the CurrentLevel attribute.

 

3.2. Bit 1: Lighting

Bit Code Feature Def Description
1 LT Lighting 0 Behavior that supports lighting applications
더보기

This feature supports an interface for controlling the level of a light source.
For the CurrentLevel attribute:
- A value of 0x00 SHALL NOT be used.
- A value of 0x01 SHALL indicate the minimum level that can be attained on a device.
- A value of 0xfe SHALL indicate the maximum level that can be attained on a device.
- A value of null SHALL represent an undefined value.
- All other values are application specific gradations from the minimum to the maximum level.

 

3.3. Bit 2: Frequency

Bit Code Feature Def Description
2 FQ Frequency 0 Supports frequency attributes and behavior. The Pulse Width Modulation cluster was created for frequency control.

4. Attributes

4.1. Current Level

ID Name Type Constraint Quality Default Access Conformance
0x0000 CurrentLevel uint8 MinLevel to MaxLevel SNX null R V M
더보기

The CurrentLevel attribute represents the current level of this device. The meaning of 'level' is device dependent.

 

4.2. Remaining Time

ID Name Type Constraint Quality Default Access Conformance
0x0001 RemainingTime uint16 all   0 R V LT
더보기

The RemainingTime attribute represents the time remaining until the current command is complete - it is specified in 1/10ths of a second.

 

4.3. Min Level

ID Name Type Constraint Quality Default Access Conformance
0x0002 MinLevel uint8 !LT: 0 to MaxLevel
LT: 1 to MaxLevel
  !LT: 0
LT: 1
R V O
더보기

The MinLevel attribute indicates the minimum value of CurrentLevel that is capable of being assigned.

 

4.4. Max Level

ID Name Type Constraint Quality Default Access Conformance
0x0003 MaxLevel uint8 MinLevel to 254   254 R V O
더보기

The MaxLevel attribute indicates the maximum value of CurrentLevel that is capable of being assigned.

 

4.5. Current Frequency

ID Name Type Constraint Quality Default Access Conformance
0x0004 CurrentFrequency uint16 MinFrequency to MaxFrequency PS 0 R V FQ
더보기

The CurrentFrequency attribute represents the frequency at which the device is at CurrentLevel. A CurrentFrequency of 0 is unknown.

 

4.6. Min Frequency

ID Name Type Constraint Quality Default Access Conformance
0x0005 MinFrequency uint16 0 to MaxFrequency   0 R V FQ
더보기

The MinFrequency attribute indicates the minimum value of CurrentFrequency that is capable of being assigned. MinFrequency SHALL be less than or equal to MaxFrequency. A value of 0 indicates undefined.

 

4.7. Max Frequency

ID Name Type Constraint Quality Default Access Conformance
0x0006 MaxFrequency uint16 MinFrequency to max   0 R V FQ
더보기

The MaxFrequency attribute indicates the maximum value of CurrentFrequency that is capable of being assigned. MaxFrequency SHALL be greater than or equal to MinFrequency. A value of 0 indicates undefined.

 

4.8. On Off Transition Time

ID Name Type Constraint Quality Default Access Conformance
0x0010 OnOffTransitionTime uint16 all   0 RW VO O
더보기

The OnOffTransitionTime attribute represents the time taken to move to or from the target level when On or Off commands are received by an On/Off cluster on the same endpoint. It is specified in 1/10ths of a second.
The actual time taken SHOULD be as close to OnOffTransitionTime as the device is able. Please note that if the device is not able to move at a variable rate, the OnOffTransitionTime attribute SHOULD NOT be implemented.

 

4.9. On Level

ID Name Type Constraint Quality Default Access Conformance
0x0011 OnLevel uint8 MinLevel to MaxLevel X null RW VO M
더보기

The OnLevel attribute determines the value that the CurrentLevel attribute is set to when the OnOff attribute of an On/Off cluster on the same endpoint is set to TRUE, as a result of processing an On/Off cluster command. If the OnLevel attribute is not implemented, or is set to the null value, it has no effect. For more details see Effect of On/Off Commands on the CurrentLevel Attribute.

 

4.10. On Transition Time

ID Name Type Constraint Quality Default Access Conformance
0x0012 OnTransitionTime uint16 all X null RW VO O
더보기

The OnTransitionTime attribute represents the time taken to move the current level from the minimum level to the maximum level when an On command is received by an On/Off cluster on the same endpoint. It is specified in 10ths of a second. If this attribute is not implemented, or contains a null value, the OnOffTransitionTime will be used instead.

 

4.11. Off Transition Time

ID Name Type Constraint Quality Default Access Conformance
0x0013 OffTransitionTime uint16 all X null RW VO O
더보기

The OffTransitionTime attribute represents the time taken to move the current level from the maximum level to the minimum level when an Off command is received by an On/Off cluster on the same endpoint. It is specified in 10ths of a second. If this attribute is not implemented, or contains a null value, the OnOffTransitionTime will be used instead.

 

4.12. Default Move Rate

ID Name Type Constraint Quality Default Access Conformance
0x0014 DefaultMoveRate uint8 all X MS RW VO O
더보기

The DefaultMoveRate attribute determines the movement rate, in units per second, when a Move command is received with a null value Rate parameter.

 

4.13. Options

ID Name Type Constraint Quality Default Access Conformance
0x000F Options map8 desc   0 RW VO M
더보기

The Options attribute is meant to be changed only during commissioning. The Options attribute is a bitmap that determines the default behavior of some cluster commands. Each command that is dependent on the Options attribute SHALL first construct a temporary Options bitmap that is in effect during the command processing. The temporary Options bitmap has the same format and meaning as the Options attribute, but includes any bits that may be overridden by command fields. Below is the format and description of the Options attribute and temporary Options bitmap and the effect on dependent commands.

Bit Name Summary Description Conformance
0 ExecuteIfOff Dependency on On/Off cluster LT | OO
1 CoupleColorTempToLevel Dependency on Color Control cluster LT

[Bit 0: ExecuteIfOff Options Bit]
Command execution SHALL NOT continue beyond the Options processing if all of these criteria are true:
• The command is one of the ‘without On/Off’ commands: Move, Move to Level, Step, or Stop.
• The On/Off cluster exists on the same endpoint as this cluster.
• The OnOff attribute of the On/Off cluster, on this endpoint, is FALSE.
• The value of the ExecuteIfOff bit is 0.

[Bit 1: CoupleColorTempToLevel Options Bit]

Valid values are:
0 - Do not couple changes to the CurrentLevel attribute with the color temperature.
1 - Couple changes to the CurrentLevel attribute with the color temperature set in the Color Control cluster.
When not supporting the Lighting feature, this bit SHALL be zero and ignored.

 

4.14. Startup Current Level

ID Name Type Constraint Quality Default Access Conformance
0x4000 StartUpCurrentLevel uint8 desc XN MS RW VM LT
더보기

The StartUpCurrentLevel attribute SHALL define the desired startup level for a device when it is supplied with power and this level SHALL be reflected in the CurrentLevel attribute. The values of the StartUpCurrentLevel attribute are listed below:

Value Action on power up
0x00 Set the CurrentLevel attribute to the minimum value permitted on the device
null Set the CurrentLevel attribute to its previous value
other values Set the CurrentLevel attribute to this value

This behavior does not apply to reboots associated with OTA. After an OTA restart, the CurrentLevel attribute SHALL return to its value prior to the restart.

5. Commands

5.1. Move to Level

ID Name Direction Response Access Conformance
0x00 MoveToLevel client → server Y O M
더보기

The MoveToLevel command SHALL have the following data fields:

ID Name Type Constraint Quality Default Conformance
0 Level uint8 0 to 254     M
1 TransitionTime uint16 all X   M
2 OptionsMask map8 desc   0 M
3 OptionsOverride map8 desc   0 M

[Effect on Receipt]

The OptionsMask and OptionsOverride fields SHALL both be present. Default values are provided to interpret missing fields from legacy devices. A temporary Options bitmap SHALL be created from the Options attribute, using the OptionsMask and OptionsOverride fields. Each bit of the temporary Options bitmap SHALL be determined as follows: 


Each bit in the Options attribute SHALL determine the corresponding bit in the temporary Options bitmap, unless the OptionsMask field is present and has the corresponding bit set to 1, in which case the corresponding bit in the OptionsOverride field SHALL determine the corresponding bit in the temporary Options bitmap.


The resulting temporary Options bitmap SHALL then be processed as defined in section Options Attribute.


On receipt of this command, a device SHALL move from its current level to the value given in the Level field. The meaning of ‘level’ is device dependent – e.g., for a light it MAY mean brightness level.


The movement SHALL be as continuous as technically practical, i.e., not a step function, and the time taken to move to the new level SHALL be equal to the value of the TransitionTime field, in tenths of a second, or as close to this as the device is able.

If the TransitionTime field takes the value null then the time taken to move to the new level SHALL instead be determined by the OnOffTransitionTime attribute. If OnOffTransitionTime, which is an optional attribute, is not present, the device SHALL move to its new level as fast as it is able.


If the device is not able to move at a variable rate, the TransitionTime field MAY be disregarded.

 

5.2. Move

ID Name Direction Response Access Conformance
0x01 Move client → server Y O M
더보기

The Move command SHALL have the following data fields:

ID Name Type Constraint Quality Default Conformance
0 MoveMode enum8 desc     M
1 Rate uint8 all X   M
2 OptionsMask map8 desc   0 M
3 OptionsOverride map8 desc   0 M

[MoveMode]

The MoveMode field SHALL be one of the non-reserved values in Values of the MoveMode Field.

MoveMode Value Description
0x00 Up
0x01 Down

[Rate]

The Rate field specifies the rate of movement in units per second. The actual rate of movement SHOULD be as close to this rate as the device is able. If the Rate field is equal to null, then the value in DefaultMoveRate attribute SHALL be used. However, if the Rate field is equal to null and the DefaultMoveRate attribute is not supported, or if the Rate field is equal to null and the value of the DefaultMoveRate attribute is equal to null, then the device SHOULD move as fast as it is able. If the device is not able to move at a variable rate, this field MAY be disregarded.

 

[Effect on Receipt]

On receipt of this command, a device SHALL first create and process a temporary Options bitmap as described in section Effect on Receipt.

On receipt of this command, a device SHALL move from its current level in an up or down direction in a continuous fashion, as detailed in Actions on Receipt for Move Command.

MoveMode Action on Receipt
Up Increase the device’s level at the rate given in the Rate field. If the level reaches the maximum allowed for the device, stop.
Down Decrease the device’s level at the rate given in the Rate field. If the level reaches the minimum allowed for the device, stop.

 

5.3. Step

ID Name Direction Response Access Conformance
0x02 Step client → server Y O M
더보기

The Step command SHALL have the following data fields:

ID Name Type Constraint Quality Default Conformance
0 StepMode enum8 desc     M
1 StepSize uint8 all     M
2 TransitionTime uint16 all X   M
3 OptionsMask map8 desc   0 M
4 OptionsOverride map8 desc   0 M

The StepMode field SHALL be one of the non-reserved values in Values of the StepMode Field.

StepMode Value Description
0x00 Up
0x01 Down

The TransitionTime field specifies the time that SHALL be taken to perform the step, in tenths of a second. A step is a change in the CurrentLevel of StepSize units. The actual time taken SHOULD be as close to this as the device is able. If the TransitionTime field is equal to null, the device SHOULD move as fast as it is able.

If the device is not able to move at a variable rate, the TransitionTime field MAY be disregarded.

 

[Effect on Receipt]

On receipt of this command, a device SHALL first create and process a temporary Options bitmap as described in section Effect on Receipt.

On receipt of this command, a device SHALL move from its current level in an up or down direction as detailed in Actions on Receipt for Step Command.

StepMode Action on Receipt
Up Increase CurrentLevel by StepSize units, or until it reaches the maximum level allowed for the device if this reached in the process. In the latter case, the transition time SHALL be proportionally reduced.
Down Decrease CurrentLevel by StepSize units, or until it reaches the minimum level allowed for the device if this reached in the process. In the latter case, the transition time SHALL be proportionally reduced.
 

 

5.4. Stop

ID Name Direction Response Access Conformance
0x03 Stop client → server Y O M
더보기

The Stop command SHALL have the following data fields:

ID Name Type Constraint Quality Default Conformance
0 OptionsMask map8 desc   0 M
1 OptionsOverride map8 desc   0 M

[Effect on Receipt]

On receipt of this command, a device SHALL first create and process a temporary Options bitmap as described in section Effect on Receipt.

Upon receipt of this command, any MoveToLevel, Move or Step command (and their 'with On/Off' variants) currently in process SHALL be terminated. The value of CurrentLevel SHALL be left at its value upon receipt of the Stop command, and RemainingTime SHALL be set to zero. 


This command has two entries in Command IDs for the Level Control Cluster, one for the MoveToLevel, Move and Step commands, and one for their 'with On/Off' counterparts. This is solely for symmetry, to allow easy choice of one or other set of commands – the Stop commands are identical, because the dependency on On/Off is determined by the original command that is being stopped.

 

5.5. Move to Level with On/Off

ID Name Direction Response Access Conformance
0x04 MoveToLevelWithOnOff client → server Y O M
더보기

The MoveToLevelWithOnOff, MoveWithOnOff and StepWithOnOff commands have identical data fields compared to the MoveToLevel, Move and Step commands respectively. They also have the same effects, except for the following additions. 

Before commencing any command that has the effect of setting the CurrentLevel attribute above the minimum level allowed by the device, the OnOff attribute of the On/Off cluster on the same endpoint, if implemented, SHALL be set to TRUE (‘On’). 
If any command that has the effect of setting the CurrentLevel attribute to the minimum level allowed by the device, the OnOff attribute of the On/Off cluster on the same endpoint, if implemented, SHALL be set to to FALSE (‘Off’). 

The StopWithOnOff command has identical data fields compared to the Stop command. Both Stop commands are identical, because the dependency on On/Off is determined by the original command that is being stopped.  

 

5.6. Move with On/Off

ID Name Direction Response Access Conformance
0x05 MoveWithOnOff client → server Y O M
더보기

The MoveToLevelWithOnOff, MoveWithOnOff and StepWithOnOff commands have identical data fields compared to the MoveToLevel, Move and Step commands respectively. They also have the same effects, except for the following additions. 

Before commencing any command that has the effect of setting the CurrentLevel attribute above the minimum level allowed by the device, the OnOff attribute of the On/Off cluster on the same endpoint, if implemented, SHALL be set to TRUE (‘On’). 
If any command that has the effect of setting the CurrentLevel attribute to the minimum level allowed by the device, the OnOff attribute of the On/Off cluster on the same endpoint, if implemented, SHALL be set to to FALSE (‘Off’). 

The StopWithOnOff command has identical data fields compared to the Stop command. Both Stop commands are identical, because the dependency on On/Off is determined by the original command that is being stopped.  

 

5.7. Step with On/Off

ID Name Direction Response Access Conformance
0x06 StepWithOnOff client → server Y O M
더보기

The MoveToLevelWithOnOff, MoveWithOnOff and StepWithOnOff commands have identical data fields compared to the MoveToLevel, Move and Step commands respectively. They also have the same effects, except for the following additions. 

Before commencing any command that has the effect of setting the CurrentLevel attribute above the minimum level allowed by the device, the OnOff attribute of the On/Off cluster on the same endpoint, if implemented, SHALL be set to TRUE (‘On’). 
If any command that has the effect of setting the CurrentLevel attribute to the minimum level allowed by the device, the OnOff attribute of the On/Off cluster on the same endpoint, if implemented, SHALL be set to to FALSE (‘Off’). 

The StopWithOnOff command has identical data fields compared to the Stop command. Both Stop commands are identical, because the dependency on On/Off is determined by the original command that is being stopped.  

 

5.8. Stop with On/Off

ID Name Direction Response Access Conformance
0x07 StopWithOnOff client → server Y O M
더보기

The MoveToLevelWithOnOff, MoveWithOnOff and StepWithOnOff commands have identical data fields compared to the MoveToLevel, Move and Step commands respectively. They also have the same effects, except for the following additions. 

Before commencing any command that has the effect of setting the CurrentLevel attribute above the minimum level allowed by the device, the OnOff attribute of the On/Off cluster on the same endpoint, if implemented, SHALL be set to TRUE (‘On’). 
If any command that has the effect of setting the CurrentLevel attribute to the minimum level allowed by the device, the OnOff attribute of the On/Off cluster on the same endpoint, if implemented, SHALL be set to to FALSE (‘Off’). 

The StopWithOnOff command has identical data fields compared to the Stop command. Both Stop commands are identical, because the dependency on On/Off is determined by the original command that is being stopped.  

 

5.9. Move to Closest Frequency

ID Name Direction Response Access Conformance
0x08 MoveToClosestFrequency client → server Y O FQ
더보기

The MoveToClosestFrequency command SHALL have the following data fields:

ID Name Type Constraint Quality Default Conformance
0 Frequency uint16 all   0 M

[Effect on Receipt]

Upon receipt of this command, the device SHALL change its current frequency to the requested frequency, or to the closest frequency that it can generate. If the device cannot approximate the frequency, then it SHALL return a default response with an error code of CONSTRAINT_ERROR. Determining if a requested frequency can be approximated by a supported frequency is a manufacturerspecific decision.

6. State Change Table for Lighting

Below is a table of examples of state changes when Level Control and On/Off clusters are on the same endpoint and the Lighting feature is set. 

  • EiO: ExecuteIfOff field in the Options attribute
  • OnOff: attribute value of On/Off cluster: FALSE=‘Off’, TRUE=‘On’
  • MIN: MinLevel
  • MAX: MaxLevel
  • MID: midpoint between MinLevel and MaxLevel
Current
Level
EiO OnOff Physical
Device
Command
Before
After
Current
Level
OnOff Physical
Device
Device Output
Result
any 0 FALSE Off MoveToLevel
(l=MID, t=2sec)
same FALSE Off stays off
any 0 FALSE Off MoveToLevelWithOnOff
(l=MID, t=2sec)
MID TRUE On
(midpint brightness)
turns on and output level adjusts or stays at half
any 1 FALSE Off MoveToLevel
(l=MID, t=2sec)
MID FALSE Off stays off
any 1 FALSE Off MoveToLevelWithOnOff
(l=MID, t=2sec)
MID TRUE On turns on and output level adjusts to or stays at half
any 1 FALSE Off Move
(up, rate=64/s)
MAX FALSE Off stays off
any 1 FALSE Off MoveWithOnOff
(up, rate=64/s)
MAX TRUE On turn on and output level adjusts to or stays at full
any 1 FALSE Off MoveWithOnOff
(down, rate=64/s)
MIN FALSE Off stays off
any any TRUE On MoveToLevelWithOnOff
(l=MID, t=2sec)
MID TRUE On
(midpoint brightness)
output level adjusts to or stays at half
any any TRUE On MoveWithOnOff
(up, rate=64/s)
MAX TRUE On
(full brightness)
output level adjusts to or stays at full
any any TRUE On Move
(down, rate=64/s)
MIN TRUE On 
(at minimum brightness)
output level adjusts to minimum
any any TRUE On MoveWithOnOff
(down, rate=64/s)
MIN FALSE Off output level adjusts to off

 

 

 

 

반응형