From fa9dd13b4f441b90c34a201a84ed80007babcd76 Mon Sep 17 00:00:00 2001
From: Erik Montnemery <erik@montnemery.com>
Date: Fri, 3 Apr 2020 11:58:11 +0200
Subject: [PATCH] =?UTF-8?q?Improve=20docs=20for=20MQTT=20state=20vacuum=20?=
 =?UTF-8?q?state=5Ftopic=20and=20value=5Ftempl=E2=80=A6=20(#12638)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Improve docs for MQTT state vacuum state_topic and value_template.

* Update vacuum.mqtt.markdown

* Update vacuum.mqtt.markdown

* Update vacuum.mqtt.markdown
---
 source/_integrations/vacuum.mqtt.markdown | 24 +++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/source/_integrations/vacuum.mqtt.markdown b/source/_integrations/vacuum.mqtt.markdown
index a3417ae0069..70d2b6f83e5 100644
--- a/source/_integrations/vacuum.mqtt.markdown
+++ b/source/_integrations/vacuum.mqtt.markdown
@@ -220,11 +220,12 @@ vacuum:
 ```
 {% endraw %}
 
-## Legacy MQTT Protocol
+### Legacy MQTT Protocol
 
 The above configuration for this integration expects an MQTT protocol like the following.
+See also [Shared MQTT Protocol](#shared-mqtt-protocol).
 
-### Legacy Basic Commands
+#### Legacy Basic Commands
 
 MQTT topic: `vacuum/command`
 
@@ -238,7 +239,7 @@ Possible MQTT payloads:
 - `locate` - Locate the vacuum (typically by playing a song)
 - `start_pause` - Toggle the vacuum between cleaning and stopping
 
-### Status/Sensor Updates
+#### Status/Sensor Updates
 
 MQTT topic: `vacuum/state`
 
@@ -349,7 +350,7 @@ set_fan_speed_topic:
   required: false
   type: string
 state_topic:
-  description: The MQTT topic subscribed to receive state messages from the vacuum. State topic is extracting JSON if no `value_template` is defined.
+  description: "The MQTT topic subscribed to receive state messages from the vacuum. Messages received on the `state_topic` must be a valid JSON dictionary, with a mandatory `state` key and optionally `battery_level` and `fan_speed` keys as shown in the [example](#state-mqtt-protocol)."
   required: false
   type: string
 supported_features:
@@ -357,10 +358,6 @@ supported_features:
   required: false
   type: [string, list]
   default: "`start`, `stop`, `return_home`, `status`, `battery`, `clean_spot`"
-value_template:
-  description: "Defines a [template](/topics/templating/) to extract possible states from the vacuum."
-  required: false
-  type: string
 {% endconfiguration %}
 
 ### State configuration example
@@ -395,11 +392,12 @@ vacuum:
 ```
 {% endraw %}
 
-## State MQTT Protocol
+### State MQTT Protocol
 
 The above configuration for this integration expects an MQTT protocol like the following.
+See also [Shared MQTT Protocol](#shared-mqtt-protocol).
 
-### State Basic Commands
+#### State Basic Commands
 
 MQTT topic: `vacuum/command`
 
@@ -412,7 +410,7 @@ Possible MQTT payloads:
 - `clean_spot` - Initialize a spot cleaning cycle
 - `locate` - Locate the vacuum (typically by playing a song)
 
-### Send Custom Command
+#### Send Custom Command
 
 Vacuum send_command allows three parameters:
 
@@ -448,7 +446,7 @@ Service trigger example:
 
 MQTT topic: `vacuum/send_command`
 
-### Status/Sensor Updates
+#### Status/Sensor Updates
 
 MQTT topic: `vacuum/state`
 
@@ -523,6 +521,8 @@ Service trigger example:
 
 MQTT topic: `vacuum/send_command`
 
+## Usage examples
+
 ### Usage with cloudless Xiaomi vacuums
 
 This integration is supported by the cloud-free Xiaomi Vacuum Webinterface [Valetudo](https://github.com/Hypfer/Valetudo).