update MQTT docs to include discover_ip option (#3809)

Co-authored-by: Keith Burzinski <kbx81x@gmail.com>
This commit is contained in:
Markus 2024-07-21 23:36:50 +02:00 committed by GitHub
parent e4a7d00721
commit 48f030f6b4
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 96 additions and 11 deletions

View File

@ -41,7 +41,9 @@ Configuration variables:
authentication. Empty (the default) means no authentication.
- **client_id** (*Optional*, string): The client id to use for opening
connections. See :ref:`mqtt-defaults` for more information.
- **discovery** (*Optional*, boolean): If Home Assistant automatic
- **discover_ip** (*Optional*, boolean): If Home Assistant automatic device
discovery should be enabled. Defaults to ``true``.
- **discovery** (*Optional*, boolean): If Home Assistant automatic entity
discovery should be enabled. Defaults to ``true``.
- **discovery_retain** (*Optional*, boolean): Whether to retain MQTT
discovery messages so that entities are added automatically on Home
@ -137,10 +139,93 @@ Configuration options:
- **retain** (*Optional*, boolean): If the published message should
have a retain flag on or not. Defaults to ``true``.
.. _mqtt-using_with_home_assistant:
Using with Home Assistant
-------------------------
.. _mqtt-device_discovery:
MQTT device discovery
---------------------
The ESPHome device will respond to the following MQTT topics if ``mqtt.discover_ip`` is enabled.
- ``esphome/discover`` (All ESPHome device will answer)
- ``esphome/ping/<APP_NAME>``
The response will be sent to ``esphome/discover/<APP_NAME>`` and is a JSON encoded message.
The MQTT device discovery is currently used for:
- ESPHome dashboard (online / offline status)
- ESPHome CLI (IP discovery; used to view logs and perform OTA uploads)
- Home Assistant device discovery
Example Payload:
.. code-block:: json
{
"ip": "192.168.0.122",
"name": "esp32-test",
"friendly_name": "Test Device",
"port": 6053,
"version": "2024.4.1",
"mac": "84fce6123456",
"platform": "ESP32",
"board": "esp32-c3-devkitm-1",
"network": "wifi",
"api_encryption": "Noise_NNpsk0_25519_ChaChaPoly_SHA256"
}
JSON keys:
- **ip** (**Required**, ip): The IP address of the ESPHome device.
- **name** (**Required**, string): Name of the device (``esphome.name``).
- **mac** (**Required**, string): MAC address of the device.
- **board** (**Required**, string): Board used for the device.
- **version** (**Required**, string): ESPHome version.
- **port** (*Optional*, port): Port of the ESPHome API (if enabled).
- **ipX** (*Optional*, ip): Additional IP addresses (X is a number starting at 1).
- **friendly_name** (*Optional*, string): Friendly name of the device (``esphome.friendly_name``).
- **platform** (*Optional*, string): Platform of the device (e.g. ESP32 or ESP8266)
- **network** (*Optional*, string): Network type.
- **project_name** (*Optional*, string): ``esphome.project.name``.
- **project_version** (*Optional*, string): ``esphome.project.version``.
- **project_version** (*Optional*, string): ``dashboard_import.package_import_url``.
- **api_encryption** (*Optional*, string): API encryption type.
.. _mqtt-using_device_discovery_with_home_assistant:
Using device discovery with Home Assistant
------------------------------------------
MQTT can be used to automatically discover the ESPHome devices in Home Assistant.
This allows Home Assistant to find the ESPHome device and connect
to it via the ESPHome API which allows the usage
of more features then MQTT entity discovery alone (e.g. Bluetooth Proxy, Voice Assistant).
This can be achieved by enabling ``api`` and ``mqtt`` with ``mqtt.discover_ip`` enabled.
It may makes sense to disable ``mqtt.discovery`` since there will be no need to use the
MQTT entity discovery if Home Assistant will connect to the ESPHome API.
Example configuration:
.. code-block:: yaml
api:
encryption:
key: "<secret>"
mqtt:
broker: 10.0.0.2
username: livingroom
password: !secret mqtt_password
discovery: False # disable entity discovery
discover_ip: True # enable device discovery
.. _mqtt-using_with_home_assistant_entities:
Using with Home Assistant MQTT entities
---------------------------------------
Using ESPHome with Home Assistant is easy, simply setup an MQTT
broker (like `mosquitto <https://mosquitto.org/>`__) and point both your
@ -377,16 +462,16 @@ Configuration variables:
- **state_topic** (*Optional*, string): The topic to publish state
updates to. Defaults to
``<TOPIC_PREFIX>/<COMPONENT_TYPE>/<COMPONENT_NAME>/state``.
ESPHome will always publish a manually configured state topic, even if
the component is internal. Use ``null`` to disable publishing the
ESPHome will always publish a manually configured state topic, even if
the component is internal. Use ``null`` to disable publishing the
component's state.
- **command_topic** (*Optional*, string): The topic to subscribe to for
commands from the remote. Defaults to
``<TOPIC_PREFIX>/<COMPONENT_TYPE>/<COMPONENT_NAME>/command``.
ESPHome will always subscribe to a manually configured command topic,
even if the component is internal. Use ``null`` to disable subscribing
ESPHome will always subscribe to a manually configured command topic,
even if the component is internal. Use ``null`` to disable subscribing
to the component's command topic.
- **command_retain** (*Optional*, boolean): Whether MQTT command messages
sent to the device should be retained or not. Default to ``false``.

View File

@ -140,7 +140,7 @@ The ``esphome upload <CONFIG>`` validates the configuration and uploads the most
.. program:: esphome clean-mqtt
The ``esphome clean-mqtt <CONFIG>`` cleans retained MQTT discovery messages from the MQTT broker.
See :ref:`mqtt-using_with_home_assistant`.
See :ref:`mqtt-using_with_home_assistant_entities`.
.. option:: --topic TOPIC