matterTools ‐ parseDescriptionAsDecodedMap

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

The parseDescriptionAsDcodedMap library is found in the file "matterTools.parseDescriptionAsDecodedMap.groovy" at the github site below.

1. Methods

This library implements an enhancement / replacement for Hubitat's parseDescriptionAsMap method.

The parseDescriptionAsDecodedMap provides for a complete decoding of Matter Tag-Length-Value data, and decodes directly to Integer, Float, Negatives, Arrays, Structures, etc. (i.e., no more hex codes for you to figure out - decoding is fully to the end-value).

The produced Map will have 4 keys: clusterInt, attrInt, endpointInt, and decodedValue

Note that the use of the key "decodedValue" rather than "value" is intentional - this is to ensure that you "must" check all uses of descMap.value to ensure that use of the fully-decoded value is correct.

2. Use Example

// This parser handles the Matter event message originating from Hubitat.
void parse(String description) {
    try {
        Map decodedDescMap = parseDescriptionAsDecodedMap(description) // Using parser from matterTools.parseDescriptionAsDecodedMap
        // Your code to handle parsing goes here!

    } catch (AssertionError e) { // Catch assertion errors from any of the called methods
        log.error "<pre>${e}<br><br>Stack trace:<br>${getStackTrace(e) }"
    } catch(e){
        log.error "<pre>${e}<br><br>when processing description string ${description}<br><br>Stack trace:<br>${getStackTrace(e) }"
    }
}

3. Decoding Notes

In general, this parser will decoded to the Matter datatypes as specified in the Matter 1.2 specifications. The following are some decoding points to be aware of:

• For decoding of integer and unsigned integer types, Integer is generally preferred.
• int8, uint8, int16, and uint16, and int32 decode to type Integer
• uint32 will decode to type Long (to avoid a negative number representation if the first bit is 1)
• int64 will decode to type Long
• uint64 will decode to type BigInteger (again, to avoid a negative number representation if the first bit is 1)
• Octet strings will decode to byte arrays. So if you just log the octet string, you'll get negative numbers! You'll generally want to log your Octet strings by converting them to Hex (many example methods can be found via google).

4. Location of Library

https://github.com/jvmahon/Hubitat-matterTools/blob/main/matterTools.getExpandedColorNames.groovy