Matter Specification - Color Control Cluster

Mater :: Color Control Cluster

---

This cluster provides an interface for changing the color of a light. Color is specified according to the Commission Internationale de l’Éclairage (CIE) specification CIE 1931 Color Space. Color control is carried out in terms of x,y values, as defined by this specification.

Additionally, color MAY optionally be controlled in terms of color temperature, or as hue and satu­ration values based on optionally variable RGB and W color points. It is recommended that the hue and saturation are interpreted according to the HSV (aka HSB) color model.

 

Control over luminance is not included, as this is provided by means of the Level Control for Light­ing cluster. It is recommended that the level provided by this cluster be interpreted as representing a proportion of the maximum intensity achievable at the current color.

 

조명의 색상을 제어하기 위한 클러스터

XY 방식, 색온도 방식, Hue/Saturation 방식 등 다양한 메커니즘으로 색상 온도를 제어할 수 있으므로, 홈네트워크 플랫폼이 지원하는 방식에 따라 취사선택 가능

RGBW, HSV 등 색에 대한 기본적인 이해가 요구되지만, 내용을 전혀 몰라도 간단한 색상 변경 제어는 쉽게 구현 가능

---

1. Classification

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

2. Identifier

Identifier	Name
0x0300	Color Control

3. Features

3.1. Bit 0: Hue/Saturation

Bit	Code	Feature	Description
0	HS	Hue/Saturation	Supports color specification via hue/saturation

3.2. Bit 1: Enhanded Hue

Bit	Code	Feature	Description
1	EHUE	Enhanced Hue	Enhanced hue is supported

※ Support for EHUE SHALL require support for HS

3.3. Bit 2: Color Loop

Bit	Code	Feature	Description
2	CL	Color Loop	Color loop is supported

※ Support for CL SHALL require support for EHUE

3.4. Bit 3: XY

Bit	Code	Feature	Description
3	XY	XY	Supports color specification via XY

3.5. Bit 4: Color Temperature

Bit	Code	Feature	Description
4	CT	Color Temperature	Supports specification of color temperature

4. Dependencies

4.1. Coupling color temperature to Level Control

If the Level Control for Lighting cluster identifier 0x0008 is supported on the same endpoint as the Color Control cluster and color temperature is supported, it is possible to couple changes in the current level to the color temperature.

The CoupleColorTempToLevel bit of the Options attribute of the Level Control cluster indicates whether the color temperature is to be linked with the CurrentLevel attribute in the Level Control cluster.

If the CoupleColorTempToLevel bit of the Options attribute of the Level Control cluster is equal to 1 and the ColorMode or EnhancedColorMode attribute is set to 2 (color temperature) then a change in the CurrentLevel attribute SHALL affect the ColorTemperatureMireds attribute. This relationship is manufacturer specific, with the qualification that the maximum value of the CurrentLevel attribute SHALL correspond to a ColorTemperatureMired attribute value equal to the CoupleColorTempToLevelMinMireds attribute. This relationship is one way so a change to the ColorTemperatureMireds attribute SHALL NOT have any effect on the CurrentLevel attribute.

In order to simulate the behavior of an incandescent bulb, a low value of the CurrentLevel attribute SHALL be associated with a high value of the ColorTemperatureMireds attribute (i.e., a low value of color temperature in kelvins). If the CoupleColorTempToLevel bit of the Options attribute of the Level Control cluster is equal to 0, there SHALL be no link between color temperature and current level.

5. Attributes

5.1. Color Information

5.1.1. Current Hue

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0000	CurrentHue	uint8	0 to 254	PN	0	R V	HS

The CurrentHue attribute contains the current hue value of the light. It is updated as fast as practical during commands that change the hue.

The hue in degrees SHALL be related to the CurrentHue attribute by the relationship:

Hue = CurrentHue x 360 / 254 (CurrentHue in the range 0 to 254 inclusive)

If this attribute is implemented then the CurrentSaturation and ColorMode attributes SHALL also be implemented.

 

5.1.2. Current Saturation

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0001	CurrentSaturation	uint8	0 to 254	PSN	0	R V	HS

The CurrentSaturation attribute holds the current saturation value of the light. It is updated as fast as practical during commands that change the saturation.

The saturation SHALL be related to the CurrentSaturation attribute by the relationship:

Saturation = CurrentSaturation / 254 (CurrentSaturation in the range 0 to 254 inclusive)

If this attribute is implemented then the CurrentHue and ColorMode attributes SHALL also be implemented.

 

5.1.3. Remaining Time

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0002	RemainingTime	uint16	0 to 65534			R V	O

The RemainingTime attribute holds the time remaining, in 1/10ths of a second, until the currently active command will be complete.

 

5.1.4. Current X

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0003	CurrentX	uint16	0 to 0xFEFF	PSN	0x616B	R V	XY

The CurrentX attribute contains the current value of the normalized chromaticity value x, as defined in the CIE xyY Color Space. It is updated as fast as practical during commands that change the color.

The value of x SHALL be related to the CurrentX attribute by the relationship

x = CurrentX / 65536 (CurrentX in the range 0 to 65279 inclusive)

 

5.1.5. Current Y

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0004	CurrentY	uint16	0 to 0xFEFF	PSN	0x607D	R V	XY

The CurrentY attribute contains the current value of the normalized chromaticity value y, as defined in the CIE xyY Color Space. It is updated as fast as practical during commands that change the color.

The value of y SHALL be related to the CurrentY attribute by the relationship

y = CurrentY / 65536 (CurrentY in the range 0 to 65279 inclusive)

 

5.1.6. Drift Compensation

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0005	DriftCompensation	enum8	0 to 4			R V	O

The DriftCompensation attribute indicates what mechanism, if any, is in use for compensation for color/intensity drift over time. It SHALL be one of the non-reserved values in Values of the DriftCompensation Attribute.

Value	Description
0	None
1	Other / Unknown
2	Temperature monitoring
3	Optical luminance monitoring and feedback
4	Optical color monitoring and feedback

 

5.1.7. Compensation Text

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0006	CompensationText	string	max 254			R V	O

The CompensationText attribute holds a textual indication of what mechanism, if any, is in use to compensate for color/intensity drift over time.

 

5.1.8. Color Temperature Mireds

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0007	ColorTemperatureMireds	uint16	0 to 0xFEFF	PSN	0x00FA	R V	CT

The ColorTemperatureMireds attribute contains a scaled inverse of the current value of the color temperature. The unit of ColorTemperatureMireds is the mired (micro reciprocal degree), AKA mirek (micro reciprocal kelvin). It is updated as fast as practical during commands that change the color.

The color temperature value in kelvins SHALL be related to the ColorTemperatureMireds attribute in mireds by the relationship

Color temperature in kelvins = 1,000,000 / ColorTemperatureMireds, where ColorTemperatureMireds is in the range 1 to 65279 mireds inclusive, giving a color temperature range from 1,000,000 kelvins to 15.32 kelvins.

If this attribute is implemented then the ColorMode attribute SHALL also be implemented.

 

5.1.9. Color Mode

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0008	ColorMode	enum8	0 to 2	N	1	R V	M

The ColorMode attribute indicates which attributes are currently determining the color of the device.

The value of the ColorMode attribute cannot be written directly - it is set upon reception of any command in section Commands to the appropriate mode for that command.

Value	Attributes that Determine the Color
0	CurrentHue and CurrentSaturation
1	CurrentX and CurrentY
2	ColorTemperatureMireds

 

5.1.10. 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	Values & Summary
0	ExecuteIfOff	0 – Do not execute command if the On/Off cluster, OnOff attribute is FALSE. 1 – Execute command if the On/Off cluster, OnOff attribute is FALSE.

ExecuteIfOff Options bit: Command execution SHALL NOT continue beyond the Options processing if all of these criteria are true:

• 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.

 

5.1.11. Enhanced Current Hue

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x4000	EnhancedCurrentHue	uint16	all	SN	0	R V	EHUE

The EnhancedCurrentHue attribute represents non-equidistant steps along the CIE 1931 color triangle, and it provides 16-bits precision.

The upper 8 bits of this attribute SHALL be used as an index in the implementation specific XY lookup table to provide the non-equidistance steps. The lower 8 bits SHALL be used to interpolate between these steps in a linear way in order to provide color zoom for the user.

To provide compatibility with standard ZCL, the CurrentHue attribute SHALL contain a hue value in the range 0 to 254, calculated from the EnhancedCurrentHue attribute.

 

5.1.12. Enhanced Color Mode

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x4001	EnhancedColorMode	enum8	0 to 3	N	1	R V	M

The EnhancedColorMode attribute specifies which attributes are currently determining the color of the device, as detailed in Values of the EnhancedColorMode Attribute.

Value	Attributes that Determine the Color
0	CurrentHue and CurrentSaturation
1	CurrentX and CurrentY
2	ColorTemperatureMireds
3	EnhancedCurrentHue and CurrentSaturation

To provide compatibility with standard ZCL, the original ColorMode attribute SHALL indicate ‘CurrentHue and CurrentSaturation’ when the light uses the EnhancedCurrentHue attribute. If the ColorMode attribute is changed, e.g., due to one of the standard Color Control cluster commands defined in the ZCL, its new value SHALL be copied to the EnhancedColorMode attribute.

 

5.1.13. Color Loop Active

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x4002	ColorLoopActive	uint8	all	SN	0	R V	CL

The ColorLoopActive attribute specifies the current active status of the color loop. If this attribute has the value 0, the color loop SHALL not be active. If this attribute has the value 1, the color loop SHALL be active. All other values (2 to 254) are reserved.

 

5.1.14. Color Loop Direction

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x4003	ColorLoopDirection	uint8	all	SN	0	R V	CL

The ColorLoopDirection attribute specifies the current direction of the color loop. If this attribute has the value 0, the EnhancedCurrentHue attribute SHALL be decremented. If this attribute has the value 1, the EnhancedCurrentHue attribute SHALL be incremented. All other values (2 to 254) are reserved.

 

5.1.15. Color Loop Time

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x4004	ColorLoopTime	uint16	all	SN	0x0019	R V	CL

The ColorLoopTime attribute specifies the number of seconds it SHALL take to perform a full color loop, i.e., to cycle all values of the EnhancedCurrentHue attribute (between 0 and 0xfffe).

 

5.1.16. Color Loop Start Enhanced Hue

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x4005	ColorLoopStartEnhancedHue	uint16	all		0x2300	R V	CL

The ColorLoopStartEnhancedHue attribute specifies the value of the EnhancedCurrentHue attribute from which the color loop SHALL be started.

 

5.1.17. Color Loop Stored Enhanbed Hue

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x4006	ColorLoopStoredEnhancedHue	uint16	all		0	R V	CL

The ColorLoopStoredEnhancedHue attribute specifies the value of the EnhancedCurrentHue attribute before the color loop was started. Once the color loop is complete, the EnhancedCurrentHue attribute SHALL be restored to this value.

 

5.1.18. Color Capabilities

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x400A	ColorCapabilities	map16	0 to 0x001F		0	R V	M

Bits 0-4 of the ColorCapabilities attribute SHALL have the same values as the corresponding bits of the FeatureMap attribute. All other bits in ColorCapabilities SHALL be 0.

 

5.1.19. Color Temp Physical Min Mireds

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x400B	ColorTempPhysicalMinMireds	uint16	0 to 0xFEFF		0	R V	CT

The ColorTempPhysicalMinMireds attribute indicates the minimum mired value supported by the hardware. ColorTempPhysicalMinMireds corresponds to the maximum color temperature in kelvins supported by the hardware. ColorTempPhysicalMinMireds ≤ ColorTemperatureMireds.

 

5.1.20. Color Temp Physical Max Mireds

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x400C	ColorTempPhysicalMaxMireds	uint16	0 to 0xFEFF		0xFEFF	R V	CT

The ColorTempPhysicalMaxMireds attribute indicates the maximum mired value supported by the hardware. ColorTempPhysicalMaxMireds corresponds to the minimum color temperature in kelvins supported by the hardware. ColorTemperatureMireds ≤ ColorTempPhysicalMaxMireds.

 

5.1.21. Couple Color Temp to Level Min Mireds

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x400D	CoupleColorTempToLevelMinMireds	uint16	(1)		MS	R V	(2)

(1): ColorTempPhysicalMinMireds to ColorTemperatureMireds

(2): CT | ColorTemperatureMireds

The CoupleColorTempToLevelMinMireds attribute specifies a lower bound on the value of the ColorTemperatureMireds attribute for the purposes of coupling the ColorTemperatureMireds attribute to the CurrentLevel attribute when the CoupleColorTempToLevel bit of the Options attribute of the Level Control cluster is equal to 1. When coupling the ColorTemperatureMireds attribute to the CurrentLevel attribute, this value SHALL correspond to a CurrentLevel value of 0xfe (100%).

This attribute SHALL be set such that the following relationship exists:

ColorTempPhysicalMinMireds ≤ CoupleColorTempToLevelMinMireds ≤ ColorTemperatureMireds

Note that since this attribute is stored as a micro reciprocal degree (mired) value (i.e. color temperature in kelvins = 1,000,000 / CoupleColorTempToLevelMinMireds), the CoupleColorTempToLevelMinMireds attribute corresponds to an upper bound on the value of the color temperature in kelvins supported by the device.

 

5.1.22. Start Up Color Temperature Mireds

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x4010	StartUpColorTemperatureMireds	uint16	0 to 0xFEFF	X	MS	RW VM	(1)

(1): CT | ColorTemperatureMireds

The StartUpColorTemperatureMireds attribute SHALL define the desired startup color temperature value a lamp SHALL use when it is supplied with power and this value SHALL be reflected in the ColorTemperatureMireds attribute. In addition, the ColorMode and EnhancedColorMode attributes SHALL be set to 0x02 (color temperature). The values of the StartUpColorTemperatureMireds attribute are listed in the table below,

Value	Action on power up
0 to 0xFEFF	Set the ColorTemperatureMireds attribute to this value.
null	Set the ColorTemperatureMireds attribute to its previous value.

5.2. Defined Primaries Information

5.2.1. Number of Primaries

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0010	NumberOfPrimaries	uint8	0 to 6	FX		R V	M

The NumberOfPrimaries attribute contains the number of color primaries implemented on this device. A value of null SHALL indicate that the number of primaries is unknown.

Where this attribute is implemented, the attributes below for indicating the “x” and “y” color values of the primaries SHALL also be implemented for each of the primaries from 1 to NumberOfPrimaries, without leaving gaps. Implementation of the Primary1Intensity attribute and subsequent intensity attributes is optional.

 

5.2.2. Primary1 X

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0011	Primary1X	uint16	0 to 0xFEFF	F		R V	M0

M0: Mandatory if the value of ther NumberOfPrimaries attribute is greater than 0, otherwise optional.

The Primary1X attribute contains the normalized chromaticity value x for this primary, as defined in the CIE xyY Color Space.

The value of x SHALL be related to the Primary1X attribute by the relationship

x = Primary1X / 65536 (Primary1X in the range 0 to 65279 inclusive)

 

5.2.3. Primary1 Y

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0012	Primary1Y	uint16	0 to 0xFEFF	F		R V	M0

M0: Mandatory if the value of ther NumberOfPrimaries attribute is greater than 0, otherwise optional.

The Primary1Y attribute contains the normalized chromaticity value y for this primary, as defined in the CIE xyY Color Space.

The value of y SHALL be related to the Primary1Y attribute by the relationship

y = Primary1Y / 65536 (Primary1Y in the range 0 to 65279 inclusive)

 

5.2.4. Primary1 Intensity

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0013	Primary1Intensity	uint8	all	FX		R V	M0

M0: Mandatory if the value of ther NumberOfPrimaries attribute is greater than 0, otherwise optional.

The Primary1intensity attribute contains a representation of the maximum intensity of this primary as defined in the Dimming Light Curve in the Ballast Configuration cluster (see Ballast Configuration Cluster), normalized such that the primary with the highest maximum intensity contains the value 0xfe.

A value of null SHALL indicate that this primary is not available.

 

5.2.5. Primary2 X

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0015	Primary2X	uint16	0 to 0xFEFF	F		R V	M1

M1: Mandatory if the value of ther NumberOfPrimaries attribute is greater than 1, otherwise optional.

 

5.2.6. Primary2 Y

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0016	Primary2Y	uint16	0 to 0xFEFF	F		R V	M1

M1: Mandatory if the value of ther NumberOfPrimaries attribute is greater than 1, otherwise optional.

 

5.2.7. Primary2 Intensity

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0017	Primary2Intensity	uint8	all	FX		R V	M0

M1: Mandatory if the value of ther NumberOfPrimaries attribute is greater than 1, otherwise optional.

 

5.2.8. Primary3 X

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0019	Primary3X	uint16	0 to 0xFEFF	F		R V	M2

M2: Mandatory if the value of ther NumberOfPrimaries attribute is greater than 1, otherwise optional.

 

5.2.9. Primary3 Y

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x001A	Primary3Y	uint16	0 to 0xFEFF	F		R V	M2

M2: Mandatory if the value of ther NumberOfPrimaries attribute is greater than 1, otherwise optional.

 

5.2.10. Primary3 Intensity

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x001B	Primary3Intensity	uint8	all	FX		R V	M2

M2: Mandatory if the value of ther NumberOfPrimaries attribute is greater than 2, otherwise optional.

 

※ The Primary2X, Primary2Y, Primary2Intensity, Primary3X, Primary3Y and Primary3Intensity attributes are used to represent the capabilities of the 2nd and 3rd primaries, where present, in the same way as for the Primary1X, Primary1Y and Primary1Intensity attributes.

5.3. Additional Defined Primaries Information

5.3.1. Primary4 X

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0020	Primary4X	uint16	0 to 0xFEFF	F		R V	M3

M3: Mandatory if the value of ther NumberOfPrimaries attribute is greater than 3, otherwise optional.

 

5.3.2. Primary4 Y

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0021	Primary4Y	uint16	0 to 0xFEFF	F		R V	M3

M3: Mandatory if the value of ther NumberOfPrimaries attribute is greater than 1, otherwise optional.

 

5.3.3. Primary4 Intensity

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0022	Primary4Intensity	uint8	all	FX		R V	M3

M3: Mandatory if the value of ther NumberOfPrimaries attribute is greater than 3, otherwise optional.

 

5.3.4. Primary5 X

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0024	Primary5X	uint16	0 to 0xFEFF	F		R V	M4

M4: Mandatory if the value of ther NumberOfPrimaries attribute is greater than 4, otherwise optional.

 

5.3.5. Primary5 Y

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0025	Primary5Y	uint16	0 to 0xFEFF	F		R V	M4

M4: Mandatory if the value of ther NumberOfPrimaries attribute is greater than 4, otherwise optional.

 

5.3.6. Primary5 Intensity

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0026	Primary5Intensity	uint8	all	FX		R V	M4

M4: Mandatory if the value of ther NumberOfPrimaries attribute is greater than 4, otherwise optional.

 

5.3.7. Primary6 X

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0028	Primary6X	uint16	0 to 0xFEFF	F		R V	M5

M5: Mandatory if the value of ther NumberOfPrimaries attribute is greater than 5, otherwise optional.

 

5.3.8. Primary6 Y

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0029	Primary6Y	uint16	0 to 0xFEFF	F		R V	M5

M5: Mandatory if the value of ther NumberOfPrimaries attribute is greater than 5, otherwise optional.

 

5.3.9. Primary6 Intensity

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x002A	Primary6Intensity	uint8	all	FX		R V	M5

M5: Mandatory if the value of ther NumberOfPrimaries attribute is greater than 5, otherwise optional.

 

※ The Primary4X, Primary4Y, Primary4Intensity, Primary5X, Primary5Y, Primary5Intensity, Primary6X, Primary6Y and Primary6Intensity attributes represent the capabilities of the 4th, 5th and 6th primaries, where present, in the same way as the Primary1X, Primary1Y and Primary1Intensity attributes.

5.4. Defined Color Points Settings

5.4.1. White Point X

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0030	WhitePointX	uint16	0 to 0xFEFF			RW VM	O

The WhitePointX attribute contains the normalized chromaticity value x, as defined in the CIE xyY Color Space, of the current white point of the device.

The value of x SHALL be related to the WhitePointX attribute by the relationship

x = WhitePointX / 65536 (WhitePointX in the range 0 to 65279 inclusive)

 

5.4.2. White Point Y

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0031	WhitePointY	uint16	0 to 0xFEFF			RW VM	O

The WhitePointY attribute contains the normalized chromaticity value y, as defined in the CIE xyY Color Space, of the current white point of the device.

The value of y SHALL be related to the WhitePointY attribute by the relationship

y = WhitePointY / 65536 (WhitePointY in the range 0 to 65279 inclusive)

 

5.4.3. Color Point Red X

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0032	ColorPointRX	uint16	0 to 0xFEFF			RW VM	O

The ColorPointRX attribute contains the normalized chromaticity value x, as defined in the CIE xyY Color Space, of the red color point of the device.

The value of x SHALL be related to the ColorPointRX attribute by the relationship

x = ColorPointRX / 65536 (ColorPointRX in the range 0 to 65279 inclusive)

 

5.4.4. Color Point Red Y

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0033	ColorPointRY	uint16	0 to 0xFEFF			RW VM	O

The ColorPointRY attribute contains the normalized chromaticity value y, as defined in the CIE xyY Color Space, of the red color point of the device.

The value of y SHALL be related to the ColorPointRY attribute by the relationship

y = ColorPointRY / 65536 (ColorPointRY in the range 0 to 65279 inclusive)

 

5.4.5. Color Point Red Intensity

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0034	ColorPointRIntensity	uint8	all	X		RW VM	O

The ColorPointRIntensity attribute contains a representation of the relative intensity of the red color point as defined in the Dimming Light Curve in the Ballast Configuration cluster (see Ballast Configuration Cluster), normalized such that the color point with the highest relative intensity contains the value 0xfe.

A value of null SHALL indicate an invalid value.

 

5.4.6. Color Point Green X

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0036	ColorPointGX	uint16	0 to 0xFEFF			RW VM	O

 

5.4.7. Color Point Green Y

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0037	ColorPointGY	uint16	0 to 0xFEFF			RW VM	O

 

5.4.8. Color Point Green Intensity

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0038	ColorPointGIntensity	uint8	all	X		RW VM	O

 

5.4.9. Color Point Blue X

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x003A	ColorPointBX	uint16	0 to 0xFEFF			RW VM	O

 

5.4.10. Color Point Blue Y

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x003B	ColorPointBY	uint16	0 to 0xFEFF			RW VM	O

 

5.4.11. Color Point Blue Intensity

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x003C	ColorPointBIntensity	uint8	all	X		RW VM	O

 

※The ColorPointGX, ColorPointGY, ColorPointGIntensity, ColorPointBX, ColorPointBY and, ColorPointBIntensity attributes are used to represent the chromaticity values and intensities of the green and blue color points, in the same way as for the ColorPointRX, ColorPointRY and ColorPointRIntensity attributes.

If any one of these red, green or blue color point attributes is implemented then they SHALL all be implemented.

6. Commands

---

[Generic Usage Notes]

When asked to change color via one of these commands, the implementation SHALL select a color, within the limits of the hardware of the device, which is as close as possible to that requested. The determination as to the true representations of color is out of the scope of this specification. However, as long as the color data fields of the received command are within the permitted range of this specification and no error condition applies, the resulting status code SHALL be SUCCESS.

For example the MoveToColorTemperature command: if the target color temperature is not achievable by the hardware then the color temperature SHALL be clipped at the physical minimum or maximum achievable (depending on the direction of the color temperature transition) when the device reaches that color temperature (which MAY be before the requested transition time).

If a color loop is active (i.e., the ColorLoopActive attribute is equal to 1), it SHALL only be stopped by sending a specific ColorLoopSet command frame with a request to deactivate the color loop (i.e., the color loop SHALL not be stopped on receipt of another command such as the EnhancedMoveToHue command). In addition, while a color loop is active, a manufacturer MAY choose to ignore incoming color commands which affect a change in hue.

[Note on Chnage of ColorMode]

The first action taken when any one of these commands is received is to change the ColorMode attribute to the appropriate value for the command (see individual commands). Note that, when moving from one color mode to another (e.g., CurrentX/CurrentY to CurrentHue/CurrentSaturation), the starting color for the command is formed by calculating the values of the new attributes (in this case CurrentHue, CurrentSaturation) from those of the old attributes (in this case CurrentX and CurrentY).

When moving from a mode to another mode that has a more restricted color range (e.g., CurrentX/CurrentY to CurrentHue/CurrentSaturation, or CurrentHue/CurrentSaturation to ColorTemperatureMireds) it is possible for the current color value to have no equivalent in the new mode. The behavior in such cases is manufacturer dependent, and therefore it is recommended to avoid color mode changes of this kind during usage.

[Use of the OptionsMask and OptionsOverride fields]

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.

---

6.1. Move to Hue

ID	Name	Direction	Response	Access	Conformance
0x00	MoveToHue	client → server	Y	O	HS

The MoveToHue command SHALL have the following data fields:

ID	Name	Type	Constraint	Quality	Default	Conformance
0	Hue	uint8	0 to 254			M
1	Direction	enum8	desc			M
2	TransitionTime	uint16	0 to 65534			M
3	OptionsMask	map8	desc		0	M
4	OptionsOverride	map8	desc		0	M

[Hue]

The Hue field specifies the hue to be moved to.

 

[Direction]

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

Value	Description
0	Shortest distance
1	Longest distance
2	Up
3	Down

[TransitionTime]

The TransitionTime field specifies, in 1/10ths of a second, the time that SHALL be taken to move to the new hue.

 

[Effect on Receipt]

On receipt of this command, a device SHALL also set the ColorMode attribute to the value 0 and then SHALL move from its current hue to the value given in the Hue field.

The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the new hue SHALL be equal to the TransitionTime field.

As hue is effectively measured on a circle, the new hue MAY be moved to in either direction. The direction of hue change is given by the Direction field. If Direction is 'Shortest distance', the direction is taken that involves the shortest path round the circle. This case corresponds to expected normal usage. If Direction is 'Longest distance', the direction is taken that involves the longest path round the circle. This case can be used for 'rainbow effects'. In both cases, if both distances are the same, the Up direction SHALL be taken.

 

6.2. Move Hue

ID	Name	Direction	Response	Access	Conformance
0x01	MoveHue	client → server	Y	O	HS

The MoveHue command SHALL have the following data fields:

ID	Name	Type	Constraint	Quality	Default	Conformance
0	MoveMode	enum8	desc			M
1	Rate	uint8	all			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. If the MoveMode field is equal to 0 (Stop), the Rate field SHALL be ignored.

Value	Description
0	Stop
1	Up
2	Reserved
3	Down

 [Rate]

The Rate field specifies the rate of movement in steps per second. A step is a change in the device’s hue of one unit. If the MoveMode field is set to 1 (up) or 3 (down) and the Rate field has a value of zero, the command has no effect and a response command SHALL be sent in response, with the status code set to INVALID_COMMAND. If the MoveMode field is set to 0 (stop) the Rate field SHALL be ignored.

  

[Effect on Receipt]

On receipt of this command, a device SHALL set the ColorMode attribute to the value 0 and SHALL then move from its current hue in an up or down direction in a continuous fashion, as detailed in Actions on Receipt for MoveHue Command.

ModeMode	Action on Receipt
Stop	If moving, stop, else ignore the command (i.e., the command is accepted but has no effect). NB This MAY also be used to stop a MoveToHue command, a MoveToSaturation command, or a MoveToHueAndSaturation command.
Up	Increase the device’s hue at the rate given in the Rate field. If the hue reaches the maximum allowed for the device, then wraparound and proceed from its minimum allowed value.
Down	Decrease the device’s hue at the rate given in the Rate field. If the hue reaches the minimum allowed for the device, then wraparound and proceed from its maximum allowed value.

 

 

6.3. Step Hue

ID	Name	Direction	Response	Access	Conformance
0x02	StepHue	client → server	Y	O	HS

The StepHue command SHALL have the following data fields:

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

[StepMode]

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

Value	Description
0	Reserverd
1	Up
2	Reserved
3	Down

[StepSize]

The change to be added to (or subtracted from) the current value of the device’s hue.

 

[TransitionTime]

The TransitionTime field specifies, in 1/10ths of a second, the time that SHALL be taken to perform the step. A step is a change in the device’s hue of ‘Step size’ units.

Note: Here the TransitionTime data field is of data type uint8, where uint16 is more common for TransitionTime data fields in other clusters / commands.

 

[Effect on Receipt]

On receipt of this command, a device SHALL set the ColorMode attribute to the value 0 and SHALL then move from its current hue in an up or down direction by one step, as detailed in Actions on Receipt for StepHue Command.

StepMode	Action on Receipt
Up	Increase the device’s hue by one step, in a continuous fashion. If the hue value reaches the maximum value then wraparound and proceed from the minimum allowed value.
Down	Decrease the device’s hue by one step, in a continuous fashion. If the hue value reaches the minimum value then wraparound and proceed from the maximum allowed value.

 

6.4. Move to Saturation

ID	Name	Direction	Response	Access	Conformance
0x03	MoveToSaturation	client → server	Y	O	HS

The MoveToSaturation command SHALL have the following data fields:

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

[Effect on Receipt]

On receipt of this command, a device set the ColorMode attribute to the value 0 and SHALL then move from its current saturation to the value given in the Saturation field.

The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the new saturation SHALL be equal to the TransitionTime field, in 1/10ths of a second.

 

6.5. Move Saturation

ID	Name	Direction	Response	Access	Conformance
0x04	MoveSaturation	client → server	Y	O	HS

The MoveSaturation command SHALL have the following data fields:

ID	Name	Type	Constraint	Quality	Default	Conformance
0	MoveMode	enum8	desc			M
1	Rate	uint8	all			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. If the MoveMode field is equal to 0 (Stop), the Rate field SHALL be ignored.

Value	Description
0	Stop
1	Up
2	Reserved
3	Down

[Rate]

The Rate field specifies the rate of movement in steps per second. A step is a change in the device’s  saturation of one unit. If the MoveMode field is set to 1 (up) or 3 (down) and the Rate field has a value of zero, the command has no effect and a response command SHALL be sent in response, with the status code set to INVALID_COMMAND. If the MoveMode field is set to 0 (stop) the Rate field SHALL be ignored.

 

[Effect on Receipt]

On receipt of this command, a device SHALL set the ColorMode attribute to the value 0 and SHALL then move from its current saturation in an up or down direction in a continuous fashion, as detailed in Actions on Receipt for MoveSaturation Command.

MoveMode	Action on Receipt
Stop	If moving, stop, else ignore the command (i.e., the command is accepted but has no effect). NB This MAY also be used to stop a MoveToSaturation command, a MoveToHue command, or a MoveToHueAndSaturation command.
Up	Increase the device’s saturation at the rate given in the Rate field. If the saturation reaches the maximum allowed for the device, stop.
Down	Decrease the device’s saturation at the rate given in the Rate field. If the saturation reaches the minimum allowed for the device, stop.

 

6.6. Step Saturation

ID	Name	Direction	Response	Access	Conformance
0x05	StepSaturation	client → server	Y	O	HS

The StepSaturation 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	uint8	all			M
3	OptionsMask	map8	desc		0	M
4	OptionsOverride	map8	desc		0	M

[StepMode]

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

Value	Description
1	Up
2	Reserved
3	Down

[StepSize]

The change to be added to (or subtracted from) the current value of the device’s saturation.

 

[TransitionTime]

The TransitionTime field specifies, in 1/10ths of a second, the time that SHALL be taken to perform the step. A step is a change in the device’s saturation of ‘Step size’ units.

Note: Here the TransitionTime data field is of data type uint8, where uint16 is more common for TransitionTime data fields in other clusters / commands.

 

[Effect on Receipt]

On receipt of this command, a device SHALL set the ColorMode attribute to the value 0 and SHALL then move from its current saturation in an up or down direction by one step, as detailed in Actions on Receipt for StepSaturation Command.

StepMode	Action on Receipt
Up	Increase the device’s saturation by one step, in a continuous fashion. However, if the saturation value is already the maximum value then do nothing.
Down	Decrease the device’s saturation by one step, in a continuous fashion. However, if the saturation value is already the minimum value then do nothing.

 

6.7. Move to Hue and Saturation

ID	Name	Direction	Response	Access	Conformance
0x06	MoveToHueAndSaturation	client → server	Y	O	HS

The MoveToHueAndSaturation command SHALL have the following data fields:

ID	Name	Type	Constraint	Quality	Default	Conformance
0	Hue	uint8	0 to 254			M
1	Saturation	uint8	0 to 254			M
2	TransitionTime	uint16	0 to 65534			M
3	OptionsMask	map8	desc		0	M
4	OptionsOverride	map8	desc		0	M

[Effect on Receipt]

On receipt of this command, a device SHALL set the ColorMode attribute to the value 0 and SHALL then move from its current hue and saturation to the values given in the Hue and Saturation fields.

The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the new color SHALL be equal to the TransitionTime field, in 1/10ths of a second.

The path through color space taken during the transition is not specified, but it is recommended that the shortest path is taken through hue/saturation space, i.e., movement is ‘in a straight line’ across the hue/saturation disk.

 

6.8. Move to Color

ID	Name	Direction	Response	Access	Conformance
0x07	MoveToColor	client → server	Y	O	XY

The MoveToColor command SHALL have the following data fields:

ID	Name	Type	Constraint	Quality	Default	Conformance
0	ColorX	uint16	0 to 0xFEFF			M
1	ColorY	uint16	0 to 0xFEFF			M
2	TransitionTime	uint16	0 to 65534			M
3	OptionsMask	map8	desc		0	M
4	OptionsOverride	map8	desc		0	M

[Effect on Receipt]

On receipt of this command, a device SHALL set the value of the ColorMode attribute, where implemented, to 1, and SHALL then move from its current color to the color given in the ColorX and ColorY fields.

The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the new color SHALL be equal to the TransitionTime field, in 1/10ths of a second.

The path through color space taken during the transition is not specified, but it is recommended that the shortest path is taken through color space, i.e., movement is 'in a straight line' across the CIE xyY Color Space.

 

6.9. Move Color

ID	Name	Direction	Response	Access	Conformance
0x08	MoveColor	client → server	Y	O	XY

The MoveColor command SHALL have the following data fields:

ID	Name	Type	Constraint	Quality	Default	Conformance
0	RateX	int16	all			M
1	RateY	int16	all			M
2	OptionsMask	map8	desc		0	M
3	OptionsOverride	map8	desc		0	M

[RateX]

The RateX field specifies the rate of movement in steps per second. A step is a change in the device’s CurrentX attribute of one unit.

 

[RateY]

The RateY field specifies the rate of movement in steps per second. A step is a change in the device’s CurrentY attribute of one unit.

 

[Effect on Receipt]

On receipt of this command, a device SHALL set the value of the ColorMode attribute, where implemented, to 1, and SHALL then move from its current color in a continuous fashion according to the rates specified. This movement SHALL continue until the target color for the next step cannot be implemented on this device.

If both the RateX and RateY fields contain a value of zero, no movement SHALL be carried out, and the command execution SHALL have no effect other than stopping the operation of any previously received command of this cluster. This command can thus be used to stop the operation of any other command of this cluster.

 

6.10. Step Color

ID	Name	Direction	Response	Access	Conformance
0x09	StepColor	client → server	Y	O	XY

The StepColor command SHALL have the following data fields:

ID	Name	Type	Constraint	Quality	Default	Conformance
0	StepX	int16	all			M
1	StepY	int16	all			M
2	TransitionTime	uint16	0 to 65534			M
3	OptionsMask	map8	desc		0	M
4	OptionsOverride	map8	desc		0	M

[StepX / StepY]

The StepX and StepY fields specify the change to be added to the device’s CurrentX attribute and CurrentY attribute respectively.

 

[TransitionTime]

The TransitionTime field specifies, in 1/10ths of a second, the time that SHALL be taken to perform the color change.

 

[Effect on Receipt]

On receipt of this command, a device SHALL set the value of the ColorMode attribute, where implemented, to 1, and SHALL then move from its current color by the color step indicated.

The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the new color SHALL be equal to the TransitionTime field, in 1/10ths of a second.

The path through color space taken during the transition is not specified, but it is recommended that the shortest path is taken through color space, i.e., movement is 'in a straight line' across the CIE xyY Color Space.

Note also that if the required step is larger than can be represented by signed 16-bit integers then more than one step command SHOULD be issued.

 

6.11. Move to Color Temperature

ID	Name	Direction	Response	Access	Conformance
0x0A	MoveToColorTemperature	client → server	Y	O	CT

The MoveToColorTemperature command SHALL have the following data fields:

ID	Name	Type	Constraint	Quality	Default	Conformance
0	ColorTemperatureMireds	uint16	0 to 0xFEFF			M
1	TransitionTime	uint16	0 to 65534			M
2	OptionsMask	map8	desc		0	M
3	OptionsOverride	map8	desc		0	M

[Effect on Receipt]

On receipt of this command, a device SHALL set the value of the ColorMode attribute, where implemented, to 2, and SHALL then move from its current color to the color given by the ColorTemperatureMireds field.

The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the new color SHALL be equal to the TransitionTime field, in 1/10ths of a second.

By definition of this color mode, the path through color space taken during the transition is along the ‘Black Body Line'.

 

6.12. Enhanced Move to Hue

ID	Name	Direction	Response	Access	Conformance
0x40	EnhancedMoveToHue	client → server	Y	O	EHUE

The EnhancedMoveToHue command allows lamps to be moved in a smooth continuous transition from their current hue to a target hue.

The EnhancedMoveToHue command SHALL have the following data fields:

ID	Name	Type	Constraint	Quality	Default	Conformance
0	EnhancedHue	uint16	all			M
1	Direction	enum8	desc			M
2	TransitionTime	uint16	0 to 65534			M
3	OptionsMask	map8	desc		0	M
4	OptionsOverride	map8	desc		0	M

[EnhancedHue]

The EnhancedHue field specifies the target extended hue for the lamp.

 

[Direction]

This field is identical to the Direction field of the MoveToHue command of the Color Control cluster (see sub-clause Use of the OptionsMask and OptionsOverride fields).

 

[TransitionTime]

This field is identical to the TransitionTime field of the MoveToHue command of the Color Control cluster (see sub-clause Use of the OptionsMask and OptionsOverride fields).

 

[Effect on Receipt]

On receipt of this command, a device SHALL set the ColorMode attribute to 0 and set the EnhancedColorMode attribute to the value 3. The device SHALL then move from its current enhanced hue to the value given in the EnhancedHue field.

The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the new enhanced hue SHALL be equal to the TransitionTime field.

 

6.13. Enhanced Move Hue

ID	Name	Direction	Response	Access	Conformance
0x41	EnhancedMoveHue	client → server	Y	O	EHUE

The EnhancedMoveHue command allows lamps to be moved in a continuous stepped transition from their current hue to a target hue.

The EnhancedMoveHue command SHALL have the following data fields:

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

[MoveMode]

This field is identical to the MoveMode field of the MoveHue command of the Color Control cluster (see sub-clause MoveHue Command). If the MoveMode field is equal to 0 (Stop), the Rate field SHALL be ignored.

 

[Rate]

The Rate field specifies the rate of movement in steps per second. A step is a change in the extended hue of a device by one unit. If the MoveMode field is set to 1 (up) or 3 (down) and the Rate field has a value of zero, the command has no effect and a response command SHALL be sent in response, with the status code set to INVALID_COMMAND. If the MoveMode field is set to 0 (stop) the Rate field SHALL be ignored.

 

[Effect on receipt]

On receipt of this command, a device SHALL set the ColorMode attribute to 0 and set the EnhancedColorMode attribute to the value 3. The device SHALL then move from its current enhanced hue in an up or down direction in a continuous fashion, as detailed in Actions on Receipt of the EnhancedMoveHueCommand.

MoveMode	Action on Receipt
Stop	If moving, stop, else ignore the command (i.e., the command is accepted but has no effect). NB This MAY also be used to stop an EnhancedMoveToHue command or an EnhancedMoveToHueAndSaturation command.
Up	Increase the device’s enhanced hue at the rate given in the Rate field. If the enhanced hue reaches the maximum allowed for the device, wraparound and proceed from its minimum allowed value.
Down	Decrease the device’s enhanced hue at the rate given in the Rate field. If the hue reaches the minimum allowed for the device, wraparound and proceed from its maximum allowed value.

 

6.14. Enhanced Step Hue

ID	Name	Direction	Response	Access	Conformance
0x42	EnhancedStepHue	client → server	Y	O	EHUE

The EnhancedStepHue command allows lamps to be moved in a stepped transition from their current hue to a target hue, resulting in a linear transition through XY space.

The EnhancedStepHue command SHALL have the following data fields:

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

[StepMode]

This field is identical to the StepMode field of the StepHue command of the Color Control cluster (see sub-clause StepHue Command).

 

[StepSize]

The StepSize field specifies the change to be added to (or subtracted from) the current value of the device’s enhanced hue.

 

[TransitionTime]

The TransitionTime field specifies, in units of 1/10ths of a second, the time that SHALL be taken to perform the step. A step is a change to the device’s enhanced hue of a magnitude corresponding to the StepSize field.

Note: Here TransitionTime data field is of data type uint16, while the TransitionTime data field of the StepHue command is of data type uint8.

 

[Effect on receipt]

On receipt of this command, a device SHALL set the ColorMode attribute to 0 and the EnhancedColorMode attribute to the value 3. The device SHALL then move from its current enhanced hue in an up or down direction by one step, as detailed in Actions on Receipt for the EnhancedStepHue Command.

StepMode	Action on Receipt
Up	Increase the device’s enhanced hue by one step. If the enhanced hue reaches the maximum allowed for the device, wraparound and proceed from its minimum allowed value.
Down	Decrease the device’s enhanced hue by one step. If the hue reaches the minimum allowed for the device, wraparound and proceed from its maximum allowed value.

 

6.15. Enhanced Move to Hue and Saturation

ID	Name	Direction	Response	Access	Conformance
0x43	EnhancedMoveToHueAndSaturation	client → server	Y	O	EHUE

The EnhancedMoveToHueAndSaturation command allows lamps to be moved in a smooth continuous transition from their current hue to a target hue and from their current saturation to a target saturation.

The EnhancedMoveToHueAndSaturation command SHALL have the following data fields:

ID	Name	Type	Constraint	Quality	Default	Conformance
0	EnhancedHue	uint16	all			M
1	Saturation	uint8	0 to 254			M
2	TransitionTime	uint16	0 to 65534			M
3	OptionsMask	map8	desc		0	M
4	OptionsOverride	map8	desc		0	M

[EnhancedHue]

The EnhancedHue field specifies the target extended hue for the lamp.

 

[Saturation]

This field is identical to the Saturation field of the MoveToHueAndSaturation command of the Color Control cluster (see sub-clause MoveToHueAndSaturation Command).

 

[TransitionTime]

This field is identical to the TransitionTime field of the MoveToHue command of the Color Control cluster (see sub-clause MoveToHueAndSaturation Command).

 

[Effect on Receipt]

On receipt of this command, a device SHALL set the ColorMode attribute to the value 0 and set the EnhancedColorMode attribute to the value 3. The device SHALL then move from its current enhanced hue and saturation to the values given in the EnhancedHue and Saturation fields.

The movement SHALL be continuous, i.e., not a step function, and the time taken to move to the new color SHALL be equal to the TransitionTime field, in 1/10ths of a second.

The path through color space taken during the transition is not specified, but it is recommended that the shortest path is taken through hue/saturation space, i.e., movement is 'in a straight line' across the hue/saturation disk.

 

6.16. Color Loop Set

ID	Name	Direction	Response	Access	Conformance
0x44	ColorLoopSet	client → server	Y	O	CL

The Color Loop Set command allows a color loop to be activated such that the color lamp cycles through its range of hues.

The ColorLoopSet command SHALL have the following data fields:

ID	Name	Type	Constraint	Quality	Default	Conformance
0	UpdateFlags	map8	desc			M
1	Action	enum8	desc			M
2	Direction	enum8	desc			M
3	Time	uint16	all			M
4	StartHue	uint16	all			M
5	OptionsMask	map8	desc		0	M
6	OptionsOverride	map8	desc		0	M

[UpdateFlags]

The UpdateFlags field specifies which color loop attributes to update before the color loop is started. This field SHALL be formatted as illustrated in Format of the UpdateFlags Field of the ColorLoopSet Command.

Bit	Nmae sub-field
0	UpdateAction
1	UpdateDirection
2	UpdateTime
3	UpdateStartHue
4-7	Reserved

The UpdateAction sub-field is 1 bit in length and specifies whether the device SHALL adhere to the action field in order to process the command. If this sub-field is set to 1, the device SHALL adhere to the action field. If this sub-field is set to 0, the device SHALL ignore the Action field.

The UpdateDirection sub-field is 1 bit in length and specifies whether the device SHALL update the ColorLoopDirection attribute with the Direction field. If this sub-field is set to 1, the device SHALL update the value of the ColorLoopDirection attribute with the value of the Direction field. If this sub-field is set to 0, the device SHALL ignore the Direction field.

The UpdateTime sub-field is 1 bit in length and specifies whether the device SHALL update the ColorLoopTime attribute with the Time field. If this sub-field is set to 1, the device SHALL update the value of the ColorLoopTime attribute with the value of the Time field. If this sub-field is set to 0, the device SHALL ignore the Time field.

The UpdateStartHue sub-field is 1 bit in length and specifies whether the device SHALL update the ColorLoopStartEnhancedHue attribute with the StartHue field. If this sub-field is set to 1, the device SHALL update the value of the ColorLoopStartEnhancedHue attribute with the value of the StartHue field. If this sub-field is set to 0, the device SHALL ignore the StartHue field.

 

[Action]

The Action field specifies the action to take for the color loop if the UpdateAction sub-field of the UpdateFlags field is set to 1. This field SHALL be set to one of the non-reserved values listed in Values of the Action Field of the ColorLoopSet Command.

Value	Description
0	De-activate the color loop.
1	Activate the color loop from the value in the ColorLoopStartEnhancedHue field.
2	Activate the color loop from the value of the EnhancedCurrentHue attribute.

 [Direction]

The Direction field specifies the direction for the color loop if the Update Direction field of the UpdateFlags field is set to 1. This field SHALL be set to one of the non-reserved values listed in Values of the Direction Field of the ColorLoopSet Command.

Value	Description
0	Decrement the hue in the color loop.
1	Increment the hue in the color loop.

 [Time]

The Time field specifies the number of seconds over which to perform a full color loop if the UpdateTime sub-field of the UpdateFlags field is set to 1.

 

[StartHue]

The StartHue field specifies the starting hue to use for the color loop if the Update StartHue field of the Update Flags field is set to 1.

 

[Effect on Receipt]

On receipt of this command, the device SHALL first update its color loop attributes according to the value of the UpdateFlags field, as follows. If the UpdateDirection sub-field is set to 1, the device SHALL set the ColorLoopDirection attribute to the value of the Direction field. If the UpdateTime sub-field is set to 1, the device SHALL set the ColorLoopTime attribute to the value of the Time field. If the UpdateStartHue sub-field is set to 1, the device SHALL set the ColorLoopStartEnhancedHue attribute to the value of the StartHue field. If the color loop is active (and stays active), the device SHALL immediately react on updates of the ColorLoopDirection and ColorLoopTime attributes.

If the UpdateAction sub-field of the UpdateFlags field is set to 1, the device SHALL adhere to the action specified in the Action field, as follows. If the value of the Action field is set to 0 and the color loop is active, i.e. the ColorLoopActive attribute is set to 1, the device SHALL de-active the color loop, set the ColorLoopActive attribute to 0 and set the EnhancedCurrentHue attribute to the value of the ColorLoopStoredEnhancedHue attribute. If the value of the Action field is set to 0 and the color loop is inactive, i.e. the ColorLoopActive attribute is set to 0, the device SHALL ignore the action update component of the command. If the value of the action field is set to 1, the device SHALL set the ColorLoopStoredEnhancedHue attribute to the value of the EnhancedCurrentHue attribute, set the ColorLoopActive attribute to 1 and activate the color loop, starting from the value of the ColorLoopStartEnhancedHue attribute. If the value of the Action field is set to 2, the device SHALL set the ColorLoopStoredEnhancedHue attribute to the value of the EnhancedCurrentHue attribute, set the ColorLoopActive attribute to 1 and activate the color loop, starting from the value of the EnhancedCurrentHue attribute.

If the color loop is active, the device SHALL cycle over the complete range of values of the EnhancedCurrentHue attribute in the direction of the ColorLoopDirection attribute over the time specified in the ColorLoopTime attribute. The level of increments/decrements is application specific.

 

6.17. Stop Move Step

ID	Name	Direction	Response	Access	Conformance
0x47	StopMoveStep	client → server	Y	O	HS | XY | CT

The StopMoveStep command is provided to allow MoveTo and Step commands to be stopped. (Note this automatically provides symmetry to the Level Control cluster.)

Note: the StopMoveStep command has no effect on an active color loop.

The StopMoveStep 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]

Upon receipt of this command, any MoveTo, Move or Step command currently in process SHALL be terminated. The values of the CurrentHue, EnhancedCurrentHue and CurrentSaturation attributes SHALL be left at their present value upon receipt of the StopMoveStep command, and the RemainingTime attribute SHALL be set to zero.

 

6.18. Move Color Temperature

ID	Name	Direction	Response	Access	Conformance
0x4B	MoveColorTemperature	client → server	Y	O	CT

The MoveColorTemperature command allows the color temperature of a lamp to be moved at a specified rate.

The MoveColorTemperature command SHALL have the following data fields:

ID	Name	Type	Constraint	Quality	Default	Conformance
0	MoveMode	map8	desc			M
1	Rate	uint16	all			M
2	ColorTemperatureMinimumMireds	uint16	0 to 0xFEFF			M
3	ColorTemperatureMaximumMireds	uint16	0 to 0xFEFF			M
4	OptionsMask	map8	desc		0	M
5	OptionsOverride	map8	desc		0	M

[MoveMode]

This field is identical to the MoveMode field of the MoveHue command of the Color Control cluster(see sub-clause MoveHue Command). If the MoveMode field is equal to 0 (Stop), the Rate field SHALL be ignored.

 

[Rate]

The Rate field specifies the rate of movement in steps per second. A step is a change in the color temperature of a device by one unit. If the MoveMode field is set to 1 (up) or 3 (down) and the Rate field has a value of zero, the command has no effect and a response command SHALL be sent in response, with the status code set to INVALID_COMMAND. If the MoveMode field is set to 0 (stop) the Rate field SHALL be ignored.

 

[ColorTemperatureMinimumMireds]

The ColorTemperatureMinimumMireds field specifies a lower bound on the ColorTemperatureMireds attribute (≡ an upper bound on the color temperature in kelvins) for the current move operation such that:

ColorTempPhysicalMinMireds ≤ ColorTemperatureMinimumMireds field ≤ ColorTemperatureMireds

As such if the move operation takes the ColorTemperatureMireds attribute towards the value of the ColorTemperatureMinimumMireds field it SHALL be clipped so that the above invariant is satisfied. If the ColorTemperatureMinimumMireds field is set to 0, ColorTempPhysicalMinMireds SHALL be used as the lower bound for the ColorTemperatureMireds attribute.

 

[ColorTemperatureMaximumMireds]

The ColorTemperatureMaximumMireds field specifies an upper bound on the ColorTemperatureMireds attribute (≡ a lower bound on the color temperature in kelvins) for the current move operation such that:

ColorTemperatureMireds ≤ ColorTemperatureMaximumMireds field ≤ ColorTempPhysicalMaxMireds

As such if the move operation takes the ColorTemperatureMireds attribute towards the value of the ColorTemperatureMaximumMireds field it SHALL be clipped so that the above invariant is satisfied. If the ColorTemperatureMaximumMireds field is set to 0, ColorTempPhysicalMaxMireds SHALL be used as the upper bound for the ColorTemperatureMireds attribute.

 

[Effect on Receipt]

On receipt of this command, a device SHALL set both the ColorMode and EnhancedColorMode attributes to 2. The device SHALL then move from its current color temperature in an up or down direction in a continuous fashion, as detailed in Actions on Receipt of the MoveColorTemperature Command.

MoveMode	Action on Receipt
Stop	If moving, stop the operation, else ignore the command (i.e., the command is accepted but has no effect).
Up	Increase the ColorTemperatureMireds attribute (≡ decrease the color temperature in kelvins) at the rate given in the Rate field. If the ColorTemperatureMireds attribute reaches the maximum allowed for the device (via either the ColorTemperatureMaximumMireds field or the ColorTempPhysicalMaxMireds attribute), the move operation SHALL be stopped.
Down	Decrease the ColorTemperatureMireds attribute (≡ increase the color temperature in kelvins) at the rate given in the Rate field. If the ColorTemperatureMireds attribute reaches the minimum allowed for the device (via either the ColorTemperatureMinimumMireds field or the ColorTempPhysicalMinMireds attribute), the move operation SHALL be stopped.

 

6.19. Step Color Temperature

ID	Name	Direction	Response	Access	Conformance
0x4C	StepColorTemperature	client → server	Y	O	CT

The StepColorTemperature command allows the color temperature of a lamp to be stepped with a specified step size.

The StepColorTemperature command SHALL have the following data fields:

ID	Name	Type	Constraint	Quality	Default	Conformance
0	StepMode	map8	desc			M
1	StepSize	uint16	all			M
2	TransitionTime	uint16	0 to 65534			M
3	ColorTemperatureMinimumMireds	uint16	0 to 0xFEFF			M
4	ColorTemperatureMaximumMireds	uint16	0 to 0xFEFF			M
5	OptionsMask	map8	desc		0	M
6	OptionsOverride	map8	desc		0	M

[StepMode]

This field is identical to the StepMode field of the StepHue command of the Color Control cluster (see sub-clause StepHue Command).

 

[StepSize]

The StepSize field specifies the change to be added to (or subtracted from) the current value of the device’s color temperature.

 

[TransitionTime]

The TransitionTime field specifies, in units of 1/10ths of a second, the time that SHALL be taken to perform the step. A step is a change to the device’s color temperature of a magnitude corresponding to the StepSize field.

 

[ColorTemperatureMinimumMireds]

The ColorTemperatureMinimumMireds field specifies a lower bound on the ColorTemperatureMireds attribute (≡ an upper bound on the color temperature in kelvins) for the current step operation such that:

ColorTempPhysicalMinMireds ≤ ColorTemperatureMinimumMireds field ≤ ColorTemperatureMireds

As such if the step operation takes the ColorTemperatureMireds attribute towards the value of the Color Temperature Minimum Mireds field it SHALL be clipped so that the above invariant is satisfied. If the ColorTemperatureMinimumMireds field is set to 0, ColorTempPhysicalMinMireds SHALL be used as the lower bound for the ColorTemperatureMireds attribute.

 

[ColorTemperatureMaximumMireds]

The ColorTemperatureMaximumMireds field specifies an upper bound on the ColorTemperatureMireds attribute (≡ a lower bound on the color temperature in kelvins) for the current step operation such that:

ColorTemperatureMireds ≤ ColorTemperatureMaximumMireds field ≤ ColorTempPhysicalMaxMireds

As such if the step operation takes the ColorTemperatureMireds attribute towards the value of the ColorTemperatureMaximumMireds field it SHALL be clipped so that the above invariant is satisfied. If the ColorTemperatureMaximum Mireds field is set to 0, ColorTempPhysicalMaxMireds SHALL be used as the upper bound for the ColorTemperatureMireds attribute.

 

[Effect on Receipt]

On receipt of this command, a device SHALL set both the ColorMode and EnhancedColorMode attributes to 2. The device SHALL then move from its current color temperature in an up or down direction by one step, as detailed in Actions on Receipt of the StepColorTemperature Command.

StepMode	Action on Receipt
Up	Increase the ColorTemperatureMireds attribute (≡ decrease the color temperature in kelvins) by one step. If the ColorTemperatureMireds attribute reaches the maximum allowed for the device (via either the ColorTemperatureMaximumMireds field or the ColorTempPhysicalMaxMireds attribute), the step operation SHALL be stopped.
Down	Decrease the ColorTemperatureMireds attribute (≡ increase the color temperature in kelvins) by one step. If the ColorTemperatureMireds attribute reaches the minimum allowed for the device (via either the ColorTemperatureMinimumMireds field or the ColorTempPhysicalMinMireds attribute), the step operation SHALL be stopped.

7. ETC

7.1. Mireds

색온도 단위

https://en.wikipedia.org/wiki/Mired

7.2. CIE 1931 Color Space

https://ko.wikipedia.org/wiki/CIE_1931_%EC%83%89_%EA%B3%B5%EA%B0%84