Merge branch 'docs/update_mqtt_wifi_coexist' into 'master'

docs: update mqtt wifi coexist

Closes DOC-4284

See merge request espressif/esp-idf!21710

docs/en/api-reference/protocols/mqtt.rst

@@ -18,39 +18,36 @@ Features
 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
-
-MQTT message retransmission
+   * :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
+
+MQTT Message Retransmission
 ---------------------------
 
-A new mqtt message is created by calling :cpp:func:`esp_mqtt_client_publish <esp_mqtt_client_publish()>` or its non blocking
-counterpart :cpp:func:`esp_mqtt_client_enqueue <esp_mqtt_client_enqueue()>`. 
+A new MQTT message is created by calling :cpp:func:`esp_mqtt_client_publish <esp_mqtt_client_publish()>` or its non blocking counterpart :cpp:func:`esp_mqtt_client_enqueue <esp_mqtt_client_enqueue()>`.
 
-Messages with QoS 0 will be sent only once, QoS 1 and 2 have a different behavior since the protocol requires extra steps to complete the process. 
+Messages with QoS 0 will be sent only once. QoS 1 and 2 have different behaviors since the protocol requires extra steps to complete the process.
 
-The ESP-MQTT library opts to always retransmit unacknowledged QoS 1 and 2 PUBLISH messages to avoid losses in faulty connections, even though the MQTT specification 
-requires the re-transmission only on reconnect with Clean Session flag been set to 0 (set :cpp:member:`disable_clean_session <esp_mqtt_client_config_t::session_t::disable_clean_session>` to true for this behavior).
+The ESP-MQTT library opts to always retransmit unacknowledged QoS 1 and 2 publish messages to avoid losses in faulty connections, even though the MQTT specification requires the re-transmission only on reconnect with Clean Session flag been set to 0 (set :cpp:member:`disable_clean_session <esp_mqtt_client_config_t::session_t::disable_clean_session>` to true for this behavior).
 
-
-Messages that could need retransmission, QoS 1 and 2, are always enqueued, but first transmission try occurs immediately if :cpp:func:`esp_mqtt_client_publish <esp_mqtt_client_publish>` is used. A transmission retry for unacknowledged messages will occur after :cpp:member:`message_retransmit_timeout <esp_mqtt_client_config_t::session_t::message_retransmit_timeout>`. After :ref:`CONFIG_MQTT_OUTBOX_EXPIRED_TIMEOUT_MS` messages will expire and deleted. If :ref:`CONFIG_MQTT_REPORT_DELETED_MESSAGES` is set an event is sent to notify the user.
+QoS 1 and 2 messages that may need retransmission are always enqueued, but first transmission try occurs immediately if :cpp:func:`esp_mqtt_client_publish <esp_mqtt_client_publish>` is used. A transmission retry for unacknowledged messages will occur after :cpp:member:`message_retransmit_timeout <esp_mqtt_client_config_t::session_t::message_retransmit_timeout>`. After :ref:`CONFIG_MQTT_OUTBOX_EXPIRED_TIMEOUT_MS` messages will expire and be deleted. If :ref:`CONFIG_MQTT_REPORT_DELETED_MESSAGES` is set, an event will be sent to notify the user.
 
 Configuration
 -------------
 
 The configuration is made by setting fields in :cpp:class:`esp_mqtt_client_config_t` struct. The configuration struct has the following sub structs to configure different aspects of the client operation.
 
-  * :cpp:class:`esp_mqtt_client_config_t::broker_t` - Allow to set address and security verification.
-  * :cpp:class:`esp_mqtt_client_config_t::credentials_t` - Client credentials for authentication.
-  * :cpp:class:`esp_mqtt_client_config_t::session_t` - Configuration for MQTT session aspects.
-  * :cpp:class:`esp_mqtt_client_config_t::network_t` - Networking related configuration. 
-  * :cpp:class:`esp_mqtt_client_config_t::task_t` - Allow to configure FreeRTOS task.
-  * :cpp:class:`esp_mqtt_client_config_t::buffer_t` - Buffer size for input and output.
+   * :cpp:class:`esp_mqtt_client_config_t::broker_t` - Allow to set address and security verification.
+   * :cpp:class:`esp_mqtt_client_config_t::credentials_t` - Client credentials for authentication.
+   * :cpp:class:`esp_mqtt_client_config_t::session_t` - Configuration for MQTT session aspects.
+   * :cpp:class:`esp_mqtt_client_config_t::network_t` - Networking related configuration.
+   * :cpp:class:`esp_mqtt_client_config_t::task_t` - Allow to configure FreeRTOS task.
+   * :cpp:class:`esp_mqtt_client_config_t::buffer_t` - Buffer size for input and output.
 
 In the following sections, the most common aspects are detailed.
 
@@ -131,7 +128,7 @@ Client Credentials
 
 All client related credentials are under the :cpp:class:`credentials <esp_mqtt_client_config_t::credentials_t>` field.
 
- * :cpp:member:`username <esp_mqtt_client_config_t::credentials_t::username>` pointer to the username used for connecting to the broker, can also be set by URI
+ * :cpp:member:`username <esp_mqtt_client_config_t::credentials_t::username>`: pointer to the username used for connecting to the broker, can also be set by URI
  * :cpp:member:`client_id <esp_mqtt_client_config_t::credentials_t::client_id>`: pointer to the client ID, defaults to ``ESP32_%CHIPID%`` where ``%CHIPID%`` are the last 3 bytes of MAC address in hex format
 
 ==============

docs/zh_CN/api-guides/coexist.rst

@@ -75,7 +75,6 @@ RF 共存
   X：不支持。
   S：在STA模式下支持且性能稳定，否则不支持。
 
-
 共存机制与策略
 ----------------------------------
 

docs/zh_CN/api-guides/wifi.rst

@@ -1163,7 +1163,6 @@ Wi-Fi 原因代码
      - 204
      - 握手超时。
 
-
 与低 RSSI 有关的 Wi-Fi 原因代码
 +++++++++++++++++++++++++++++++++
 
@@ -2213,7 +2212,6 @@ Wi-Fi 协议中定义了四个 AC （访问类别），每个 AC 有各自的优
 
     {IDF_TARGET_NAME} 支持接收和发送 AMSDU。开启 AMSDU 发送比较消耗内存，默认不开启 AMSDU 发送。可通过选项 :ref:`CONFIG_ESP32_WIFI_AMSDU_TX_ENABLED` 使能 AMSDU 发送功能， 但是使能 AMSDU 发送依赖于 :ref:`CONFIG_SPIRAM` 。
 
-
 Wi-Fi 分片
 -------------------------
 

docs/zh_CN/api-reference/protocols/mqtt.rst

@@ -18,26 +18,36 @@ ESP-MQTT 是 `MQTT <https://mqtt.org/>`_ 协议客户端的实现。MQTT 是一
 应用示例
 -------------------
 
-    * :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
+   * :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
 
+MQTT 消息重传
+--------------------------
+
+调用 :cpp:func:`esp_mqtt_client_publish <esp_mqtt_client_publish()>` 或其非阻塞形式 :cpp:func:`esp_mqtt_client_enqueue <esp_mqtt_client_enqueue()>`，可以创建新的 MQTT 消息。
+
+QoS 0 的消息将只发送一次，QoS 1 和 2 具有不同行为，因为协议需要执行额外步骤来完成该过程。
+
+ESP-MQTT 库将始终重新传输未确认的 QoS 1 和 2 发布消息，以避免连接错误导致信息丢失，虽然 MQTT 规范要求仅在重新连接且 Clean Session 标志设置为 0 时重新传输（针对此行为，将 :cpp:member:`disable_clean_session <esp_mqtt_client_config_t::session_t::disable_clean_session>` 设置为 true）。
+
+可能需要重传的 QoS 1 和 2 消息总是处于排队状态，但若使用 :cpp:func:`esp_mqtt_client_publish <esp_mqtt_client_publish>` 则会立即进行第一次传输尝试。未确认消息的重传将在 :cpp:member:`message_retransmit_timeout <esp_mqtt_client_config_t::session_t::message_retransmit_timeout>` 之后进行。在 :ref:`CONFIG_MQTT_OUTBOX_EXPIRED_TIMEOUT_MS` 之后，消息会过期并被删除。如已设置 :ref:`CONFIG_MQTT_REPORT_DELETED_MESSAGES`，则会发送事件来通知用户。
 
 配置
 -------------
 
-通过设置 ``esp_mqtt_client_config_t`` 结构体中的字段来进行配置。配置结构体包含以下子结构体，用于配置客户端的多种操作。
+通过设置 :cpp:class:`esp_mqtt_client_config_t` 结构体中的字段来进行配置。配置结构体包含以下子结构体，用于配置客户端的多种操作。
 
-  * :cpp:member:`broker<esp_mqtt_client_config::broker>` - 允许设置地址和安全验证。
-  * :cpp:member:`credentials<esp_mqtt_client_config::credentials>` - 用于身份验证的客户端凭据。
-  * :cpp:member:`session<esp_mqtt_client_config::session>` - MQTT 会话相关配置。
-  * :cpp:member:`network<esp_mqtt_client_config::network>` - 网络相关配置。
-  * :cpp:member:`task<esp_mqtt_client_config::task>` - 允许配置 FreeRTOS 任务。
-  * :cpp:member:`buffer<esp_mqtt_client_config::buffer>` - 输入输出的缓冲区大小。
+   * :cpp:class:`esp_mqtt_client_config_t::broker_t` - 允许设置地址和安全验证。
+   * :cpp:class:`esp_mqtt_client_config_t::credentials_t` - 用于身份验证的客户端凭据。
+   * :cpp:class:`esp_mqtt_client_config_t::session_t` - MQTT 会话相关配置。
+   * :cpp:class:`esp_mqtt_client_config_t::network_t` - 网络相关配置。
+   * :cpp:class:`esp_mqtt_client_config_t::task_t` - 允许配置 FreeRTOS 任务。
+   * :cpp:class:`esp_mqtt_client_config_t::buffer_t` - 输入输出的缓冲区大小。
 
 下文将详细介绍不同配置。
 
@@ -48,9 +58,9 @@ ESP-MQTT 是 `MQTT <https://mqtt.org/>`_ 协议客户端的实现。MQTT 是一
 地址
 ===========
 
-通过 ``broker.address`` 结构体的 ``uri`` 字段或者 ``hostname``、``transport`` 以及 ``port`` 的组合，可以设置服务器地址。您也可以选择设置 ``path``，该字段对 WebSocket 连接而言非常有用。
+通过 :cpp:class:`address <esp_mqtt_client_config_t::broker_t::address_t>` 结构体的 :cpp:member:`uri <esp_mqtt_client_config_t::broker_t::address_t::uri>` 字段或者 :cpp:member:`hostname <esp_mqtt_client_config_t::broker_t::address_t::hostname>`、:cpp:member:`transport <esp_mqtt_client_config_t::broker_t::address_t::transport>` 以及 :cpp:member:`port <esp_mqtt_client_config_t::broker_t::address_t::port>` 的组合，可以设置服务器地址。您也可以选择设置 :cpp:member:`path <esp_mqtt_client_config_t::broker_t::address_t::path>`，该字段对 WebSocket 连接而言非常有用。
 
-使用 ``uri`` 字段的格式为 ``scheme://hostname:port/path``。
+使用 :cpp:member:`uri <esp_mqtt_client_config_t::broker_t::address_t::uri>` 字段的格式为 ``scheme://hostname:port/path``。
 
 - 当前支持 ``mqtt``、``mqtts``、``ws`` 和 ``wss`` 协议
 - 基于 TCP 的 MQTT 示例：
@@ -90,12 +100,16 @@ ESP-MQTT 是 `MQTT <https://mqtt.org/>`_ 协议客户端的实现。MQTT 是一
 验证
 =============
 
-为验证服务器身份，对于使用 TLS 的安全链接，必须设置 ``broker.verification`` 结构体。
-服务器证书可设置为 PEM 或 DER 格式。如要选择 DER 格式，必须设置等效 ``_len`` 字段，否则应在 ``certificate`` 字段传入以空字符结尾的 PEM 格式字符串。
+为验证服务器身份，对于使用 TLS 的安全链接，必须设置 :cpp:class:`verification <esp_mqtt_client_config_t::broker_t::verification_t>` 结构体。
+服务器证书可设置为 PEM 或 DER 格式。如要选择 DER 格式，必须设置等效 :cpp:member:`certificate_len <esp_mqtt_client_config_t::broker_t::verification_t::certificate_len>` 字段，否则应在 :cpp:member:`certificate <esp_mqtt_client_config_t::broker_t::verification_t::certificate>` 字段传入以空字符结尾的 PEM 格式字符串。
 
 -  从服务器获取证书，例如：``mqtt.eclipseprojects.io``
-   ``openssl s_client -showcerts -connect mqtt.eclipseprojects.io:8883 </dev/null 2>/dev/null|openssl x509 -outform PEM >mqtt_eclipse_org.pem``
--  检查示例应用程序：``examples/mqtt_ssl``
+    .. code::
+
+       openssl s_client -showcerts -connect mqtt.eclipseprojects.io:8883 < /dev/null \
+       2> /dev/null | openssl x509 -outform PEM > mqtt_eclipse_org.pem
+
+-  检查示例应用程序：:example:`protocols/mqtt/ssl`
 -  配置：
 
 .. code:: c
@@ -112,43 +126,43 @@ ESP-MQTT 是 `MQTT <https://mqtt.org/>`_ 协议客户端的实现。MQTT 是一
 客户端凭据
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-``credentials`` 字段下包含所有客户端相关凭据。
+:cpp:class:`credentials <esp_mqtt_client_config_t::credentials_t>` 字段下包含所有客户端相关凭据。
 
- * ``username``：指向用于连接服务器用户名的指针，也可通过 URI 设置
- * ``client_id``：指向客户端 ID 的指针，默认为 ``ESP32_%CHIPID%``，其中 ``%CHIPID%`` 是十六进制 MAC 地址的最后 3 个字节
+ * :cpp:member:`username <esp_mqtt_client_config_t::credentials_t::username>`：指向用于连接服务器用户名的指针，也可通过 URI 设置
+ * :cpp:member:`client_id <esp_mqtt_client_config_t::credentials_t::client_id>`：指向客户端 ID 的指针，默认为 ``ESP32_%CHIPID%``，其中 ``%CHIPID%`` 是十六进制 MAC 地址的最后 3 个字节
 
 ===============
 认证
 ===============
 
-可以通过 ``authentication`` 字段设置认证参数。客户端支持以下认证方式：
+可以通过 :cpp:class:`authentication <esp_mqtt_client_config_t::credentials_t::authentication_t>` 字段设置认证参数。客户端支持以下认证方式：
 
- * ``authentication.password``：使用密码
- * ``authentication.certificate`` 和 ``authentication.key``：进行双向 TLS 身份验证，PEM 或 DER 格式均可
- * ``authentication.use_secure_element``：使用 ESP32-WROOM-32SE 中的安全元素
- * ``authentication.ds_data``：使用某些乐鑫设备的数字签名外设
+ * :cpp:member:`password <esp_mqtt_client_config_t::credentials_t::authentication_t::password>`：使用密码
+ * * :cpp:member:`certificate <esp_mqtt_client_config_t::credentials_t::authentication_t::certificate>` 和 :cpp:member:`key <esp_mqtt_client_config_t::credentials_t::authentication_t::key>`：进行双向 TLS 身份验证，PEM 或 DER 格式均可
+ * :cpp:member:`use_secure_element <esp_mqtt_client_config_t::credentials_t::authentication_t::use_secure_element>`：使用 ESP32-WROOM-32SE 中的安全元素
+ * :cpp:member:`ds_data <esp_mqtt_client_config_t::credentials_t::authentication_t::ds_data>`：使用某些乐鑫设备的数字签名外设
 
 会话
 ^^^^^^^^^^^^
 
-使用 ``section`` 字段进行 MQTT 会话相关配置。
+使用 :cpp:class:`session <esp_mqtt_client_config_t::session_t>` 字段进行 MQTT 会话相关配置。
 
 ========================
 遗嘱消息 (LWT)
 ========================
 
-通过设置 ``esp_mqtt_client_config_t.session.last_will`` 结构体的以下字段，MQTT 会在一个客户端意外断开连接时通过遗嘱消息通知其他客户端。
+通过设置 :cpp:class:`last_will <esp_mqtt_client_config_t::session_t::last_will_t>` 结构体的以下字段，MQTT 会在一个客户端意外断开连接时通过遗嘱消息通知其他客户端。
 
- * ``topic``：指向 LWT 消息主题的指针
- * ``msg``：指向 LWT 消息的指针
- * ``msg_len``：LWT 消息的长度，``msg`` 不以空字符结尾时需要该字段
- * ``qos``：LWT 消息的服务质量
- * ``retain``：指定 LWT 消息的保留标志
+ * :cpp:member:`topic <esp_mqtt_client_config_t::session_t::last_will_t::topic>`：指向 LWT 消息主题的指针
+ * :cpp:member:`msg <esp_mqtt_client_config_t::session_t::last_will_t::msg>`：指向 LWT 消息的指针
+ * :cpp:member:`msg_len <esp_mqtt_client_config_t::session_t::last_will_t::msg_len>`：LWT 消息的长度，:cpp:member:`msg <esp_mqtt_client_config_t::session_t::last_will_t::msg>` 不以空字符结尾时需要该字段
+ * :cpp:member:`qos <esp_mqtt_client_config_t::session_t::last_will_t::qos>`：LWT 消息的服务质量
+ * :cpp:member:`retain <esp_mqtt_client_config_t::session_t::last_will_t::retain>`：指定 LWT 消息的保留标志
 
 在项目配置菜单中设置 MQTT
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-通过 ``idf.py menuconfig``，可以在 ``Component config`` > ``ESP-MQTT Configuration`` 中找到 MQTT 设置。
+通过 :code:`idf.py menuconfig`，可以在 ``Component config`` > ``ESP-MQTT Configuration`` 中找到 MQTT 设置。
 
 相关设置如下：
 
@@ -169,8 +183,8 @@ MQTT 客户端可能会发布以下事件：
 * ``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`` 结构体的哪些部分会被填充。
+* ``MQTT_EVENT_DATA``：客户端已收到发布消息。事件数据包含：消息 ID、发布消息所属主题名称、收到的数据及其长度。对于超出内部缓冲区的数据，将发布多个 ``MQTT_EVENT_DATA``，并更新事件数据的 :cpp:member:`current_data_offset <esp_mqtt_event_t::current_data_offset>` 和 :cpp:member:`total_data_len<esp_mqtt_event_t::total_data_len>` 以跟踪碎片化消息。
+* ``MQTT_EVENT_ERROR``：客户端遇到错误。使用事件数据 :cpp:type:`error_handle <esp_mqtt_error_codes_t>` 字段中的 :cpp:type:`error_type <esp_mqtt_error_type_t>`，可以发现错误。错误类型决定 :cpp:type:`error_handle <esp_mqtt_error_codes_t>` 结构体的哪些部分会被填充。
 
 API 参考
 -------------