matterTools - Identify Cluster 0x0003 Command Support

This posting explains how to use the Identify Cluster library from my matterTools library files.

The identify tools library is found in the "matterTools.identifyClusterMethods0x0003.groovy" at the github site below.

Install Notes:

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

1. Methods

This library implements Mater Cluster Spec Section 1.2.7, Identify command. It includes the methods as described below:

1.1 identify(timeInSeconds)

void identify(timeInSeconds)

This method is intended to be called as a command from a driver's metadata's "command" section. Usage is as follows:

        command "identify", [[name: "Identify", type:"NUMBER", description:"Put device into Identify mode"]]

1.2 identify(ep: null, identifyTime: 10)

void identify(ep: null, identifyTime: 10)

This is a named parameter version of the identify command
typeof ep = String
typeof identifyTime = Integer

On calling this command, the targetd device will put itself into identify mode for the specified number of seconds. The number of seconds defaults to 10.

1.3 void componentIdentify

void componentIdentify(com.hubitat.app.DeviceWrapper cd, timeInSeconds) {
    ep:getEndpointIdInt(cd)), identifyTime:timeInSeconds
}

This is a component version that can be called from a child device.

1.4 Note on getEndpointIdInt(cd) method

Serveral 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