diff --git a/components/mqtt.rst b/components/mqtt.rst index c255d8ef2..6ec0cd291 100644 --- a/components/mqtt.rst +++ b/components/mqtt.rst @@ -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/`` + +The response will be sent to ``esphome/discover/`` 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: "" + + 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 `__) and point both your @@ -377,16 +462,16 @@ Configuration variables: - **state_topic** (*Optional*, string): The topic to publish state updates to. Defaults to ``///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 ``///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``. diff --git a/guides/cli.rst b/guides/cli.rst index 68e600eb2..37910334c 100644 --- a/guides/cli.rst +++ b/guides/cli.rst @@ -140,7 +140,7 @@ The ``esphome upload `` validates the configuration and uploads the most .. program:: esphome clean-mqtt The ``esphome clean-mqtt `` 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