Colour Control Cluster

This chapter describes the Colour Control cluster which is defined in the ZCL.

The Colour Control cluster has a Cluster ID of 0x0300.

Overview

The Colour Control cluster is used to control the colour of a light.

Note: Note 1: This cluster should normally be used with the Level Control cluster (see Chapter 16) and On/Off cluster (see Chapter 14). This is assumed to be the case in this description.

Note: Note 2: This cluster only controls the colour balance and not the overall brightness of a light. The brightness is adjusted using the Level Control cluster.

The Colour Control cluster provides the facility to specify the colour of a light in the colour space defined in the Commission Internationale de l’Éclairage (CIE) specification (1931). Colour control can be performed in terms of any of the following:

x and y values, as defined in the CIE specification
hue and saturation
colour temperature

To use the functionality of this cluster, you must include the file ColourControl.h in your application and enable the cluster by defining CLD_COLOUR_CONTROL in the zcl_options.h file - see Section 31.9.

It is also necessary to enable the cluster as a server or client, or as both:

The cluster server is able to receive commands to change the colour on the local light device.
The cluster client is able to send commands to change the colour on the remote light device.

The inclusion of the client or server software must be pre-defined in the application’s compile-time options (in addition, if the cluster is to reside on a custom endpoint then the role of client or server must also be specified when creating the cluster instance).

The compile-time options for the Colour Control cluster are fully detailed in Section31.9.

The information that can potentially be stored in this cluster is organized into the following attribute sets:

Colour Information
Defined Primaries Information
Additional Defined Primaries Information
Defined Colour Point Settings
Enhanced Colour Mode

Parent topic:Colour Control Cluster

Colour Control Cluster structure and attributes

The structure definition for the Colour Control cluster is:

typedef struct
{
#ifdef COLOUR_CONTROL_SERVER
    /* Colour information attribute set */
#ifdef CLD_COLOURCONTROL_ATTR_CURRENT_HUE
    zuint8                u8CurrentHue;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_CURRENT_SATURATION
    zuint8                u8CurrentSaturation;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_REMAINING_TIME
    zuint16               u16RemainingTime;
#endif
    zuint16                 u16CurrentX;
    zuint16                u16CurrentY;
#ifdef CLD_COLOURCONTROL_ATTR_DRIFT_COMPENSATION
    zenum8                u8DriftCompensation;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COMPENSATION_TEXT
    tsZCL_CharacterString   sCompensationText;
    uint8             au8CompensationText[
        CLD_COLOURCONTROL_COMPENSATION_TEXT_MAX_STRING_LENGTH];
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_TEMPERATURE_MIRED
    zuint16               16ColourTemperatureMired;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_MODE
    zenum8                  u8ColourMode;
#endif
    zbmap8                  u8Options;
    /* Defined Primaries Information attribute set */
#ifdef CLD_COLOURCONTROL_ATTR_NUMBER_OF_PRIMARIES
    zuint8               u8NumberOfPrimaries;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_PRIMARY_1_X
    zuint16                 u16Primary1X;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_PRIMARY_1_Y
    zuint16                 u16Primary1Y;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_PRIMARY_1_INTENSITY
    zuint8               u8Primary1Intensity;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_PRIMARY_2_X
    zuint16                 u16Primary2X;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_PRIMARY_2_Y
    zuint16                 u16Primary2Y;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_PRIMARY_2_INTENSITY
    zuint8                u8Primary2Intensity;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_PRIMARY_3_X
    zuint16                 u16Primary3X;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_PRIMARY_3_Y
    zuint16                 u16Primary3Y;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_PRIMARY_3_INTENSITY
    zuint8              u8Primary3Intensity;
#endif
    /* Additional Defined Primaries Information attribute set */
#ifdef CLD_COLOURCONTROL_ATTR_PRIMARY_4_X
    zuint16                 u16Primary4X;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_PRIMARY_4_Y
    zuint16                 u16Primary4Y;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_PRIMARY_4_INTENSITY
    zuint8               u8Primary4Intensity;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_PRIMARY_5_X
    zuint16                 u16Primary5X;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_PRIMARY_5_Y
    zuint16                 u16Primary5Y;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_PRIMARY_5_INTENSITY
    zuint8                u8Primary5Intensity;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_PRIMARY_6_X
    zuint16                 u16Primary6X;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_PRIMARY_6_Y
    zuint16                 u16Primary6Y;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_PRIMARY_6_INTENSITY
    zuint8                  u8Primary6Intensity;
#endif
    /* Defined Colour Points Settings attribute set */
#ifdef CLD_COLOURCONTROL_ATTR_WHITE_POINT_X
    zuint16               u16WhitePointX;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_WHITE_POINT_Y
    zuint16                u16WhitePointY;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_POINT_R_X
    zuint16                u16ColourPointRX;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_POINT_R_Y
    zuint16                u16ColourPointRY;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_POINT_R_INTENSITY
    zuint8             u8ColourPointRIntensity;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_POINT_G_X
    zuint16            u16ColourPointGX;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_POINT_G_Y
    zuint16                u16ColourPointGY;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_POINT_G_INTENSITY
    zuint8              u8ColourPointGIntensity;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_POINT_B_X
    zuint16                u16ColourPointBX;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_POINT_B_Y
    zuint16                u16ColourPointBY;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_POINT_B_INTENSITY
    zuint8              u8ColourPointBIntensity;
#endif
/* Colour information attribute set */
#ifdef CLD_COLOURCONTROL_ATTR_ENHANCED_CURRENT_HUE
    zuint16                u16EnhancedCurrentHue;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_ENHANCED_COLOUR_MODE
    zenum8                u8EnhancedColourMode;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_LOOP_ACTIVE
    zuint8              u8ColourLoopActive;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_LOOP_DIRECTION
    zuint8             u8ColourLoopDirection;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_LOOP_TIME
    zuint16             u16ColourLoopTime;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_LOOP_START_ENHANCED_HUE
    zuint16             u16ColourLoopStartEnhancedHue;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_LOOP_STORED_ENHANCED_HUE
    zuint16                 u16ColourLoopStoredEnhancedHue;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_CAPABILITIES
    zuint16                 u16ColourCapabilities;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_TEMPERATURE_MIRED_PHY_MIN
    zuint16           u16ColourTemperatureMiredPhyMin;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COLOUR_TEMPERATURE_MIRED_PHY_MAX
    zuint16          u16ColourTemperatureMiredPhyMax;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_COUPLE_COLOUR_TEMPERATURE_TO_LEVEL_MIN_MIRED
    zuint16    u16CoupleColourTempToLevelMinMired;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_STARTUP_COLOUR_TEMPERATURE_MIRED
    zuint16          u16StartupColourTemperatureMired;
#endif
#ifdef CLD_COLOURCONTROL_ATTR_ATTRIBUTE_REPORTING_STATUS
    zenum8           u8AttributeReportingStatus;
#endif
#endif
    zuint16           u16ClusterRevision;
} tsCLD_ColourControl;

where:

‘Colour Information’ Attribute Set

Note that the attributes u8CurrentHue, u8CurrentSaturation, u16CurrentX,``u16CurrentY and u16ColourTemperatureMired are enabled as part of ‘Colour Capabilities’ groups - see Table 34 on page 704.

u8CurrentHue is the current hue value of the light in the range 0-254. This value can be converted to hue in degrees using the following formula:

hue = u8CurrentHue x 360/254. This attribute is only valid when the attributes u8CurrentSaturation and u8ColorMode are also implemented.
u8CurrentSaturation is the current saturation value of the light in the range 0-254. This value can be converted to saturation as a fraction using the following formula: saturation = u8CurrentSaturation/254. This attribute is only valid when the attributes u8CurrentHue and u8ColorMode are also implemented.
u16RemainingTime is the time duration, in tenths of a second, before the currently active command completes.
u16CurrentX is the current value for the chromaticity x, as defined in the CIE xyY colour space, in the range 0-65279. The normal value of x is calculated using the following formula: x = u16CurrentX/65536.
u16CurrentY is the current value for the chromaticity y, as defined in the CIE xyY colour space, in the range 0-65279. The normal value of y is calculated using the following formula: y = u16CurrentY/65536.
u8DriftCompensation indicates the mechanism, if any, is being used to compensate for colour/intensity drift over time. One of the following values is specified:

u8DriftCompensation	Drift Compensation Mechanism
0x00	None
0x01	Other or unknown
0x02	Temperature monitoring
0x03	Optical luminance monitoring and feedback
0x04	Optical colour monitoring and feedback
0x05 - 0xFF	Reserved

The following optional pair of attributes are used to store a textual indication of the drift compensation mechanism used:
- sCompensationText is a tsZCL_CharacterString structure (see Section 6.1.14) for a character string representing the drift compensation method used
- au8CompensationText[] is a byte-array which contains the character data bytes representing the drift compensation method used
u16ColourTemperatureMired is the colour temperature of the light expressed as a micro reciprocal degree (mired) value. It is a scaled reciprocal of the current value of the colour temperature, in the range 1-65279

(0 is undefined and 65535 indicates an invalid value). The colour temperature, in Kelvin, is calculated using the following formula:

T = 1000000/u16ColourTemperature``Mired. This attribute is only valid when the attribute u8Colo``u``rMode is also implemented.
u8ColourMode indicates which method is currently being used to control the colour of the light. One of the following values is specified:

u8ColourMode	Colour Control Method/Attributes
0x00	Hue and saturation

(u8CurrentHue and u8CurrentSaturation)

| |0x01|Chromaticities x and y from CIE xyY colour space

(u16CurrentX and u16CurrentY)

u8Options is a bitmap which allows behaviors connected with certain commands to be defined (these behaviors should only be defined during commissioning), as follows:

Bits	Name	Description
0	ChangeIfOff	Defines whether changes to the Colour Control cluster can be made from control clusters (e.g. Level Control) when the `bOnOff` attribute of the On/Off cluster is zero (off):

1 – Allow changes
0 – Do not allow changes

| |1-7|-|Reserved|

‘Defined Primaries Information’

u8NumberOfPrimaries is the number of colour primaries implemented on the device, in the range 1-6 (0xFF is used if the number of primaries is unknown).
- For each colour primary, there is a set of three attributes used (see below) - for example, for the first primary this attribute trio comprises u16Primary1X, u16Primary1Y and u8Primary1Intensity. Therefore, the number of primaries specified determines the number of these attribute trios used.

Note: The number of primaries is set using a macro at compile-time (see Section 31.9). This automatically enables the relevant u16PrimaryNX, u16PrimaryNY and u8PrimaryNIntensity (N=1 to 6) attributes.

The attribute definitions below are valid for colour primary N, where N is 1, 2 or 3.
u16PrimaryNX is the value for the chromaticity x for colour primary N, as defined in the CIE xyY colour space, in the range 0-65279. The normalized value of x is calculated using the following formula: x = u16PrimaryNX/65536.
u16PrimaryNY is the value for the chromaticity y for colour primary N, as defined in the CIE xyY colour space, in the range 0-65279. The normalized value of y is calculated using the following formula: y = u16PrimaryNY/65536.
u8PrimaryNIntensity is a representation of the maximum intensity of colour primary 1, normalized such that the primary with the highest maximum intensity has the value 0xFE.

‘Additional Defined Primaries Information’ Attribute Set

The attribute definitions for this set are as for u16PrimaryNX, u16PrimaryNY and u8PrimaryNIntensity above, where N is 4, 5 or 6.
As indicated in the Note above for the ‘Defined Primaries Information’ AttributeSet, these attributes are enabled automatically according to the number of required primaries defined at compile-time (see Section 31.9).

‘Defined Colour Points Settings’

u16WhitePointX is the value for the chromaticity x for the white point of the device, as defined in the CIE xyY colour space, in the range 0-65279. The normalized value of x is calculated using the following formula:

x = u16WhitePointX/65536.
u16WhitePointY is the value for the chromaticity y for the white point of the device, as defined in the CIE xyY colour space, in the range 0-65279. The normalized value of y is calculated using the following formula:

y = u16WhitePointY/65536.
u16ColourPointRX is the value for the chromaticity x for the red colour point of the device, as defined in the CIE xyY colour space, in the range 0-65279. The normalized value of x is calculated using the following formula:

x = u16ColourPointRX/65536.
u16ColourPointRY is the value for the chromaticity y for the red colour point of the device, as defined in the CIE xyY colour space, in the range 0-65279. The normalized value of y is calculated using the following formula:

y = u16ColourPointRY/65536.
u8ColourPointRIntensity is a representation of the relative intensity of the red colour point of the device, normalized such that the colour point with the highest relative intensity has the value 0xFE (the value 0xFF indicates an invalid value).
u16ColourPointGX is the value for the chromaticity x for the green colour point of the device, as defined in the CIE xyY colour space, in the range 0-65279. The normalized value of x is calculated using the following formula:

x = u16ColourPointGX/65536.
u16ColourPointGY is the value for the chromaticity y for the green colour point of the device, as defined in the CIE xyY colour space, in the range 0-65279. The normalized value of y is calculated using the following formula:

y = u16ColourPointGY/65536.
u8ColourPointGIntensity is a representation of the relative intensity of the green colour point of the device, normalized such that the colour point with the highest relative intensity has the value 0xFE (the value 0xFF indicates an invalid value).
u16ColourPointBX is the value for the chromaticity x for the blue colour point of the device, as defined in the CIE xyY colour space, in the range 0-65279. The normalized value of x is calculated using the following formula:

x = u16ColourPointBX/65536.
u16ColourPointBY is the value for the chromaticity y for the blue colour point of the device, as defined in the CIE xyY colour space, in the range 0-65279. The normalized value of y is calculated using the following formula:

y = u16ColourPointBY/65536.
u8ColourPointBIntensity is a representation of the relative intensity of the blue colour point of the device, normalized such that the colour point with the highest relative intensity has the value 0xFE (the value 0xFF indicates an invalid value).

Enhanced Colour Mode Attributes

These attributes are enabled as part of ‘Colour Capabilities’ groups - see Table 34 onpage 704.

u16EnhancedCurrentHue contains the current hue of the light in terms of (unequal) steps around the CIE colour ‘triangle’:
- 8 most significant bits represent an index into the XY look-up table that contains the step values, thus indicating the current step used
- 8 least significant bits represent a linear interpolation value between the current step and next step (up), facilitating a colour zoom
  - The value of the u8CurrentHue attribute is calculated from the above values.
u8EnhancedColourMode indicates which method is currently being used to control the colour of the light. One of the following values is specified:

u8ColourMode	Colour Control Method/Attributes
0x00	Current hue and current saturation

(u8CurrentHue and u8CurrentSaturation)

| |0x01|Chromaticities x and y from CIE xyY colour space

(u16CurrentX and u16CurrentY)

| |0x02|Colour temperature (u16ColourTemperature``Mired)| |0x03|Enhanced hue and current saturation

(u16EnhancedCurrentHue and u8CurrentSaturation)

| |0x03 - 0xFF|Reserved|

u8ColourLoopActive indicates whether the colour loop is currently active: 0x01 - active, 0x00 - not active (all other values are reserved). The colour loop follows the hue steps around the CIE colour ‘triangle’ by incrementing or decrementing the value of u16EnhancedCurrentHue.
u8ColourLoopDirection indicates the current direction of the colour loop in terms of the direction of change of u16EnhancedCurrentHue:

0x01 - incrementing, 0x00 - decrementing (all other values are reserved).
u16ColourLoopTime is the period, in seconds, of a full colour loop - that is, the time to cycle all possible values of u16EnhancedCurrentHue.
u16ColourLoopStartEnhancedHue indicates the value of u16EnhancedCurrentHue at which the colour loop must be started.
u16ColourLoopStoredEnhancedHue contains the value of u16EnhancedCurrentHue at which the last colour loop completed (this value is stored on completing a colour loop).
u16ColourCapabilities is a bitmap indicating the Colour Control cluster features (and attributes) supported by the device, as detailed below (a bit is set to ‘1’ if the feature is supported or ‘0’ otherwise):

Bits	Feature	Attributes
0	Hue/Saturation	```
u8CurrentHue
u8CurrentSaturation

|
|1|Enhanced Hue

 \(Hue/Saturation must also be supported\)

|```
u16EnhancedCurrentHue

| |2|Colour Loop

(Enhanced Hue must also be supported)

|``` u8ColourLoopActive u8ColourLoopDirection u16ColourLoopTime u16ColourLoopStartEnhancedHue u16ColourLoopStoredEnhancedHue u16ColourCapabilities

|
|3|CIE XY Values|```
u16CurrentX
u16CurrentY

| |4|Colour Temperature (Mired)|``` u16ColourTemperatureMired u16ColourTemperatureMiredPhyMin u16ColourTemperatureMiredPhyMax

|
|5-15|Reserved|-|

Macros are provided to select the required Colour Capabilities at compile-time - see [Table 34 on page 704](compile-time_options.md#id_d6675cb0-6090-4409-b15f-2c832f964ed4).

-   `u16ColourTemperature``Mired``PhyMin` indicates the minimum value \(supported by the hardware\) of the mired colour temperature attribute.
-   `u16ColourTemperature``Mired``PhyMax` indicates the maximum value \(supported by the hardware\) of the mired colour temperature attribute.
-   `u16CoupleColourTempToLevelMinMired` is an optional attribute that is used when the `u16ColourTemperatureMired` attribute is coupled to the `u8CurrentLevel` attribute of the Level Control cluster \(this is the case when the CoupleColorTempToLevel bit of the `u8Options` attribute of the Level Control cluster is equal to 1\). `u16CoupleColourTempToLevelMinMired` specifies a lower bound on the value of the `u16ColourTemperatureMired` attribute, where this lower bound corresponds to a `u8CurrentLevel` value of 0xFE \(100%\). Note that because the colour temperature is represented as a mired \(reciprocal\) value, a high value of `u8CurrentLevel` corresponds to a low value of `u16ColourTemperatureMired` and the `16CoupleColourTempToLevelMinMired` attribute corresponds to an upper bound on the value of the colour temperature supported by the device. The value of this attribute must be at least equal to the value of `u16ColourTemperatureMiredPhyMin`.
-   `u16StartupColourTemperatureMired` is an optional attribute to define the required start-up colour temperature of a light when it is supplied with power. It determines the initial value of `u16ColourTemperatureMired` on start-up.

## Global Attributes 

-   `u8AttributeReportingStatus` is an optional attribute that should be enabled when attribute reporting is used for the cluster \(see [Section 2.3.5](../../ZCL_fundamentals/topics/attribute_reporting.md#id_d3e2d682-d5e6-4aa5-870f-4d2e0320637e)\). The value of this attribute indicates whether there are attribute reports still pending \(0x00\) or the attribute reports are complete \(0x01\) - all other values are reserved. This attribute is also described in [Section 2.4](../../ZCL_fundamentals/topics/global_attributes.md#id_8f80e769-8ccd-4b4f-8609-579f4457d527).


u16ClusterRevision is a mandatory attribute that specifies the revision of the cluster specification on which this cluster instance is based. The cluster specification in the ZCLr6 corresponds to a cluster revision of 1. The value is incremented by one for each subsequent revision of the cluster specification. This attribute is also described in[Section2.4](../../ZCL_fundamentals/topics/global_attributes.md#id_8f80e769-8ccd-4b4f-8609-579f4457d527).

**Parent topic:**[Colour Control Cluster](../../Colour_Control_cluster/topics/colour_control_cluster.md)

Attributes for Default Reporting

The following attributes of the Colour Control cluster can be selected for default reporting:

u8CurrentHue 
u8CurrentSaturation
u16CurrentX

u16CurrentY

Attribute reporting (including default reporting) is described in Appendix B. Enabling reports for these attributes is described in Appendix B.3.6.

Parent topic:Colour Control Cluster

Initialization

The function eCLD_ColourControlCreateColourControl() is used to create an instance of the Colour Control cluster. The function is generally called by the initialization function for the host device.

Parent topic:Colour Control Cluster

Sending Commands

The NXP implementation of the ZCL provides functions for sending commands between a Colour Control cluster client and server. A command is sent from the client to one or more endpoints on the server. Multiple endpoints can usually be targeted using binding or group addressing.

Note: Any ‘Move to’, ‘Move’ or ‘Step’ command that is currently in progress can be stopped at any time by calling the function: eCLD_ColourControlCommandStopMoveStepCommandSend()

Controlling Hue

Colour can be controlled in terms of hue, which is related to the dominant wavelength (or frequency) of the light emitted by a lighting device. On a device that supports the Colour Control cluster, the hue is controlled by means of the ‘current hue’ attribute (u8CurrentHue) of the cluster. This attribute can take a value in the range 0-254, which can be converted to hue in degrees using the following formula:

Hue in degrees = u8CurrentHue x 360/254

The ‘current hue’ attribute can be controlled in a number of ways using commands of the Colour Control cluster. API functions are available to send these commands to endpoints on remote devices.

‘Move to Hue’ Command

The ‘Move to Hue’ command allows the ‘current hue’ attribute to be moved (increased or decreased) to a specified target value in a continuous manner over a specified transition time. This command can be sent to an endpoint on a remote device using the function

eCLD_ColourControlCommandMoveToHueCommandSend()

Since the possible hues are represented on a closed boundary, the target hue can be reached by moving the attribute value in either direction, up or down (the attribute value wraps around). Options are also provided for taking the ‘shortest route’ and ‘longest route’ around the boundary.

‘Move Hue’ Command

The ‘Move Hue’ command allows the ‘current hue’ attribute to be moved in a given direction (increased or decreased) at a specified rate indefinitely, until stopped. This command can be sent to an endpoint on a remote device using the function

eCLD_ColourControlCommandMoveHueCommandSend()

Since the possible hues are represented on a closed boundary, the movement is cyclic (the attribute value wraps around). The above function can also be used to stop the movement.

‘Step Hue’ Command

The ‘Step Hue’ command allows the ‘current hue’ attribute to be moved (increased or decreased) by a specified amount in a continuous manner over a specified transition time. This command can be sent to an endpoint on a remote device using the function

eCLD_ColourControlCommandStepHueCommandSend()

Note: Hue can also be moved in conjunction with saturation, as described in Section 31.5.7. The ‘enhanced’ hue can be moved in similar ways, as described in Section 31.5.5.

Parent topic:Sending Commands

Controlling Saturation

Colour can be controlled in terms of saturation, which is related to the spread of wavelengths (or frequencies) in the light emitted by a lighting device. On a device that supports the Colour Control cluster, the saturation is controlled by means of the ‘current saturation’ attribute (u8CurrentSaturation) of the cluster. This attribute can take a value in the range 0-254, which can be converted to saturation as a fraction using the following formula:

Saturation = u8CurrentSaturation/254

The ‘current saturation’ attribute can be controlled in a number of ways using commands of the Colour Control cluster. API functions are available to send these commands to endpoints on remote devices.

‘Move to Saturation’ Command

The ‘Move to Saturation’ command allows the ‘current saturation’ attribute to be moved (increased or decreased) to a specified target value in a continuous manner over a specified transition time. This command can be sent to an endpoint on a remote device using the function

eCLD_ColourControlCommandMoveToSaturationCommandSend()

‘Move Saturation’ Command

The ‘Move Saturation’ command allows the ‘current saturation’ attribute to be moved in a given direction (increased or decreased) at a specified rate until stopped or until the current saturation reaches its minimum or maximum value. This command can be sent to an endpoint on a remote device using the function

eCLD_ColourControlCommandMoveSaturationCommandSend()

The above function can also be used to stop the movement.

‘Step Saturation’ Command

The ‘Step Saturation’ command allows the ‘current saturation’ attribute to be moved (increased or decreased) by a specified amount in a continuous manner over a specified transition time. This command can be sent to an endpoint on a remote device using the function

eCLD_ColourControlCommandStepSaturationCommandSend()

Note: Saturation can also be moved in conjunction with hue, as described in Section 31.5.7.

Parent topic:Sending Commands

Controlling Colour (CIE x and y Chromaticities)

Colour can be controlled in terms of the x and y chromaticities defined in the CIE xyY colour space. On a device that supports the Colour Control cluster, these values are controlled by means of the ‘current x’ attribute (u16CurrentX) and ‘current y’ attribute (u16CurrentY) of the cluster. Each of these attributes can take a value in the range 0-65279. The normalized x and y chromaticities can then be calculated from these values using the following formulae:

x = u16CurrentX/65536

y = u16CurrentY/65536

The x and y chromaticity attributes can be controlled in a number of ways using commands of the Colour Control cluster. API functions are available to send these commands to endpoints on remote devices.

‘Move to Colour’ Command

The ‘Move to Colour’ command allows the ‘current x’ and ‘current y’ attributes to be moved (increased or decreased) to specified target values in a continuous manner over a specified transition time. This command can be sent to an endpoint on a remote device using the function

eCLD_ColourControlCommandMoveToColourCommandSend()

‘Move Colour’ Command

The ‘Move Colour’ command allows the ‘current x’ and ‘current y’ attributes to be moved in a given direction (increased or decreased) at specified rates until stopped or until both attributes reach their minimum or maximum value. This command can be sent to an endpoint on a remote device using the function

eCLD_ColourControlCommandMoveColourCommandSend()

The above function can also be used to stop the movement.

‘Step Colour’ Command

The ‘Step Colour’ command allows the ‘current x’ and ‘current y’ attributes to be moved (increased or decreased) by specified amounts in a continuous manner over a specified transition time. This command can be sent to an endpoint on a remote device using the function

eCLD_ColourControlCommandStepColourCommandSend()

Parent topic:Sending Commands

Controlling Colour Temperature

Colour can be controlled in terms of colour temperature, which is the temperature of an ideal black body which radiates light of a similar hue to that of the lighting device. On a device that supports the Colour Control cluster, the colour temperature is controlled by means of the ‘mired colour temperature’ attribute (u16ColourTemperature``Mired) of the cluster. This attribute stores a micro reciprocal degree (mired) value, which is a scaled reciprocal of the current value of the colour temperature of the light, in the range 1-65279. The colour temperature, in Kelvin, can be calculated from the attribute value using the following formula:

T = 1000000/u16ColourTemperature``Mired

Note: The movement of colour temperature through colour space always follows the ‘Black Body Line’.

‘Move to Colour Temperature’ Command

The ‘Move to Colour Temperature’ command allows the ‘mired colour temperature’ attribute to be moved (increased or decreased) to a specified target value in a continuous manner over a specified transition time. This command can be sent to an endpoint on a remote device using the function

eCLD_ColourControlCommandMoveToColourTemperatureCommandSend()

‘Move Colour Temperature’ Command

The ‘Move Colour Temperature’ command allows the ‘mired colour temperature’ attribute to be moved in a given direction (increased or decreased) at a specified rate until stopped. This command can be sent to an endpoint on a remote device using the function

eCLD_ColourControlCommandMoveColourTemperatureCommandSend()

The above function can also be used to stop the movement.

Maximum and minimum values for the ‘mired colour temperature’ attribute during the movement are also specified. If the attribute value reaches the specified maximum or minimum before the required change has been achieved, the movement will automatically stop.

‘Step Colour Temperature’ Command

The ‘Step Colour Temperature’ command allows the ‘mired colour temperature’ attribute to be moved (increased or decreased) by a specified amount in a continuous manner over a specified transition time. This command can be sent to an endpoint on a remote device using the function

eCLD_ColourControlCommandStepColourTemperatureCommandSend()

Maximum and minimum values for the ‘mired colour temperature’ attribute during the movement are also specified. If the attribute value reaches the specified maximum or minimum before the required change has been achieved, the movement will automatically stop.

Parent topic:Sending Commands

Controlling ‘Enhanced’ Hue

Colour can be controlled in terms of hue, which is related to the dominant wavelength (or frequency) of the light emitted by a lighting device. The hue can alternatively be controlled by means of the ‘enhanced current hue’ attribute (u16EnhancedCurrentHue), instead of the ‘current hue’ attribute (the ‘current hue’ attribute is automatically adjusted when the ‘enhanced current hue’ attribute value changes).

The ‘enhanced current hue’ attribute allows hue to be controlled on a finer scale than the ‘current hue’ attribute. Hue steps are defined in a look-up table and values between the steps can be achieved through linear interpolation. This 16-bit attribute value therefore comprises two 8-bit components, as described below.

Bits 15-8	Bits 7-0
Index into the look-up table that

contains the hue step values, thus indicating the current step used

|Linear interpolation value between the

current step and next step (up)

|

Thus, if the current hue step value is Hi (where i is the relevant table index) and the linear interpolation value is interp, the ‘enhanced’ hue is given by the formula:

Enhanced hue = Hi + (interp/255) x (Hi+1 - Hi )

To convert this hue to a value in degrees, it is then necessary to multiply by 360/255.

The ‘enhanced current hue’ attribute can be controlled in a number of ways using commands of the Colour Control cluster. API functions are available to send these commands to endpoints on remote devices.

Note: **Note:**These commands are issued by a cluster client and are performed on a cluster server. The look-up table is user-defined on the server. When this command is received by the server, the user-defined callback function that is invoked must read the entry with the specified index from the look-up table and calculate the corresponding ‘enhanced’ hue value.

‘Enhanced Move to Hue’ Command

The ‘Enhanced Move to Hue’ command allows the ‘enhanced current hue’ attribute to be moved (increased or decreased) to a specified target value in a continuous manner over a specified transition time (the ‘current hue’ attribute is also moved to a value based on the target ‘enhanced current hue’ value). This command can be sent to an endpoint on a remote device using the function

eCLD_ColourControlCommandEnhancedMoveToHueCommandSend()

Since the possible hues are represented on a closed boundary, the target hue can be reached by moving the attribute value in either direction, up or down (the attribute value wraps around). Options are also provided for taking the ‘shortest route’ and ‘longest route’ around the boundary.

‘Enhanced Move Hue’ Command

The ‘Enhanced Move Hue’ command allows the ‘enhanced current hue’ attribute to be moved in a given direction (increased or decreased) at a specified rate indefinitely, until stopped (the ‘current hue’ attribute is also moved through values based on the ‘enhanced current hue’ value). This command can be sent to an endpoint on a remote device using the function

eCLD_ColourControlCommandEnhancedMoveHueCommandSend()

The above function can also be used to stop the movement.

Since the possible hues are represented on a closed boundary, the movement is cyclic (the attribute value wraps around). The above function can also be used to stop the movement.

‘Enhanced Step Hue’ Command

The ‘Enhanced Step Hue’ command allows the ‘enhanced current hue’ attribute to be moved (increased or decreased) by a specified amount in a continuous manner over a specified transition time (the ‘current hue’ attribute is also moved through values based on the ‘enhanced current hue’ value). This command can be sent to an endpoint on a remote device using the function

eCLD_ColourControlCommandEnhancedStepHueCommandSend()

Note: Note 1: ‘Enhanced’ hue can also be moved in conjunction with saturation, as described in Section31.5.7.

Note: Note 2: The value of the ‘enhanced current hue’ attribute can be moved around a colour loop, as described in Section 31.5.6.

Parent topic:Sending Commands

Controlling a Colour Loop

The colour of a device can be controlled by moving the value of the ‘enhanced current hue’ attribute around a colour loop corresponding to the CIE colour ‘triangle’ - refer to Section 31.5.5 for details of the ‘enhanced current hue’ attribute.

Movement along the colour loop can be controlled using the ‘Colour Loop Set’ command of the Colour Control cluster. A function is available to send this command to endpoints on remote devices.

‘Colour Loop Set’ Command

The ‘Colour Loop Set’ command allows movement of the ‘enhanced current hue’ attribute value around the colour loop to be configured and started. The direction(up or down), start ‘enhanced’ hue and duration of the movement can be specified. This command can be sent to an endpoint on a remote device using the function

eCLD_ColourControlCommandColourLoopSetCommandSend()

The above function can also be used to stop the movement.

Parent topic:Sending Commands

Controlling Hue and Saturation

Colour can be completely specified in terms of hue and saturation, which respectively represent the dominant wavelength (or frequency) of the light and the spread of wavelengths (around the former) within the light. Therefore, the Colour Control cluster provides commands to change both the hue and saturation at the same time. In fact, commands are provided to control the values of the:

‘current hue’ and ‘current saturation’ attributes
‘enhanced current hue’ and ‘current saturation’ attributes

API functions are available to send these commands to endpoints on remote devices.

‘Move to Hue and Saturation’ Command

The ‘Move to Hue and Saturation’ command allows the ‘current hue’ and ‘current saturation’attributes to be moved to specified target values in a continuous manner over a specified transition time. This command can be sent to an endpoint on a remote device using the function

eCLD_ColourControlCommandMoveToHueCommandSend()

‘Enhanced Move to Hue and Saturation’ Command

The ‘Enhanced Move to Hue and Saturation’ command allows the ‘enhanced current hue’ and ‘current saturation’attributes to be moved to specified target values in a continuous manner over a specified transition time. This command can be sent to an endpoint on a remote device using the function

eCLD_ColourControlCommandEnhancedMoveToHueAndSaturationCommandSend()

Parent topic:Sending Commands

Parent topic:Colour Control Cluster

Functions

The following Colour Control cluster functions are provided in the NXP implementation of the ZCL:

eCLD_ColourControlCreateColourControl

teZCL_Status eCLD_ColourControlCreateColourControl(
    tsZCL_ClusterInstance *psClusterInstance,
    bool_t bIsServer,
    tsZCL_ClusterDefinition *psClusterDefinition,
    void *pvEndPointSharedStructPtr,
    uint8 *pu8AttributeControlBits,
    tsCLD_ColourControlCustomDataStructure
    *psCustomDataStructure);

Description

This function creates an instance of the Colour Control cluster on an endpoint. The cluster instance is created on the endpoint which is associated with the supplied tsZCL_ClusterInstance structure and can act as a server or a client, as specified.

The function should only be called when setting up a custom endpoint containing one or more selected clusters (rather than the whole set of clusters supported by a standard ZigBee device). This function creates a Colour Control cluster instance on the endpoint, but instances of other clusters may also be created on the same endpoint by calling their corresponding creation functions.

Note: This function must not be called for an endpoint on which a standard ZigBee device is used. In this case, the device and its supported clusters must be registered on the endpoint using the relevant device registration function.

When used, this function must be the first Colour Control cluster function called in the application, and must be called after the stack has been started and after the ZCL has been initialized.

The function requires an array to be declared for internal use, which contains one element (of type uint8) for each attribute of the cluster. The array length should therefore equate to the total number of attributes supported by the Colour Control cluster. The function initializes the array elements to zero.

Parameters

psClusterInstance: Pointer to structure containing information about the cluster instance to be created (see Section 6.1.16). This structure is updated by the function by initializing individual structure fields.
bIsServer : Type of cluster instance (server or client) to be created:
TRUE - server
FALSE - client
psClusterDefinition: Pointer to structure indicating the type of cluster to be created (see Section 6.1.2). In this case, this structure must contain the details of the Colour Control cluster. This parameter can refer to a pre-filled structure called sCLD_ColourControl which is provided in the ColourControl.h file.
pvEndPointSharedStructPtr: Pointer to the shared structure used for attribute storage. This parameter should be the address of the structure of type tsCLD_ColourControl which defines the attributes of Colour Control cluster. The function initializes the attributes with default values.
pu8AttributeControlBits: Pointer to an array of uint8 values, with one element for each attribute in the cluster (see above).
psCustomDataStructure: Pointer to a structure containing the storage for internal functions of the cluster (see Section 31.7.1)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControlCommandMoveToHueCommandSend

teZCL_Status eCLD_ColourControlCommandMoveToHueCommandSend(
        uint8 u8SourceEndPointId,
        uint8 u8DestinationEndPointId,
        tsZCL_Address *psDestinationAddress,
        uint8 *pu8TransactionSequenceNumber,
        tsCLD_ColourControl_MoveToHueCommandPayload
    *psPayload);

Description

This function sends a Move to Hue command to instruct a device to move its ‘current hue’ attribute to a target hue value in a continuous manner within a given time. The hue value, direction and transition time are specified in the payload of the command (see Section 31.7.2).

Since the possible hues are represented on a closed boundary, the target hue can be reached by moving the attribute value in either direction, up or down (the attribute value wraps around). Options are also provided for ‘shortest route’ and ‘longest route’ around the boundary.

The device receiving this message generates a callback event on the endpoint on which the Colour Control cluster was registered. The device must first ensure that ‘hue and saturation’ mode is selected by setting the ‘colour mode’ attribute to 0x00, if required. It can then move the ‘current hue’ value as requested.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘current hue’ attribute is enabled in the Colour Control cluster.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
psDestinationAddress: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
*psPayload: Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

This function invokes the ZigBee PRO stack function to transmit the data. In case an error is returned, call the eZCL_GetLastZpsError() function to get the error.

Parent topic:Functions

eCLD_ColourControlCommandMoveHueCommandSend

teZCL_Status eCLD_ColourControlCommandMoveHueCommandSend(
uint8 u8SourceEndPointId,
uint8 u8DestinationEndPointId,
tsZCL_Address *psDestinationAddress,
uint8 *pu8TransactionSequenceNumber,
tsCLD_ColourControl_MoveHueCommandPayload
*psPayload);

Description

This function sends a Move Hue command to instruct a device to move its ‘current hue’ attribute value in a given direction at a specified rate for an indefinite time. The direction and rate are specified in the payload of the command (see Section 31.7.2).

The command can request that the hue is moved up or down, or that existing movement is stopped. Since the possible hues are represented on a closed boundary, the movement is cyclic (the attribute value wraps around). Once started, the movement will continue until it is stopped.

The device receiving this message will generate a callback event on the endpoint on which the Colour Control cluster was registered. The device must first ensure that ‘hue and saturation’ mode is selected by setting the ‘colour mode’ attribute to 0x00, if required. It can then move the ‘current hue’ value as requested.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘current hue’ attribute is enabled in the Colour Control cluster.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
pu8TransactionSequenceNumber: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
*psPayload: Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControlCommandStepHueCommandSend

teZCL_Status eCLD_ColourControlCommandStepHueCommandSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_ColourControl_StepHueCommandPayload
*psPayload);

Description

This function sends a Step Hue command to instruct a device to increase or decrease its ‘current hue’ attribute by a specified ‘step’ value in a continuous manner within a given time. The step size, direction and transition time are specified in the payload of the command (see Section 31.7.2).

The device receiving this message will generate a callback event on the endpoint on which the Colour Control cluster was registered. The device must first ensure that ‘hue and saturation’ mode is selected by setting the ‘colour mode’ attribute to 0x00, if required. It can then move the ‘current hue’ value as requested.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘current hue’ attribute is enabled in the Colour Control cluster.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
psDestinationAddress: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
*psPayload: Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControlCommandMoveToSaturationCommandSend

teZCL_Status eCLD_ColourControlCommandMoveToSaturationCommandSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_ColourControl_MoveToSaturationCommandPayload
*psPayload);

Description

This function sends a Move to Saturation command to instruct a device to move its ‘current saturation’ attribute to a target saturation value in a continuous manner within a given time. The saturation value and transition time are specified in the payload of the command (see Section 31.7.2).

The device receiving this message will generate a callback event on the endpoint on which the Colour Control cluster was registered. The device must first ensure that ‘hue and saturation’ mode is selected by setting the ‘colour mode’ attribute to 0x00, if required. It can then move the ‘current saturation’ value as requested.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘current saturation’ attribute is enabled in the Colour Control cluster.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
psDestinationAddress: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
*psPayload: Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControlCommandMoveSaturationCommandSend

teZCL_Status eCLD_ColourControlCommandMoveSaturationCommandSend(
uint8 u8SourceEndPointId,
uint8 u8DestinationEndPointId,
tsZCL_Address *psDestinationAddress,
uint8 *pu8TransactionSequenceNumber,
tsCLD_ColourControl_MoveSaturationCommandPayload
*psPayload);

Description

This function sends a Move Saturation command to instruct a device to move its ‘current saturation’ attribute value in a given direction at a specified rate for an indefinite time. The direction and rate are specified in the payload of the command (see Section 31.7.2).

The command can request that the saturation is moved up or down, or that existing movement is stopped. Once started, the movement will continue until it is stopped. If the current saturation reaches its minimum or maximum value, the movement will automatically stop.

The device receiving this message will generate a callback event on the endpoint on which the Colour Control cluster was registered. The device must first ensure that ‘hue and saturation’ mode is selected by setting the ‘colour mode’ attribute to 0x00, if required. It can then move the ‘current saturation’ value as requested.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘current saturation’ attribute is enabled in the Colour Control cluster.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
psDestinationAddress: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
*psPayload: Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControlCommandStepSaturationCommandSend

teZCL_Status eCLD_ColourControlCommandStepSaturationCommandSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_ColourControl_StepSaturationCommandPayload
*psPayload);

Description

This function sends a Step Saturation command to instruct a device to increase or decrease its ‘current saturation’ attribute by a specified ‘step’ value in a continuous manner within a given time. The step size, direction and transition time are specified in the payload of the command (see Section 31.7.2).

The device receiving this message will generate a callback event on the endpoint on which the Colour Control cluster was registered. The device must first ensure that ‘hue and saturation’ mode is selected by setting the ‘colour mode’ attribute to 0x00, if required. It can then move the ‘current saturation’ value as requested.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘current saturation’ attribute is enabled in the Colour Control cluster.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
pu8TransactionSequenceNumber: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
psPayload: Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControlCommandMoveToHueAndSaturationCommandSend

teZCL_Status eCLD_ColourControlCommandMoveToColourCommandSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_ColourControl_MoveToColourCommandPayload
    *psPayload);

Description

This function sends a Move to Hue and Saturation command to instruct a device to move its ‘current hue’ and ‘current saturation’ attributes to target values in a continuous manner within a given time. The hue value, saturation value and transition time are specified in the payload of the command (see Section 31.7.2).

The device receiving this message will generate a callback event on the endpoint on which the Colour Control cluster was registered. The device must first ensure that ‘hue and saturation’ mode is selected by setting the ‘colour mode’ attribute to 0x00, if required. It can then move the ‘current hue’ and ‘current saturation’ values as requested.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘current hue’ and ‘current saturation’ attributes are enabled in the Colour Control cluster.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
pu8TransactionSequenceNumber: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
psPayload: Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControlCommandMoveToColourCommandSend

teZCL_Status eCLD_ColourControlCommandMoveToColourCommandSend(
        uint8 u8SourceEndPointId,
        uint8 u8DestinationEndPointId,
        tsZCL_Address *psDestinationAddress,
        uint8 *pu8TransactionSequenceNumber,
        tsCLD_ColourControl_MoveToColourCommandPayload
    *psPayload);

Description

This function sends a Move to Colour command to instruct a device to move its ‘current x’ and ‘current y’ attributes to target values in a continuous manner within a given time (where x and y are the chromaticities from the CIE xyY colour space). The x-value, y-value and transition time are specified in the payload of the command (see Section 31.7.2).

The device receiving this message will generate a callback event on the endpoint on which the Colour Control cluster was registered. The device must first ensure that ‘chromaticities x and y’ mode is selected by setting the ‘colour mode’ attribute to 0x01, if required. It can then move the ‘current x’ and ‘current y’ values as requested.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘current x’ and ‘current y’ attributes are enabled in the Colour Control cluster.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
psDestinationAddress: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
*psPayload: Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControlCommandMoveColourCommandSend

teZCL_Status eCLD_ColourControlCommandMoveColourCommandSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_ColourControl_MoveColourCommandPayload
*psPayload);

Description

This function sends a Move Colour command to instruct a device to move its ‘current x’ and ‘current y’ attribute values at a specified rate for each attribute for an indefinite time (where x and y are the chromaticities from the CIE xyY colour space). The rates are specified in the payload of the command (see Section 31.7.2 and each rate can be positive (increase) or negative (decrease).

Once started, the movement will continue until it is stopped. The movement can be stopped by calling this function with both rates set to zero. The movement will be automatically stopped when either of the attributes reaches its minimum of maximum value.

The device receiving this message will generate a callback event on the endpoint on which the Colour Control cluster was registered. The device must first ensure that ‘chromaticities x and y’ mode is selected by setting the ‘colour mode’ attribute to 0x01, if required. It can then move the ‘current x’ and ‘current y’ values as requested.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘current x’ and ‘current y’ values attributes are enabled in the Colour Control cluster.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
psDestinationAddress: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
*psPayload: Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControlCommandStepColourCommandSend

teZCL_Status eCLD_ColourControlCommandStepColourCommandSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_ColourControl_StepColourCommandPayload
*psPayload);

Description

This function sends a Step Colour command to instruct a device to change its ‘current x’ and ‘current y’ attribute values by a specified ‘step’ value for each attribute in a continuous manner within a given time (where x and y are the chromaticities from the CIE xyY colour space). The step sizes and transition time are specified in the payload of the command (see Section 31.7.2), and each step size can be positive (increase) or negative (decrease).

The device receiving this message will generate a callback event on the endpoint on which the Colour Control cluster was registered. The device must first ensure that ‘chromaticities x and y’ mode is selected by setting the ‘colour mode’ attribute to 0x01, if required. It can then move the ‘current x’ and ‘current y’ values as requested.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘current x’ and ‘current y’ values attributes are enabled in the Colour Control cluster.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
psDestinationAddress: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
*psPayload: Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControlCommandEnhancedMoveToHueCommandSend

teZCL_Status eCLD_ColourControlCommandEnhancedMoveToHueCommandSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_ColourControl_EnhancedMoveToHueCommandPayload
*psPayload);

Description

This function sends an Enhanced Move to Hue command to instruct a device to move its ‘enhanced current hue’ attribute to a target hue value in a continuous manner within a given time. The enhanced hue value, direction and transition time are specified in the payload of the command (see Section 31.7.2). The ‘current hue’ attribute is also moved to a value based on the target ‘enhanced current hue’ value.

Since the possible hues are represented on a closed boundary, the target hue can be reached by moving the attribute value in either direction, up or down (the attribute value wraps around). Options are also provided for ‘shortest route’ and ‘longest route’ around the boundary.

The device receiving this message will generate a callback event on the endpoint on which the Colour Control cluster was registered. The device must first ensure that ‘hue and saturation’ mode is selected by setting the ‘colour mode’ attribute to 0x00 and that ‘enhanced hue and saturation’ mode is selected by setting the ‘enhanced colour mode’ attribute to 0x03, if required. It can then move the ‘enhanced current hue’ value as requested.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘enhanced current hue’ attribute is enabled in the Colour Control cluster.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
pu8TransactionSequenceNumber: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
psPayload: Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControlCommandEnhancedMoveHueCommandSend

teZCL_Status eCLD_ColourControlCommandEnhancedMoveHueCommandSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_ColourControl_EnhancedMoveHueCommandPayload
*psPayload);

Description

This function sends an Enhanced Move Hue command to instruct a device to move its ‘enhanced current hue’ attribute value in a given direction at a specified rate for an indefinite time. The direction and rate are specified in the payload of the command (see Section 31.7.2). The ‘current hue’ attribute is also moved through values based on the ‘enhanced current hue’ value.

The command can request that the hue is moved up or down, or that existing movement is stopped. Since the possible hues are represented on a closed boundary, the movement is cyclic (the attribute value wraps around). Once started, the movement will continue until it is stopped.

The device receiving this message will generate a callback event on the endpoint on which the Colour Control cluster was registered. The device must first ensure that ‘hue and saturation’ mode is selected by setting the ‘colour mode’ attribute to 0x00 and that ‘enhanced hue and saturation’ mode is selected by setting the ‘enhanced colour mode’ attribute to 0x03, if required. It can then move the ‘enhanced current hue’ value as requested.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘enhanced current hue’ attribute is enabled in the Colour Control cluster.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
psDestinationAddress: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
*psPayload: Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControlCommandEnhancedStepHueCommandSend

teZCL_Status eCLD_ColourControlCommandEnhancedStepHueCommandSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_ColourControl_EnhancedStepHueCommandPayload
*psPayload);

Description

This function sends an Enhanced Step Hue command to instruct a device to increase or decrease its ‘enhanced current hue’ attribute by a specified ‘step’ value in a continuous manner within a given time. The step size, direction and transition time are specified in the payload of the command (see Section 31.7.2). The ‘current hue’ attribute is also moved through values based on the ‘enhanced current hue’ value.

The device receiving this message will generate a callback event on the endpoint on which the Colour Control cluster was registered. The device must first ensure that ‘hue and saturation’ mode is selected by setting the ‘colour mode’ attribute to 0x00 and that ‘enhanced hue and saturation’ mode is selected by setting the ‘enhanced colour mode’ attribute to 0x03, if required. It can then move the ‘enhanced current hue’ value as requested.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘enhanced current hue’ attribute is enabled in the Colour Control cluster.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
psDestinationAddress: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
*psPayload: Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControlCommandEnhancedMoveToHueAndSaturationCommandSend

teZCL_Status eCLD_ColourControlCommandEnhancedMoveToHueAndSaturationCommandSend(
        uint8 u8SourceEndPointId,
        uint8 u8DestinationEndPointId,
        tsZCL_Address *psDestinationAddress,
        uint8 *pu8TransactionSequenceNumber,
        tsCLD_ColourControl_EnhancedMoveToHueAndSaturation
    CommandPayload *psPayload);

Description

This function sends an Enhanced Move to Hue and Saturation command to instruct a device to move its ‘enhanced current hue’ and ‘current saturation’ attributes to target values in a continuous manner within a given time. The enhanced hue value, saturation value and transition time are specified in the payload of the command (see Section 31.7.2). The ‘current hue’ attribute is also moved to a value based on the target ‘enhanced current hue’ value.

The device receiving this message will generate a callback event on the endpoint on which the Colour Control cluster was registered. The device must first ensure that ‘hue and saturation’ mode is selected by setting the ‘colour mode’ attribute to 0x00 and that ‘enhanced hue and saturation’ mode is selected by setting the ‘enhanced colour mode’ attribute to 0x03, if required. It can then move the ‘enhanced current hue’ and ‘current saturation’ values as requested.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘enhanced current hue’ and ‘current saturation’ attributes are enabled in the Colour Control cluster.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
psDestinationAddress: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
*psPayload: Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControlCommandColourLoopSetCommandSend

teZCL_Status eCLD_ColourControlCommandColourLoopSetCommandSend(
        uint8 u8SourceEndPointId,
        uint8 u8DestinationEndPointId,
        tsZCL_Address *psDestinationAddress,
        uint8 *pu8TransactionSequenceNumber,
        tsCLD_ColourControl_ColourLoopSetCommandPayload
    *psPayload);

Description

This function sends a Colour Loop Set command to instruct a device to configure the movement of the ‘enhanced current hue’ attribute value around the colour loop corresponding to the CIE colour ‘triangle’. The configured movement can be started in either direction and for a specific duration. The start hue, direction and duration are specified in the payload of the command (see Section 31.7.2). The ‘current hue’ attribute is also moved through values based on the ‘enhanced current hue’ value.

The function can also be used to stop existing movement around the colour loop.

The device receiving this message will generate a callback event on the endpoint on which the Colour Control cluster was registered. The device must first ensure that ‘hue and saturation’ mode is selected by setting the ‘colour mode’ attribute to 0x00 and that ‘enhanced hue and saturation’ mode is selected by setting the ‘enhanced colour mode’ attribute to 0x03, if required. It can then move the ‘enhanced current hue’ value as requested.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘enhanced current hue’ attribute is enabled in the Colour Control cluster.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
psDestinationAddress: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
*psPayload: Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControlCommandStopMoveStepCommandSend

teZCL_Status eCLD_ColourControlCommandStopMoveStepCommandSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_ColourControl_StopMoveStepCommandPayload
*psPayload);

Description

This function sends a Stop Move Step command to instruct a device to stop a ‘Move to’, ‘Move’ or ‘Step’ command that is currently in progress.

The device receiving this message will generate a callback event on the endpoint on which the Colour Control cluster was registered, and stop the current action.

The ‘current hue’, ‘enhanced current hue’ and ‘current saturation’ attributes will subsequently keep the values they have when the current action is stopped.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘enhanced current hue’ attribute is enabled in the Colour Control cluster.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
pu8TransactionSequenceNumber: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
psPayload : Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControlCommandMoveToColourTemperatureCommandSend

teZCL_Status eCLD_ColourControlCommandMoveToColourTemperatureCommandSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_ColourControl_MoveToColourTemperatureCommandPayload
*psPayload);

Description

This function sends a Move to Colour Temperature command to instruct a device to move its ‘mired colour temperature’ attribute to a target value in a continuous manner within a given time. The attribute value is a scaled reciprocal of colour temperature, as indicated in Section 31.5.4. The target attribute value, direction and transition time are specified in the payload of the command (see Section 31.7.2).

The movement through colour space will follow the ‘Black Body Line’.

The device receiving this message will generate a callback event on the endpoint on which the Colour Control cluster was registered. The device must first ensure that ‘colour temperature’ mode is selected by setting the ‘colour mode’ attribute to 0x02, if required. It can then move the ‘mired colour temperature’ value as requested.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘mired colour temperature’ attribute is enabled in the Colour Control cluster.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
psDestinationAddress: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
*psPayload: Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControlCommandMoveColourTemperatureCommandSend

teZCL_Status eCLD_ColourControlCommandMoveColourTemperatureCommandSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_ColourControl_MoveColourTemperatureCommandPayload
*psPayload);
        

Description

This function sends a Move Colour Temperature command to instruct a device to move its ‘mired colour temperature’ attribute value in a given direction at a specified rate. The attribute value is a scaled reciprocal of colour temperature, as indicated in Section 31.5.4. The direction and rate are specified in the payload of the command (see Section 31.7.2). Maximum and minimum attribute values for the movement are also specified in the payload.

The command can request that the attribute value is moved up or down, or that existing movement is stopped. Once started, the movement will automatically stop when the attribute value reaches the specified maximum or minimum.

The movement through colour space will follow the ‘Black Body Line’.

The device receiving this message will generate a callback event on the endpoint on which the Colour Control cluster was registered. The device must first ensure that ‘colour temperature’ mode is selected by setting the ‘colour mode’ attribute to 0x02, if required. It can then move the ‘mired colour temperature’ value as requested.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘mired colour temperature’ attribute is enabled in the Colour Control cluster, as well as the ‘mired colour temperature maximum’ and ‘mired colour temperature minimum’ attributes.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
pu8TransactionSequenceNumber: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
*psPayload: Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControlCommandStepColourTemperatureCommandSend

teZCL_Status eCLD_ColourControlCommandStepColourTemperatureCommandSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_ColourControl_StepColourTemperatureCommandPayload
*psPayload);

Description

This function sends a Step Colour Temperature command to instruct a device to increase or decrease its ‘mired colour temperature’ attribute by a specified ‘step’ value in a continuous manner within a given time. The attribute value is a scaled reciprocal of colour temperature, as indicated in Section 31.5.4. The step size, direction and transition time are specified in the payload of the command (see Section 31.7.2). Maximum and minimum attribute values for the movement are also specified in the payload.

The command can request that the attribute value is moved up or down. If this value reaches the specified maximum or minimum before the required change has been achieved, the movement will automatically stop.

The movement through colour space will follow the ‘Black Body Line’.

The device receiving this message will generate a callback event on the endpoint on which the Colour Control cluster was registered. The device must first ensure that ‘colour temperature’ mode is selected by setting the ‘colour mode’ attribute to 0x02, if required. It can then move the ‘mired colour temperature’ value as requested.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

This function can only be used when the ‘mired colour temperature’ attribute is enabled in the Colour Control cluster, as well as the ‘mired colour temperature maximum’ and ‘mired colour temperature minimum’ attributes.

Parameters

u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values
u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP
psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent
psDestinationAddress: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request
*psPayload: Pointer to a structure containing the payload for this message (see Section 31.7.2)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_ZBUFFER_FAIL
E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_ColourControl_GetRGB

teZCL_Status eCLD_ColourControl_GetRGB(
    uint8 u8SourceEndPointId,
    uint8 *pu8Red,
    uint8 *pu8Green,
    uint8 *pu8Blue);

Description

This function obtains the current colour of the device on the specified (local) endpoint in terms of the Red (R), Green (G) and Blue (B) components.

Parameters

u8SourceEndPointId: Number of local endpoint on which the device resides
pu8Red: Pointer to a location to receive the red value, in the range 0-255
pu8Green: Pointer to a location to receive the green value, in the range 0-255
pu8Blue: Pointer to a location to receive the blue value, in the range 0-255

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_CLUSTER_NOT_FOUND

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

Parent topic:Colour Control Cluster

Structures

Custom Data Structure

The Colour Control cluster requires extra storage space to be allocated for use by internal functions. The structure definition for this storage is shown below:

typedef struct
{
    teCLD_ColourControl_ColourMode     eColourMode;
    uint16                             u16CurrentHue;
    tsCLD_ColourControl_Transition     sTransition;
    /* Matrices for XYZ <> RGB conversions */
    float                              afXYZ2RGB[3][3];
    float                              afRGB2XYZ[3][3];
    tsZCL_ReceiveEventAddress          sReceiveEventAddress;
    tsZCL_CallBackEvent                sCustomCallBackEvent;
    tsCLD_ColourControlCallBackMessage sCallBackMessage;
} tsCLD_ColourControlCustomDataStructure;

The fields are for internal use and no knowledge of them is required.

Parent topic:Structures

Custom Command Payloads

The following structures contain the payloads for the Colour Control cluster custom commands.

Move to Hue Command Payload

typedef struct
{
    uint8                           u8Hue;
    teCLD_ColourControl_Direction   eDirection;
    uint16                          u16TransitionTime;
} tsCLD_ColourControl_MoveToHueCommandPayload;

where:

u8Hue is the target hue value.
eDirection indicates the direction/path of the change in hue:

eDirection	Direction/Path
0x00	Shortest path
0x01	Longest path
0x02	Up
0x03	Down
0x04 – 0xFF	Reserved

u16TransitionTime is the time period, in tenths of a second, over which the change in hue should be implemented.

Move Hue Command Payload

typedef struct
{
    teCLD_ColourControl_MoveMode    eMode;
    uint8                           u8Rate;
    zbmap8                          u8OptionsMask;
    zbmap8                          u8OptionsOverride;    
} tsCLD_ColourControl_MoveHueCommandPayload;

where:

eMode indicates the required action and/or direction of the change in hue:

eMode	Action/Direction
0x00	Stop existing movement in hue
0x01	Start increasing hue
0x02	Reserved
0x03	Start decreasing hue
0x04 – 0xFF	Reserved

u8Rate is the required rate of movement in hue steps per second (a step is one unit of hue for the device).
OptionsMask and OptionsOverride must be either both present or both not present. These fields are used in creating a temporary Options bitmap from the u8Options attribute. Each bit of the u8Options attribute is carried across to the temporary Options bitmap unless the corresponding bit of OptionsMask is set (to 1). In this case, the corresponding bit of OptionsOverride is used in the temporary Options bitmap instead.

Step Hue Command Payload

typedef struct
{
    teCLD_ColourControl_StepMode    eMode;
    uint8                           u8StepSize;
    uint8                           u8TransitionTime;
    zbmap8                          u8OptionsMask;
    zbmap8                          u8OptionsOverride;     
} tsCLD_ColourControl_StepHueCommandPayload;

where:

eMode indicates the required direction of the change in hue:

eMode	Action/Direction
0x00	Reserved
0x01	Increase hue
0x02	Reserved
0x03	Decrease hue
0x04 – 0xFF	Reserved

u8StepSize is the amount by which the hue is to be changed (increased or decreased), in units of hue for the device.
u8TransitionTime is the time period, in tenths of a second, over which the change in hue should be implemented.
OptionsMask and OptionsOverride must be either both present or both not present. These fields are used in creating a temporary Options bitmap from the u8Options attribute. Each bit of the u8Options attribute is carried across to the temporary Options bitmap unless the corresponding bit of OptionsMask is set (to 1). In this case, the corresponding bit of OptionsOverride is used in the temporary Options bitmap instead.

Move To Saturation Command Payload

typedef struct
{
    uint8                          u8Saturation;
    uint16                         u16TransitionTime;
    zbmap8                         u8OptionsMask;
    zbmap8                         u8OptionsOverride;     
} tsCLD_ColourControl_MoveToSaturationCommandPayload;

where:

u8Saturation is the target saturation value.
u16TransitionTime is the time period, in tenths of a second, over which the change in saturation should be implemented.
OptionsMask and OptionsOverride must be either both present or both not present. These fields are used in creating a temporary Options bitmap from the u8Options attribute. Each bit of the u8Options attribute is carried across to the temporary Options bitmap unless the corresponding bit of OptionsMask is set (to 1). In this case, the corresponding bit of OptionsOverride is used in the temporary Options bitmap instead.

Move Saturation Command Payload

typedef struct
{
    teCLD_ColourControl_MoveMode    eMode;
    uint8                           u8Rate;
    zbmap8                          u8OptionsMask;
    zbmap8                          u8OptionsOverride;     
} tsCLD_ColourControl_MoveSaturationCommandPayload;

where:

eMode indicates the required action and/or direction of the change in saturation:

eMode	Action/Direction
0x00	Stop existing movement in hue
0x01	Start increasing saturation
0x02	Reserved
0x03	Start decreasing saturation
0x04 – 0xFF	Reserved

u8Rate is the required rate of movement in saturation steps per second (a step is one unit of saturation for the device).
OptionsMask and OptionsOverride must be either both present or both not present. These fields are used in creating a temporary Options bitmap from the u8Options attribute. Each bit of the u8Options attribute is carried across to the temporary Options bitmap unless the corresponding bit of OptionsMask is set (to 1). In this case, the corresponding bit of OptionsOverride is used in the temporary Options bitmap instead.

Step Saturation Command Payload

typedef struct
{
    teCLD_ColourControl_StepMode    eMode;
    uint8                           u8StepSize;
    uint8                           u8TransitionTime;
    zbmap8                          u8OptionsMask;
    zbmap8                          u8OptionsOverride;     
} tsCLD_ColourControl_StepSaturationCommandPayload;

where:

eMode indicates the required direction of the change in saturation:

eMode	Action/Direction
0x00	Reserved
0x01	Increase saturation
0x02	Reserved
0x03	Decrease saturation
0x04 – 0xFF	Reserved

u8StepSize is the amount by which the saturation is to be changed (increased or decreased), in units of saturation for the device.
u8TransitionTime is the time period, in tenths of a second, over which the change in hue should be implemented.
OptionsMask and OptionsOverride must be either both present or both not present. These fields are used in creating a temporary Options bitmap from the u8Options attribute. Each bit of the u8Options attribute is carried across to the temporary Options bitmap unless the corresponding bit of OptionsMask is set (to 1). In this case, the corresponding bit of OptionsOverride is used in the temporary Options bitmap instead.

Move To Hue And Saturation Command Payload

typedef struct
{
    uint8                           u8Hue;
    uint8                           u8Saturation;
    uint16                          u16TransitionTime;
    zbmap8                          u8OptionsMask;
    zbmap8                          u8OptionsOverride;     
} tsCLD_ColourControl_MoveToHueAndSaturationCommandPayload;

where:

u8Hue is the target hue value.
u8Saturation is the target saturation value.
16TransitionTime is the time period, in tenths of a second, over which the change in hue and saturation should be implemented.
OptionsMask and OptionsOverride must be either both present or both not present. These fields are used in creating a temporary Options bitmap from the u8Options attribute. Each bit of the u8Options attribute is carried across to the temporary Options bitmap unless the corresponding bit of OptionsMask is set (to 1). In this case, the corresponding bit of OptionsOverride is used in the temporary Options bitmap instead.

Move To Colour Command Payload

typedef struct
{
    uint16                         u16ColourX;
    uint16                         u16ColourY;
    uint16                         u16TransitionTime;
    zbmap8                         u8OptionsMask;
    zbmap8                         u8OptionsOverride;     
} tsCLD_ColourControl_MoveToColourCommandPayload;

where:

u16ColourX is the target x-chromaticity in the CIE xyY colour space
u16ColourY is the target y-chromaticity in the CIE xyY colour space
u16TransitionTime is the time period, in tenths of a second, over which the colour change should be implemented.
OptionsMask and OptionsOverride must be either both present or both not present. These fields are used in creating a temporary Options bitmap from the u8Options attribute. Each bit of the u8Options attribute is carried across to the temporary Options bitmap unless the corresponding bit of OptionsMask is set (to 1). In this case, the corresponding bit of OptionsOverride is used in the temporary Options bitmap instead.

Move Colour Command Payload

typedef struct
{
    int16                          i16RateX;
    int16                          i16RateY;
    zbmap8                         u8OptionsMask;
    zbmap8                         u8OptionsOverride;     
} tsCLD_ColourControl_MoveColourCommandPayload;

where:

i16RateX is the required rate of movement of x-chromaticity in the CIE xyY colour space, in steps per second (a step is one unit of x-chromaticity for the device).
i16RateY is the required rate of movement of y-chromaticity in the CIE xyY colour space, in steps per second (a step is one unit of y-chromaticity for the device).
OptionsMask and OptionsOverride must be either both present or both not present. These fields are used in creating a temporary Options bitmap from the u8Options attribute. Each bit of the u8Options attribute is carried across to the temporary Options bitmap unless the corresponding bit of OptionsMask is set (to 1). In this case, the corresponding bit of OptionsOverride is used in the temporary Options bitmap instead.

Step Colour Command Payload

typedef struct
{
    int16                           i16StepX;
    int16                           i16StepY;
    uint16                          u16TransitionTime;
    zbmap8                          u8OptionsMask;
    zbmap8                          u8OptionsOverride;     
} tsCLD_ColourControl_StepColourCommandPayload;

where:

i16StepX is the amount by which the x-chromaticity in the CIE xyY colour space is to be changed (increased or decreased), in units of x-chromaticity for the device.
i16StepY is the amount by which the y-chromaticity in the CIE xyY colour space is to be changed (increased or decreased), in units of y-chromaticity for the device.
u16TransitionTime is the time period, in tenths of a second, over which the colour change should be implemented.
OptionsMask and OptionsOverride must be either both present or both not present. These fields are used in creating a temporary Options bitmap from the u8Options attribute. Each bit of the u8Options attribute is carried across to the temporary Options bitmap unless the corresponding bit of OptionsMask is set (to 1). In this case, the corresponding bit of OptionsOverride is used in the temporary Options bitmap instead.

Move To Colour Temperature Command Payload

typedef struct
{
    uint16                          u16ColourTemperatureMired;
    uint16                          u16TransitionTime;
    zbmap8                          u8OptionsMask;
    zbmap8                          u8OptionsOverride;     
} tsCLD_ColourControl_MoveToColourTemperatureCommandPayload;

where:

u16ColourTemperature``Mired is the target value of the mired colour temperature attribute u16ColourTemperature``Mired (this value is a scaled reciprocal of colour temperature - for details, refer to the attribute description in Section 31.2).
u16TransitionTime is the time period, in tenths of a second, over which the change in colour temperature should be implemented.
OptionsMask and OptionsOverride must be either both present or both not present. These fields are used in creating a temporary Options bitmap from the u8Options attribute. Each bit of the u8Options attribute is carried across to the temporary Options bitmap unless the corresponding bit of OptionsMask is set (to 1). In this case, the corresponding bit of OptionsOverride is used in the temporary Options bitmap instead.

Move Colour Temperature Command Payload

typedef struct
{
    teCLD_ColourControl_MoveMode     eMode;
    uint16                           u16Rate;
    uint16                           u16ColourTemperatureMiredMin;
    uint16                           u16ColourTemperatureMiredMax;
    zbmap8                           u8OptionsMask;
    zbmap8                           u8OptionsOverride;    
} tsCLD_ColourControl_MoveColourTemperatureCommandPayload;

where:

eMode indicates the required action and/or direction of the change in the mired colour temperature attribute value:

eMode	Action/Direction
0x00	Stop existing movement in colour temperature
0x01	Start increasing mired colour temperature attribute value
0x02	Reserved
0x03	Start decreasing mired colour temperature attribute value
0x04 – 0xFF	Reserved

u16Rate is the required rate of movement in mired colour temperature steps per second (a step is one unit of the mired colour temperature attribute).
u16ColourTemperature``Mired``Min is the lower limit for the mired colour temperature attribute during the operation resulting from this command.
u16ColourTemperature``Mired``Max is the upper limit for the mired colour temperature attribute during the operation resulting from this command.
OptionsMask and OptionsOverride must be either both present or both not present. These fields are used in creating a temporary Options bitmap from the u8Options attribute. Each bit of the u8Options attribute is carried across to the temporary Options bitmap unless the corresponding bit of OptionsMask is set (to 1). In this case, the corresponding bit of OptionsOverride is used in the temporary Options bitmap instead.

Step Colour Temperature Command Payload

typedef struct
{
    teCLD_ColourControl_StepMode     eMode;
    uint16                           u16StepSize;
    uint16                           u16TransitionTime;
    uint16                           u16ColourTemperatureMiredMin;
    uint16                           u16ColourTemperatureMiredMax;
    zbmap8                           u8OptionsMask;
    zbmap8                           u8OptionsOverride;    
} tsCLD_ColourControl_StepColourTemperatureCommandPayload;

where:

eMode indicates the required direction of the change in the mired colour temperature attribute value:

eMode	Action/Direction
0x00	Reserved
0x01	Increase mired colour temperature attribute value
0x02	Reserved
0x03	Decrease mired colour temperature attribute value
0x04 – 0xFF	Reserved

u16StepSize is the amount by which the mired colour temperature attribute is to be changed (increased or decreased).
u16TransitionTime is the time period, in tenths of a second, over which the change in the mired colour temperature attribute should be implemented.
u16ColourTemperature``Mired``Min is the lower limit for the mired colour temperature attribute during the operation resulting from this command.
u16ColourTemperature``Mired``Max is the upper limit for the mired colour temperature attribute during the operation resulting from this command.
OptionsMask and OptionsOverride must be either both present or both not present. These fields are used in creating a temporary Options bitmap from the u8Options attribute. Each bit of the u8Options attribute is carried across to the temporary Options bitmap unless the corresponding bit of OptionsMask is set (to 1). In this case, the corresponding bit of OptionsOverride is used in the temporary Options bitmap instead.

Enhanced Move To Hue Command Payload

typedef struct
{
    uint16                              u16EnhancedHue;
    teCLD_ColourControl_Direction       eDirection;
    uint16                              u16TransitionTime;
    zbmap8                              u8OptionsMask;
    zbmap8                              u8OptionsOverride;     
} tsCLD_ColourControl_EnhancedMoveToHueCommandPayload;

where:

u16EnhancedHue is the target ‘enhanced’ hue value in terms of a step around the CIE colour ‘triangle’ - for the format, refer to the description of the attribute u16EnhancedCurrentHue in Section 31.2.
eDirection indicates the direction/path of the change in hue:

eDirection	Direction/Path
0x00	Shortest path
0x01	Longest path
0x02	Up
0x03	Down
0x04 – 0xFF	Reserved

u16TransitionTime is the time period, in tenths of a second, over which the change in hue should be implemented.
OptionsMask and OptionsOverride must be either both present or both not present. These fields are used in creating a temporary Options bitmap from the u8Options attribute. Each bit of the u8Options attribute is carried across to the temporary Options bitmap unless the corresponding bit of OptionsMask is set (to 1). In this case, the corresponding bit of OptionsOverride is used in the temporary Options bitmap instead.

Enhanced Move Hue Command Payload

typedef struct
{
    teCLD_ColourControl_MoveMode        eMode;
    uint16                              u16Rate;
    zbmap8                              u8OptionsMask;
    zbmap8                              u8OptionsOverride;     
} tsCLD_ColourControl_EnhancedMoveHueCommandPayload;

where:

eMode indicates the required action and/or direction of the change in hue:

eMode	Action/Direction
0x00	Stop existing movement in hue
0x01	Start increase in hue
0x02	Reserved
0x03	Start decrease in hue
0x04 – 0xFF	Reserved

u16Rate is the required rate of movement in ‘enhanced’ hue steps per second (a step is one unit of hue for the device).
OptionsMask and OptionsOverride must be either both present or both not present. These fields are used in creating a temporary Options bitmap from the u8Options attribute. Each bit of the u8Options attribute is carried across to the temporary Options bitmap unless the corresponding bit of OptionsMask is set (to 1). In this case, the corresponding bit of OptionsOverride is used in the temporary Options bitmap instead.

Enhanced Step Hue Command Payload

typedef struct
{
    teCLD_ColourControl_StepMode        eMode;
    uint16                              u16StepSize;
    uint16                              u16TransitionTime;
    zbmap8                              u8OptionsMask;
    zbmap8                              u8OptionsOverride;     
} tsCLD_ColourControl_EnhancedStepHueCommandPayload;

where:

eMode indicates the required direction of the change in hue:

eMode	Action/Direction
0x00	Reserved
0x01	Increase in hue
0x02	Reserved
0x03	Decrease in hue
0x04 – 0xFF	Reserved

u16StepSize is the amount by which the ‘enhanced’ hue is to be changed (increased or decreased) - for the format, refer to the description of the attribute u16EnhancedCurrentHue in Section 31.2.
u8TransitionTime is the time period, in tenths of a second, over which the change in hue should be implemented.
OptionsMask and OptionsOverride must be either both present or both not present. These fields are used in creating a temporary Options bitmap from the u8Options attribute. Each bit of the u8Options attribute is carried across to the temporary Options bitmap unless the corresponding bit of OptionsMask is set (to 1). In this case, the corresponding bit of OptionsOverride is used in the temporary Options bitmap instead.

Enhanced Move To Hue And Saturation Command Payload

typedef struct
{
    uint16                             u16EnhancedHue;
    uint8                              u8Saturation;
    uint16                             u16TransitionTime;
    zbmap8                             u8OptionsMask;
    zbmap8                             u8OptionsOverride;    
} tsCLD_ColourControl_EnhancedMoveToHueAndSaturationCommandPayload;

where:

u16EnhancedHue is the target ‘enhanced’ hue value in terms of a step around the CIE colour ‘triangle’ - for the format, refer to the description of the attribute u16EnhancedCurrentHue in Section 31.2.
u8Saturation is the target saturation value.
16TransitionTime is the time period, in tenths of a second, over which the change in hue and saturation should be implemented.
OptionsMask and OptionsOverride must be either both present or both not present. These fields are used in creating a temporary Options bitmap from the u8Options attribute. Each bit of the u8Options attribute is carried across to the temporary Options bitmap unless the corresponding bit of OptionsMask is set (to 1). In this case, the corresponding bit of OptionsOverride is used in the temporary Options bitmap instead.

Colour Loop Set Command Payload

typedef struct
{
    uint8                               u8UpdateFlags;
    teCLD_ColourControl_LoopAction      eAction;
    teCLD_ColourControl_LoopDirection   eDirection;
    uint16                              u16Time;
    uint16                              u16StartHue;
    zbmap8                              u8OptionsMask;
    zbmap8                              u8OptionsOverride;    
} tsCLD_ColourControl_ColourLoopSetCommandPayload;

where:

u8UpdateFlags is a bitmap indicating which of the other fields of the structure must be set (a bit must be set to ‘1’ to enable the corresponding field, and ‘0’ otherwise):

Bits	Field
0	```
eAction

|
|1|```
eDirection

| |2|``` u16Time

|
|3|```
u16StartHue

| |4–7|Reserved|

eAction indicates the colour loop action to be taken (if enabled through u8UpdateFlags), as one of:

Enumeration	Value	Action
E_CLD_COLOURCONTROL_COLOURLOOP_ACTION_

DEACTIVATE

|0x00|Deactivate colour loop| |E_CLD_COLOURCONTROL_COLOURLOOP_ACTION_

ACTIVATE_FROM_START

|0x01|Activate colour loop from specified start (enhanced) hue value| |E_CLD_COLOURCONTROL_COLOURLOOP_ACTION_

ACTIVATE_FROM_CURRENT

|0x02|Activate colour from current (enhanced) hue value|

eDirection indicates the direction to be taken around the colour loop (if enabled through u8UpdateFlags) in terms of the direction of change of u16EnhancedCurrentHue:

Enumeration	Value	Direction
E_CLD_COLOURCONTROL_COLOURLOOP_

DIRECTION_DECREMENT

|0x00|Decrement current (enhanced) hue value| |E_CLD_COLOURCONTROL_COLOURLOOP_

DIRECTION_INCREMENT

|0x01|Increment current (enhanced) hue value|

u16Time is the period, in seconds, of a full colour loop - that is, the time to cycle all possible values of u16EnhancedCurrentHue.
u16StartHue is the value of u16EnhancedCurrentHue at which the colour loop is to be started (if enabled through u8UpdateFlags).
OptionsMask and OptionsOverride must be either both present or both not present. These fields are used in creating a temporary Options bitmap from the u8Options attribute. Each bit of the u8Options attribute is carried across to the temporary Options bitmap unless the corresponding bit of OptionsMask is set (to 1). In this case, the corresponding bit of OptionsOverride is used in the temporary Options bitmap instead.

Stop Move Step Command Payload

typedef struct
{
    zbmap8                 u8OptionsMask;
    zbmap8                 u8OptionsOverride;    
} tsCLD_ColourControl_StopMoveStepCommandPayload;

where OptionsMask and OptionsOverride must be either both present or both not present. These fields are used in creating a temporary Options bitmap from the u8Options attribute. Each bit of the u8Options attribute is carried across to the temporary Options bitmap unless the corresponding bit of OptionsMask is set (to 1). In this case, the corresponding bit of OptionsOverride is used in the temporary Options bitmap instead.

Parent topic:Structures

Parent topic:Colour Control Cluster

Enumerations

teCLD_ColourControl_ClusterID

The following structure contains the enumerations used to identify the attributes of the Colour Control cluster.

typedef enum 
{
    E_CLD_COLOURCONTROL_ATTR_CURRENT_HUE                = 0x0000,
    E_CLD_COLOURCONTROL_ATTR_CURRENT_SATURATION,
    E_CLD_COLOURCONTROL_ATTR_REMAINING_TIME,
    E_CLD_COLOURCONTROL_ATTR_CURRENT_X,
    E_CLD_COLOURCONTROL_ATTR_CURRENT_Y,
    E_CLD_COLOURCONTROL_ATTR_DRIFT_COMPENSATION,
    E_CLD_COLOURCONTROL_ATTR_COMPENSATION_TEXT,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_TEMPERATURE_MIRED,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_MODE,
    E_CLD_COLOURCONTROL_ATTR_OPTIONS         = 0x000F,
    E_CLD_COLOURCONTROL_ATTR_NUMBER_OF_PRIMARIES     = 0x0010,
    E_CLD_COLOURCONTROL_ATTR_PRIMARY_1_X,
    E_CLD_COLOURCONTROL_ATTR_PRIMARY_1_Y, 
    E_CLD_COLOURCONTROL_ATTR_PRIMARY_1_INTENSITY,
    E_CLD_COLOURCONTROL_ATTR_PRIMARY_2_X            = 0x0015,
    E_CLD_COLOURCONTROL_ATTR_PRIMARY_2_Y,
    E_CLD_COLOURCONTROL_ATTR_PRIMARY_2_INTENSITY,
    E_CLD_COLOURCONTROL_ATTR_PRIMARY_3_X            = 0x0019,
    E_CLD_COLOURCONTROL_ATTR_PRIMARY_3_Y,
    E_CLD_COLOURCONTROL_ATTR_PRIMARY_3_INTENSITY,
    E_CLD_COLOURCONTROL_ATTR_PRIMARY_4_X            = 0x0020,
    E_CLD_COLOURCONTROL_ATTR_PRIMARY_4_Y,     
    E_CLD_COLOURCONTROL_ATTR_PRIMARY_4_INTENSITY,       
    E_CLD_COLOURCONTROL_ATTR_PRIMARY_5_X            = 0x0024,
    E_CLD_COLOURCONTROL_ATTR_PRIMARY_5_Y,
    E_CLD_COLOURCONTROL_ATTR_PRIMARY_5_INTENSITY,
    E_CLD_COLOURCONTROL_ATTR_PRIMARY_6_X            = 0x0028,
    E_CLD_COLOURCONTROL_ATTR_PRIMARY_6_Y,
    E_CLD_COLOURCONTROL_ATTR_PRIMARY_6_INTENSITY,
    E_CLD_COLOURCONTROL_ATTR_WHITE_POINT_X           = 0x0030,
    E_CLD_COLOURCONTROL_ATTR_WHITE_POINT_Y,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_POINT_R_X,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_POINT_R_Y,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_POINT_R_INTENSITY,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_POINT_G_X          = 0x0036,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_POINT_G_Y,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_POINT_G_INTENSITY,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_POINT_B_X          = 0x003A,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_POINT_B_Y,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_POINT_B_INTENSITY,
    E_CLD_COLOURCONTROL_ATTR_ENHANCED_CURRENT_HUE       = 0x4000,
    E_CLD_COLOURCONTROL_ATTR_ENHANCED_COLOUR_MODE,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_LOOP_ACTIVE,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_LOOP_DIRECTION,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_LOOP_TIME,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_LOOP_START_ENHANCED_HUE,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_LOOP_STORED_ENHANCED_HUE,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_CAPABILITIES       = 0x400a,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_TEMPERATURE_MIRED_PHY_MIN,
    E_CLD_COLOURCONTROL_ATTR_COLOUR_TEMPERATURE_MIRED_PHY_MAX,
    E_CLD_COLOURCONTROL_ATTR_COUPLE_COLOUR_TEMPERATURE_TO_LEVEL_MIN_MIRED,
    E_CLD_COLOURCONTROL_ATTR_STARTUP_COLOUR_TEMPERATURE_MIRED = 0x4010,
} teCLD_ColourControl_ClusterID;

Parent topic:Enumerations

Parent topic:Colour Control Cluster

Compile-time Options

To enable the Colour Control cluster in the code to be built, it is necessary to add the following to the zcl_options.h file:

#define CLD_COLOUR_CONTROL

In addition, to include the software for a cluster client or server or both, it is necessary to add one or both of the following to the same file:

#define COLOUR_CONTROL_CLIENT
#define COLOUR_CONTROL_SERVER

The Colour Cluster cluster attributes reside on the server only. Therefore, attributes should not be enabled in the zcl_options.h file for the cluster client.

Optional Attributes

The optional attributes of the Colour Control cluster are enabled/disabled by defining the following in the zcl_options.h file:

For optional attributes from the ‘Colour Information’ attribute set:
- CLD_COLOURCONTROL_ATTR_REMAINING_TIME
- CLD_COLOURCONTROL_ATTR_DRIFT_COMPENSATION
- CLD_COLOURCONTROL_ATTR_COMPENSATION_TEXT
- CLD_COLOURCONTROL_ATTR_COLOUR_MODE
  - Certain attributes from this attribute set are enabled through a ‘ColourCapabilities’ Definition (see below) - these are u8CurrentHue, u8CurrentSaturation and u16ColourTemperatureMired.
For optional attributes from the ‘Defined Primaries Information’ and ‘Additional Defined Primaries Information’ attribute sets, the macro
- CLD_COLOURCONTROL_ATTR_NUMBER_OF_PRIMARIES
  - is used to define the required number of colour primaries, N, in the range 1 to 6 (0xFF can also be specified if the number of primaries is not known). This macro is used to automatically enable the required attributes from these attribute sets - for example, if N is set to 4 then the following attributes are enabled:
  - u16Primary1X, u16Primary1Y, u8Primary1Intensity, u16Primary2X, u16Primary2Y, u8Primary2Intensity, u16Primary3X, u16Primary3Y, u8Primary3Intensity, u16Primary4X, u16Primary4Y, u8Primary4Intensity.
For optional attributes from the ‘Defined Colour Points Settings’ attribute set:
- CLD_COLOURCONTROL_ATTR_WHITE_POINT_X
- CLD_COLOURCONTROL_ATTR_WHITE_POINT_Y
- CLD_COLOURCONTROL_ATTR_COLOUR_POINT_R_X
- CLD_COLOURCONTROL_ATTR_COLOUR_POINT_R_Y
- CLD_COLOURCONTROL_ATTR_COLOUR_POINT_R_INTENSITY
- CLD_COLOURCONTROL_ATTR_COLOUR_POINT_G_X
- CLD_COLOURCONTROL_ATTR_COLOUR_POINT_G_Y
- CLD_COLOURCONTROL_ATTR_COLOUR_POINT_G_INTENSITY
- CLD_COLOURCONTROL_ATTR_COLOUR_POINT_B_X
- CLD_COLOURCONTROL_ATTR_COLOUR_POINT_B_Y
- CLD_COLOURCONTROL_ATTR_COLOUR_POINT_B_INTENSITY
For optional attributes from the ‘Enhanced Colour Mode’ attributes, the following must be defined:
- CLD_COLOURCONTROL_ATTR_ENHANCED_COLOUR_MODE
- CLD_COLOURCONTROL_ATTR_COLOUR_CAPABILITIES
  - The required ‘Enhanced Colour Mode’ attributes for a device must then be enabled through a ‘Colour Capabilities’ Definition (see below).

Global Attributes

Add this line to enable the optional Attribute Reporting Status attribute:

#define CLD_COLOURCONTROL_ATTR_ID_ATTRIBUTE_REPORTING_STATUS

Add this line to define the value (n) of the Cluster Revision attribute:

#define CLD_COLOURCONTROL_CLUSTER_REVISION <n>

The default value is 1, which corresponds to the revision of the cluster in the ZCL r6 specification (see Section 2.4).

‘Colour Capabilities’ Definition

If required, certain ‘Colour Information’ attributes and all ‘Enhanced Colour Mode’ attributes must be enabled through a ‘Colour Capabilities’ definition. Attributes are enabled as a group according to the required capability/functionality. The capabilities are detailed in the table below, with their corresponding attributes and macros.

Table 1. ‘Colour Capabilities’ Macros
Capability/Functionality	Attributes	Macro
Hue/Saturation	u8CurrentHue u8CurrentSaturation	COLOUR_CAPABILITY_HUE_SATURATION_SUPPORTED
Enhanced Hue (also need Hue/Saturation)	u16EnhancedCurrentHue*	COLOUR_CAPABILITY_ENHANCE_HUE_SUPPORTED
Colour Loop (also need Enhanced Hue)	u8ColourLoopActive* u8ColourLoopDirection* u16ColourLoopTime* u16ColourLoopStartEnhancedHue* u16ColourLoopStoredEnhancedHue*	COLOUR_CAPABILITY_COLOUR_LOOP_SUPPORTED
CIE XY Values (this is mandatory)	u16CurrentX u16CurrentY	COLOUR_CAPABILITY_XY_SUPPORTED
Colour Temperature	u16ColourTemperatureMired u16ColourTemperatureMiredPhyMin* u16ColourTemperatureMiredPhyMax* u16ColourTemperatureMiredMin* u16ColourTemperatureMiredMax* bColourCoupleTemperatureMired-ToLevel* u16StartupColourTemperatureMired*	COLOUR_CAPABILITY_COLOUR_TEMPERATURE_SUPPORTED

The ‘Enhanced Colour Mode’ attributes also require ‘enhanced colour mode’ to be enabled through `#``define CLD_COLOURCONTROL_ATTR_ENHANCED_COLOUR_MODE`

The above macros automatically invoke the macros for the individual attributes in the capability group. For example, E_CLD_COLOURCONTROL_ATTR_CURRENT_HUE is invoked for the attribute u8CurrentHue.

The enabled Colour Capabilities are reflected in the ‘Enhanced Colour Mode’ attribute (bitmap) u16ColourCapabilities.

Example Colour Capabilities definitions are provided below for different devices.

ZLO Extended Colour Light:

#define CLD_COLOURCONTROL_COLOUR_CAPABILITIES 
           (COLOUR_CAPABILITY_HUE_SATURATION_SUPPORTED | \\
         COLOUR_CAPABILITY_ENHANCE_HUE_SUPPORTED  | \\
         COLOUR_CAPABILITY_COLOUR_LOOP_SUPPORTED | \\
         COLOUR_CAPABILITY_XY_SUPPORTED | \\
         COLOUR_CAPABILITY_COLOUR_TEMPERATURE_SUPPORTED)

ZLO Colour Light:

#define CLD_COLOURCONTROL_COLOUR_CAPABILITIES                    
              (COLOUR_CAPABILITY_HUE_SATURATION_SUPPORTED | \\
              COLOUR_CAPABILITY_ENHANCE_HUE_SUPPORTED    | \\
              COLOUR_CAPABILITY_COLOUR_LOOP_SUPPORTED    | \\
              COLOUR_CAPABILITY_XY_SUPPORTED)

ZLO Colour Temperature Light:

#define CLD_COLOURCONTROL_COLOUR_CAPABILITIES             
        (COLOUR_CAPABILITY_COLOUR_TEMPERATURE_SUPPORTED)

Parent topic:Colour Control Cluster