From a358c6e3e8bc9aa7543ab70582cbda1c64cd0d3b Mon Sep 17 00:00:00 2001
From: Otto Winter <otto@otto-winter.com>
Date: Thu, 7 Jun 2018 23:01:07 +0200
Subject: [PATCH] Add MQTT discovery note

---
 esphomeyaml/components/mqtt.rst | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/esphomeyaml/components/mqtt.rst b/esphomeyaml/components/mqtt.rst
index 3162fcaad..f57ddc676 100644
--- a/esphomeyaml/components/mqtt.rst
+++ b/esphomeyaml/components/mqtt.rst
@@ -150,7 +150,7 @@ Last Will And Birth Messages
 
 esphomelib (and esphomeyaml) uses the `last will
 testament <https://www.hivemq.com/blog/mqtt-essentials-part-9-last-will-and-testament>`__
-and birth message feature of MQTT to achieve availabilty reporting for
+and birth message feature of MQTT to achieve availability reporting for
 Home Assistant. If the node is not connected to MQTT, Home Assistant
 will show all its entities as unavailable (a feature 😉).
 
@@ -181,7 +181,7 @@ You can change these messages by overriding the ``birth_message`` and
 - **will_message** (*Optional*, :ref:`mqtt-message`)
 
 If the birth message and last will message have empty topics or topics
-that are different from each other, availabilty reporting will be
+that are different from each other, availability reporting will be
 disabled.
 
 .. _mqtt-ssl_fingerprints:
@@ -226,7 +226,7 @@ MQTT can have some overrides for specific options.
     # Optional variables:
     retain: True
     discovery: True
-    availabilty:
+    availability:
       topic: livingroom/status
       payload_available: online
       payload_not_available: offline
@@ -241,8 +241,8 @@ Configuration variables:
    be retained. Defaults to ``True``.
 -  **discovery** (*Optional*, boolean): Manually enable/disable
    discovery for a component. Defaults to the global default.
--  **availabilty** (*Optional*): Manually set what should be sent to
-   Home Assistant for showing entity availabilty. Default derived from
+-  **availability** (*Optional*): Manually set what should be sent to
+   Home Assistant for showing entity availability. Default derived from
    :ref:`global birth/last will message <mqtt-last_will_birth>`.
 -  **state_topic** (*Optional*, string): The topic to publish state
    updates to. Defaults to
@@ -251,6 +251,11 @@ Configuration variables:
    commands from the remote. Defaults to
    ``<TOPIC_PREFIX>/<COMPONENT_TYPE>/<COMPONENT_NAME>/command``.
 
+.. warning::
+
+    When changing these options and you're using MQTT discovery, you will need to restart Home Assistant.
+    This is because Home Assistant only discovers a device once in every Home Assistant start.
+
 .. _mqtt-on_message:
 
 on_message