jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-21 00:06:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update MQTT discovery examples (#9315)

Browse Source 
* Update discovery.markdown

* Update discovery.markdown
This commit is contained in:
Erik Montnemery 2019-05-10 22:43:41 +02:00 committed by Fabian Affolter
parent 42e26897b9
commit 07cf9a6474
1 changed files with 12 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
source/_docs/mqtt/discovery.markdown
View File

@ -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
<discovery_prefix>/<component>/[<node_id>/]<object_id>/<>
<discovery_prefix>/<component>/[<node_id>/]<object_id>/config
```
- `<component>`: One of the supported components, eg. `binary_sensor`.
- `<node_id>` (*Optional*): ID of the node providing the topic.
- `<component>`: One of the supported MQTT components, eg. `binary_sensor`.
- `<node_id>` (*Optional*): ID of the node providing the topic, this is not used by Home Assistant but may be used to structure the MQTT topic.
- `<object_id>`: 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 <discovery_prefix>/<component>/[<node_id>/]<object_id>/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.