The package name of this class is matter. So, to use in an app or driver you, would reference it with matter..
The matter object is available to Matter drivers (since 2.3.7). It builds Matter commands, parses the descriptions the hub delivers to the driver, and looks up cluster information.
Most methods that build a command return a hub command String. Return it from a command method (as in Building a Matter Driver), or send it with sendHubCommand(). Endpoints, clusters, attributes, and commands are identified by number (e.g., 0x0006 for the On/Off cluster) or, for some methods, by name. Unless noted, transition values are in seconds.
Also see the hubitat.matter.DataType class, which defines the Matter data type IDs (such as DataType.UINT8) and has methods to encode values.
For a complete example driver, see: https://github.com/hubitat/HubitatPublic/blob/master/examples/drivers/thirdRealityMatterNightLight.groovy
Builds a command to turn the endpoint on.
String on()None
String - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Builds a command to turn the endpoint off.
String off()None
String - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Builds a command to set the level of the endpoint.
String setLevel(Number level, Number transition = null)level - The target level, as a percentage (0 to 100)transition - Optional; the transition time, in seconds (defaults to 1).String - a Matter hub command; return it from your command method, or send it with sendHubCommand(), or an empty list if level is null
Builds a command to set the color from hue and saturation.
String setColor(Map value)value - A Map with these keys:
hue - the hue, as a percentage (0 to 100)saturation - the saturation, as a percentage (0 to 100)rate - optional; the transition time, in seconds (defaults to 1)String - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Builds a command to set the color temperature.
String setColorTemperature(Number value, Number transition = null)value - The color temperature, in kelvintransition - Optional; the transition time, in seconds (defaults to 1).String - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Builds a command to set the color from XY coordinates.
String setColorXY(Map value)value - A Map with these keys:
x - the x coordinatey - the y coordinaterate - optional; the transition time, in seconds (defaults to 1)String - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Builds a command to set the color hue.
String setHue(Integer value, Number transition = null)value - The hue, as a percentage (0 to 100)transition - Optional; the transition time, in seconds (defaults to 1).String - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Builds a command to set the color saturation.
String setSaturation(Integer value, Number transition = null)value - The saturation, as a percentage (0 to 100)transition - Optional; the transition time, in seconds (defaults to 1).String - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Builds a command to lock a door lock endpoint. (Since 2.4.2)
String lock(String pinCode = null)pinCode - Optional; a PIN code to include in the commandString - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Builds a command to unlock a door lock endpoint. (Since 2.4.2)
String unlock(String pinCode = null)pinCode - Optional; a PIN code to include in the commandString - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Starts the Matter over-the-air (OTA) firmware update flow for this device.
HubAction updateFirmware()None
The HubAction that starts the firmware update
Builds a command to read the on/off attribute.
String onOffRefresh()None
String - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Builds a command to read the level attribute.
String levelRefresh()None
String - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Builds a command to read the color temperature attribute.
String colorTemperatureRefresh()None
String - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Builds a command to read the electrical active power attribute.
String electricMeasurementPowerRefresh()None
String - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Builds a Matter attribute path map. Result keys:
ep (String) - endpoint identifier prefixed with 0xcluster (String) - cluster identifier prefixed with 0x and formatted to four hexadecimal digitsattr (String) - attribute identifier prefixed with 0x and formatted to four hexadecimal digitsMap<String, String> attributePath(Integer ep, Integer cluster, Integer attr)Map<String, String> attributePath(String ep, Integer cluster, Integer attr)ep - The endpoint ID (an Integer, or a hexadecimal String)cluster - The cluster IDattr - The attribute IDMap described above
Builds an attribute path after resolving the cluster and attribute names.
Map<String, String> attributePathByName(Integer ep, String clusterName, String attributeName)Map<String, String> attributePathByName(String ep, String clusterName, String attributeName)ep - The endpoint ID (an Integer, or a hexadecimal String)clusterName - Matter cluster nameattributeName - Matter attribute nameAttribute path map described by attributePath(String, Integer, Integer), or null when the cluster or attribute is not found
Builds a Matter event path map. Result keys:
ep (String) - endpoint identifier prefixed with 0xcluster (String) - cluster identifier prefixed with 0x and formatted to four hexadecimal digitsevt (String) - event identifier prefixed with 0x and formatted to four hexadecimal digitsisUrgent (String) - supplied Boolean converted to textMap<String, String> eventPath(Integer ep, Integer cluster, Integer attr, Boolean isUrgent = false)Map<String, String> eventPath(String ep, Integer cluster, Integer attr, Boolean isUrgent = false)ep - The endpoint ID (an Integer, or a hexadecimal String)cluster - The cluster IDattr - The event IDisUrgent - Optional; whether the event path is marked urgent (defaults to false)Map described above
Builds a Matter attribute subscription hub command. Each map is an attribute path with ep, cluster, and attr keys as returned by attributePath(String, Integer, Integer).
String subscribe(Integer minReportTime, Integer maxReportTime, List<Map<String, String>> attributePaths)minReportTime - The minimum report interval, in secondsmaxReportTime - The maximum report interval, in secondsattributePaths - A list of attribute paths (see attributePath()) to subscribe toString - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Builds a clean Matter attribute subscription hub command. Each map is an attribute path with ep, cluster, and attr keys as returned by attributePath(String, Integer, Integer). (Since 2.3.9)
String cleanSubscribe(Integer minReportTime, Integer maxReportTime, List<Map<String, String>> attributePaths)minReportTime - The minimum report interval, in secondsmaxReportTime - The maximum report interval, in secondsattributePaths - A list of attribute paths (see attributePath()) to subscribe toString - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Builds a command to remove the subscription.
String unsubscribe()None
String - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Builds a Matter attribute read hub command. Each map is an attribute path with ep, cluster, and attr keys as returned by attributePath(String, Integer, Integer).
String readAttributes(List<Map<String, String>> attributePaths)attributePaths - A list of attribute paths (see attributePath()) to readString - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Builds a Matter attribute write request map. Result keys:
ep (String) - endpoint identifier prefixed with 0xcluster (String) - cluster identifier prefixed with 0x and formatted to four hexadecimal digitsattr (String) - attribute identifier prefixed with 0x and formatted to four hexadecimal digitsdata (String) - type byte and encoded value; integer types are byte-swapped, Boolean/null types have no data bytes, and UTF8/octet strings carry a length byteMap<String, String> attributeWriteRequest(Integer ep, Integer cluster, Integer attr, Integer type, String data)Map<String, String> attributeWriteRequest(String ep, Integer cluster, Integer attr, Integer type, String data)ep - The endpoint ID (an Integer, or a hexadecimal String)cluster - The cluster IDattr - The attribute IDtype - The Matter data type ID (see hubitat.matter.DataType)data - The data bytes, as a hexadecimal StringMap described above
Builds a Matter attribute write hub command. Each map is an attribute write request with ep, cluster, attr, and data keys as returned by attributeWriteRequest(String, Integer, Integer, Integer, String).
String writeAttributes(List<Map<String, String>> attributeWriteRequests)attributeWriteRequests - A list of attribute write requests (see attributeWriteRequest())String - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Builds a command to invoke a cluster command.
String invoke(Integer ep, Integer cluster, Integer cmd, Integer timeOut = 0, List<Map<String, String>> fields)String invoke(Integer ep, Integer cluster, Integer cmd, Integer timeOut = 0, String data = "1518")String invoke(String ep, Integer cluster, Integer cmd, Integer timeOut = 0)String invoke(String ep, Integer cluster, Integer cmd, Integer timeOut = 0, List<Map<String, String>> fields)ep - The endpoint ID (an Integer, or a hexadecimal String)cluster - The cluster IDcmd - The command IDtimeOut - Optional; the command timeout, in milliseconds (defaults to 0)fields - Optional; an ordered list of field Maps, each with type, num, and data String values (see cmdField())data - Optional; the pre-encoded command payload as a hexadecimal String. Defaults to an empty Matter structure ("1518").String - a Matter hub command; return it from your command method, or send it with sendHubCommand()
Builds a command field Map (for the fields parameter of invoke()) from numeric type and tag values.
Map<String, String> cmdField(int type, int num, String data = "")type - The Matter data type IDnum - The context tag numberdata - Optional; the field data as a hexadecimal String (defaults to empty)Map described above
Encodes one command field with a context-specific tag.
String cmdFieldStr(String type, String num, String data = "")String cmdFieldStr(int type, int num, String data = "")type - The Matter data type IDnum - The context tag numberdata - Optional; the field data as a hexadecimal String (defaults to empty)Encoded hexadecimal field bytes
NumberFormatException if type or num is not decimal integer text
Parses an event, invoke-response, or read-attribute description into a Map.
Map parseDescriptionAsMap(String description)description - Description beginning with event -, read attr -, or invoke resp -Fields described above, or an empty map for an unsupported prefix
Converts a recognized Matter description into an event Map (e.g., for use with sendEvent()).
Map getEvent(String description)description - Catchall or read-attribute description text; null throws NullPointerExceptionEvent map with the keys above, or an empty map when no event is recognized
Parses a hexadecimal Matter TLV sequence into its tag map.
type (String) is the TLV type byte as hexadecimal.isContextSpecific (Boolean) is the context-specific bit.value (String or null): integers/floats are byte-swapped hexadecimal strings, UTF-8 is decoded text, octet strings are hexadecimal text, Boolean values are "00"/"01", and null TLV values are null.values (nested tag Map) instead of value.Structure containers do not create a structure entry; their contained elements are flattened into the surrounding result map. The public result has no remainder key. Null, empty, or malformed TLV data can throw null-dereference, indexing, or range exceptions. Parses a Matter TLV byte sequence into its tag map.
type (String) is the TLV type byte as hexadecimal.isContextSpecific (Boolean) is the context-specific bit.value (String or null): integers/floats are byte-swapped hexadecimal strings, UTF-8 is decoded text, octet strings are hexadecimal text, Boolean values are "00"/"01", and null TLV values are null.values (nested tag Map) instead of value.Structure containers do not create a structure entry; their contained elements are flattened into the surrounding result map. The public result has no remainder key. Null, empty, or malformed TLV data can throw null-dereference, indexing, or range exceptions. (Since 2.4.2)
Map TLVparser(String value)Map TLVparser(byte[] tlv)value - Optional; hexadecimal Matter TLV bytestlv - Optional; Matter TLV bytesMap from Byte tag identifiers to element maps described above
Decodes supported scalar values from a Matter ARRAY TLV. The returned list contains decoded UTF-8 strings, byte-swapped hexadecimal strings for integer and floating-point values, or "00"/"01" for Boolean values. Unsupported element types are skipped.
List<String> parseArray(String tlvString)tlvString - Hexadecimal Matter TLV sequence, including its array type byteDecoded values in their source order; empty for an empty sequence or when no supported values are present
Returns the endpoint information reported for the Matter device. (Since 2.3.9)
List<Map<String, String>> getMatterEndpoints()None
Endpoint maps described above, or an empty list for other device types
Returns the fingerprints reported for the Matter device.
List<Fingerprint> getMatterFingerprints()None
A list of fingerprints; empty for other types of devices
Looks up a cluster by its integer or hexadecimal ID.
Matter.MatterCluster clusterLookup(def cluster)cluster - The cluster IDThe matching MatterCluster, or null if there is no match
Returns the enum class that defines this helper's cluster constants.
Class<MatterCluster> getCluster()None
The MatterCluster enum class
Returns the Matter cluster names exposed by the controller library.
List<String> getClusterNames()None
Generated cluster class names, excluding BaseCluster
Looks up the cluster name for a numeric identifier.
String getClusterName(Long clusterId)clusterId - Matter cluster identifierCluster name, or null when no matching cluster is available
Looks up a Matter cluster identifier by its generated class name.
Long getClusterIdByName(String clusterName)clusterName - Matter cluster nameNumeric cluster identifier, or null when its generated cluster class is unavailable
Looks up an attribute name in a Matter cluster.
String getClusterAttributeName(Long clusterId, Long attributeId)clusterId - Matter cluster identifierattributeId - Matter attribute identifierAttribute name, or null when no matching cluster or attribute is available
Looks up an attribute identifier by cluster and attribute name.
Long getClusterAttributeByName(Long clusterId, String attributeName)Long getClusterAttributeByName(String clusterName, String attributeName)clusterId - Optional; Matter cluster identifierattributeName - Matter attribute nameclusterName - Optional; Matter cluster nameAttribute identifier, or null when no matching cluster or attribute is available
Looks up a command name in a Matter cluster.
String getClusterCommandName(Long clusterId, Long commandId)clusterId - Matter cluster identifiercommandId - Matter command identifierCommand name, or null when no matching cluster or command is available
Looks up a command identifier by cluster and command name.
Long getClusterCommandByName(Long clusterId, String attributeName)Long getClusterCommandByName(String clusterName, String attributeName)clusterId - Optional; Matter cluster identifierattributeName - Matter command nameclusterName - Optional; Matter cluster nameCommand identifier, or null when no matching cluster or command is available
Formats an integer as uppercase hexadecimal with a minimum width. Widths below one use one digit; values longer than the requested width are not truncated.
String convertToHexString(Integer value, Integer width)value - Integer to formatwidth - Minimum hexadecimal width in digitsUppercase hexadecimal string
Parses a hexadecimal string as an integer.
Integer convertHexToInt(String value)value - Hexadecimal digits to parseParsed Integer value
NumberFormatException if the text is not a valid hexadecimal integer
Decodes each pair of hexadecimal digits into one character.
String hex2String(String arg)arg - Even-length hexadecimal textDecoded characters as a String
NumberFormatException if a pair is not hexadecimal
StringIndexOutOfBoundsException if the text ends with a single digit
Formats an integer as uppercase hexadecimal with a minimum width of two digits.
String integerTo8bitUnsignedHex(int value)value - Integer to format; values longer than one byte are not truncatedUppercase hexadecimal string