From 81402ce154d7ac2451392fbfaf6a0a87d3746640 Mon Sep 17 00:00:00 2001 From: Jan Bouwhuis Date: Mon, 13 Nov 2023 10:37:22 +0100 Subject: [PATCH] Explain how to use MQTT discovery messages (#29701) * Explain how to use MQTT discovery messages * Minor tweaks Co-authored-by: Jan Bouwhuis * tiny tweak --------- Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> --- source/_integrations/mqtt.markdown | 96 ++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) diff --git a/source/_integrations/mqtt.markdown b/source/_integrations/mqtt.markdown index 54a3654d3f8..befa36758c2 100644 --- a/source/_integrations/mqtt.markdown +++ b/source/_integrations/mqtt.markdown @@ -578,6 +578,102 @@ support_url: ``` {% enddetails %} +### How to use discovery messages + +When MQTT discovery is set up, and a device or service sends a discovery message, +an MQTT entity, tag, or device automation will be set up directly after receiving the message. +When Home Assistant is restarting, discovered MQTT items with a unique ID will be unavailable until a new +discovery message is received. MQTT items without a unique ID will not be added at startup. +So a device or service using MQTT discovery must make sure a configuration message is offered +after the **MQTT** integration has been (re)started. There are 2 common approaches to make sure the +discovered items are set up at startup: + +1. Using Birth and Will messages to trigger setup +2. Using retained messages + +Finally, it is a best practice to publish your device or service availability status. + +#### Use the Birth and Will messages to trigger discovery + +When the **MQTT** integration starts, a birth message is published at `homeassistant/status` by default. +A device or service connected to the shared `mqtt` broker can subscribe to this topic and use an `online` message +to trigger discovery messages. See also the [birth and last will messages](/integrations/mqtt/#birth-and-last-will-messages) +section. After the configs have been published, the state topics will need an update, so they need to be republished. + +#### Using retained config messages + +An alternative method for a device or service is to publish discovery messages with a `retain` flag. This will make sure +discovery messages are replayed when the **MQTT** integration connects to the broker. +After the configs have been published, the state topics will need an update. + +#### Using retained state messages + +State updates also need to be re-published after a config as been processed. +This can also be done by publishing `retained` messages. As soon as a config is received (or replayed from a retained message), +the setup will subscribe any state topics. If a retained message is available at a state topic, + this message will be replayed so that the state can be restored for this topic. + +
+ +A disadvantage of using retained messages is that these messages retain at the broker, +even when the device or service stops working. They are retained even after the system or broker has been restarted. +Retained messages can create ghost entities that keep coming back. +

+Especially when you have many entities, (unneeded) discovery messages can cause excessive system load. For this reason, use discovery messages with caution. + +
+ +### Using Availability topics + +A device or service can announce its availability by publishing a Birth message and set a Will message at the broker. +When the device or service loses connection to the broker, the broker will publish the Will message. +This allows the **MQTT** integration to make an entity unavailable. + +Platform specific availability settings are available for `mqtt` entity platforms only. + +{% details "Platform specific availability settings" %} + +{% configuration %} +availability: + description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`. + required: false + type: list + keys: + payload_available: + description: The payload that represents the available state. + required: false + type: string + default: online + payload_not_available: + description: The payload that represents the unavailable state. + required: false + type: string + default: offline + topic: + description: An MQTT topic subscribed to receive availability (online/offline) updates. + required: true + type: string + value_template: + description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract a device's availability from the `topic`. To determine the device's availability, the result of this template will be compared to `payload_available` and `payload_not_available`." + required: false + type: template +availability_topic: + description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`. + required: false + type: string +availability_mode: + description: When `availability` is configured, this controls the conditions needed to set the entity to `available`. Valid entries are `all`, `any`, and `latest`. If set to `all`, `payload_available` must be received on all configured availability topics before the entity is marked as online. If set to `any`, `payload_available` must be received on at least one configured availability topic before the entity is marked as online. If set to `latest`, the last `payload_available` or `payload_not_available` received on any configured availability topic controls the availability. + required: false + type: string + default: latest +availability_template: + description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract device's availability from the `availability_topic`. To determine the devices's availability result of this template will be compared to `payload_available` and `payload_not_available`." + required: false + type: template +{% endconfiguration %} + +{% enddetails %} + ### Support by third-party tools The following software has built-in support for MQTT discovery: