Merge branch 'docs/update_at_faq' into 'master'

docs: update at faq

See merge request application/esp-at!1582

docs/en/AT_Binary_Lists/esp_at_binaries.rst

@@ -18,7 +18,15 @@ It is recommended to use the lastest version of firmware. Currently, Espressif r
     - The AT firmware versions v2.2.0.0 to v3.2.0.0 support the {IDF_TARGET_NAME} ECO0 (Rev v0.0) to ECO4 (Rev v0.4) series chips (including ECO0 and ECO4).
     - The AT firmware version v3.3.0.0 supports the {IDF_TARGET_NAME} ECO0 (Rev v0.0) to ECO4 (Rev v0.4), ECO6 (Rev v1.0), and ECO7 (Rev v1.1) series chips.
 
-  - 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`.
+  .. only:: esp32 or esp32c2
+
+    - If you are unsure which AT firmware your module should use, please read the :doc:`../Compile_and_Develop/esp-at_firmware_differences` document first. This document compares the differences among different {IDF_TARGET_NAME} AT firmwares in terms of supported command sets, hardware configurations, and module compatibility, helping you determine if there is a suitable firmware for your module's hardware configuration.
+
+  .. only:: esp32c3 or esp32c6 or esp32s2
+
+    - If you are unsure whether your module can use the default AT firmware, please read the :doc:`../Compile_and_Develop/esp-at_firmware_differences` document first. This document compares the differences among different {IDF_TARGET_NAME} AT firmwares in terms of supported command sets, hardware configurations, and module compatibility, helping you confirm if your module's hardware configuration is suitable for using the default AT firmware.
+
+  - If you need to modify the following configurations, you can generate a new firmware by modifying the AT firmware using the :doc:`../Compile_and_Develop/tools_at_py`.
 
     .. list::
 
@@ -27,6 +35,13 @@ It is recommended to use the lastest version of firmware. Currently, Espressif r
       - :ref:`at-py-modify-pki`
       :esp32 or esp32c2 or esp32c3 or esp32c6: - :ref:`at-py-modify-gatts`
 
+  .. only:: esp32c2
+
+    - Currently, {IDF_TARGET_NAME} AT released firmware does not support most of :ref:`Bluetooth® Low Energy AT Commands <BLE-AT>` (excluding BluFi commands). If you only need to use :ref:`Basic AT Commands <Basic-AT>` and :ref:`Bluetooth® Low Energy AT Commands <BLE-AT>` on {IDF_TARGET_NAME}, follow the steps described in :doc:`How_to_download_the_latest_temporary_version_of_AT_from_github <../Compile_and_Develop/How_to_build_project_with_web_page>` to directly download the esp32c2-ble-2mb-at firmware, or compile this firmware by yourself following the steps in the :doc:`How_to_clone_project_and_compile_it <../Compile_and_Develop/How_to_clone_project_and_compile_it>` (Note: When setting up the environment in step three of the document, choose ESP32C2-BLE-2MB).
+
+        - This firmware currently does not support OTA function.
+        - AT firmware on GitHub will automatically expire after 6 months, so please save the downloaded AT firmware.
+
 .. only:: esp32
 
   ESP32-WROOM-32 Series

docs/en/AT_Command_Examples/TCP-IP_AT_Examples.rst

@@ -1728,6 +1728,8 @@ UART Wi-Fi passthrough transmission when the {IDF_TARGET_NAME} works as a softAP
 
      OK
 
+.. _example-passive_recv:
+
 {IDF_TARGET_NAME} obtains socket data in passive receiving mode
 -----------------------------------------------------------------------
 

docs/en/AT_Command_Set/HTTP_AT_Commands.rst

@@ -399,6 +399,8 @@ Note
 - The HTTP request headers configured by this command are global. Once set, all HTTP commands will carry these request headers.
 - If the ``key`` in the HTTP request header set by this command is the same as that of other HTTP commands, the HTTP request header set by this command will be used.
 
+.. _cmd-HTTPCHEAD_example:
+
 Example
 ^^^^^^^
 

docs/en/AT_Command_Set/TCP-IP_AT_Commands.rst

@@ -2220,6 +2220,13 @@ Parameters
 -  **<"remote IP">**: string parameter showing the remote IPv4 address or IPv6 address, enabled by the command :ref:`AT+CIPDINFO=1 <cmd-IPDINFO>`.
 -  **<remote port>**: the remote port number, enabled by the command :ref:`AT+CIPDINFO=1 <cmd-IPDINFO>`.
 
+Note
+^^^^^
+
+- The command needs to be executed in passive receive mode. Otherwise, ERROR is returned. You can verify whether AT is in passive receive mode by using the :ref:`AT+CIPRECVTYPE <cmd-CIPRECVTYPE>` command.
+- When this command is executed without any data available to read, it will directly return ERROR. You can verify if there is readable data at that time by using the :ref:`AT+CIPRECVLEN? <cmd-CIPRECVLEN>` command.
+- When executing the command ``AT+CIPRECVDATA=<len>``, at least ``<len> + 128`` bytes of memory are required. You can use the command :ref:`AT+SYSRAM? <Basic-AT>` to check the current available memory. When insufficient memory leads to a memory allocation failure, this command will also return ERROR. You can review the :doc:`AT log output </Get_Started/Hardware_connection>` for ``alloc fail`` or similar print messages to confirm whether a memory allocation failure has occurred.
+
 Example
 ^^^^^^^^
 

docs/en/faq.rst

@@ -290,3 +290,11 @@ How to enable debug log for AT?
     - Enable Wi-Fi debug: ``./build.py menuconfig`` > ``Component config`` > ``Wi-Fi`` > ``Wi-Fi debug log level`` set to ``Debug``.
     - Enable TCP/IP debug: ``./build.py menuconfig`` > ``Component config`` > ``LWIP`` > ``Enable LWIP Debug`` > Set the log level of the specific part you want to debug to ``Debug``.
     - Enable Bluetooth LE debug: ``./build.py menuconfig`` > ``Component config`` > ``Bluetooth`` > ``Bluedroid Options`` > ``Disable BT debug logs`` > ``BT DEBUG LOG LEVEL`` > Set the log level of the specific part you want to debug to ``Debug``.
+
+How does the AT command implement the functionality of resuming HTTP transfers after interrupts?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  - Currently, AT commands provide two methods:
+
+    - Specify the data range to be read using the HTTP Range field. For specific details, please refer to the example of :ref:`AT+HTTPCHEAD <cmd-HTTPCHEAD_example>`.
+    - You can construct an HTTP GET request using AT TCP series commands. Between steps 6 and 7 of the example :ref:`{IDF_TARGET_NAME} obtains socket data in passive receiving mode <example-passive_recv>`, add a step: Use the :ref:`AT+CIPSEND <cmd-SEND>` command to send your own HTTP GET request header to the server. In passive receive mode, for HTTP GET request data received from the server, the MCU needs to actively send the :ref:`AT+CIPRECVDATA <cmd-CIPRECVDATA>` command to read the data. This helps avoid situations where the MCU may be unable to process data promptly due to large amounts of data being transferred from the server.

docs/zh_CN/AT_Binary_Lists/esp_at_binaries.rst

@@ -18,7 +18,15 @@
     - v2.2.0.0 ~ v3.2.0.0 版本的 AT 固件均支持 {IDF_TARGET_NAME} ECO0 (Rev v0.0) ~ ECO4 (Rev v0.4) 系列芯片（包括 ECO0 和 ECO4）。
     - v3.3.0.0 版本的 AT 固件支持 {IDF_TARGET_NAME} ECO0 (Rev v0.0) ~ ECO4 (Rev v0.4)、ECO6 (Rev v1.0)、ECO7 (Rev v1.1) 系列芯片。
 
-  - 如果您的模组没有发布的固件，可以使用相同硬件配置的模组的固件（点击 :doc:`../Compile_and_Develop/esp-at_firmware_differences` 查看与您的模组硬件配置相同的固件），或者如果您需要修改下面的配置，则可以通过 :doc:`../Compile_and_Develop/tools_at_py` 修改发布的固件，为您的模组生成新的固件。
+  .. only:: esp32 or esp32c2
+
+    - 如果您不确定自己的模组应该使用哪个 AT 固件，请先阅读 :doc:`../Compile_and_Develop/esp-at_firmware_differences` 文档，该文档比较了不同 {IDF_TARGET_NAME} AT 固件在支持的命令集、硬件配置和模组方面的差异，帮助您确认是否有适合您模组硬件配置的固件。
+
+  .. only:: esp32c3 or esp32c6 or esp32s2
+
+    - 如果您不确定自己的模组是否可以使用 AT 默认固件，请先阅读 :doc:`../Compile_and_Develop/esp-at_firmware_differences` 文档，该文档比较了不同 {IDF_TARGET_NAME} AT 固件在支持的命令集、硬件配置和模组方面的差异，帮助您确认您的模组硬件配置是否适合使用 AT 默认固件。
+
+  - 如果您想要修改 AT 固件中下面的配置，您可以通过 :doc:`../Compile_and_Develop/tools_at_py` 修改 AT 固件并生成新的 AT 固件。
 
     .. list::
 
@@ -27,6 +35,13 @@
       - :ref:`at-py-modify-pki`
       :esp32 or esp32c2 or esp32c3 or esp32c6: - :ref:`at-py-modify-gatts`
 
+  .. only:: esp32c2
+
+    - 目前，所有发布的 {IDF_TARGET_NAME} AT 固件尚不支持大部分的 :ref:`Bluetooth® Low Energy AT 命令 <BLE-AT>` （BluFi 命令支持），如果您在 {IDF_TARGET_NAME} 上只需要使用 :ref:`基础 AT 命令 <Basic-AT>` 和 :ref:`Bluetooth® Low Energy AT 命令 <BLE-AT>`，可以根据 :doc:`如何从 GitHub Actions 里下载 ESP-AT 固件文档 <../Compile_and_Develop/How_to_build_project_with_web_page>` 的流程直接下载 ``esp32c2-ble-2mb-at`` 固件，或者根据 :doc:`本地编译 ESP-AT 工程文档 <../Compile_and_Develop/How_to_clone_project_and_compile_it>` 自行编译此固件（注意：在文档的第三步安装环境时，请选择 ESP32C2-BLE-2MB）。
+
+        - 此固件不支持 OTA 功能。
+        - GitHub 上的 AT 固件会在到达 6 个月有效期后自动失效，请自行保存下载的 AT 固件。
+
 .. only:: esp32
 
   ESP32-WROOM-32 系列

docs/zh_CN/AT_Command_Examples/TCP-IP_AT_Examples.rst

@@ -1728,6 +1728,8 @@ TCP-IP AT 示例
 
      OK
 
+.. _example-passive_recv:
+
 {IDF_TARGET_NAME} 设备获取被动接收模式下的套接字数据
 -----------------------------------------------------------
 

docs/zh_CN/AT_Command_Set/HTTP_AT_Commands.rst

@@ -399,6 +399,8 @@ HTTP AT 命令集
 - 本命令配置的 HTTP 请求头是全局性的，一旦设置，所有 HTTP 的命令都会携带这些请求头。
 - 本命令设置的 HTTP 请求头中的 ``key`` 如果和其它 HTTP 命令的请求头中的 ``key`` 相同，则会使用本命令中设置的 HTTP 请求头。
 
+.. _cmd-HTTPCHEAD_example:
+
 示例
 ^^^^
 

docs/zh_CN/AT_Command_Set/TCP-IP_AT_Commands.rst

@@ -2220,6 +2220,13 @@ ESP-AT 在运行时，通过 Wi-Fi 从指定的服务器上下载新固件到某
 -  **[<remote IP>]**：字符串参数，表示对端 IP 地址，通过 :ref:`AT+CIPDINFO=1 <cmd-IPDINFO>` 命令使能。
 -  **[<remote port>]**：对端端口，通过 :ref:`AT+CIPDINFO=1 <cmd-IPDINFO>` 命令使能。
 
+说明
+^^^^
+
+- 该命令需要在被动接收模式下执行，否则会直接返回 ERROR，可以通过 :ref:`AT+CIPRECVTYPE? <cmd-CIPRECVTYPE>` 命令确认是否是在被动接收模式。
+- 该命令在没有数据可读的情况下执行时会直接返回 ERROR，可以通过 :ref:`AT+CIPRECVLEN? <cmd-CIPRECVLEN>` 命令确认此时是否有可读数据。
+- 执行 ``AT+CIPRECVDATA=<len>`` 命令时，至少需要 ``<len> + 128`` 字节的内存，您可以使用命令 :ref:`AT+SYSRAM? <Basic-AT>` 查询当前可用内存情况。当内存不足导致内存申请失败时此命令也会返回 ERROR。你可以通过 :doc:`AT 输出日志口 </Get_Started/Hardware_connection>` 查看是否有类似 ``alloc fail`` 的打印信息，以确认是否出现了内存分配失败的情况。
+
 示例
 ^^^^
 

docs/zh_CN/faq.rst

@@ -97,7 +97,7 @@ Wi-Fi 常见的兼容性问题有哪些？
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
   - AMPDU 兼容性问题。
-  
+
     - 如果路由器不支持 AMPDU，那么 {IDF_TARGET_NAME} 会在和路由器交互时，自动关闭 AMPDU 功能。
     - 如果路由器支持 AMPDU，但是路由器和 {IDF_TARGET_NAME} 之间的 AMPDU 传输存在兼容性问题，那么建议关闭路由器的 AMPDU 功能或者 {IDF_TARGET_NAME} 的 AMPDU 功能。如果您要禁用 {IDF_TARGET_NAME} 的 AMPDU 功能，请自行 :doc:`编译 ESP-AT 工程 <../Compile_and_Develop/How_to_clone_project_and_compile_it>`，在第五步配置工程里选择：
 
@@ -290,3 +290,11 @@ AT 如何使能调试日志？
     - 使能 Wi-Fi debug： ``./build.py menuconfig`` > ``Component config`` > ``Wi-Fi`` > ``Wi-Fi debug log level`` 设置到 ``Debug``。
     - 使能 TCP/IP debug： ``./build.py menuconfig`` > ``Component config`` > ``LWIP`` > ``Enable LWIP Debug`` > 将具体想要调试的部分 log 等级设置到 ``Debug``。
     - 使能 BLE debug： ``./build.py menuconfig`` > ``Component config`` > ``Bluetooth`` > ``Bluedroid Options`` > ``Disable BT debug logs`` > ``BT DEBUG LOG LEVEL`` > 将具体想要调试的部分 log 等级设置到 ``Debug``。
+
+AT 指令如何实现 HTTP 断点续传功能？
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  - 目前 AT 指令提供两种方法：
+
+    - 通过 HTTP 的 Range 字段指定读取的数据范围，具体详情请参考 :ref:`AT+HTTPCHEAD 示例 <cmd-HTTPCHEAD_example>`。
+    - 可以使用 AT TCP 系列指令自行构造 HTTP GET 请求。在 :ref:`{IDF_TARGET_NAME} 设备获取被动接收模式下的套接字数据示例 <example-passive_recv>` 的第 6 步和第 7 步之间，添加一步：设备使用 :ref:`AT+CIPSEND <cmd-SEND>` 命令发送您自行构造的 HTTP GET 请求包给服务端即可。在被动接收模式下，对于从服务端获取的 HTTP GET 请求数据，MCU 需要通过主动下发 :ref:`AT+CIPRECVDATA <cmd-CIPRECVDATA>` 命令来读取这些数据，以避免因服务端传输大量数据而导致 MCU 端无法及时处理的情况。