Using the location of the buttons on a multi-button switch device / TagList attribute and Position Semantic Tag

[lboue]

Hello,

Some device like Aqara Climate Sensor W100 has TagList attribute in Descriptor Cluster.
This allow the controller to rename entities using the location of the buttons on a multi-button switch device.

Button 1: [{"0":null,"1":7,"2":1},{"0":null,"1":8,"2":2}] = 1, Top
Button 2: [{"0":null,"1":7,"2":2},{"0":null,"1":8,"2":4}] = 2, Middle
Button 3: [{"0":null,"1":7,"2":3},{"0":null,"1":8,"2":3}] = 3, Bottom

From the specs: 24-31936-004_Matter-1.4.1-Standard-Namespace-Specification.pdf

Common Number Semantic Tag (7)
 Namespace
 This section contains the Common Number semantic tag namespace as part of the semantic tag feature.
 The tags contained in this namespace MAY be used in any domain or context, to indicate an association with a certain numeric feature of a device (e.g. a numeric input button).


Common Position Semantic Tag (8)
 Namespace
 This section contains the Common Position semantic tag namespace as part of the semantic tag feature.
 The tags contained in this namespace MAY be used in any domain or context, to indicate an association with a position relative to the device (e.g. the temperature sensor in the top drawer of a refrigerator, or location of the buttons on a multi-button switch device).

Is it possible to implement this in Home Assistant when endpoints are discovered?

Current

Using Number Semantic Tag and Position Semantic Tag

We can combine Number Semantic Tag and Position Semantic Tag:

Regards

Diag file

matter-01J7VHBAZ27J6PW7C6FVS4TNJS-Climate Sensor W100-b5685a6a2720a6b0255258a3345f7e9c.json

[lboue]

Here's a test with a decoding function:

Position = {
    0: "Left",
    1: "Right",
    2: "Top",
    3: "Bottom",
    4: "Middle"
}

EP_tagList = {
    3: [{"0":"null","1":7,"2":1},{"0":"null","1":8,"2":2}],
    4: [{"0":"null","1":7,"2":2},{"0":"null","1":8,"2":4}],
    5: [{"0":"null","1":7,"2":3},{"0":"null","1":8,"2":3}],
    6: [{"0":"null","1":7,"2":4},{"0":"null","1":8,"2":3}, {"0":"null","1":8,"2":0}],
}

for ep, tags in EP_tagList.items():
    entity_name = ""
    print(f"Endpoint {ep}:")
    for tag in tags:
        # Common Number Semantic Tag
        if tag["1"] == 7:
            num = tag["2"]
            entity_name = str(num)
            # print("Common Number Semantic Tag", "Button", num)
        # Common Position Semantic Tag
        elif tag["1"] == 8:
            pos = tag["2"]
            # print("Common Position Semantic Tag", "Position", Position[pos])
            entity_name = entity_name + " " + Position[pos]
    print("\tEntity Name:", entity_name)

Output

Endpoint 3:
        Entity Name: 1 Top
Endpoint 4:
        Entity Name: 2 Middle
Endpoint 5:
        Entity Name: 3 Bottom
Endpoint 6:
        Entity Name: 4 Bottom Left

[jvmahon]

I had also considered how to handle tags, and their translations, once they come into use. I was thinking that this should start with a "generic all-purpose" tag translation function in the helpers.py file with a form like "decode_tag(tagList, namespace)" which accepts the tagList, and a semantic tag namespace ID number. The return value would be a list [str] of translated names for found tags within the namespace. This would work across any of the 17 namespaces.

There's a lot of tags and namespaces to include, but this should be conceptually simple to implemen[0xt in helpers.py and strings.json. Probably as a simple dictionary of dictionaries keyed by namespace then tag ID.

Anyway, I am not planning on implementing this now, but am providing this additional thought as you had tagged my current PR addressing labeling (after that current PR gets finished, maybe this gets revisited as a future enhancement?).

The handling of tags may also want to build on my current concept in PR 142396 where the discovery schema for particular entity types specifies a set of fixedLabel labels to look for. Similarly, here, the discovery schema might specify tags that apply to the particular entity type. E.g., for buttons there might be a discovery attribute "label_using_tag_namespaces = 0x07, 0x08".