Move MQTT device_tracker manual config (#22887)

This commit is contained in:
Jan Bouwhuis 2022-05-30 09:57:45 +02:00 committed by Franck Nijhof
parent d9e227fec5
commit 3ad95910db
No known key found for this signature in database
GPG Key ID: D62583BA8AB11CA3

View File

@ -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: `<discovery_prefix>/device_tracker/[<node_id>/]<object_id>/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: `<discovery_prefix>/device_tracker/[<node_id>/]<object_id>/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 %}