YOGYUI
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 saturation 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 Lighting 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
색온도 단위
7.2. CIE 1931 Color Space
'홈네트워크(IoT) > Matter' 카테고리의 다른 글
| Matter Specification - Administrator Commissioning Cluster (0) | 2023.04.26 |
|---|---|
| Matter - Device Type (0) | 2023.04.17 |
| Matter Specification - Level Control Cluster (0) | 2023.03.25 |
| Matter Specification - On/Off Cluster (0) | 2023.03.24 |
| Matter - WiFi IP 주소 할당 이벤트 캐치 (0) | 2023.02.15 |
