From 1c82960fb32028088944a419ac655c4a08d5b08b Mon Sep 17 00:00:00 2001
From: Alba Mendez <me@alba.sh>
Date: Fri, 19 Nov 2021 09:24:12 +0100
Subject: [PATCH] Document existing / new MQTT connection properties (#20353)

This change is related to home-assistant/core#59920.

Expand the manual configuration section a bit, to mention WebSockets support as well as the existing `protocol` property.

I've also tried to structure it more clearly and to be consistent with the quoting.
I know this is subjective, and there may be a style guide that I could have missed. Sorry if that's the case :(
---
 source/_integrations/mqtt.markdown | 32 ++++++++++++++++++++++++++----
 1 file changed, 28 insertions(+), 4 deletions(-)

diff --git a/source/_integrations/mqtt.markdown b/source/_integrations/mqtt.markdown
index 13aa74193d4..c8ca3721b55 100644
--- a/source/_integrations/mqtt.markdown
+++ b/source/_integrations/mqtt.markdown
@@ -30,6 +30,8 @@ MQTT (aka MQ Telemetry Transport) is a machine-to-machine or "Internet of Things
 
 Your first step to get MQTT and Home Assistant working is to choose a [broker](/docs/mqtt/broker).
 
+**Note:** If you use TLS or WebSocket, then manual configuration (see below) is currently the only option.
+
 {% include integrations/config_flow.md %}
 
 ## Manual configuration
@@ -41,10 +43,20 @@ To connect to your [own MQTT broker](/docs/mqtt/broker#run-your-own):
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  broker: IP_ADDRESS_BROKER
+  broker: "IP_ADDRESS_BROKER"
 ```
 
-Manual configuration is required when connecting to a broker over TLS.
+If your broker requires username / password authentication:
+
+```yaml
+# Example configuration.yaml entry
+mqtt:
+  broker: "IP_ADDRESS_BROKER"
+  username: "MQTT_USERNAME"
+  password: !secret MQTT_PASSWORD
+```
+
+If your broker uses TLS, specify `certificate: auto` or your own CA certificate:
 
 ```yaml
 # Example configuration.yaml entry
@@ -52,10 +64,22 @@ mqtt:
   certificate: "PATH_TO_CA.crt"
   broker: "IP_ADDRESS_BROKER"
   port: 8883
-  username: "MQTT_USERNAME"
-  password: !secret MQTT_PASSWORD
 ```
 
+If your broker uses MQTT over WebSocket, specify `transport: websockets` and optionally `ws_path` and `ws_headers` to control the handshake:
+
+```yaml
+# Example configuration.yaml entry
+mqtt:
+  broker: "IP_ADDRESS_BROKER"
+  transport: websockets
+  ws_path: "/mqtt"
+  headers:
+    authorization: Bearer <token>
+```
+
+The version of the MQTT protocol can be changed through the `protocol` attribute.
+
 ## Additional features
 
 - [Certificate](/docs/mqtt/certificate/)