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