mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-22 16:56:50 +00:00
Update documentation for MQTT import flow removal (#21583)
This commit is contained in:
parent
de74a51b84
commit
f7bc4f3013
@ -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".
|
||||
|
@ -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>
|
||||
|
@ -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:
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
Loading…
x
Reference in New Issue
Block a user