Make state_topic optional for MQTT device_tracker and improve examples (#27482)

* Make state_topic optional for MQTT device_tracker

* Update source/_integrations/device_tracker.mqtt.markdown

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>

* Update source/_integrations/device_tracker.mqtt.markdown

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>

* Improve formatting

---------

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
This commit is contained in:
Jan Bouwhuis 2023-05-24 13:56:53 +02:00 committed by GitHub
parent 75f224451d
commit a739d844cc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -118,7 +118,14 @@ json_attributes_template:
required: false
type: template
json_attributes_topic:
description: The MQTT topic subscribed to receive a JSON dictionary payload and then set as device_tracker attributes. Usage example can be found in [MQTT sensor](/integrations/sensor.mqtt/#json-attributes-topic-configuration) documentation.
description: "The MQTT topic subscribed to receive a JSON dictionary message containing device tracker attributes.
This topic can be used to set the location of the device tracker under the following conditions:
* If the attributes in the JSON message include `longitude`, `latitude`, and `gps_accuracy` (optional).\n
* If the device tracker is within a configured [zone](/integrations/zone/).\n
If these conditions are met, it is not required to configure `state_topic`.\n\n
Be aware that any location message received at `state_topic` overrides the location received via `json_attributes_topic` until a message configured with `payload_reset` is received at `state_topic`. For a more generic usage example of the `json_attributes_topic`, refer to the [MQTT sensor](/integrations/sensor.mqtt/#json-attributes-topic-configuration) documentation."
required: false
type: string
name:
@ -164,8 +171,8 @@ source_type:
required: false
type: string
state_topic:
description: The MQTT topic subscribed to receive device tracker state changes.
required: true
description: The MQTT topic subscribed to receive device tracker state changes. The states defined in `state_topic` override the location states defined by the `json_attributes_topic`. This state override is turned inactive if the `state_topic` receives a message containing `payload_reset`. The `state_topic` can only be omitted if `json_attributes_topic` is used.
required: false
type: string
unique_id:
description: "An ID that uniquely identifies this device_tracker. If two device_trackers have the same unique ID, Home Assistant will raise an exception."
@ -208,6 +215,8 @@ If the device supports GPS coordinates then they can be sent to Home Assistant b
- Attributes topic: `a4567d663eaf/attributes`
- Example attributes payload:
Example message to be received at topic `a4567d663eaf/attributes`:
```json
{
"latitude": 32.87336,
@ -219,9 +228,15 @@ If the device supports GPS coordinates then they can be sent to Home Assistant b
To create the device_tracker with GPS coordinates support:
```bash
mosquitto_pub -h 127.0.0.1 -t homeassistant/device_tracker/a4567d663eaf/config -m '{"state_topic": "a4567d663eaf/state", "name": "My Tracker", "payload_home": "home", "payload_not_home": "not_home", "json_attributes_topic": "a4567d663eaf/attributes"}'
mosquitto_pub -h 127.0.0.1 -t homeassistant/device_tracker/a4567d663eaf/config -m '{"json_attributes_topic": "a4567d663eaf/attributes", "name": "My Tracker"}'
```
<div class='note info'>
Using `state_topic` is optional when using `json_attributes_topic` to determine the state of the device tracker.
</div>
To set the state of the device tracker to specific coordinates:
```bash