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-23 17:27:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation for MQTT import flow removal (#21583)

Browse Source
This commit is contained in:
Erik Montnemery 2022-02-14 14:41:42 +01:00 committed by GitHub
parent de74a51b84
commit f7bc4f3013
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 36 additions and 139 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
source/_docs/mqtt/birth_will.markdown
View File

@ -8,68 +8,4 @@ Home Assistant's MQTT integration supports so-called Birth and Last Will and Tes
By default, Home Assistant sends `online` and `offline` to `homeassistant/status`.
To customize the MQTT Birth and Last Will messages, add the following section to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
mqtt:
birth_message:
topic: "hass/status"
payload: "online"
will_message:
topic: "hass/status"
payload: "offline"
```
{% configuration %}
birth_message:
description: Birth Message. Set to the empty dict, `{}`, to disable publishing a birth message.
required: false
type: map
keys:
topic:
description: The MQTT topic to publish the message.
required: false
default: homeassistant/status
type: string
payload:
description: The message content.
required: false
default: online
type: string
qos:
description: The maximum QoS level of the topic.
required: false
default: 0
type: integer
retain:
description: If the published message should have the retain flag on or not.
required: false
default: false
type: boolean
will_message:
description: Will Message. Set to the empty dict, `{}`, to disable publishing a will message.
required: false
type: map
keys:
topic:
description: The MQTT topic to publish the message.
required: false
default: homeassistant/status
type: string
payload:
description: The message content.
required: false
default: offline
type: string
qos:
description: The maximum QoS level of the topic.
required: false
default: 0
type: integer
retain:
description: If the published message should have the retain flag on or not.
required: false
default: false
type: boolean
{% endconfiguration %}
MQTT Birth and Last Will messages can be customized or disabled from the UI. To do this, click on "Configure" in the integration page in the UI, then "Re-configure MQTT" and then "Next".

66
source/_docs/mqtt/broker.markdown
View File

@ -22,23 +22,38 @@ There is [an issue](https://github.com/rabbitmq/rabbitmq-mqtt/issues/154) with t
</div>
## Configuration
## Connect to a public broker
The Mosquitto project runs a [public broker](https://test.mosquitto.org). This is the easiest to set up, but there is no privacy as all messages are public. Use this only for testing purposes and not for real tracking of your devices or controlling your home.
```yaml
# Example configuration.yaml entry
mqtt:
broker: 192.168.1.100
broker: test.mosquitto.org
port: 1883 or 8883
# Optional, replace port 1883 with following if you want encryption
# (doesn't really matter because broker is public)
port: 8883
# Download certificate from https://test.mosquitto.org/ssl/mosquitto.org.crt
certificate: /home/paulus/downloads/mosquitto.org.crt
```
<div class='note'>
If you experience an error message like `Failed to connect due to exception: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed`, then add `certificate: auto` to your broker configuration and restart Home Assistant.
</div>
## Broker configuration
MQTT broker settings are configured when the MQTT integration is first setup, and can be changed if needed. To change the settings, click on "Configure" in the integration page in the UI, then "Re-configure MQTT".
## Advanced broker configuration
Some broker configuration options can't be set via the user interface, but require changes of your `configuration.yaml` file.
Additional SSL certificate options are documented [here](/docs/mqtt/certificate/).
{% configuration %}
broker:
required: false
description: The IP address or hostname of your MQTT broker, e.g., 192.168.1.32.
type: string
port:
required: false
description: The network port to connect to. Default is 1883.
type: integer
client_id:
required: false
description: The client ID that Home Assistant will use. Has to be unique on the server. Default is a randomly generated one.
@ -47,14 +62,6 @@ keepalive:
required: false
description: The time in seconds between sending keep alive messages for this client. Default is 60.
type: integer
username:
required: false
description: The username to use with your MQTT broker.
type: string
password:
required: false
description: The corresponding password for the username to use with your MQTT broker.
type: string
protocol:
required: false
description: "Protocol to use: 3.1 or 3.1.1. By default it connects with 3.1.1 and falls back to 3.1 if server does not support 3.1.1."
@ -76,24 +83,3 @@ If you are running a Mosquitto instance on a different server with proper SSL en
</div>
### Public broker
The Mosquitto project runs a [public broker](https://test.mosquitto.org). This is the easiest to set up, but there is no privacy as all messages are public. Use this only for testing purposes and not for real tracking of your devices or controlling your home.
```yaml
mqtt:
broker: test.mosquitto.org
port: 1883 or 8883
# Optional, replace port 1883 with following if you want encryption
# (doesn't really matter because broker is public)
port: 8883
# Download certificate from https://test.mosquitto.org/ssl/mosquitto.org.crt
certificate: /home/paulus/downloads/mosquitto.org.crt
```
<div class='note'>
If you experience an error message like `Failed to connect due to exception: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed`, then add `certificate: auto` to your broker configuration and restart Home Assistant.
</div>

18
source/_docs/mqtt/discovery.markdown
View File

@ -29,20 +29,14 @@ Supported by MQTT discovery:
- [Tag Scanners](/integrations/tag.mqtt/)
- [Vacuums](/integrations/vacuum.mqtt/)
MQTT discovery is enabled by default. To disable MQTT discovery, add the following to your `configuration.yaml` file:
## Configuration
MQTT discovery is enabled by default, but can be disable. To do this, click on "Configure" in the integration page in the UI, then "Re-configure MQTT" and then "Next".
```yaml
# Example configuration.yaml entry
mqtt:
discovery: false
```
### Advanced discovery configuration
It's possible to configure the prefix of the discovery topic through `configuration.yaml`.
{% configuration %}
discovery:
description: If the MQTT discovery should be enabled or not.
required: false
default: true
type: boolean
discovery_prefix:
description: The prefix for the discovery topic.
required: false
@ -50,7 +44,7 @@ discovery_prefix:
type: string
{% endconfiguration %}
### Discovery topic
## Discovery topic
The discovery topic need to follow a specific format:

25
source/_integrations/mqtt.markdown
View File

@ -33,29 +33,10 @@ Your first step to get MQTT and Home Assistant working is to choose a [broker](/
{% include integrations/config_flow.md %}
## Manual configuration
### Advanced broker configuration
Alternatively, if you want to manually configure MQTT, you will need to add the following to your `configuration.yaml` file.
To connect to your [own MQTT broker](/docs/mqtt/broker#run-your-own):
```yaml
# Example configuration.yaml entry
mqtt:
broker: IP_ADDRESS_BROKER
```
Manual configuration is required when connecting to a broker over TLS.
```yaml
# Example configuration.yaml entry
mqtt:
certificate: "PATH_TO_CA.crt"
broker: "IP_ADDRESS_BROKER"
port: 8883
username: "MQTT_USERNAME"
password: !secret MQTT_PASSWORD
```
Some broker configuration options can't be set via the user interface, but require changes of your `configuration.yaml` file.
This includes configuring SSL [certificate](/docs/mqtt/certificate/) options.
## Additional features