From 5a600d7ec0111d6a4b8f992bcd48ea4d4ebc4e2a Mon Sep 17 00:00:00 2001
From: Jan Bouwhuis <jbouwh@users.noreply.github.com>
Date: Mon, 23 May 2022 14:31:58 +0200
Subject: [PATCH] MQTT switch config to integration key (#22837)

---
 source/_integrations/switch.mqtt.markdown | 63 +++++++++++++++--------
 1 file changed, 41 insertions(+), 22 deletions(-)

diff --git a/source/_integrations/switch.mqtt.markdown b/source/_integrations/switch.mqtt.markdown
index 974611ae327..90c03efbc15 100644
--- a/source/_integrations/switch.mqtt.markdown
+++ b/source/_integrations/switch.mqtt.markdown
@@ -22,11 +22,30 @@ To enable this switch in your installation, add the following to your `configura
 
 ```yaml
 # Example configuration.yaml entry
+mqtt:
+  switch:
+    - command_topic: "home/bedroom/switch1/set"
+```
+
+<a id='new_format'></a>
+
+{% 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:
+
+```yaml
 switch:
   - platform: mqtt
     command_topic: "home/bedroom/switch1/set"
 ```
 
+{% enddetails %}
+
 {% configuration %}
 availability:
   description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
@@ -225,21 +244,21 @@ The example below shows a full configuration for a switch.
 
 ```yaml
 # Example configuration.yaml entry
-switch:
-  - platform: mqtt
-    unique_id: bedroom_switch
-    name: "Bedroom Switch"
-    state_topic: "home/bedroom/switch1"
-    command_topic: "home/bedroom/switch1/set"
-    availability:
-      - topic: "home/bedroom/switch1/available"
-    payload_on: "ON"
-    payload_off: "OFF"
-    state_on: "ON"
-    state_off: "OFF"
-    optimistic: false
-    qos: 0
-    retain: true
+mqtt:
+  switch:
+    - unique_id: bedroom_switch
+      name: "Bedroom Switch"
+      state_topic: "home/bedroom/switch1"
+      command_topic: "home/bedroom/switch1/set"
+      availability:
+        - topic: "home/bedroom/switch1/available"
+      payload_on: "ON"
+      payload_off: "OFF"
+      state_on: "ON"
+      state_off: "OFF"
+      optimistic: false
+      qos: 0
+      retain: true
 ```
 
 For a check, you can use the command line tools `mosquitto_pub` shipped with `mosquitto` to send MQTT messages. This allows you to operate your switch manually:
@@ -262,11 +281,11 @@ The configuration will look like the example below:
 
 ```yaml
 # Example configuration.yaml entry
-switch:
-  - platform: mqtt
-    name: bathroom
-    state_topic: "home/bathroom/gpio/13"
-    command_topic: "home/bathroom/gpio/13"
-    payload_on: "1"
-    payload_off: "0"
+mqtt:
+  switch:
+    - name: bathroom
+      state_topic: "home/bathroom/gpio/13"
+      command_topic: "home/bathroom/gpio/13"
+      payload_on: "1"
+      payload_off: "0"
 ```