From f0566c7a68a32dd0d3be9cf8177e50b209c5a6f4 Mon Sep 17 00:00:00 2001
From: kahrendt <kahrendt@gmail.com>
Date: Sun, 5 Nov 2023 20:19:06 -0500
Subject: [PATCH] Document null MQTT topic behavior (#3316)

---
 components/mqtt.rst | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/components/mqtt.rst b/components/mqtt.rst
index 4412fbc94..d1d901eef 100644
--- a/components/mqtt.rst
+++ b/components/mqtt.rst
@@ -60,8 +60,9 @@ Configuration variables:
   `Abbreviations <https://www.home-assistant.io/docs/mqtt/discovery/>`__
   in discovery messages. Defaults to ``true``.
 - **topic_prefix** (*Optional*, string): The prefix used for all MQTT
-  messages. Should not contain trailing slash. Defaults to
-  ``<APP_NAME>``.
+  messages. Should not contain trailing slash. Defaults to ``<APP_NAME>``. 
+  Use ``null`` to disable publishing or subscribing of any MQTT topic unless
+  it is explicitly configured.
 - **log_topic** (*Optional*, :ref:`mqtt-message`): The topic to send MQTT log
   messages to. Use ``null`` if you want to disable sending logs to MQTT.
 
@@ -373,9 +374,17 @@ 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 
+   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 
+   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``.