Merge branch 'docs/update_at_docs' into 'master'

docs: Updated a serial of at docs See merge request application/esp-at!1474
espressif · Dec 12, 2023 · 48519f9 · 48519f9
2 parents 4bb5844 + 90c7a50
commit 48519f9
Show file tree

Hide file tree

Showing 17 changed files with 93 additions and 41 deletions.
diff --git a/README.md b/README.md
@@ -43,7 +43,7 @@ The AT command firmware allows for rapid integration by providing:
 
 - ESP32-C6 Series
   - **Preferred recommended chip for using ESP-AT on**
-  - The first version of ESP-AT firmware (v4.0.0.0) is planned to be released in October 2023.
+  - The first version of ESP-AT firmware (v4.0.0.0) is planned to be released in December 2023.
 
 - ESP32 Series
   - Recommended released version: [v3.2.0.0](https://github.com/espressif/esp-at/releases/tag/v3.2.0.0)
@@ -98,7 +98,7 @@ esp-at 作为由 Espressif Systems (@[espressif](https://github.com/espressif/))
 
 - ESP32-C6 系列
   - **ESP-AT 首选推荐芯片**
-  - 计划在 2023 年 10 月发布首版 ESP-AT 固件（v4.0.0.0）
+  - 计划在 2023 年 12 月发布首版 ESP-AT 固件（v4.0.0.0）
 
 - ESP32 系列
   - 推荐使用的发布版本：[v3.2.0.0](https://github.com/espressif/esp-at/releases/tag/v3.2.0.0)

diff --git a/docs/en/AT_Binary_Lists/ESP32-C3_AT_binaries.rst b/docs/en/AT_Binary_Lists/ESP32-C3_AT_binaries.rst
@@ -6,12 +6,14 @@ Released Firmware
 It is recommended to use the lastest version of firmware. Currently, Espressif only releases AT firmware for the following {IDF_TARGET_NAME} series of modules. 
 
 .. note::
-  If there is no released firmware for your module, you can either use the firmware for the module that has the same hardware configuration as yours (see :doc:`../Compile_and_Develop/esp-at_firmware_differences` for which module has the same configuration), or if you need to modify the following configurations, you can generate a new firmware for your module by modifying the released firmware using the :doc:`../Compile_and_Develop/tools_at_py`.
+  - The current {IDF_TARGET_NAME} AT firmware supports ECO0 (Rev v0.0) to ECO4 (Rev v0.4) chip versions (including ECO0 and ECO4), but does not support {IDF_TARGET_NAME} ECO6 (Rev v1.0), ECO7 (Rev v1.1), and subsequent versions.
 
-  * :ref:`at-py-modify-uart`
-  * :ref:`at-py-modify-wifi`
-  * :ref:`at-py-modify-pki`
-  * :ref:`at-py-modify-gatts`
+  - If there is no released firmware for your module, you can either use the firmware for the module that has the same hardware configuration as yours (see :doc:`../Compile_and_Develop/esp-at_firmware_differences` for which module has the same configuration), or if you need to modify the following configurations, you can generate a new firmware for your module by modifying the released firmware using the :doc:`../Compile_and_Develop/tools_at_py`.
+
+    * :ref:`at-py-modify-uart`
+    * :ref:`at-py-modify-wifi`
+    * :ref:`at-py-modify-pki`
+    * :ref:`at-py-modify-gatts`
 
 ESP32-C3-MINI-1 Series
 ^^^^^^^^^^^^^^^^^^^^^^

diff --git a/docs/en/AT_Binary_Lists/ESP32-C6_AT_binaries.rst b/docs/en/AT_Binary_Lists/ESP32-C6_AT_binaries.rst
@@ -3,4 +3,4 @@ Released Firmware
 
 :link_to_translation:`zh_CN:[中文]`
 
-- The first version of ESP-AT firmware (v4.0.0.0) is planned to be released in October 2023.
+- The first version of ESP-AT firmware (v4.0.0.0) is planned to be released in December 2023.
diff --git a/docs/en/AT_Command_Set/Basic_AT_Commands.rst b/docs/en/AT_Command_Set/Basic_AT_Commands.rst
@@ -208,7 +208,7 @@ Set Command
 
 ::
 
-    AT+GSLP=<time>  
+    AT+GSLP=<time>
 
 **Response:**
 
@@ -221,10 +221,17 @@ Set Command
 Parameter
 ^^^^^^^^^^
 
--  **<time>**: the duration when the device stays in Deep-sleep. Unit: millisecond. When the time is up, the device automatically wakes up, calls Deep-sleep wake stub, and then proceeds to load the application.
+-  **<time>**: The duration when the device stays in Deep-sleep. Unit: millisecond. When the time is up, the device automatically wakes up, calls Deep-sleep wake stub, and then proceeds to load the application.
 
-    - 0 means restarting right now
-    - the maximum Deep-sleep time is about 28.8 days (2 :sup:`31`-1 milliseconds)
+   .. only:: esp32c3 or esp32c2 or esp32
+
+       - 0 means restarting right now
+
+   .. only:: esp32c6
+
+       - The minimum Deep-sleep time is 5 milliseconds
+
+    - The maximum Deep-sleep time is about 28.8 days (2 :sup:`31`-1 milliseconds)
 
 Notes
 ^^^^^^

diff --git a/docs/en/AT_Command_Set/MQTT_AT_Commands.rst b/docs/en/AT_Command_Set/MQTT_AT_Commands.rst
@@ -258,7 +258,7 @@ Parameters
    -  1: disable clean session.
 
 -  **<lwt_topic>**: LWT (Last Will and Testament) message topic. Maximum length: 128 bytes.
--  **<lwt_msg>**: LWT message. Maximum length: 64 bytes.
+-  **<lwt_msg>**: LWT message. Maximum length: 128 bytes.
 -  **<lwt_qos>**: LWT QoS, which can be set to 0, 1, or 2. Default: 0.
 -  **<lwt_retain>**: LWT retain, which can be set to 0 or 1. Default: 0.
 

diff --git a/docs/en/AT_Command_Set/TCP-IP_AT_Commands.rst b/docs/en/AT_Command_Set/TCP-IP_AT_Commands.rst
@@ -263,6 +263,12 @@ Example
 :ref:`AT+CIPSTART <TCPIP-AT>`: Establish TCP Connection, UDP Transmission, or SSL Connection
 --------------------------------------------------------------------------------------------
 
+* :ref:`esp-at-cipstart-tcp`
+* :ref:`esp-at-cipstart-udp`
+* :ref:`esp-at-cipstart-ssl`
+
+.. _esp-at-cipstart-tcp:
+
 Establish TCP Connection
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -302,7 +308,7 @@ Parameters
 
 -  **<link ID>**: ID of network connection (0~4), used for multiple connections. The range of this parameter depends on two configuration items in ``menuconfig``. One is ``AT_SOCKET_MAX_CONN_NUM`` of the ``AT`` component, and its default value is 5. The other is ``LWIP_MAX_SOCKETS`` of the ``LWIP`` component, and its default value is 10. To modify the range of this parameter, you need to set ``AT_SOCKET_MAX_CONN_NUM`` and make sure it is no larger than the value of ``LWIP_MAX_SOCKETS``. (See :doc:`../Compile_and_Develop/How_to_clone_project_and_compile_it` for details on configuring and build ESP-AT projects.)
 -  **<"type">**: string parameter showing the type of transmission: "TCP", or "TCPv6". Default: "TCP".
--  **<"remote host">**: IPv4 address, IPv6 address, or domain name of remote host. The maximum length is 64 bytes.
+-  **<"remote host">**: IPv4 address, IPv6 address, or domain name of remote host. The maximum length is 64 bytes. If you need to use a domain name and the length of the domain name exceeds 64 bytes, use the :ref:`AT+CIPDOMAIN <cmd-DOMAIN>` command to obtain the IP address corresponding to the domain name, and then use the IP address to establish a connection.
 -  **<remote port>**: the remote port number.
 -  **<keep_alive>**: It configures the `SO_KEEPALIVE <https://man7.org/linux/man-pages/man7/socket.7.html#SO_KEEPALIVE>`__ option for socket. Unit: second.
 
@@ -340,6 +346,8 @@ Example
     // esp-at has obtained an IPv6 global address by AT+CWJAP before
     AT+CIPSTART="TCPv6","2404:6800:4005:80b::2004",80,,"240e:3a1:2070:11c0:32ae:a4ff:fe80:65ac"
 
+.. _esp-at-cipstart-udp:
+
 Establish UDP Transmission
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -379,7 +387,7 @@ Parameters
 
 -  **<link ID>**: ID of network connection (0~4), used for multiple connections.
 -  **<"type">**: string parameter showing the type of transmission: "UDP", or "UDPv6". Default: "TCP".
--  **<"remote host">**: IPv4 address, IPv6 address, or domain name of remote host. The maximum length is 64 bytes.
+-  **<"remote host">**: IPv4 address, IPv6 address, or domain name of remote host. The maximum length is 64 bytes. If you need to use a domain name and the length of the domain name exceeds 64 bytes, use the :ref:`AT+CIPDOMAIN <cmd-DOMAIN>` command to obtain the IP address corresponding to the domain name, and then use the IP address to establish a connection.
 -  **<remote port>**: remote port number.
 -  **<local port>**: UDP port of {IDF_TARGET_NAME}.
 -  **<mode>**: In the UDP Wi-Fi passthrough, the value of this parameter has to be 0.
@@ -421,6 +429,8 @@ Example
     // UDP multicast based on IPv6 network
     AT+CIPSTART="UDPv6","FF02::FC",1000,1002,0
 
+.. _esp-at-cipstart-ssl:
+
 Establish SSL Connection
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -460,7 +470,7 @@ Parameters
 
 -  **<link ID>**: ID of network connection (0~4), used for multiple connections.
 -  **<"type">**: string parameter showing the type of transmission: "SSL", or "SSLv6". Default: "TCP".
--  **<"remote host">**: IPv4 address, IPv6 address, or domain name of remote host. The maximum length is 64 bytes.
+-  **<"remote host">**: IPv4 address, IPv6 address, or domain name of remote host. The maximum length is 64 bytes. If you need to use a domain name and the length of the domain name exceeds 64 bytes, use the :ref:`AT+CIPDOMAIN <cmd-DOMAIN>` command to obtain the IP address corresponding to the domain name, and then use the IP address to establish a connection.
 -  **<remote port>**: the remote port number.
 -  **<keep_alive>**: It configures the `SO_KEEPALIVE <https://man7.org/linux/man-pages/man7/socket.7.html#SO_KEEPALIVE>`__ option for socket. Unit: second.
 
@@ -1635,7 +1645,7 @@ Notes
 -  After you upgrade the AT firmware, you are suggested to call the command :ref:`AT+RESTORE <cmd-RESTORE>` to restore the factory default settings.
 -  The timeout of OTA process is ``3`` minutes.
 -  The response ``OK`` in non-blocking mode does not necessarily come before the response ``+CIPUPDATE:<state>``. It may be output before ``+CIPUPDATE:<state>`` or after it.
--  Upgraded to an older version is not recommended.
+-  Downgrading to an older version is not recommended due to potential compatibility issues and the risk of operational failure. If you still prefer downgrading to an older version, please test and verify the functionality based on your product.
 -  Please refer to :doc:`../Compile_and_Develop/How_to_implement_OTA_update` for more OTA commands.
 
 Example
@@ -1645,7 +1655,7 @@ Example
 
     AT+CWMODE=1
     AT+CWJAP="1234567890","1234567890"
-    AT+CIUPDATE  
+    AT+CIUPDATE
     AT+CIUPDATE=1
     AT+CIUPDATE=1,"v1.2.0.0"
     AT+CIUPDATE=1,"v2.2.0.0","mqtt_ca"
@@ -2232,7 +2242,7 @@ Parameters
 Note
 ^^^^^
 
--  For SSL connections, ESP-AT will return the length of the encrypted data, so the returned length will be larger than the real data length.
+-  For SSL connections, the data length returned by ESP-AT may be less than the actual data length.
 
 Example
 ^^^^^^^^

diff --git a/docs/en/AT_Command_Set/user_at_commands.rst b/docs/en/AT_Command_Set/user_at_commands.rst
@@ -172,6 +172,7 @@ Note
 
 -  The speed of the upgrade depends on the network status.
 -  If the upgrade fails due to unfavorable network conditions, AT will return ``ERROR``. Please wait for some time before retrying.
+-  Downgrading to an older version is not recommended due to potential compatibility issues and the risk of operational failure. If you still prefer downgrading to an older version, please test and verify the functionality based on your product.
 -  After you upgrade the AT firmware, you are suggested to call the command AT+RESTORE to restore the factory default settings.
 -  ``AT+USEROTA`` supports ``HTTP`` and ``HTTPS``.
 -  After AT outputs the ``>`` character, the special characters in the URL does not need to be escaped through the escape character, and it does not need to end with a new line(CR-LF).

diff --git a/docs/en/AT_Command_Set/websocket_at_commands.rst b/docs/en/AT_Command_Set/websocket_at_commands.rst
@@ -104,7 +104,7 @@ Set Command
 
 ::
 
-    AT+WSOPEN=<link_id>,<"uri">[,<"subprotocol">][,<timeout_ms>]
+    AT+WSOPEN=<link_id>,<"uri">[,<"subprotocol">][,<timeout_ms>][,<"auth">]
 
 **Response:**
 
@@ -135,6 +135,7 @@ Parameters
 - **<"uri">**: Uniform resource identifier of WebSocket server.
 - **<"subprotocol">**: The subprotocol of WebSocket (refer to `RFC6455 1.9 part <https://www.rfc-editor.org/rfc/rfc6455#section-1.9>`_ for more details).
 - **<timeout_ms>**: Timeout for establishing a WebSocket connection. Unit: millisecond. Range: [0,180000]. Default: 15000.
+- **<"auth">**: The authorization of WebSocket (refer to `RFC6455 4.1.12 part <https://www.rfc-editor.org/rfc/rfc6455#section-4.1>`_ for more details).
 
 Example
 ^^^^^^^

diff --git a/docs/en/faq.rst b/docs/en/faq.rst
@@ -86,7 +86,12 @@ What commands are supported by the default ESP-AT firmware on different modules,
 When the host MCU sends an AT command to the {IDF_TARGET_NAME} device, there is no response. What is the reason?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-  A terminator ("AT\r\n") must be added after an AT command when the host MCU sending AT commands to an {IDF_TARGET_NAME} device. Please see :ref:`check-whether-at-works`.
+  A terminator ("AT\\r\\n") must be added after an AT command when the host MCU sending AT commands to an {IDF_TARGET_NAME} device. Please see :ref:`check-whether-at-works`.
+
+Why is Wi-Fi disconnected (``WIFI DISCONNECT`` printed)?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  You can check the Wi-Fi disconnection reason code on the :term:`AT log port`, which usually prints ``wifi disconnected, rc:<reason_code>``. The ``<reason_code>`` here refers to `Wi-Fi Reason Code <https://docs.espressif.com/projects/esp-idf/en/latest/{IDF_TARGET_PATH_NAME}/api-guides/wifi.html#wi-fi-reason-code>`_.
 
 Do AT commands support ESP-WIFI-MESH?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -141,7 +146,7 @@ Can the serial port baudrate be modified in AT Commands? (Default: 115200)
 After {IDF_TARGET_NAME} enters the passthrough mode using AT commands, can {IDF_TARGET_NAME} give a message if the connected hotspot is disconnected?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-  - Yes, you can configure it with :ref:`AT+SYSMSG <cmd-SYSMSG>`, i.e., set AT+SYSMSG=4. In this way, the serial port will report "WIFI DISCONNECT\r\n" when the connected hotspot is disconnected.
+  - Yes, you can configure it with :ref:`AT+SYSMSG <cmd-SYSMSG>`, i.e., set AT+SYSMSG=4. In this way, the serial port will report ``WIFI DISCONNECT\\r\\n`` when the connected hotspot is disconnected.
   - Note that this command is added after AT v2.1.0. It is not available for v2.1.0 and earlier versions.
 
 .. only:: esp32

diff --git a/docs/zh_CN/AT_Binary_Lists/ESP32-C3_AT_binaries.rst b/docs/zh_CN/AT_Binary_Lists/ESP32-C3_AT_binaries.rst
@@ -6,12 +6,14 @@
 推荐下载最新版本的固件。目前，乐鑫只发布了以下 {IDF_TARGET_NAME} 系列模组的 AT 固件。
 
 .. note::
-  如果您的模组没有发布的固件，可以使用相同硬件配置的模组的固件（点击 :doc:`../Compile_and_Develop/esp-at_firmware_differences` 查看与您的模组硬件配置相同的固件），或者如果您需要修改下面的配置，则可以通过 :doc:`../Compile_and_Develop/tools_at_py` 修改发布的固件，为您的模组生成新的固件。
+  - 当前的 {IDF_TARGET_NAME} AT 固件支持 {IDF_TARGET_NAME} ECO0 (Rev v0.0) ~ ECO4 (Rev v0.4) 系列芯片（包括 ECO0 和 ECO4），暂不支持 {IDF_TARGET_NAME} 的 ECO6 (Rev v1.0)、ECO7 (Rev v1.1) 以及之后的芯片。
 
-  * :ref:`at-py-modify-uart`
-  * :ref:`at-py-modify-wifi`
-  * :ref:`at-py-modify-pki`
-  * :ref:`at-py-modify-gatts`
+  - 如果您的模组没有发布的固件，可以使用相同硬件配置的模组的固件（点击 :doc:`../Compile_and_Develop/esp-at_firmware_differences` 查看与您的模组硬件配置相同的固件），或者如果您需要修改下面的配置，则可以通过 :doc:`../Compile_and_Develop/tools_at_py` 修改发布的固件，为您的模组生成新的固件。
+
+    * :ref:`at-py-modify-uart`
+    * :ref:`at-py-modify-wifi`
+    * :ref:`at-py-modify-pki`
+    * :ref:`at-py-modify-gatts`
 
 ESP32-C3-MINI-1 系列
 ^^^^^^^^^^^^^^^^^^^^^^

diff --git a/docs/zh_CN/AT_Binary_Lists/ESP32-C6_AT_binaries.rst b/docs/zh_CN/AT_Binary_Lists/ESP32-C6_AT_binaries.rst
@@ -3,4 +3,4 @@
 
 :link_to_translation:`en:[English]`
 
-- 计划在 2023 年 10 月发布首版 ESP-AT 固件 (v4.0.0.0)
+- 计划在 2023 年 12 月发布首版 ESP-AT 固件 (v4.0.0.0)
diff --git a/docs/zh_CN/AT_Command_Set/Basic_AT_Commands.rst b/docs/zh_CN/AT_Command_Set/Basic_AT_Commands.rst
@@ -208,7 +208,7 @@
 
 ::
 
-    AT+GSLP=<time>  
+    AT+GSLP=<time>
 
 **响应：**
 
@@ -222,8 +222,15 @@
 ^^^^
 
 -  **<time>**：设备进入 Deep-sleep 的时长，单位：毫秒。设定时间到后，设备自动唤醒，调用深度睡眠唤醒桩，然后加载应用程序。
-
-   - 0 表示立即重启 
+
+   .. only:: esp32c3 or esp32c2 or esp32
+
+       - 0 表示立即重启
+
+   .. only:: esp32c6
+
+       - 最小 Deep-sleep 时长为 5 毫秒。
+
    - 最大 Deep-sleep 时长约为 28.8 天（2 :sup:`31`-1 毫秒）。
 
 说明

diff --git a/docs/zh_CN/AT_Command_Set/MQTT_AT_Commands.rst b/docs/zh_CN/AT_Command_Set/MQTT_AT_Commands.rst
@@ -258,7 +258,7 @@ MQTT AT 命令集
    -  1: 禁用清理会话
 
 -  **<lwt_topic>**：遗嘱 topic，最大长度：128 字节。
--  **<lwt_msg>**：遗嘱 message，最大长度：64 字节。
+-  **<lwt_msg>**：遗嘱 message，最大长度：128 字节。
 -  **<lwt_qos>**：遗嘱 QoS，参数可选 0、1、2，默认值：0。
 -  **<lwt_retain>**：遗嘱 retain，参数可选 0 或 1，默认值：0。