diff --git a/docs/en/api-reference/protocols/mqtt.rst b/docs/en/api-reference/protocols/mqtt.rst index 1346305bb3b..4109c371f7f 100644 --- a/docs/en/api-reference/protocols/mqtt.rst +++ b/docs/en/api-reference/protocols/mqtt.rst @@ -4,42 +4,42 @@ ESP-MQTT Overview -------- -ESP-MQTT is an implementation of [MQTT](mqtt.org) protocol client (MQTT is a lightweight publish/subscribe messaging protocol). +ESP-MQTT is an implementation of `MQTT `_ protocol client. MQTT is a lightweight publish/subscribe messaging protocol. Features -------- - * Supports MQTT over TCP, SSL with mbedtls, MQTT over Websocket, MQTT over Websocket Secure. + * Support MQTT over TCP, SSL with Mbed TLS, MQTT over WebSocket, and MQTT over WebSocket Secure * Easy to setup with URI - * Multiple instances (Multiple clients in one application) - * Support subscribing, publishing, authentication, last will messages, keep alive pings and all 3 QoS levels (it should be a fully functional client). + * Multiple instances (multiple clients in one application) + * Support subscribing, publishing, authentication, last will messages, keep alive pings, and all 3 Quality of Service (QoS) levels (it should be a fully functional client) -Application Example -------------------- +Application Examples +--------------------- - * :example:`protocols/mqtt/tcp`: MQTT over tcp, default port 1883 - * :example:`protocols/mqtt/ssl`: MQTT over tls, default port 8883 - * :example:`protocols/mqtt/ssl_ds`: MQTT over tls using digital signature peripheral for authentication, default port 8883. - * :example:`protocols/mqtt/ssl_mutual_auth`: MQTT over tls using certificates for authentication, default port 8883 - * :example:`protocols/mqtt/ssl_psk`: MQTT over tls using pre-shared keys for authentication, default port 8883. - * :example:`protocols/mqtt/ws`: MQTT over Websocket, default port 80 - * :example:`protocols/mqtt/wss`: MQTT over Websocket Secure, default port 443 + * :example:`protocols/mqtt/tcp`: MQTT over TCP, default port 1883 + * :example:`protocols/mqtt/ssl`: MQTT over TLS, default port 8883 + * :example:`protocols/mqtt/ssl_ds`: MQTT over TLS using digital signature peripheral for authentication, default port 8883 + * :example:`protocols/mqtt/ssl_mutual_auth`: MQTT over TLS using certificates for authentication, default port 8883 + * :example:`protocols/mqtt/ssl_psk`: MQTT over TLS using pre-shared keys for authentication, default port 8883 + * :example:`protocols/mqtt/ws`: MQTT over WebSocket, default port 80 + * :example:`protocols/mqtt/wss`: MQTT over WebSocket Secure, default port 443 Configuration ------------- -The configuration is made by setting fields in ``esp_mqtt_client_config_t`` struct. The configuration struct has the following sub structs to configure different aspects of the client operation. +The configuration is made by setting fields in ``esp_mqtt_client_config_t`` struct. The configuration struct has the following sub structs to configure different aspects of the client operation. * :cpp:member:`broker` - Allow to set address and security verification. * :cpp:member:`credentials` - Client credentials for authentication. * :cpp:member:`session` - Configuration for MQTT session aspects. - * :cpp:member:`network` - Networking related configuration. + * :cpp:member:`network` - Networking related configuration. * :cpp:member:`task` - Allow to configure FreeRTOS task. * :cpp:member:`buffer` - Buffer size for input and output. -In the following session the most common aspects are detailed. +In the following sections, the most common aspects are detailed. Broker ^^^^^^^^^^^ @@ -48,17 +48,16 @@ Broker Address =========== -Broker address can be set by usage of ``broker.address`` struct. The configuration can be made by usage of ``uri`` field -or the combination of ``hostname``, ``transport`` and ``port``. Optionally, `path` could be set, this field is useful in -websocket connections. +Broker address can be set by usage of ``broker.address`` struct. The configuration can be made by usage of ``uri`` field or the combination of ``hostname``, ``transport`` and ``port``. Optionally, ``path`` could be set, this field is useful in WebSocket connections. + +The ``uri`` field is used in the format ``scheme://hostname:port/path``. -The ``uri`` field is used in the following format ``scheme://hostname:port/path``. - Curently support ``mqtt``, ``mqtts``, ``ws``, ``wss`` schemes - MQTT over TCP samples: - - ``mqtt://mqtt.eclipseprojects.io``: MQTT over TCP, default port 1883: - - ``mqtt://mqtt.eclipseprojects.io:1884`` MQTT over TCP, port 1884: - - ``mqtt://username:password@mqtt.eclipseprojects.io:1884`` MQTT over TCP, + - ``mqtt://mqtt.eclipseprojects.io``: MQTT over TCP, default port 1883 + - ``mqtt://mqtt.eclipseprojects.io:1884``: MQTT over TCP, port 1884 + - ``mqtt://username:password@mqtt.eclipseprojects.io:1884``: MQTT over TCP, port 1884, with username and password - MQTT over SSL samples: @@ -66,11 +65,11 @@ The ``uri`` field is used in the following format ``scheme://hostname:port/path` - ``mqtts://mqtt.eclipseprojects.io``: MQTT over SSL, port 8883 - ``mqtts://mqtt.eclipseprojects.io:8884``: MQTT over SSL, port 8884 -- MQTT over Websocket samples: +- MQTT over WebSocket samples: - ``ws://mqtt.eclipseprojects.io:80/mqtt`` -- MQTT over Websocket Secure samples: +- MQTT over WebSocket Secure samples: - ``wss://mqtt.eclipseprojects.io:443/mqtt`` @@ -85,15 +84,14 @@ The ``uri`` field is used in the following format ``scheme://hostname:port/path` esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID, mqtt_event_handler, client); esp_mqtt_client_start(client); -- Note: By default mqtt client uses event loop library to post related mqtt events (connected, subscribed, published, etc.) +.. note:: By default MQTT client uses event loop library to post related MQTT events (connected, subscribed, published, etc.). ============ Verification ============ -For secure connections TLS is used, and to guarantee Broker's identity the ``broker.verification`` struct must be set. -The broker certificate may be set in PEM or DER format. To select DER the equivalent ``_len`` field must be set, -otherwise a NULL terminated string in PEM format should be provided to ``certificate`` field. +For secure connections with TLS used, and to guarantee Broker's identity, the ``broker.verification`` struct must be set. +The broker certificate may be set in PEM or DER format. To select DER, the equivalent ``_len`` field must be set. Otherwise, a null-terminated string in PEM format should be provided to ``certificate`` field. - Get certificate from server, example: ``mqtt.eclipseprojects.io`` ``openssl s_client -showcerts -connect mqtt.eclipseprojects.io:8883 /dev/null|openssl x509 -outform PEM >mqtt_eclipse_org.pem`` @@ -109,15 +107,15 @@ otherwise a NULL terminated string in PEM format should be provided to ``certifi }, }; -To details on other fields check the Reference API and :ref:`esp_tls_server_verification`. +For details about other fields, please check the `API Reference`_ and :ref:`esp_tls_server_verification`. Client Credentials ^^^^^^^^^^^^^^^^^^ All client related credentials are under the ``credentials`` field. - * ``username``: pointer to the username used for connecting to the broker, can also be set by URI. - * ``client_id``: pointer to the client id, defaults to ``ESP32_%CHIPID%`` where %CHIPID% are the last 3 bytes of MAC address in hex format + * ``username``: pointer to the username used for connecting to the broker, can also be set by URI + * ``client_id``: pointer to the client ID, defaults to ``ESP32_%CHIPID%`` where ``%CHIPID%`` are the last 3 bytes of MAC address in hex format ============== Authentication @@ -125,22 +123,21 @@ Authentication It's possible to set authentication parameters through the ``authentication`` field. The client supports the following authentication methods: - * Using a password by setting ``authentication.password``. - * Muthual authentication with TLS by setting ``authentication.certificate`` and ``authentication.key``, both can be provided in PEM or DER format. - * Using secure element available in ESP32-WROOM-32SE, setting ``authentication.use_secure_element``. - * Using Digital Signature Peripheral available in some Espressif devices, setting ``authentication.ds_data``. + * ``authentication.password``: use a password by setting + * ``authentication.certificate`` and ``authentication.key``: mutual authentication with TLS, and both can be provided in PEM or DER format + * ``authentication.use_secure_element``: use secure element available in ESP32-WROOM-32SE + * ``authentication.ds_data``: use Digital Signature Peripheral available in some Espressif devices Session ^^^^^^^^^^^ -For MQTT session related configurations ``section`` fields should be used. +For MQTT session related configurations, ``section`` fields should be used. ======================= Last Will and Testament ======================= -MQTT allows for a last will and testament (LWT) message to notify other clients when a client ungracefully disconnects. This is configured by the following fields -in the ``esp_mqtt_client_config_t.session.last_will``-struct. +MQTT allows for a last will and testament (LWT) message to notify other clients when a client ungracefully disconnects. This is configured by the following fields in the ``esp_mqtt_client_config_t.session.last_will`` struct. * ``topic``: pointer to the LWT message topic * ``msg``: pointer to the LWT message @@ -148,18 +145,18 @@ in the ``esp_mqtt_client_config_t.session.last_will``-struct. * ``qos``: quality of service for the LWT message * ``retain``: specifies the retain flag of the LWT message -Change settings in Project Configuration Menu +Change Settings in Project Configuration Menu ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The settings for MQTT can be found using ``idf.py menuconfig``, under Component config -> ESP-MQTT Configuration +The settings for MQTT can be found using ``idf.py menuconfig``, under ``Component config`` > ``ESP-MQTT Configuration``. The following settings are available: -- :ref:`CONFIG_MQTT_PROTOCOL_311`: Enables 3.1.1 version of MQTT protocol +- :ref:`CONFIG_MQTT_PROTOCOL_311`: enable 3.1.1 version of MQTT protocol -- :ref:`CONFIG_MQTT_TRANSPORT_SSL`, :ref:`CONFIG_MQTT_TRANSPORT_WEBSOCKET`: Enables specific MQTT transport layer, such as SSL, WEBSOCKET, WEBSOCKET_SECURE +- :ref:`CONFIG_MQTT_TRANSPORT_SSL` and :ref:`CONFIG_MQTT_TRANSPORT_WEBSOCKET`: enable specific MQTT transport layer, such as SSL, WEBSOCKET, and WEBSOCKET_SECURE -- :ref:`CONFIG_MQTT_CUSTOM_OUTBOX`: Disables default implementation of mqtt_outbox, so a specific implementaion can be supplied +- :ref:`CONFIG_MQTT_CUSTOM_OUTBOX`: disable default implementation of mqtt_outbox, so a specific implementation can be supplied Events @@ -171,9 +168,9 @@ The following events may be posted by the MQTT client: * ``MQTT_EVENT_DISCONNECTED``: The client has aborted the connection due to being unable to read or write data, e.g. because the server is unavailable. * ``MQTT_EVENT_SUBSCRIBED``: The broker has acknowledged the client's subscribe request. The event data will contain the message ID of the subscribe message. * ``MQTT_EVENT_UNSUBSCRIBED``: The broker has acknowledged the client's unsubscribe request. The event data will contain the message ID of the unsubscribe message. -* ``MQTT_EVENT_PUBLISHED``: The broker has acknowledged the client's publish message. This will only be posted for Quality of Service level 1 and 2, as level 0 does not use acknowledgements. The event data will contain the message ID of the publish message. -* ``MQTT_EVENT_DATA``: The client has received a publish message. The event data contains: message ID, name of the topic it was published to, received data and its length. For data that exceeds the internal buffer multiple `MQTT_EVENT_DATA` will be posted and `current_data_offset` and `total_data_len` from event data updated to keep track of the fragmented message. -* ``MQTT_EVENT_ERROR``: The client has encountered an error. `esp_mqtt_error_type_t` from `error_handle` in the event data can be used to further determine the type of the error. The type of error will determine which parts of the `error_handle` struct is filled. +* ``MQTT_EVENT_PUBLISHED``: The broker has acknowledged the client's publish message. This will only be posted for QoS level 1 and 2, as level 0 does not use acknowledgements. The event data will contain the message ID of the publish message. +* ``MQTT_EVENT_DATA``: The client has received a publish message. The event data contains: message ID, name of the topic it was published to, received data and its length. For data that exceeds the internal buffer, multiple ``MQTT_EVENT_DATA`` will be posted and ``current_data_offset`` and ``total_data_len`` from event data updated to keep track of the fragmented message. +* ``MQTT_EVENT_ERROR``: The client has encountered an error. ``esp_mqtt_error_type_t`` from ``error_handle`` in the event data can be used to further determine the type of the error. The type of error will determine which parts of the ``error_handle`` struct is filled. API Reference ------------- diff --git a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-index.rst b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-index.rst index 34ed2ccf3f0..82b33ba3514 100644 --- a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-index.rst +++ b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-index.rst @@ -225,6 +225,7 @@ ESP-BLE-MESH 示例 * ESP-BLE-MESH 节点控制台 - 该演示实现 ESP-BLE-MESH 节点的基本功能。在演示中，Provisioner and Node 可以扫描、验证节点，节点可以回复 Provisioner 的获取/设置消息，示例请见：:example:`example code `。 + .. _esp-ble-mesh-demo-videos: ESP-BLE-MESH 演示视频 diff --git a/docs/zh_CN/api-reference/protocols/mqtt.rst b/docs/zh_CN/api-reference/protocols/mqtt.rst index 4f5ad7d0c37..8f3eefbd000 100644 --- a/docs/zh_CN/api-reference/protocols/mqtt.rst +++ b/docs/zh_CN/api-reference/protocols/mqtt.rst @@ -1 +1,178 @@ -.. include:: ../../../en/api-reference/protocols/mqtt.rst \ No newline at end of file +ESP-MQTT +======== + +概述 +-------- + +ESP-MQTT 是 `MQTT `_ 协议客户端的实现。MQTT 是一种基于发布/订阅模式的轻量级消息传输协议。 + + +特性 +-------- + * 支持基于 TCP 的 MQTT、基于 Mbed TLS 的 SSL、基于 WebSocket 的 MQTT 以及基于 WebSocket Secure 的 MQTT + * 通过 URI 简化配置流程 + * 多个实例（一个应用程序中有多个客户端） + * 支持订阅、发布、认证、遗嘱消息、保持连接心跳机制以及 3 个服务质量 (QoS) 级别（组成全功能客户端） + + +应用示例 +------------------- + + * :example:`protocols/mqtt/tcp`：基于 TCP 的 MQTT，默认端口 1883 + * :example:`protocols/mqtt/ssl`：基于 TLS 的 MQTT，默认端口 8883 + * :example:`protocols/mqtt/ssl_ds`：基于 TLS 的 MQTT，使用数字签名外设进行身份验证，默认端口 8883 + * :example:`protocols/mqtt/ssl_mutual_auth`：基于 TLS 的 MQTT，使用证书进行身份验证，默认端口 8883 + * :example:`protocols/mqtt/ssl_psk`：基于 TLS 的 MQTT，使用预共享密钥进行身份验证，默认端口 8883 + * :example:`protocols/mqtt/ws`：基于 WebSocket 的 MQTT，默认端口 80 + * :example:`protocols/mqtt/wss`：基于 WebSocket Secure 的 MQTT，默认端口 443 + + +配置 +------------- + +通过设置 ``esp_mqtt_client_config_t`` 结构体中的字段来进行配置。配置结构体包含以下子结构体，用于配置客户端的多种操作。 + + * :cpp:member:`broker` - 允许设置地址和安全验证。 + * :cpp:member:`credentials` - 用于身份验证的客户端凭据。 + * :cpp:member:`session` - MQTT 会话相关配置。 + * :cpp:member:`network` - 网络相关配置。 + * :cpp:member:`task` - 允许配置 FreeRTOS 任务。 + * :cpp:member:`buffer` - 输入输出的缓冲区大小。 + +下文将详细介绍不同配置。 + +服务器 +^^^^^^^^^^^^ + +=========== +地址 +=========== + +通过 ``broker.address`` 结构体的 ``uri`` 字段或者 ``hostname``、``transport`` 以及 ``port`` 的组合，可以设置服务器地址。您也可以选择设置 ``path``，该字段对 WebSocket 连接而言非常有用。 + +使用 ``uri`` 字段的格式为 ``scheme://hostname:port/path``。 + +- 当前支持 ``mqtt``、``mqtts``、``ws`` 和 ``wss`` 协议 +- 基于 TCP 的 MQTT 示例： + + - ``mqtt://mqtt.eclipseprojects.io``：基于 TCP 的 MQTT，默认端口 1883 + - ``mqtt://mqtt.eclipseprojects.io:1884``：基于 TCP 的 MQTT，端口 1884 + - ``mqtt://username:password@mqtt.eclipseprojects.io:1884``：基于 TCP 的 MQTT， + 端口 1884，带有用户名和密码 + +- 基于 SSL 的 MQTT 示例： + + - ``mqtts://mqtt.eclipseprojects.io``：基于 SSL 的 MQTT，端口 8883 + - ``mqtts://mqtt.eclipseprojects.io:8884``：基于 SSL 的 MQTT，端口 8884 + +- 基于 WebSocket 的 MQTT 示例： + + - ``ws://mqtt.eclipseprojects.io:80/mqtt`` + +- 基于 WebSocket Secure 的 MQTT 示例： + + - ``wss://mqtt.eclipseprojects.io:443/mqtt`` + +- 最简配置： + +.. code:: c + + const esp_mqtt_client_config_t mqtt_cfg = { + .broker.address.uri = "mqtt://mqtt.eclipseprojects.io", + }; + esp_mqtt_client_handle_t client = esp_mqtt_client_init(&mqtt_cfg); + esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID, mqtt_event_handler, client); + esp_mqtt_client_start(client); + +.. note:: 默认情况下，MQTT 客户端使用事件循环库来发布相关 MQTT 事件（已连接、已订阅、已发布等）。 + +============= +验证 +============= + +为验证服务器身份，对于使用 TLS 的安全链接，必须设置 ``broker.verification`` 结构体。 +服务器证书可设置为 PEM 或 DER 格式。如要选择 DER 格式，必须设置等效 ``_len`` 字段，否则应在 ``certificate`` 字段传入以空字符结尾的 PEM 格式字符串。 + +- 从服务器获取证书，例如：``mqtt.eclipseprojects.io`` + ``openssl s_client -showcerts -connect mqtt.eclipseprojects.io:8883 /dev/null|openssl x509 -outform PEM >mqtt_eclipse_org.pem`` +- 检查示例应用程序：``examples/mqtt_ssl`` +- 配置： + +.. code:: c + + const esp_mqtt_client_config_t mqtt_cfg = { + .broker = { + .address.uri = "mqtts://mqtt.eclipseprojects.io:8883", + .verification.certificate = (const char *)mqtt_eclipse_org_pem_start, + }, + }; + +了解其他字段的详细信息，请查看 `API 参考`_ 以及 :ref:`esp_tls_server_verification`。 + +客户端凭据 +^^^^^^^^^^^^^^^^^^^^^^^^ + +``credentials`` 字段下包含所有客户端相关凭据。 + + * ``username``：指向用于连接服务器用户名的指针，也可通过 URI 设置 + * ``client_id``：指向客户端 ID 的指针，默认为 ``ESP32_%CHIPID%``，其中 ``%CHIPID%`` 是十六进制 MAC 地址的最后 3 个字节 + +=============== +认证 +=============== + +可以通过 ``authentication`` 字段设置认证参数。客户端支持以下认证方式： + + * ``authentication.password``：使用密码 + * ``authentication.certificate`` 和 ``authentication.key``：进行双向 TLS 身份验证，PEM 或 DER 格式均可 + * ``authentication.use_secure_element``：使用 ESP32-WROOM-32SE 中的安全元素 + * ``authentication.ds_data``：使用某些乐鑫设备的数字签名外设 + +会话 +^^^^^^^^^^^^ + +使用 ``section`` 字段进行 MQTT 会话相关配置。 + +======================== +遗嘱消息 (LWT) +======================== + +通过设置 ``esp_mqtt_client_config_t.session.last_will`` 结构体的以下字段，MQTT 会在一个客户端意外断开连接时通过遗嘱消息通知其他客户端。 + + * ``topic``：指向 LWT 消息主题的指针 + * ``msg``：指向 LWT 消息的指针 + * ``msg_len``：LWT 消息的长度，``msg`` 不以空字符结尾时需要该字段 + * ``qos``：LWT 消息的服务质量 + * ``retain``：指定 LWT 消息的保留标志 + +在项目配置菜单中设置 MQTT +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +通过 ``idf.py menuconfig``，可以在 ``Component config`` > ``ESP-MQTT Configuration`` 中找到 MQTT 设置。 + +相关设置如下： + +- :ref:`CONFIG_MQTT_PROTOCOL_311`：启用 MQTT 协议 3.1.1 版本 + +- :ref:`CONFIG_MQTT_TRANSPORT_SSL` 和 :ref:`CONFIG_MQTT_TRANSPORT_WEBSOCKET`：启用特定 MQTT 传输层，例如 SSL、WEBSOCKET 和 WEBSOCKET_SECURE + +- :ref:`CONFIG_MQTT_CUSTOM_OUTBOX`：禁用 mqtt_outbox 默认实现，因此可以提供特定实现 + + +事件 +------------ +MQTT 客户端可能会发布以下事件： + +* ``MQTT_EVENT_BEFORE_CONNECT``：客户端已初始化并即将开始连接至服务器。 +* ``MQTT_EVENT_CONNECTED``：客户端已成功连接至服务器。客户端已准备好收发数据。 +* ``MQTT_EVENT_DISCONNECTED``：由于无法读取或写入数据，例如因为服务器无法使用，客户端已终止连接。 +* ``MQTT_EVENT_SUBSCRIBED``：服务器已确认客户端的订阅请求。事件数据将包含订阅消息的消息 ID。 +* ``MQTT_EVENT_UNSUBSCRIBED``：服务器已确认客户端的退订请求。事件数据将包含退订消息的消息 ID。 +* ``MQTT_EVENT_PUBLISHED``：服务器已确认客户端的发布消息。消息将仅针对 QoS 级别 1 和 2 发布，因为级别 0 不会进行确认。事件数据将包含发布消息的消息 ID。 +* ``MQTT_EVENT_DATA``：客户端已收到发布消息。事件数据包含：消息 ID、发布消息所属主题名称、收到的数据及其长度。对于超出内部缓冲区的数据，将发布多个 ``MQTT_EVENT_DATA``，并更新事件数据的 ``current_data_offset`` 和 ``total_data_len`` 以跟踪碎片化消息。 +* ``MQTT_EVENT_ERROR``：客户端遇到错误。使用事件数据 ``error_handle`` 中的 ``esp_mqtt_error_type_t``，可以进一步判断错误类型。错误类型决定 ``error_handle`` 结构体的哪些部分会被填充。 + +API 参考 +------------- + +.. include-build-file:: inc/mqtt_client.inc