Improve docs for MQTT state vacuum state_topic and value_templ… (#12638)

* Improve docs for MQTT state vacuum state_topic and value_template.

* Update vacuum.mqtt.markdown

* Update vacuum.mqtt.markdown

* Update vacuum.mqtt.markdown
This commit is contained in:
Erik Montnemery 2020-04-03 11:58:11 +02:00 committed by GitHub
parent 8ff49f184b
commit fa9dd13b4f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

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