How endpoint names work in a composed Matter device

[Luligu]

The Hass plugin reads the native devices from HA, converts them as best as possible to Matter respecting of course all the Matter specifications and publish them in Matter.

Then you can pair the published Matter device(s) to any controller supporting Matter.

To be more precise what we publish is an aggregator (a bridge) that inside has 1 child endpoint for any individual or split entity or device found in HA.

Each Matter device in Hass plugin (like all other plugins) can be a compound device (it has child endpoints too), a composed device (it has more then one device type and child endpoints too) or a simple device.

Simple when the device is simple and doesn't have overlapping device types or clusters. Think about an HA template switch that only has the switch and nothing else.

Compound when has child endpoint each of them with a device type (PowerSource for battery, 2 or more Lights, maybe a Motion sensor etc. etc.). Here comes the issue: Matter allows me to give a name to the child endpoints but the controllers don't support that so far. The naming strategy for the child endpoints is named tagList.

Composed when is complex so has more device types (PowerSource for battery, 2 or more Lights, maybe a Motion sensor etc. etc.). In this case the Matter device has child endpoints (our 2 Lights and whatever else). Here comes the issue: Matter allows me to give a name to the child endpoints but the controllers don't support so far. The naming strategy for the child endpoints is named tagList.

The plugin allows when the HA device is simple to avoid to use child endpoints (the name issue is a reason but there are others).

With the Merge strategy, I can put all together if I don't have 2 switches or 2 temperature and so on.

If I have 2 switches or 2 temperature, Matter doesn't allow this (disambiguation rule).

So if the final matter device is compound or composed and has 2 of more endpoint like a Switch then all the endpoint have the same name because the controller doesn't show the tagList in its UI.

If you have a temperature and a humidity with the same name no issue cause you understand what they are.

When you have 2 Switches or 2 Temperatures you cannot understand what is one and what is the other without the tagList.

Imagine an advanced Thermostat that has more then one reading for the temperature like Indoor and Outdoor and also the water temperature of the heat pump at the entry and at the exit from the circuit. All these 4 temperature are so far with the same name because the tagList is not shown in the controller UI. Very upsetting but it is in this way.

The device entities (when they overlap) in Matter are child endpoints (composed devices cause there is the disambiguation rule).

9.2.7. Disambiguation
Using the terms and composition patterns described above, some endpoints will have sibling endpoints
with an overlap in application device type(s). For this case, the Duplicate condition has been
defined (see the Base Device Type in the Device Library).
• A device type definition MAY define a method for disambiguation when the Duplicate condition
applies to either the endpoint with that device type or to its children.
• If no disambiguation method is defined in the relevant device type definitions, an endpoint to
which the Duplicate condition applies SHALL have a TagList attribute in its Descriptor cluster
and its set of tags SHALL be distinct from the set of tags of any sibling endpoint with which it
has an overlap in application device type(s). When comparing sets of tags, ordering of the list
SHALL be ignored.
• The TagList feature and attribute MAY also be used in other cases to provide guidance to a client
and/or a user.
• When the Duplicate condition applies, clients SHOULD disambiguate the relevant sibling endpoints
in their user interfaces and client logic using the method defined in the device type or the
TagList attribute values if no other method is defined.

So I can use the tagList and I do but the controllers doesn't show it yet.

This an example of Matter composed device taken from Matter specs:

The semantig tag (tagList) is what should give a name on the controller.

The controller should name the first cabinet Refrigerator and the second Fridge but it doesn't.

Split Entities

The Split Entity is the solution to the naming issue, waiting for the tagList to be shown in controllers UI. This approach is possible only with custom compound devices, the hard coded composed matter device types (like the Refrigerator in the screenshot) cannot be split!

What you can do today (releases from 0.4.0) to solve the naming issue.

We use this example case: you have a plug (named "Guest room Roomba plug") with 2 Switches where the first is the Power and the second is the Child lock.

You have some possible solution to this:

• rename on the controller (Alexa in this case) the "First plug" to "Guest room Roomba plug" and the "Second plug" to "Guest room Roomba plug Child lock". In this way, the plug device will still be composed but it will not have any duplicated Switches names.

• add to the deviceEntityBlackList the entity of the Child lock if you don't need it. In this way, the plug device will not be anymore composed and will not have any duplicated Switches names.

• if you need also the Child lock, add to the splitEntities the entity of the Child lock and restart. In this way, the plug device will not be anymore composed and will not have any duplicated Switches names and you can control also the Child lock. If you use the whiteList, select your switch.computer_plug_child_lock (will show up with the entity name "Computer plug Child lock") and restart. This is the best option available from release 0.4.0.