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-09 18:36:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add switch example and list of supported devices (#2312)

Browse Source
This commit is contained in:
Fabian Affolter 2017-03-26 15:49:21 +02:00 committed by GitHub
parent 3e06754c14
commit f45ea8261d
1 changed files with 28 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -11,7 +11,15 @@ logo: mqtt.png
redirect_from: /components/mqtt/#discovery
---
The discovery of MQTT devices will enable one to use MQTT devices with only minimal configuration effort on the side of Home Assistant. The configuration is done on the device itself and the topic used by the device. Similar to the [HTTP binary sensor](/components/binary_sensor.http/) and the [HTTP sensor](/components/sensor.http/). Currently, binary sensors, lights and sensors are supported. A discovery binary sensor or sensor will load the `mqtt` platform. For discovered light components the JSON payload can contain a `platform` attribute with one of `mqtt`, `mqtt_json` or `mqtt_template` defined. If no `platform` attribute is defined then `mqtt` is used.
The discovery of MQTT devices will enable one to use MQTT devices with only minimal configuration effort on the side of Home Assistant. The configuration is done on the device itself and the topic used by the device. Similar to the [HTTP binary sensor](/components/binary_sensor.http/) and the [HTTP sensor](/components/sensor.http/).
Supported by MQTT discovery:
- [Binary sensors](/components/binary_sensor.mqtt/)
- [Lights](/components/light.mqtt/)
- [Sensors](/components/sensor.mqtt/)
- [Switches](/components/switch.mqtt/)
To enable MQTT discovery, add the following to your `configuration.yaml` file:
@ -34,13 +42,13 @@ The discovery topic need to follow a specific format:
- `<component>`: One of the supported components, eg. `binary_sensor`.
- `<object_id>`: The ID of the device. This will become the `entity_id` in Home Assistant.
- `<config>`: The topic `config` or `state` which defines the current action.
- `<>`: 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.
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`.
### {% linkable_title Example %}
### {% 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 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.
- Configuration topic: `homeassistant/binary_sensor/garden/config`
- State topic: `homeassistant/binary_sensor/garden/state`
@ -57,3 +65,18 @@ Update the state.
$ mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/state" -m ON
```
Setting up a switch is similar but requires a `command_topic` as mentionend in the [MQTT switch documentation](/components/switch.mqtt/).
- Configuration topic: `homeassistant/switch/irrigation/config`
- State topic: `homeassistant/switch/irrigation/state`
- Payload: `{"name": "garden", "command_topic": "homeassistant/switch/irrigation/set"}`
```bash
$ mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/switch/irrigation/config" \
-m '{"name": "garden", "command_topic": "homeassistant/switch/irrigation/set"}'
```
Set the state.
```bash
$ mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/switch/irrigation/set" -m ON
```