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.

Install Notes:

Use of this library requires:
matterTools.endpointAndChildDeviceTools // needed for getEndpointIdInt() function
matterTools.concurrentRuntimeDataStorage // needed to retrieve stored timing data

1. Methods

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:

1.1 setLevel

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.

1.2 startLevelChange

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.

1.3 stopLevelChange

void stopLevelChange(direction)
void stopLevelChange( ep:null )

This method implements Matter 1.2 Cluster Spec Section 1.6.7.6 Stop command (command 0x03)

1.4 Child Component Functions

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) 

1.5 Notes on fan control

The code has "stub" support for fan control. This is will be added when a fan device is available!

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

1 Like