matterTools ‐ On Off Cluster 0x0006 Command Support
This posting explains how to use the matterTools On/Off Cluster library.
The On/Off tools library is found in the file "matterTools.OnOffClusterTools0x0006.groovy" at the github site below.
Use of this library requires including:
- matterTools.endpointAndChildDeviceTools . This is needed for getEndpointIdInt() method if you have not defined your own!
This library implements Matter Cluster Spec Section 1.5, On/Off cluster command. This expands on Hubitat's built-in methods to allow control by endpoint and using named parameters. The library includes the methods described below:
void off(ep: ep:getEndpointIdInt(device))
This method implements Matter 1.2 Cluster Spec Section 1.5.7.1, 'off' command.
See note below on the getEndpointIdInt(cd) method which will need to be defined by your driver.
void on(ep: getEndpointIdInt(device))
This method implements Matter 1.2 Cluster Spec Section 1.5.7.2, 'on' command.
This method works both as a command that can be called from a capabilites "Switch" UI element, or as a regular method.
See note below on the getEndpointIdInt(cd) method which will need to be defined by your driver.
void toggleOnOff( ep: getEndpointIdInt(device))
This method implements Matter 1.2 Cluster Spec Section 1.5.7.3, Toggle command. This method toggles a device between On and Off switch states
See note below on the getEndpointIdInt(cd) method which will need to be defined by your driver.
void offWithEffect( ep: getEndpointIdInt(device), effectIdentifier: 0, effectVariant:0)
This method implements Matter 1.2 Cluster Spec Section 1.5.7.4, "OffWithEffect" command. See the Matter Cluster Spec for effectIdentifier and effectVariant parameter settings.
See note below on the getEndpointIdInt(cd) method which will need to be defined by your driver.
(Matter 1.2 Cluster Spec Section 1.5.7.5 - Not Implemented. Not really sure how useful this is. Add a comment on gitHub if you need it and I'll add).
void onWithTimedOff( ep: getEndpointIdInt(device), onTime10ths: 10, offWaitTime10ths:0 )
This method implements Matter 1.2 Cluster Spec Section 1.5.7.6, 'OnWithTimedOff' command
This method will turn on a device for a set amount of time, after which the device will automatically turn off. A guard time (offWaitTime10ths) parameter is included, but the guard time is not currently functional (may be a device problem - more testing is needed!). See Matter spec section 1.5.7.6 for additional details on parameter settings..
onTime10ths and offWaitTime10ths are specified in tenths of a second, so, e.g., 30 = 3 seconds.
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}
Legacy child Generic Component device drivers (i.e., Hubitat's built-in Generic Component devices) are supported with the following component methods:
void componentOn(com.hubitat.app.DeviceWrapper cd){ on( ep:getEndpointIdInt(cd)) }
void componentOff(com.hubitat.app.DeviceWrapper cd){ off(ep:getEndpointIdInt(cd)) }
For "new" methods not found in legacy drivers (e.g., toggleOnOff, offWithEffect, onWithTimedOff), a child device does not need to call a "componentXXX" variant, but can call the main function directly by passing its endpoint number and other parameters using the "named" parameter methods. See example Matter Generic RGB Component here: https://github.com/jvmahon/Hubitat-matterTools/blob/main/matterTools.MatterGenericComponentRGBW.groovy
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.