What is the purpose if uniq_id and name for device types?

[klausj1]

Environment

Used library version: 2.0 Board: Arduino Mega

Summary

The HA uses the name of the HASensor as entity ID, not the uniq_id, which is provided in the constructor of the device. When you change the name of the HASensor with setName, you are confused afterwards (at least I was) .

Maybe related to #183, not sure.

Details

Define one sensor like this:

HASensorNumber var0("construct0", HASensorNumber::PrecisionP2);
var0.setName="var0 friendly name";

This is the result in the broker:

{"name":"var0 friendly name","uniq_id":"construct0","ic":"mdi:home","unit_of_meas":"V","dev":{"ids":"ESP32_GasMonitoring","name":"Gas Monitoring","sw":"1.0.0","mf":"Klaus","mdl":"ESP32C3"},"avty_t":"aha/ESP32_GasMonitoring/avty_t","stat_t":"aha/ESP32_GasMonitoring/construct0/stat_t"}

The string provided in the constructor (the uniq_id) is the ID in MQTT

And this is the result in HA:

The name defined with setName is used as entity ID (plus the device)

I do not understand this behaviour. The entity name should be construct0 in this case. When I now change the setName to "yet another friendly name", this is what I get:

As expected in the broker:

{"name":"yet another friendly name","uniq_id":"construct0","ic":"mdi:home","unit_of_meas":"V","dev":{"ids":"ESP32_GasMonitoring","name":"Gas Monitoring","sw":"1.0.0","mf":"Klaus","mdl":"ESP32C3"},"avty_t":"aha/ESP32_GasMonitoring/avty_t","stat_t":"aha/ESP32_GasMonitoring/construct0/stat_t"}

And in HA:

Thats not so good, because now I have an entity ID in HA which us not even used in the current code.

Now, change "construct0" to "newconstruct0".

The broker now has two topics, construct0 and newconstruct0. Thats whats expected:

{"name":"yet another friendly name","uniq_id":"construct0","ic":"mdi:home","unit_of_meas":"V","dev":{"ids":"ESP32_GasMonitoring","name":"Gas Monitoring","sw":"1.0.0","mf":"Klaus","mdl":"ESP32C3"},"avty_t":"aha/ESP32_GasMonitoring/avty_t","stat_t":"aha/ESP32_GasMonitoring/construct0/stat_t"}
{"name":"yet another friendly name","uniq_id":"newconstruct0","ic":"mdi:home","unit_of_meas":"V","dev":{"ids":"ESP32_GasMonitoring","name":"Gas Monitoring","sw":"1.0.0","mf":"Klaus","mdl":"ESP32C3"},"avty_t":"aha/ESP32_GasMonitoring/avty_t","stat_t":"aha/ESP32_GasMonitoring/newconstruct0/stat_t"}

Also in HA there are now two entities (please notice that only yet the change of the setName to "yet another friendly name" has an effect on the entity ID in HA):

I would prefer it the uniq_id is used as a base for the entity ID, and the name is a kind of description which can change all the time. In the current solution I do not understand why I need the uniq_id and the name the uniq_id alone would be enough.

I do not know if this is even possible with the MQTT integration. If not, as said, I propose to deprecate the setName-method. In any case, it would be great to have this effect documented.

It would also be nice to have a link in the documentation how to remove obsolete entities in HA (see here.

And thanks a lot for your work, the integration of the library worked like a charm!

[dawidchyrzynski]

@klausj1 The uniq_id serves as an internal identifier for the entity within the HA) instance. Once the entity with a specific uniq_id is created, it cannot be altered, as this identifier is not accessible through the user interface. Home Assistant utilizes this identifier internally to store the parameters of the entity in the database. Given that the uniq_id must be unique across the entire HA instance, multiple devices cannot expose entities with "construct0" as unique ID.

The entity ID is utilized by dashboards and automations and must compatible with YAML format, meaning it should not include any special characters, spaces, etc. Think of it as a variable name. When the entity is created in HA for the very first time, the name field is automatically used to generate the entity ID. However, once created, you can modify it to your preference via the HA UI. HA internally references the entity using its unique ID. Therefore, altering the entity ID or friendly name does not break the integration between the device and the HA instance (via MQTT).

https://www.home-assistant.io/faq/unique_id/

[klausj1]

Thanks for the explanation, now I can understand this. Still, it would be great if you could add this to the documentation.

[dawidchyrzynski]

I will add it in the coming version of the lib.

[dawidchyrzynski]

Hi @klausj1, please let me if this documentation provides adequate information:

[klausj1]

Looks great, thank you!