Matter Specification - On/Off Cluster

Matter :: On/Off Cluster

Attributes and commands for turning devices on and off.
조명, 콘센트(outlet), 팬(fan) 등 다양한 디바이스의 전원/동작 상태를 켜고 끄는 데 사용되는 클러스터
거의 모든 종류의 엔드포인트의 하위 클러스터로 포함된다

1. Classification

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

2. Identifier

Identifier	PICS Code	Name
0x0006	OO	On/Off

3. Features

3.1. Bit 0: Level Control for Lighting

Bit	Code	Feature	Description
0	LT	Level Control for Lighting	Behavior that supports lighting applications

This cluster is used for a lighting application.
On receipt of a Level Control cluster command that causes the OnOff attribute to be set to FALSE, the OnTime attribute SHALL be set to 0.
On receipt of a Level Control cluster command that causes the OnOff attribute to be set to TRUE, if the value of the OnTime attribute is equal to 0, the server SHALL set the OffWaitTime attribute to 0.

4. Data Types

4.1. StartUpOnOffEnum

Value	Name	Conformance	Description
0	Off	M	Set the OnOff attribute to FALSE
1	On	M	Set the OnOff attribute to TRUE
2	Toggle	M	If the previous value of the OnOff attribute is equal to FALSE, set the OnOff attribute to TRUE. If the previous value of the OnOff attribute is equal to TRUE, set the OnOff attribute to FALSE (toggle).

5. Attributes

5.1. On Off

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0000	OnOff	bool	all	SN	FALSE	R V	M

The OnOff attribute indicates whether the device type implemented on the endpoint is turned off or turned on, in these cases the value of the OnOff attribute equals FALSE, or TRUE respectively.

 

5.2. Global Scene Control

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x4000	GlobalSceneControl	bool	all		TRUE	R V	LT

In order to support the use case where the user gets back the last setting of a set of devices (e.g. level settings for lights), a global scene is introduced which is stored when the devices are turned off and recalled when the devices are turned on. The global scene is defined as the scene that is stored with group identifier 0 and scene identifier 0.
The GlobalSceneControl attribute is defined in order to prevent a second Off command storing the all-devices-off situation as a global scene, and to prevent a second On command destroying the current settings by going back to the global scene.
The GlobalSceneControl attribute SHALL be set to TRUE after the reception of a command which causes the OnOff attribute to be set to TRUE, such as a standard On command, a MoveToLevel(WithOnOff) command, a RecallScene command or a OnWithRecallGlobalScene command (see OnWithRecallGlobalScene Command).
The GlobalSceneControl attribute is set to FALSE after reception of a OffWithEffect command.
These concepts are illustrated in Explanation of the Behavior of Store and Recall Global Scene functionality using a State Diagram.

 

5.3. On Time

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x4001	OnTime	uint16	all	X	0	RW VO	LT

The OnTime attribute specifies the length of time (in 1/10ths second) that the ‘On’ state SHALL be maintained before automatically transitioning to the ‘Off’ state when using the OnWithTimedOff command. This attribute can be written at any time, but writing a value only has effect when in the ‘Timed On’ state. See OnWithTimedOff Command for more details.

 

5.4. Off Wait Time

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x4002	OffWaitTime	uint16	all	X	0	RW VO	LT

The OffWaitTime attribute specifies the length of time (in 1/10ths second) that the ‘Off’ state SHALL be guarded to prevent another OnWithTimedOff command turning the server back to its ‘On’ state (e.g., when leaving a room, the lights are turned off but an occupancy sensor detects the leaving person and attempts to turn the lights back on). This attribute can be written at any time, but writing a value only has an effect when in the ‘Timed On’ state followed by a transition to the ‘Delayed Off' state, or in the ‘Delayed Off’ state. See OnWithTimedOff Command for more details.

 

5.5. Start Up On Off

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x4003	StartUpOnOff	StartUpOnOffEnum	desc	XN	MS	RW VM	LT

The StartUpOnOff attribute SHALL define the desired startup behavior of a device when it is supplied with power and this state SHALL be reflected in the OnOff attribute. If the value is null, the OnOff attribute is set to its previous value. Otherwise, the behavior is defined in the table defining StartUpOnOffEnum.
This behavior does not apply to reboots associated with OTA. After an OTA restart, the OnOff attribute shall return to its value prior to the restart.

6. Commands

6.1. Off

ID	Name	Direction	Response	Access	Conformance
0x00	Off	client → server	Y	O	M

This command does not have any data fields.
[Effect on Receipt]
On receipt of the Off command, a server SHALL set the OnOff attribute to FALSE. Additionally, when the OnTime attribute is supported, the server SHALL set the OnTime attribute to 0.

 

6.2. On

ID	Name	Direction	Response	Access	Conformance
0x01	On	client → server	Y	O	M

This command does not have any data fields.
[Effect on Receipt]
On receipt of the On command, a server SHALL set the OnOff attribute to TRUE.
Additionally, when the OnTime and OffWaitTime attributes are both supported, if the value of the OnTime attribute is equal to 0, the server SHALL set the OffWaitTime attribute to 0.

 

6.3. Toggle

ID	Name	Direction	Response	Access	Conformance
0x02	Toggle	client → server	Y	O	M

This command does not have any data fields.
[Effect on Receipt]
On receipt of the Toggle command, if the value of the OnOff attribute is equal to FALSE, the server SHALL set the OnOff attribute to TRUE, otherwise, the server SHALL set the OnOff attribute to FALSE.
Additionally, when the OnTime and OffWaitTime attributes are both supported, if the value of the OnOff attribute is equal to FALSE and if the value of the OnTime attribute is equal to 0, the server SHALL set the OffWaitTime attribute to 0. If the value of the OnOff attribute is equal to TRUE, the server SHALL set the OnTime attribute to 0.

 

6.4. Off with Effect

ID	Name	Direction	Response	Access	Conformance
0x40	OffWithEffect	client → server	Y	O	LT

The OffWithEffect command allows devices to be turned off using enhanced ways of fading.
The OffWithEffect command SHALL have the following data fields:
<자세한 내용은 본문 참고>

 

6.5. On with Recall Global Scene

ID	Name	Direction	Response	Access	Conformance
0x41	OnWithRecallGlobalScene	client → server	Y	O	LT

The OnWithRecallGlobalScene command allows the recall of the settings when the device was turned off.
The OnWithRecallGlobalScene command SHALL have no parameters.
[Effect on Receipt]
On receipt of the OnWithRecallGlobalScene command, if the GlobalSceneControl attribute is equal to TRUE, the server SHALL discard the command.
If the GlobalSceneControl attribute is equal to FALSE, the Scene cluster server on the same endpoint SHALL recall its global scene, updating the OnOff attribute accordingly. The OnOff server SHALL then set the GlobalSceneControl attribute to TRUE.
Additionally, when the OnTime and OffWaitTime attributes are both supported, if the value of the OnTime attribute is equal to 0, the server SHALL set the OffWaitTime attribute to 0.

 

6.6. On with Timed Off

ID	Name	Direction	Response	Access	Conformance
0x42	OnWithTimedOff	client → server	Y	O	LT

The OnWithTimedOff command allows devices to be turned on for a specific duration with a guarded off duration so that SHOULD the device be subsequently turned off, further OnWithTimedOff commands, received during this time, are prevented from turning the devices back on. Further OnWithTimedOff commands received while the server is turned on, will update the period that the device is turned on.
The OnWithTimedOff command SHALL have the following data fields:
<자세한 내용은 본문 참고>

7. State Description

The operation of the On/Off cluster with respect to the On, Off, and OnWithTimedOff commands is illustrated in On/Off Cluster Operation State Machine. In this diagram, the values X and Y correspond to the OnTime and OffWaitTime fields, respectively, of the OnWithTimedOff command. In the ‘Timed On’ state, the OnTime attribute is decremented every 1/10th second, unless its value equals null. Similarly, in the ‘Delayed Off’ state, the OffWaitTime attribute is decremented every 1/10th second, unless its value equals null.