From f7bc4f301334637b028201a1d3271cca60e8078a Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Mon, 14 Feb 2022 14:41:42 +0100 Subject: [PATCH] Update documentation for MQTT import flow removal (#21583) --- source/_docs/mqtt/birth_will.markdown | 66 +-------------------------- source/_docs/mqtt/broker.markdown | 66 +++++++++++---------------- source/_docs/mqtt/discovery.markdown | 18 +++----- source/_integrations/mqtt.markdown | 25 ++-------- 4 files changed, 36 insertions(+), 139 deletions(-) diff --git a/source/_docs/mqtt/birth_will.markdown b/source/_docs/mqtt/birth_will.markdown index 7ffa0a48ba9..89fd94709dd 100644 --- a/source/_docs/mqtt/birth_will.markdown +++ b/source/_docs/mqtt/birth_will.markdown @@ -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". diff --git a/source/_docs/mqtt/broker.markdown b/source/_docs/mqtt/broker.markdown index e5e42f02a38..f019c7c0a05 100644 --- a/source/_docs/mqtt/broker.markdown +++ b/source/_docs/mqtt/broker.markdown @@ -22,23 +22,38 @@ There is [an issue](https://github.com/rabbitmq/rabbitmq-mqtt/issues/154) with t -## 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 ``` +
+ +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. + +
+ +## 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 -### 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 -``` - -
- -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. - -
diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index a292748e876..eff3760e77f 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -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: diff --git a/source/_integrations/mqtt.markdown b/source/_integrations/mqtt.markdown index 6ae7951031b..b0bf8ae68ae 100644 --- a/source/_integrations/mqtt.markdown +++ b/source/_integrations/mqtt.markdown @@ -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