From 3ad95910db4ebfedbd09a4f1aedfadd99f186af2 Mon Sep 17 00:00:00 2001 From: Jan Bouwhuis Date: Mon, 30 May 2022 09:57:45 +0200 Subject: [PATCH] Move MQTT device_tracker manual config (#22887) --- .../device_tracker.mqtt.markdown | 87 ++++++++++++------- 1 file changed, 54 insertions(+), 33 deletions(-) diff --git a/source/_integrations/device_tracker.mqtt.markdown b/source/_integrations/device_tracker.mqtt.markdown index 2b5ee9b422a..6ef5bb47ccf 100644 --- a/source/_integrations/device_tracker.mqtt.markdown +++ b/source/_integrations/device_tracker.mqtt.markdown @@ -9,14 +9,32 @@ ha_domain: mqtt --- -The `mqtt` device tracker platform allows you to define new device_trackers through [manual YAML configuration](#yaml-configuration) in `configuration.yaml` and also to automatically discover device_trackers through a [discovery schema](#discovery-schema) using the MQTT Discovery protocol. +The `mqtt` device tracker platform allows you to define new device_trackers through [manual YAML configuration](#yaml-configuration) in `configuration.yaml` and also to automatically discover device_trackers [using the MQTT Discovery protocol](#using-the-discovery-protocol). -## YAML Configuration +## Configuration To use this device tracker in your installation, add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry +mqtt: + device_tracker: + - name: "annetherese_n4" + state_topic: "location/annetherese" + - name: "paulus_oneplus" + state_topic: "location/paulus" +``` + +{% details "Previous configuration format" %} + +The configuration format of manual configured MQTT items has changed. +The old format that places configurations under the `switch` platform key +should no longer be used and is deprecated. + +The above example shows the new and modern way, +this is the previous/old example and deprecated configuration schema: + +```yaml device_tracker: - platform: mqtt devices: @@ -24,6 +42,15 @@ device_tracker: annetherese_n4: "location/annetherese" ``` +To set the state of the device_tracker then you need to publish a JSON message to the topic (e.g., via mqtt.publish service). As an example, the following JSON message would set the `paulus_oneplus` device_tracker to `home`: + +```json +{ + "topic": "location/paulus", + "payload": "home" +} +``` + {% configuration %} devices: description: List of devices with their topic. @@ -49,35 +76,7 @@ source_type: type: string {% endconfiguration %} -## Complete YAML example configuration - -```yaml -# Complete configuration.yaml entry -device_tracker: - - platform: mqtt - devices: - paulus_oneplus: "location/paulus" - annetherese_n4: "location/annetherese" - qos: 1 - payload_home: "present" - payload_not_home: "not present" - source_type: bluetooth -``` - -## YAML Usage - -To set the state of the device_tracker then you need to publish a JSON message to the topic (e.g., via mqtt.publish service). As an example, the following JSON message would set the `paulus_oneplus` device_tracker to `home`: - -```json -{ - "topic": "location/paulus", - "payload": "present" -} -``` - -## Discovery Schema - -MQTT device_trackers are also supported through [MQTT discovery](/docs/mqtt/discovery/). This is different to the YAML configuration from above. Here, the device_tracker can be created via a discovery topic that follows the following topic name convention: `/device_tracker/[/]/config` and the JSON message content of a specific format as defined below. +{% enddetails %} {% configuration %} availability: @@ -220,9 +219,13 @@ value_template: type: template {% endconfiguration %} -## Discovery Example +## Examples -You can use the discovery protocol to create a new device tracker and set its state using the command line tool `mosquitto_pub` shipped with `mosquitto` or the `mosquitto-clients` package to send MQTT messages. +### Using the discovery protocol + +The device_tracker can be created via a discovery topic that follows the following topic name convention: `/device_tracker/[/]/config`. + +You can use the command line tool `mosquitto_pub` shipped with `mosquitto` or the `mosquitto-clients` package to send MQTT messages. To create the device_tracker: @@ -235,3 +238,21 @@ To set the state of the device tracker to "home": ```bash mosquitto_pub -h 127.0.0.1 -t a4567d663eaf/state -m 'home' ``` + +### YAML configuration + +The following example shows how to configure the same device tracker through configuration.yaml + +{% raw %} + +```yaml +# Example configuration.yaml entry +mqtt: + device_tracker: + - name: "My Tracker" + state_topic: "a4567d663eaf/state" + payload_home: "home" + payload_not_home: "not_home" +``` + +{% endraw %}