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.

Install Notes:

Use of this library requires:
matterTools.endpointAndChildDeviceTools // needed for getEndpointIdInt() function

1. Methods

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:

1.1 setHue

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.

1.2 setSaturation

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

1.3 setColor

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

1.4 setColorTemperature

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

1.5 Child Component Functions

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

1.6 Note on getEndpointIdInt(cd) method

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}

2 Hubitat Events

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

3 Location of Library

2 Likes