matterTools ‐ Level Cluster 0x0008 Command Support
This posting explains how to use the Level Cluster library from my matterTools library files.
The Level tools library is found in the "matterTools.levelClusterMethods0x0008.groovy" at the github site below.
Use of this library requires: matterTools.endpointAndChildDeviceTools // needed for getEndpointIdInt() function matterTools.concurrentRuntimeDataStorage // needed to retrieve stored timing data
This library implements Matter Level Spec Section 1.6, Level command. This expands on Hubitat's built-in methods to allow control by endpoint and using named parameters.
It includes the methods as described below:
void setLevel(inputLevel)
void setLevel(inputLevel, durationSeconds)
void setLevel(ep: null , level: null , transitionTime10ths: null)
ep is Integer
level - expressed in percent 0..100
transitionTime10ths - transition time in 0.1 seconds. I.e., 30 = 3 seconds
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 "SwitchLevel"
The third method, setLevel(ep: null , 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.
void startLevelChange(direction)
void startLevelChange(ep:null, direction: null, rate:50, moveWithOnOff:true )
ep: endpoint as an integer
direction: accepts either "up" or "down"
rate: expressed in units per second on a scale of 1..254). Defaults to 50 resulting in an ~5 second transition from 0-100%.
moveWithOnOff: Defaults to 'true'. If 'true', this will cause an off device to turn on when moving in the up direct, or a device to turn 'off' when it reaches 0. If false, the command has no 'up' impact if the device is off, and will only reduce device to 1%, not fully off.
These methods implement Matter 1.2 Cluster Spec Section 1.6.7.2 Move command (command 0x01) or Section 1.6.7.6 MoveWithOnOff command (command 0x05) MoveWithOnOff is used by default, but can be changed by setting moveWithOnOff parameter to false.
The first method is intended to be called from the web UI when the ChangeLevel capability is included in a driver.
Second method is preferred for use in other code as it supports endpoints as well as named parameters and type checking for easier readability.
void stopLevelChange(direction)
void stopLevelChange( ep:null )
This method implements Matter 1.2 Cluster Spec Section 1.6.7.6 Stop command (command 0x03)
Child devices are supported with the following component functions:
void componentStartLevelChange(com.hubitat.app.DeviceWrapper cd, direction, rate = 50 )
void componentStopLevelChange(com.hubitat.app.DeviceWrapper cd)
void componentSetLevel(com.hubitat.app.DeviceWrapper cd, cdLevel, cdDuration = null)
The code has "stub" support for fan control. This is will be added when a fan device is available!
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