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-22 16:56:50 +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: The discovery topic need to follow a specific format:
```text ```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`. - `<component>`: One of the supported MQTT components, eg. `binary_sensor`.
- `<node_id>` (*Optional*): ID of the node providing the topic. - `<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`. - `<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. 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 %} ### {% 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` - Configuration topic: `homeassistant/binary_sensor/garden/config`
- State topic: `homeassistant/binary_sensor/garden/state` - 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/). To create a new sensor manually. For more details please refer to the [MQTT testing section](/docs/mqtt/testing/).
```bash ```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. 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` - Configuration topic: `homeassistant/switch/irrigation/config`
- State topic: `homeassistant/switch/irrigation/state` - 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 ```bash
$ mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/switch/irrigation/config" \ $ 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. Set the state.