From fcaf10581c84de3687c920913bf466c9ffc35d59 Mon Sep 17 00:00:00 2001 From: caixinying-git Date: Mon, 31 Jul 2023 16:13:41 +0800 Subject: [PATCH] docs: update format issues for EN and CN under api-reference/protocols and migration-guides --- docs/en/api-reference/protocols/mqtt.rst | 24 ++++++++++++--------- docs/zh_CN/api-reference/protocols/mqtt.rst | 10 ++++++--- 2 files changed, 21 insertions(+), 13 deletions(-) diff --git a/docs/en/api-reference/protocols/mqtt.rst b/docs/en/api-reference/protocols/mqtt.rst index b6e9233..7e8392e 100644 --- a/docs/en/api-reference/protocols/mqtt.rst +++ b/docs/en/api-reference/protocols/mqtt.rst @@ -1,5 +1,6 @@ ESP-MQTT ======== + :link_to_translation:`zh_CN:[中文]` Overview @@ -10,6 +11,7 @@ ESP-MQTT is an implementation of `MQTT `__ protocol client, w Features -------- + * 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) @@ -33,7 +35,7 @@ MQTT Message Retransmission A new MQTT message is created by calling :cpp:func:`esp_mqtt_client_publish ` or its non blocking counterpart :cpp:func:`esp_mqtt_client_enqueue `. -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. +Messages with QoS 0 is 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 ` to true for this behavior). @@ -87,7 +89,7 @@ The :cpp:member:`uri ` field - Minimal configurations: -.. code:: c +.. code-block:: c const esp_mqtt_client_config_t mqtt_cfg = { .broker.address.uri = "mqtt://mqtt.eclipseprojects.io", @@ -96,7 +98,9 @@ The :cpp:member:`uri ` field 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 @@ -137,7 +141,7 @@ All client related credentials are under the :cpp:class:`credentials ` field. The client supports the following authentication methods: +It is possible to set authentication parameters through the :cpp:class:`authentication ` field. The client supports the following authentication methods: * :cpp:member:`password `: use a password by setting * :cpp:member:`certificate ` and :cpp:member:`key `: mutual authentication with TLS, and both can be provided in PEM or DER format @@ -181,12 +185,12 @@ The following events may be posted by the MQTT client: * ``MQTT_EVENT_BEFORE_CONNECT``: The client is initialized and about to start connecting to the broker. * ``MQTT_EVENT_CONNECTED``: The client has successfully established a connection to the broker. The client is now ready to send and receive data. -* ``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 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 :cpp:member:`current_data_offset ` and :cpp:member:`total_data_len` from event data updated to keep track of the fragmented message. -* ``MQTT_EVENT_ERROR``: The client has encountered an error. The field :cpp:type:`error_handle ` in the event data contains :cpp:type:`error_type ` that can be used to identify the error. The type of error will determine which parts of the :cpp:type:`error_handle ` struct is filled. +* ``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 contains the message ID of the subscribe message. +* ``MQTT_EVENT_UNSUBSCRIBED``: The broker has acknowledged the client's unsubscribe request. The event data contains the message ID of the unsubscribe message. +* ``MQTT_EVENT_PUBLISHED``: The broker has acknowledged the client's publish message. This is only posted for QoS level 1 and 2, as level 0 does not use acknowledgements. The event data contains 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`` events are posted and :cpp:member:`current_data_offset ` and :cpp:member:`total_data_len` from event data updated to keep track of the fragmented message. +* ``MQTT_EVENT_ERROR``: The client has encountered an error. The field :cpp:type:`error_handle ` in the event data contains :cpp:type:`error_type ` that can be used to identify the error. The type of error determines which parts of the :cpp:type:`error_handle ` struct is filled. API Reference ------------- diff --git a/docs/zh_CN/api-reference/protocols/mqtt.rst b/docs/zh_CN/api-reference/protocols/mqtt.rst index b3e5cfc..fa0a47b 100644 --- a/docs/zh_CN/api-reference/protocols/mqtt.rst +++ b/docs/zh_CN/api-reference/protocols/mqtt.rst @@ -1,5 +1,6 @@ ESP-MQTT ======== + :link_to_translation:`en:[English]` 概述 @@ -10,6 +11,7 @@ ESP-MQTT 是 `MQTT `__ 协议客户端的实现，MQTT 是一 特性 -------- + * 支持基于 TCP 的 MQTT、基于 Mbed TLS 的 SSL、基于 WebSocket 的 MQTT 以及基于 WebSocket Secure 的 MQTT * 通过 URI 简化配置流程 * 多个实例（一个应用程序中有多个客户端） @@ -60,7 +62,7 @@ ESP-MQTT 库将始终重新传输未确认的 QoS 1 和 2 发布消息，以避 地址 =========== -通过 :cpp:class:`address ` 结构体的 :cpp:member:`uri ` 字段或者 :cpp:member:`hostname `、:cpp:member:`transport ` 以及 :cpp:member:`port ` 的组合，可以设置服务器地址。您也可以选择设置 :cpp:member:`path `，该字段对 WebSocket 连接而言非常有用。 +通过 :cpp:class:`address ` 结构体的 :cpp:member:`uri ` 字段或者 :cpp:member:`hostname `、:cpp:member:`transport ` 以及 :cpp:member:`port ` 的组合，可以设置服务器地址。也可以选择设置 :cpp:member:`path `，该字段对 WebSocket 连接而言非常有用。 使用 :cpp:member:`uri ` 字段的格式为 ``scheme://hostname:port/path``。 @@ -87,7 +89,7 @@ ESP-MQTT 库将始终重新传输未确认的 QoS 1 和 2 发布消息，以避 - 最简配置： -.. code:: c +.. code-block:: c const esp_mqtt_client_config_t mqtt_cfg = { .broker.address.uri = "mqtt://mqtt.eclipseprojects.io", @@ -96,7 +98,9 @@ ESP-MQTT 库将始终重新传输未确认的 QoS 1 和 2 发布消息，以避 esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID, mqtt_event_handler, client); esp_mqtt_client_start(client); -.. note:: 默认情况下，MQTT 客户端使用事件循环库来发布相关 MQTT 事件（已连接、已订阅、已发布等）。 +.. note:: + + 默认情况下，MQTT 客户端使用事件循环库来发布相关 MQTT 事件（已连接、已订阅、已发布等）。 ============= 验证