matterTools - On/Off Cluster 0x0006 Command Support

This posting explains how to use the On/Off Cluster library from my matterTools library files.

The On/Off tools library is found in the file "matterTools.OnOffClusterTools0x0006.groovy" at the github site below.

Install Notes:

Use of this library requires including:

  1. matterTools.endpointAndChildDeviceTools . This is needed for getEndpointIdInt() method if you have not defined your own!

1. Methods

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:

1.1 off

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.

1.2 on

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.

1.3 toggle

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.

1.4 offWithEffect

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.

1.5 OnWithRecallGlobalScene

(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).

1.6 onWithTimedOff

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.

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: Hubitat-matterTools/matterTools.endpointAndChildDeviceTools.groovy at main · jvmahon/Hubitat-matterTools · GitHub . 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. Legacy Child Generic Component Methods

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: Hubitat-matterTools/matterTools.MatterGenericComponentRGBW.groovy at main · jvmahon/Hubitat-matterTools · GitHub

3. 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

4. Location of Library

6 Likes

This is an useful function, although rarely used with Hubitat. It guarantees that the device will automatically switch off after the configured time period, even if the connection to the hub was lost.

Sending an explicit off (or on) command cancels the automatic timer.

1 Like