mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-15 21:36:52 +00:00
Move MQTT device_tracker manual config (#22887)
This commit is contained in:
parent
d9e227fec5
commit
3ad95910db
@ -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 %}
|
||||
|
Loading…
x
Reference in New Issue
Block a user