From a739d844ccd4664eb60893f745bd0f7f0f9f39d1 Mon Sep 17 00:00:00 2001
From: Jan Bouwhuis <jbouwh@users.noreply.github.com>
Date: Wed, 24 May 2023 13:56:53 +0200
Subject: [PATCH] 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>
---
 .../device_tracker.mqtt.markdown              | 23 +++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/source/_integrations/device_tracker.mqtt.markdown b/source/_integrations/device_tracker.mqtt.markdown
index e4de2edc032..24e0a145026 100644
--- a/source/_integrations/device_tracker.mqtt.markdown
+++ b/source/_integrations/device_tracker.mqtt.markdown
@@ -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