update MQTT docs to include discover_ip option (#3809)

Co-authored-by: Keith Burzinski <kbx81x@gmail.com>

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/<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

guides/cli.rst

@@ -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