From 2b2866765265336794266e50f57249b4b48e5169 Mon Sep 17 00:00:00 2001
From: Fabian Affolter <mail@fabian-affolter.ch>
Date: Tue, 7 Feb 2017 19:13:16 +0100
Subject: [PATCH] Add MQTT discovery (#1952)

* Add MQTT discovery

* Update configuration
---
 source/_components/mqtt.markdown | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/source/_components/mqtt.markdown b/source/_components/mqtt.markdown
index 1a0e649b816..f0d6cdb249f 100644
--- a/source/_components/mqtt.markdown
+++ b/source/_components/mqtt.markdown
@@ -29,6 +29,7 @@ mqtt:
   password: PASSWORD
   certificate: /home/paulus/dev/addtrustexternalcaroot.crt
   protocol: 3.1
+  discovery: "discovery/#"
   birth_message:
     topic: 'hass/status'
     payload: 'online'
@@ -53,6 +54,7 @@ Configuration variables:
 - **client_key** (*Optional*): Client key (example: `/home/user/owntracks/cookie.key`)
 - **client_cert** (*Optional*): Client certificate (example: `/home/user/owntracks/cookie.crt`)
 - **protocol** (*Optional*): Protocol to use: 3.1 or 3.1.1. By default it connects with 3.1.1 and falls back to 3.1 if server does not support 3.1.
+- **discovery** (*Optional*): The MQTT topic subscribed to use for discovery of MQTT devices.
 - **birth_message** (*Optional*):
   - **topic** (*Required*): The MQTT topic to publish the message.
   - **payload** (*Required*): The message content.
@@ -183,7 +185,7 @@ Home Assistant will automatically load the correct certificate if you connect to
 
  - Integrating it into own component. See the [MQTT example component](/cookbook/python_component_mqtt_basic/) how to do this.
 
-### {% linkable_title Publish service %}
+## {% linkable_title Publish service %}
 
 The MQTT component will register the service `publish` which allows publishing messages to MQTT topics. There are two ways of specifying your payload. You can either use `payload` to hard-code a payload or use `payload_template` to specify a [template](/topics/templating/) that will be rendered to generate the payload.
 
@@ -201,7 +203,23 @@ The MQTT component will register the service `publish` which allows publishing m
 }
 ```
 
-### {% linkable_title Logging %}
+## {% linkable_title Discovery %}
+
+The discovery of MQTT devices will enable one to use MQTT devices with only minimal configuration effort on the side of Home Assistant. The configuration is done on the device itself and the topic used by the device. Similar to the [HTTP binary sensor](/components/binary_sensor.http/) and the [HTTP sensor](/components/sensor.http/). Only support for binary sensor is available at the moment.
+
+To enable MQTT discovery, add the following to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+mqtt:
+  discovery: true
+  # Optional
+  discovery_prefix: homeassistant
+```
+
+A motion detection device for your garden would sent its configuration as JSON payload `{"name": "garden", "sensor_class": "motion"}` to the topic `homeassistant/binary_sensor/garden/config`. After the first message to `config`, then the MQTT messages sent to `state`, eg. `homeassistant/binary_sensor/garden/state`, will update the state in Home Assistant.
+
+## {% linkable_title Logging %}
 
 The [logger](/components/logger/) component allow the logging of received MQTT messages.