jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-25 02:07:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document existing / new MQTT connection properties (#20353)

Browse Source 
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 :(
This commit is contained in:
Alba Mendez 2021-11-19 09:24:12 +01:00 committed by GitHub
parent e82f38fefd
commit 1c82960fb3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 28 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
source/_integrations/mqtt.markdown
View File

@ -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). 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 %} {% include integrations/config_flow.md %}
## Manual configuration ## Manual configuration
@ -41,10 +43,20 @@ To connect to your [own MQTT broker](/docs/mqtt/broker#run-your-own):
```yaml ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
mqtt: 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 ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
@ -52,10 +64,22 @@ mqtt:
certificate: "PATH_TO_CA.crt" certificate: "PATH_TO_CA.crt"
broker: "IP_ADDRESS_BROKER" broker: "IP_ADDRESS_BROKER"
port: 8883 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 ## Additional features
- [Certificate](/docs/mqtt/certificate/) - [Certificate](/docs/mqtt/certificate/)