From 3ad95910db4ebfedbd09a4f1aedfadd99f186af2 Mon Sep 17 00:00:00 2001
From: Jan Bouwhuis <jbouwh@users.noreply.github.com>
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: `<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 %}