matterTools ‐ Color Cluster 0x0300 Command Support
This posting explains how to use the Color Cluster library from my matterTools library files.
The Color Cluster tools library is found in the "matterTools.colorClusterMethods0x0300.groovy" at the github site below.
Use of this library requires: matterTools.endpointAndChildDeviceTools // needed for getEndpointIdInt() function
This library implements Matter Color Cluster Spec Section 3.2, Color commands. This expands on Hubitat's built-in methods to allow control by endpoint and using named parameters.
It includes the methods as described below:
Implements Matter Command MoveToHue (Command 0x00), Matter 1.2 Spec, Section 3.2.11.4
void setHue(hue)
void setHue( ep:getEndpointIdInt(device), transitionTime10ths: 0, hue:null , level:null)
ep: is Integer
hue: expressed in percent 0..100
transitionTime10ths : (optional, default 0) time in 0.1 seconds. I.e., 30 = 3 seconds
level: (optional, if omitted, don't set level) expressed in percent 0..100
The first two of these methods are simple stub procedures that are intended to be called from the Hubitat web UI element by drivers having capability "ColorControl"
The third method, setHue(ep: null , hue:hull, level: null , transitionTime10ths: null) is for more general coding use and supports endpoint selection as well as additional functions and type checking
See note below on the getEndpointIdInt(cd) method which will need to be defined by your driver.
Implements Matter Command "MoveToSaturation" (command 0x03), Matter 1.2 Spec, Section 3.2.11.7
void setSaturation(saturation)
void setSaturation( ep:getEndpointIdInt(device), transitionTime10ths: 0, saturation:null , level:null)
ep: is Integer
saturation: expressed in percent 0..100
transitionTime10ths : (optional, default 0) time in 0.1 seconds. I.e., 30 = 3 seconds
level: (optional, if omitted, don't set level) expressed in percent 0..100
Description to be added
Implements Matter Command "MoveToHueAndSaturation" (Command 0x06), Matter 1.2 Spec, Section 3.2.11.10
void setColor(ep:getEndpointIdInt(device), transitionTime10ths:0, hue: null, saturation: null, level: null )
ep: is Integer
hue: expressed in percent 0..100
saturation: expressed in percent 0..100
transitionTime10ths : (optional, default 0) time in 0.1 seconds. I.e., 30 = 3 seconds
level: (optional, if omitted, don't set level) expressed in percent 0..100
Further description to be added
Implements Matter Command MoveToColorTemperature (Command 0x0A), Matter 1.2 Spec, Section 3.2.11.14
void setColorTemperature(colortemperature, level, transitionTime)
level is optional
trasitionTime is optional, but use requires level
void setColorTemperature( ep: null, colortemperature:null, level:null, transitionTime10ths: null )
ep: is Integer
colortemperature: expressed in Kelvin. Minimum supported is 16 based on Matter standards.
transitionTime10ths : (optional, default 0) time in 0.1 seconds. I.e., 30 = 3 seconds
level: (optional, if omitted, don't set level) expressed in percent 0..100
Further description to be added
Child devices are supported with the following component functions:
void componentSetHue(com.hubitat.app.DeviceWrapper cd, hue)
void componentSetSaturation(com.hubitat.app.DeviceWrapper cd, saturation)
void componentSetColor(com.hubitat.app.DeviceWrapper cd, Map colormap)
void componentSetColorTemperature(cd, cdColortemperature, cdLevel = null, cdTransitionTime = null)
Further description to be added
Several of the methods reference a function: getEndpointIdInt(cd). This function helps to enable child device support. Your driver should define a function that produces an endpoint number from the child device wrapper. If getEndpointIdInt is called in the parent device, it can be called as getEndpointIdInt(device) and should return the parent Endpoint ID as an integer.
The matterTools library defines such a function here: https://github.com/jvmahon/Hubitat-matterTools/blob/main/matterTools.endpointAndChildDeviceTools.groovy . mattertools always works in Integers for endpoints (and type checks for that).
If your driver only has a single endpoint and no child devices, you can define a simple function like:
Integer getEndpointIdInt(cd) { return 1}
The event library (hubitatTools.createMatterEvents.groovy) can be used to generate Hubitat events that are sendable by the sendEvent method. This will be explained in a later posting. The principal use of such event messages is to display countdowns of remaining identify time