From 07cf9a6474b0c185a5dd631b5b8457fed6f72bc5 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Fri, 10 May 2019 22:43:41 +0200 Subject: [PATCH] Update MQTT discovery examples (#9315) * Update discovery.markdown * Update discovery.markdown --- source/_docs/mqtt/discovery.markdown | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index 0be6a1714b5..573f64dd174 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -55,15 +55,16 @@ The [embedded MQTT broker](/docs/mqtt/broker#embedded-broker) does not save any The discovery topic need to follow a specific format: ```text -//[/]/<> +//[/]/config ``` -- ``: One of the supported components, eg. `binary_sensor`. -- `` (*Optional*): ID of the node providing the topic. +- ``: One of the supported MQTT components, eg. `binary_sensor`. +- `` (*Optional*): ID of the node providing the topic, this is not used by Home Assistant but may be used to structure the MQTT topic. - ``: The ID of the device. This is only to allow for separate topics for each device and is not used for the `entity_id`. -- `<>`: The topic `config` or `state` which defines the current action. -The payload will be checked like an entry in your `configuration.yaml` file if a new device is added. This means that missing variables will be filled with the platform's default values. All configuration variables which are *required* must be present in the initial payload send to `/config`. +The payload must be a JSON dictionary and will be checked like an entry in your `configuration.yaml` file if a new device is added. This means that missing variables will be filled with the platform's default values. All configuration variables which are *required* must be present in the initial payload send to `/config`. + +If the component is `alarm_control_panel`, `binary_sensor`, or `sensor` and the mandatory `state_topic` is not present in the payload, `state_topic` will be automatically set to //[/]/state. The automatic setting of `state_topic` id depracated and may be removed in a future version of Home Assistant. An empty payload will cause a previously discovered device to be deleted. @@ -222,16 +223,16 @@ The following software has built-in support for MQTT discovery: ### {% linkable_title Examples %} -A motion detection device which can be represented by a [binary sensor](/components/binary_sensor.mqtt/) for your garden would sent its configuration as JSON payload to the Configuration topic. After the first message to `config`, then the MQTT messages sent to the state topic will update the state in Home Assistant. +A motion detection device which can be represented by a [binary sensor](/components/binary_sensor.mqtt/) for your garden would send its configuration as JSON payload to the Configuration topic. After the first message to `config`, then the MQTT messages sent to the state topic will update the state in Home Assistant. - Configuration topic: `homeassistant/binary_sensor/garden/config` - State topic: `homeassistant/binary_sensor/garden/state` -- Payload: `{"name": "garden", "device_class": "motion"}` +- Payload: `{"name": "garden", "device_class": "motion", "state_topic": "homeassistant/binary_sensor/garden/state"}` To create a new sensor manually. For more details please refer to the [MQTT testing section](/docs/mqtt/testing/). ```bash -$ mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/config" -m '{"name": "garden", "device_class": "motion"}' +$ mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/config" -m '{"name": "garden", "device_class": "motion", "state_topic": "homeassistant/binary_sensor/garden/state"}' ``` Update the state. @@ -249,11 +250,12 @@ Setting up a switch is similar but requires a `command_topic` as mentioned in th - Configuration topic: `homeassistant/switch/irrigation/config` - State topic: `homeassistant/switch/irrigation/state` -- Payload: `{"name": "garden", "command_topic": "homeassistant/switch/irrigation/set"}` +- Command topic: `homeassistant/switch/irrigation/set` +- Payload: `{"name": "garden", "command_topic": "homeassistant/switch/irrigation/set", "state_topic": "homeassistant/switch/irrigation/state"}` ```bash $ mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/switch/irrigation/config" \ - -m '{"name": "garden", "command_topic": "homeassistant/switch/irrigation/set"}' + -m '{"name": "garden", "command_topic": "homeassistant/switch/irrigation/set", "state_topic": "homeassistant/switch/irrigation/state"}' ``` Set the state.