From 3d56720ef2b92fec428a942f357a17ba70faa1d8 Mon Sep 17 00:00:00 2001 From: Andrej Komelj <akomelj@gmail.com> Date: Tue, 8 Feb 2022 10:58:43 +0100 Subject: [PATCH] Describe MQTT discovery object_id generator (#1856) Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com> --- components/mqtt.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/components/mqtt.rst b/components/mqtt.rst index acb2852df..b7bd12c15 100644 --- a/components/mqtt.rst +++ b/components/mqtt.rst @@ -47,6 +47,9 @@ Configuration variables: to use. Can be one of ``legacy`` or ``mac``. Defaults to ``legacy``, which generates unique_id in format ``ESP<component_type><default_object_id>``. ``mac`` generator uses format ``<mac_address>-<component_type>-<fnv1_hash(friendly_name)>``. +- **discovery_object_id_generator** (*Optional*, string): The object_id generator + to use. Can be one of ``none`` or ``device_name``. Defaults to ``none`` which + does not generate object_id. ``device_name`` generator uses format ``<device_name>_<friendly_name>``. - **use_abbreviations** (*Optional*, boolean): Whether to use `Abbreviations <https://www.home-assistant.io/docs/mqtt/discovery/>`__ in discovery messages. Defaults to ``true``. @@ -160,6 +163,17 @@ This will remove all retained messages with the topic ``<DISCOVERY_PREFIX>/+/NODE_NAME/#``. If you want to purge on another topic, simply add ``--topic <your_topic>`` to the command. +Home Assistant generates entity names for all discovered devices based on entity type and +entity name (e.g. ``sensor.uptime``). Numeric suffixes are appended to entity names when +multiple devices use the same name for a sensor, making it harder to distinguish between +similar sensors on different devices. Home Assistant 2021.12 allows MQTT devices to change +this behaviour by specifying ``object_id`` discovery attribute which replaces the sensor +name part of the generated entity name. Setting ``discovery_object_id_generator: device_name`` +in ESPHome MQTT integration configuration will cause Home Assistant to include device name +in the generated entity names (e.g. ``sensor.uptime`` becomes ``sensor.<device name>_uptime``), +making it easier to distinguish the entities in various entity lists. + + .. _mqtt-defaults: Defaults