Matter Specification - Level Control Cluster

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