diff --git a/components/mqtt.rst b/components/mqtt.rst index 3d9a75344..042dac909 100644 --- a/components/mqtt.rst +++ b/components/mqtt.rst @@ -24,6 +24,12 @@ in which case this is not needed. username: livingroom password: !secret mqtt_password + +.. note:: + + Support for esp-idf is still experminental. Please report issues you have with mqtt using the esp-idf framework. + + Configuration variables: ------------------------ @@ -71,8 +77,13 @@ Configuration variables: - **shutdown_message** (*Optional*, :ref:`mqtt-message`): The message to send when the node shuts down and the connection is closed cleanly. See :ref:`mqtt-last_will_birth` for more information. - **ssl_fingerprints** (*Optional*, list): Only on ESP8266. A list of SHA1 hashes used - for verifying SSL connections. See :ref:`mqtt-ssl_fingerprints` + for verifying SSL connections. See :ref:`mqtt-ssl_fingerprints`. for more information. +- **certificate_authority** *(Optional*, string): Only with `esp-idf`. CA certificate in PEM format. See :ref:`mqtt-tls-idf` for more information +- **skip_cert_cn_check** (*Optional*, bool): Only with `esp-idf`. Don't verify if the common name in the server certificate matches the value of ``broker``. +- **idf_send_async** (*Optional*, bool): Only with `esp-idf`. Default is false. If true publishing the message happens from the internal mqtt task. The client only enqueues the message. + The advantage of asyncronous publishing is that it doesn't block the esphome main thread. The disadvantage is a delay (up to 1-2 seconds) until the messages are actually sent out. + Set this to true if ypi send large amounts of of data over mqtt. - **reboot_timeout** (*Optional*, :ref:`config-time`): The amount of time to wait before rebooting when no MQTT connection exists. Can be disabled by setting this to ``0s``. Defaults to ``15min``. - **keepalive** (*Optional*, :ref:`config-time`): The time @@ -262,6 +273,56 @@ then run the ``mqtt-fingerprint`` script of ESPHome to get the certificate: .. _config-mqtt-component: + +.. _mqtt-tls-idf: + +TLS with esp-idf (esp32) +------------------------ + +If used with the esp-idf framework a TLS connection to a mqtt broker can be established. +The servers CA certificate is required to validate the connection. + +You have to download the server CA certficiate in PEM format and add it to ``certificate_authority``. +Usually these are .crt files and you can open them with any text editor. +Also make sure to change the ``port`` of the mqtt broker. Most brokers use port 8883 for TLS connections. + +.. code-block:: yaml + + mqtt: + broker: test.mymqtt.local + port: 8883 + discovery: true + discovery_prefix: ${mqtt_prefix}/homeassistant + log_topic: ${mqtt_prefix}/logs + skip_cert_cn_check: true + idf_send_async: false + certificate_authority: | + -----BEGIN CERTIFICATE----- + MIIEAzCCAuugAwIBAgIUBY1hlCGvdj4NhBXkZ/uLUZNILAwwDQYJKoZIhvcNAQEL + BQAwgZAxCzAJBgNVBAYTAkdCMRcwFQYDVQQIDA5Vbml0ZWQgS2luZ2RvbTEOMAwG + A1UEBwwFRGVyYnkxEjAQBgNVBAoMCU1vc3F1aXR0bzELMAkGA1UECwwCQ0ExFjAU + BgNVBAMMDW1vc3F1aXR0by5vcmcxHzAdBgkqhkiG9w0BCQEWEHJvZ2VyQGF0Y2hv + by5vcmcwHhcNMjAwNjA5MTEwNjM5WhcNMzAwNjA3MTEwNjM5WjCBkDELMAkGA1UE + BhMCR0IxFzAVBgNVBAgMDlVuaXRlZCBLaW5nZG9tMQ4wDAYDVQQHDAVEZXJieTES + MBAGA1UECgwJTW9zcXVpdHRvMQswCQYDVQQLDAJDQTEWMBQGA1UEAwwNbW9zcXVp + dHRvLm9yZzEfMB0GCSqGSIb3DQEJARYQcm9nZXJAYXRjaG9vLm9yZzCCASIwDQYJ + KoZIhvcNAQEBBQADggEPADCCAQoCggEBAME0HKmIzfTOwkKLT3THHe+ObdizamPg + UZmD64Tf3zJdNeYGYn4CEXbyP6fy3tWc8S2boW6dzrH8SdFf9uo320GJA9B7U1FW + Te3xda/Lm3JFfaHjkWw7jBwcauQZjpGINHapHRlpiCZsquAthOgxW9SgDgYlGzEA + s06pkEFiMw+qDfLo/sxFKB6vQlFekMeCymjLCbNwPJyqyhFmPWwio/PDMruBTzPH + 3cioBnrJWKXc3OjXdLGFJOfj7pP0j/dr2LH72eSvv3PQQFl90CZPFhrCUcRHSSxo + E6yjGOdnz7f6PveLIB574kQORwt8ePn0yidrTC1ictikED3nHYhMUOUCAwEAAaNT + MFEwHQYDVR0OBBYEFPVV6xBUFPiGKDyo5V3+Hbh4N9YSMB8GA1UdIwQYMBaAFPVV + 6xBUFPiGKDyo5V3+Hbh4N9YSMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQEL + BQADggEBAGa9kS21N70ThM6/Hj9D7mbVxKLBjVWe2TPsGfbl3rEDfZ+OKRZ2j6AC + 6r7jb4TZO3dzF2p6dgbrlU71Y/4K0TdzIjRj3cQ3KSm41JvUQ0hZ/c04iGDg/xWf + +pp58nfPAYwuerruPNWmlStWAXf0UTqRtg4hQDWBuUFDJTuWuuBvEXudz74eh/wK + sMwfu1HFvjy5Z0iMDU8PUDepjVolOCue9ashlS4EB5IECdSR2TItnAIiIwimx839 + LdUdRudafMu5T5Xma182OC0/u/xRlEm+tvKGGmfFcN0piqVl8OrSPBgIlb+1IKJE + m/XriWr/Cq4h/JfB7NTsezVslgkBaoU= + -----END CERTIFICATE----- + + MQTT Component Base Configuration ---------------------------------