Matter Specification - Fan Control Cluster

Matter :: Fan Control Cluster

This cluster specifies an interface to control the speed of a fan.
모터 등으로 회전하는 '팬' 기기의 속도 제어를 위한 클러스터
선풍기, 환풍기, 에어서큘레이터, 에어컨 등 다양한 종류의 디바이스에 적용할 수 있다

1. Classification

Hierarchy	Role	Scope	PICS Code
Base	Application	Endpoint	FAN

2. Identifier

Identifier	Name
0x0202	Fan Control

3. Features

Bit	Code	Feature	Summary
0	SPD	MultiSpeed	1-100 speeds
Legacy Fan Control cluster revision 0-1 defined 3 speeds (low, medium and high) plus automatic speed control but left it up to the implementer to decide what was supported. Therefore, it is assumed that legacy client implementations are capable of determining, from the server, the number of speeds supported between 1, 2, or 3, and whether automatic speed control is supported. The MultiSpeed feature includes new attributes that support a running fan speed value from 1 to a maximum of 100. See Speed Rules for more details.
1	AUT	Auto	Automatic mode supported for fan speed
2	RCK	Rocking	Rocking movement supported
3	WND	Wind	Wind emulation supported
4	STEP	Step	Step command supported
5	DIR	Airflow Direction	Airflow Direction attribute is supported

4. Attributes

4.1. Fan Mode

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0000	FanMode	FanModeEnum	0 to 6	N	0	RW VO	M

This attribute SHALL indicate the current speed mode of the fan. This attribute MAY be written by the client to indicate a new speed mode of the fan. This attribute SHALL be set to one of the values in FanModeEnum.

When the FanMode attribute is written to, the PercentSetting and SpeedSetting (if present) attributes SHALL be set to appropriate values, as defined by the Percent Rules and Speed Rules respectively, unless otherwise specified below.

When the FanMode attribute is set to any given mode, the PercentCurrent and SpeedCurrent (if present) SHALL indicate the actual currently operating fan speed, unless otherwise specified below.

[Off value]

Setting the attribute value to Off SHALL set the values of these attributes to 0 (zero):

• PercentSetting
• PercentCurrent
• SpeedSetting (if present)
• SpeedCurrent (if present)

[Auto value]

Setting the attribute value to Auto SHALL set the values of these attributes to null:

• PercentSetting
• SpeedSetting (if present)

These attributes SHALL continue to indicate the current state of the fan while this attribute value is Auto:

• PercentCurrent
• SpeedCurrent (if present)

[On value]

If a client attempts to write a value of On, the attribute SHALL be set to High.

[Smart value]

If a client attempts to write a value of Smart and the AUT feature is supported, the attribute SHALL be set to Auto, otherwise the attribute SHALL be set to High.

4.1.1. FanModeEnum

Value	Name	Summary	Conformance
0	Off	Fan is off	M
1	Low	Fan using low speed	desc
If the fan supports 2 or more speeds, the Low value SHALL be supported. The Low value SHALL be supported if and only if the FanModeSequence attribute value is less than 4.
2	Medium	Fan using medium speed	desc
If the fan supports 3 or more speeds, the Medium value SHALL be supported. The Medium value SHALL be supported if and only if the FanModeSequence attribute value is 0 or 2.
3	High	Fan using high speed	M
4	On		D
5	Auto	Fan is using auto mode	AUT
6	Smart	Fan is using smart mode	D

 

4.2. Fan Mode Sequence

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0001	FanModeSequence	FanModeSequenceEnum	0 to 5	N	MS	R V	M

This attribute indicates the fan speed ranges that SHALL be supported.

4.2.1. FanModeSequenceEnum

Value	Name	Summary	Conformance
0	Off/Low/Med/High	Fan is capable of off, low, medium and high modes	[!AUT].a
1	Off/Low/High	Fan is capable of off, low and high modes	[!AUT].a
2	Off/Low/Med/High/Auto	Fan is capable of off, low, medium, high and auto modes	[AUT].a
3	Off/Low/High/Auto	Fan is capable of off, low, high and auto modes	[AUT].a
4	Off/High/Auto	Fan is capable of off, high and auto modes	[AUT].a
5	Off/High	Fan is capable of off and high modes	[!AUT].a

 

4.3. Percent Setting

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0002	PercentSetting	percent	0 to 100	X	0	RW VO	M

This attribute SHALL indicate the speed setting for the fan. This attribute MAY be written by the client to indicate a new fan speed. If the client writes null to this attribute, the attribute value SHALL NOT change. If this is set to 0, the server SHALL set the FanMode attribute value to Off.

 

[Percent Rules]

It is up to the server implementation to map between ranges of the PercentSetting attribute and FanMode attribute enumerated values. Percent values are split into ranges, each range corresponding to a supported FanMode attribute value. Percent ranges SHALL NOT overlap. All percent values in the High speed range SHALL be higher than all percent values in the Medium and Low speed ranges, if supported. All percent values in the Medium speed range SHALL be higher than all percent values in the Low speed range. If the client sets the FanMode attribute to Low, Medium or High, the server SHALL set the PercentSetting attribute to a value within the corresponding range. If the client sets the PercentSetting attribute, the server SHALL set the FanMode attribute to Low, Medium or High, based on the percent value being in the corresponding range.

If the MultiSpeed feature is supported, the calculation of SpeedSetting or SpeedCurrent (speed) from a percent value change for PercentSetting or PercentCurrent respectively (percent) SHALL hold true:

• speed = ceil( SpeedMax * (percent * 0.01) )

For example: If the SpeedMax attribute is 42 (42 speed fan) and PercentSetting is changed to 25, then SpeedSetting and SpeedCurrent become 11 (rounding up 10.5).

4.4. Percent Current

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0003	PercentCurrent	percent	0 to 100		desc	R V	M

This attribute SHALL indicate the actual currently operating fan speed, or zero to indicate that the fan is off. See Percent Rules for more details.

4.5. Speed Max

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0004	SpeedMax	uint8	1 to 100	F	MS	R V	SPD

This attribute SHALL indicate that the fan has one speed (value of 1) or the maximum speed, if the fan is capable of multiple speeds.

4.6. Speed Setting

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0005	SpeedSetting	uint8	0 to SpeedMax	X	0	RW VO	SPD

This attribute SHALL indicate the speed setting for the fan. This attribute MAY be written by the client to indicate a new fan speed. If the client writes null to this attribute, the attribute value SHALL NOT change. If this is set to 0, the server SHALL set the FanMode attribute value to Off. Please see the Speed Rules for details on other values.

 

[Speed Rules]

It is up to the server implementation to map between ranges of the SpeedSetting attribute and FanMode attribute enumerated values. Speed values are split into ranges, each range corresponding to a FanMode attribute value. Speed ranges SHALL NOT overlap. All speed values in the High speed range SHALL be higher than all speed values in the Medium and Low speed ranges, if supported. All speed values in the Medium speed range SHALL be higher than all speed values in the Low speed range. If the client sets the FanMode attribute to Low, Medium or High, the server SHALL set the SpeedSetting attribute to a value within the corresponding range. If the client sets the SpeedSetting attribute, the server SHALL set the FanMode attribute to Low, Medium or High, based on the speed value being in the corresponding range.

This calculation for the value of PercentSetting or PercentCurrent (percent) from a speed value change for SpeedSetting or SpeedCurrent respectively (speed) SHALL hold true:

• percent = floor( speed/SpeedMax * 100 )

For example: If the SpeedMax attribute is 42 (42 speed fan) and SpeedSetting attribute is changed to 11, then PercentSetting and PercentCurrent become 26.

4.7. Speed Current

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0006	SpeedCurrent	uint8	0 to SpeedMax	P	desc	R V	SPD

This attribute SHALL indicate the actual currently operating fan speed, or zero to indicate that the fan is off.

4.8. Rock Support

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0007	RockSupport	RockBitmap	desc	F	0	R V	RCK

This attribute is a bitmap that indicates what rocking motions the server supports.

4.8.1. RockBitmap

Value	Name	Summary	Conformance
0	RockLeftRight	Indicate rock left to right	M
1	RockUpDown	Indicate rock up and down	M
2	RockRound	Indicate rock arounc	M

 

4.9. Rock Setting

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0008	RockSetting	RockBitmap	desc	P	0	RW VO	RCK

This attribute is a bitmap that indicates the current active fan rocking motion settings. Each bit SHALL only be set to 1, if the corresponding bit in the RockSupport attribute is set to 1, otherwise a status code of CONSTRAINT_ERROR SHALL be returned.

If a combination of supported bits is set by the client, and the server does not support the combination, the lowest supported single bit in the combination SHALL be set and active, and all other bits SHALL indicate zero.

For example: If RockUpDown and RockRound are both set, but this combination is not possible, then only RockUpDown becomes active.

4.10. Wind Support

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0009	WindSupport	WindBitmap	desc	F	0	R V	WND

This attribute is a bitmap that indicates what wind modes the server supports. At least one wind mode bit SHALL be set.

4.10.1 WindBitmap

Value	Name	Summary	Conformance
0	SleepWind	Indicate sleep wind	M
The fan speed, based on current settings, SHALL gradually slow down to a final minimum speed. For this process, the sequence, speeds and duration are MS.
1	NaturalWind	Indicate natural wind	M
The fan speed SHALL vary to emulate natural wind. For this setting, the sequence, speeds and duration are MS

 

4.11. Wind Setting

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x000A	WindSetting	WindBitmap	desc	P	0	RW VO	WND

This attribute is a bitmap that indicates the current active fan wind feature settings. Each bit SHALL only be set to 1, if the corresponding bit in the WindSupport attribute is set to 1, otherwise a status code of CONSTRAINT_ERROR SHALL be returned.

If a combination of supported bits is set by the client, and the server does not support the combination, the lowest supported single bit in the combination SHALL be set and active, and all other bits SHALL indicate zero.

For example: If Sleep Wind and Natural Wind are set, but this combination is not possible, then only Sleep Wind becomes active.

4.12. Airflow Direction

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x000B	AirflowDirection	AirflowDirectionEnum	desc	P	0	RW VO	DIR

This attribute SHALL indicate the current airflow direction of the fan. This attribute MAY be written by the client to indicate a new airflow direction for the fan. This attribute SHALL be set to one of the values in the AirflowDirectionEnum table.

4.12.1. AirflowDirectionEnum

Value	Name	Summary	Conformance
0	Forward	Airflow is in the forward direction	M
1	Reverse	Airflow is in the reverse direction	M

5. Commands

5.1. Step

ID	Name	Direction	Response	Access	Conformance
0x00	Step	client → server	Y	O	STEP

This command speeds up or slows down the fan, in steps, without the client having to know the fan speed. This command supports, for example, a user operated wall switch, where the user provides the feedback or control to stop sending this command when the proper speed is reached. The step speed values are implementation specific. How many step speeds are implemented is implementation specific.

This command supports these fields:

ID	Name	Type	Constraint	Quality	Default	Conformance
0	Direction	StepDirectionEnum			Increase	M
1	Wrap	bool			false	O
2	LowestOff	bool			true	O

[Direction field]

This field SHALL indicate whether the fan speed increases or decreases to the next step value.

[Wrap Field]

This field SHALL indicate if the fan speed wraps between highest and lowest step value.

[LowestOff Field]

This field SHALL indicate that the fan being off (speed value 0) is included as a step value.

[When Generated]

The client sends this command to speed the fan up or down in a step by step fashion.

[Effect Upon Receipt]

• This command SHALL be executed even if the fan speed is not currently at an implemented step value.
• If the Direction field is Increase,
  • If the fan speed is lower than the highest step value, the fan speed SHALL change to the lowest step value that is higher than the current fan speed.
  • Else if Wrap is TRUE, the fan speed SHALL change to the lowest step value.
  • Else the fan speed SHALL change to (or remain at) the highest step value.
• If the Direction field is Decrease,
  • If the fan speed is higher than the lowest step value, the fan speed SHALL change to the highest step value that is lower than the current fan speed.
  • Else if Wrap is TRUE, the fan speed SHALL change to the highest step value.
  • Else the fan speed SHALL change to (or remain at) the lowest step value.
• Although the effect of the Step command is implementation specific, the effect on receipt of the Step command SHALL adhere to the conformance of the affected attributes.

5.1.1. StepDirectionEnum

Value	Name	Summary	Conformance
0	Increase	Step moves in increasing direction	M
1	Decrease	Step moves in decreasing direction	M