Merge branch 'docs/add_timeout_param_for_cipstart_and_cipdomain' into…

… 'master' docs: Added a timeout parameter for AT+CIPSTART and AT+CIPDOMAIN command See merge request application/esp-at!1602
espressif · Oct 18, 2024 · 3c053c2 · 3c053c2
2 parents 6103b20 + c626e10
commit 3c053c2
Show file tree

Hide file tree

Showing 2 changed files with 46 additions and 18 deletions.
diff --git a/docs/en/AT_Command_Set/TCP-IP_AT_Commands.rst b/docs/en/AT_Command_Set/TCP-IP_AT_Commands.rst
@@ -221,7 +221,7 @@ Set Command
 
 ::
 
-    AT+CIPDOMAIN=<"domain name">[,<ip network>]
+    AT+CIPDOMAIN=<"domain name">[,<ip network>][,<timeout>]
 
 **Response:**
 
@@ -242,6 +242,7 @@ Parameter
    - 3: resolve IPv6 address only
 
 -  **<"IP address">**: the resolved IPv4 address or IPv6 address.
+-  **<timeout>**: Command timeout. Unit: milliseconds. Default value: 0. Range: [0,60000]. When set to 0, the command timeout depends on the network and lwIP protocol stack; when set to a non-zero value, the command will return within the specified timeout, but it will consume about 5 KB more heap space.
 
 Example
 ^^^^^^^^
@@ -283,10 +284,10 @@ Set Command
 ::
 
     // Single connection (AT+CIPMUX=0):
-    AT+CIPSTART=<"type">,<"remote host">,<remote port>[,<keep_alive>][,<"local IP">]
+    AT+CIPSTART=<"type">,<"remote host">,<remote port>[,<keep_alive>][,<"local IP">][,<timeout>]
 
     // Multiple Connections (AT+CIPMUX=1):
-    AT+CIPSTART=<link ID>,<"type">,<"remote host">,<remote port>[,<keep_alive>][,<"local IP">]
+    AT+CIPSTART=<link ID>,<"type">,<"remote host">,<remote port>[,<keep_alive>][,<"local IP">][,<timeout>]
 
 **Response:**
 
@@ -323,6 +324,7 @@ Parameters
    - This parameter of this command is the same as the ``<keep_alive>`` parameter of :ref:`AT+CIPTCPOPT <cmd-TCPOPT>` command. It always takes the value set later by either of the two commands. If it is omitted or not set, the last configured value is used by default.
 
 -  **<"local IP">**: the local IPv4 address or IPv6 address that the connection binds. This parameter is useful when you are using multiple network interfaces or multiple IP addresses. By default, it is disabled. If you want to use it, you should specify it first. Null is also valid.
+-  **<timeout>**: Command timeout. Unit: milliseconds. Default value: 0. Range: [0,60000]. When set to 0, the command timeout depends on the network and lwIP protocol stack; when set to a non-zero value, the command will return within the specified timeout, but it will consume about 5 KB more heap space.
 
 Notes
 """"""
@@ -343,6 +345,10 @@ Example
     AT+CIPSTART="TCP","192.168.101.110",1000
     AT+CIPSTART="TCP","192.168.101.110",2500,60
     AT+CIPSTART="TCP","192.168.101.110",1000,,"192.168.101.100"
+
+    // Connect to GitHub's TCP server with a 5-second timeout
+    AT+CIPSTART="TCP","www.github.com",80,,,5000
+
     AT+CIPSTART="TCPv6","test-ipv6.com",80
     AT+CIPSTART="TCPv6","fe80::860d:8eff:fe9d:cd90",1000,,"fe80::411c:1fdb:22a6:4d24"
 
@@ -362,10 +368,10 @@ Set Command
 ::
 
     // Single connection (AT+CIPMUX=0):
-    AT+CIPSTART=<"type">,<"remote host">,<remote port>[,<local port>,<mode>,<"local IP">]
+    AT+CIPSTART=<"type">,<"remote host">,<remote port>[,<local port>,<mode>,<"local IP">][,<timeout>]
 
     // Multiple connections (AT+CIPMUX=1):
-    AT+CIPSTART=<link ID>,<"type">,<"remote host">,<remote port>[,<local port>,<mode>,<"local IP">]
+    AT+CIPSTART=<link ID>,<"type">,<"remote host">,<remote port>[,<local port>,<mode>,<"local IP">][,<timeout>]
 
 **Response:**
 
@@ -400,6 +406,7 @@ Parameters
    -  2: Each time UDP data is received, the ``<"remote host">`` and ``<remote port>`` will be changed to the IP address and port of the device that sends the data.
 
 -  **<"local IP">**: the local IPv4 address or IPv6 address that the connection binds. This parameter is useful when you are using multiple network interfaces or multiple IP addresses. By default, it is disabled. If you want to use it, you should specify it first. Null is also valid.
+-  **<timeout>**: Command timeout. Unit: milliseconds. Default value: 0. Range: [0,60000]. When set to 0, the command timeout depends on the network and lwIP protocol stack; when set to a non-zero value, the command will return within the specified timeout, but it will consume about 5 KB more heap space.
 
 Notes
 """"""
@@ -426,6 +433,9 @@ Example
     AT+CIPSTART="UDP","192.168.101.110",1000,1002,2
     AT+CIPSTART="UDP","192.168.101.110",1000,,,"192.168.101.100"
 
+    // Establish UDP transmission with pool.ntp.org, set 5-second timeout
+    AT+CIPSTART="UDP","pool.ntp.org",123,,,,5000
+
     // UDP unicast based on IPv6 network
     AT+CIPSTART="UDPv6","fe80::32ae:a4ff:fe80:65ac",1000,,,"fe80::5512:f37f:bb03:5d9b"
 
@@ -445,10 +455,10 @@ Set Command
 ::
 
     // Single connection (AT+CIPMUX=0):
-    AT+CIPSTART=<"type">,<"remote host">,<remote port>[,<keep_alive>,<"local IP">]
+    AT+CIPSTART=<"type">,<"remote host">,<remote port>[,<keep_alive>,<"local IP">][,<timeout>]
 
     // Multiple connections (AT+CIPMUX=1):
-    AT+CIPSTART=<link ID>,<"type">,<"remote host">,<remote port>[,<keep_alive>,<"local IP">]
+    AT+CIPSTART=<link ID>,<"type">,<"remote host">,<remote port>[,<keep_alive>,<"local IP">][,<timeout>]
 
 **Response:**
 
@@ -485,6 +495,7 @@ Parameters
    - This parameter of this command is the same as the ``<keep_alive>`` parameter of :ref:`AT+CIPTCPOPT <cmd-TCPOPT>` command. It always takes the value set later by either of the two commands. If it is omitted or not set, the last configured value is used by default.
 
 -  **<"local IP">**: the local IPv4 address or IPv6 address that the connection binds. This parameter is useful when you are using multiple network interfaces or multiple IP addresses. By default, it is disabled. If you want to use it, you should specify it first. Null is also valid.
+-  **<timeout>**: Command timeout. Unit: milliseconds. Default value: 0. Range: [0,60000]. When set to 0, the command timeout depends on the network and lwIP protocol stack; when set to a non-zero value, the command will return within the specified timeout, but it will consume about 5 KB more heap space.
 
 Notes
 """"""
@@ -508,6 +519,9 @@ Example
     AT+CIPSTART="SSL","iot.espressif.cn",8443
     AT+CIPSTART="SSL","192.168.101.110",1000,,"192.168.101.100"
 
+    // Connect to Microsoft Bing's SSL server with a 5-second timeout
+    AT+CIPSTART="SSL","www.bing.com",443,,,5000
+
     // esp-at has obtained an IPv6 global address by AT+CWJAP before
     AT+CIPSTART="SSLv6","240e:3a1:2070:11c0:6972:6f96:9147:d66d",1000,,"240e:3a1:2070:11c0:55ce:4e19:9649:b75"
 

diff --git a/docs/zh_CN/AT_Command_Set/TCP-IP_AT_Commands.rst b/docs/zh_CN/AT_Command_Set/TCP-IP_AT_Commands.rst
@@ -221,7 +221,7 @@ TCP/IP AT 命令
 
 ::
 
-    AT+CIPDOMAIN=<"domain name">[,<ip network>]
+    AT+CIPDOMAIN=<"domain name">[,<ip network>][,<timeout>]
 
 **响应：**
 
@@ -241,7 +241,8 @@ TCP/IP AT 命令
    - 2：只解析为 IPv4 地址
    - 3：只解析为 IPv6 地址
 
--  **<"IP address">**：解析出的 IP 地址
+-  **<"IP address">**：解析后的 IPv4 地址或 IPv6 地址
+-  **<timeout>**：命令超时。单位：毫秒。默认值：0。范围：[0,60000]。设置为 0 时，命令的超时依赖于网络和 lwIP 协议栈；设置为非 0 时，命令会在指定超时内返回，但会多消耗约 5 KB 的堆空间。
 
 示例
 ^^^^
@@ -283,10 +284,10 @@ TCP/IP AT 命令
 ::
 
     // 单连接 (AT+CIPMUX=0):
-    AT+CIPSTART=<"type">,<"remote host">,<remote port>[,<keep_alive>][,<"local IP">]
+    AT+CIPSTART=<"type">,<"remote host">,<remote port>[,<keep_alive>][,<"local IP">][,<timeout>]
 
     // 多连接 (AT+CIPMUX=1):
-    AT+CIPSTART=<link ID>,<"type">,<"remote host">,<remote port>[,<keep_alive>][,<"local IP">]
+    AT+CIPSTART=<link ID>,<"type">,<"remote host">,<remote port>[,<keep_alive>][,<"local IP">][,<timeout>]
 
 **响应：**
 
@@ -322,7 +323,8 @@ TCP/IP AT 命令
 
   -  本命令中的 ``<keep_alive>`` 参数与 :ref:`AT+CIPTCPOPT <cmd-TCPOPT>` 命令中的 ``<keep_alive>`` 参数相同，最终值由后设置的命令决定。如果运行本命令时不设置 ``<keep_alive>`` 参数，则默认使用上次配置的值。
 
--  **<"local IP">**：连接绑定的本机 IPv4 地址或 IPv6 地址，该参数在本地多网络接口时和本地多 IP 地址时非常有用。默认为禁用，如果您想使用，需自行设置，空值也为有效值
+-  **<"local IP">**：本地的 IPv4 地址或 IPv6 地址，用于绑定连接。使用多个网络接口或多个 IP 地址时，此参数非常有用。默认为禁用。如需使用请先自行设置。可设置为空。
+-  **<timeout>**：命令超时。单位：毫秒。默认值：0。范围：[0,60000]。设置为 0 时，命令的超时依赖于网络和 lwIP 协议栈；设置为非 0 时，命令会在指定超时内返回，但会多消耗约 5 KB 的堆空间。
 
 说明
 """"""
@@ -343,6 +345,10 @@ TCP/IP AT 命令
     AT+CIPSTART="TCP","192.168.101.110",1000
     AT+CIPSTART="TCP","192.168.101.110",2500,60
     AT+CIPSTART="TCP","192.168.101.110",1000,,"192.168.101.100"
+
+    // 连接 GitHub 的 TCP 服务器，设置 5 秒超时
+    AT+CIPSTART="TCP","www.github.com",80,,,5000
+
     AT+CIPSTART="TCPv6","test-ipv6.com",80
     AT+CIPSTART="TCPv6","fe80::860d:8eff:fe9d:cd90",1000,,"fe80::411c:1fdb:22a6:4d24"
 
@@ -362,10 +368,10 @@ TCP/IP AT 命令
 ::
 
     // 单连接：(AT+CIPMUX=0)
-    AT+CIPSTART=<"type">,<"remote host">,<remote port>[,<local port>,<mode>,<"local IP">]
+    AT+CIPSTART=<"type">,<"remote host">,<remote port>[,<local port>,<mode>,<"local IP">][,<timeout>]
 
     // 多连接：(AT+CIPMUX=1)
-    AT+CIPSTART=<link ID>,<"type">,<"remote host">,<remote port>[,<local port>,<mode>,<"local IP">]
+    AT+CIPSTART=<link ID>,<"type">,<"remote host">,<remote port>[,<local port>,<mode>,<"local IP">][,<timeout>]
 
 **响应：**
 
@@ -399,7 +405,8 @@ TCP/IP AT 命令
    -  1: 仅第一次接收到与初始设置不同的对端 UDP 数据时，改变对端 UDP 地址信息为发送数据设备的 IP 地址和端口
    -  2: 每次接收到 UDP 数据时，都改变对端 UDP 地址信息为发送数据的设备的 IP 地址和端口
 
--  **<"local IP">**：连接绑定的本机 IPv4 地址或 IPv6 地址，该参数在本地多网络接口时和本地多 IP 地址时非常有用。默认为禁用，如果您想使用，需自行设置，空值也为有效值
+-  **<"local IP">**：本地的 IPv4 地址或 IPv6 地址，用于绑定连接。使用多个网络接口或多个 IP 地址时，此参数非常有用。默认为禁用。如需使用请先自行设置。可设置为空。
+-  **<timeout>**：命令超时。单位：毫秒。默认值：0。范围：[0,60000]。设置为 0 时，命令的超时依赖于网络和 lwIP 协议栈；设置为非 0 时，命令会在指定超时内返回，但会多消耗约 5 KB 的堆空间。
 
 说明
 """""
@@ -426,6 +433,9 @@ TCP/IP AT 命令
     AT+CIPSTART="UDP","192.168.101.110",1000,1002,2
     AT+CIPSTART="UDP","192.168.101.110",1000,,,"192.168.101.100"
 
+    // 建立和 pool.ntp.org 的 UDP 传输，设置 5 秒超时
+    AT+CIPSTART="UDP","pool.ntp.org",123,,,,5000
+
     // 基于 IPv6 网络的 UDP 单播
     AT+CIPSTART="UDPv6","fe80::32ae:a4ff:fe80:65ac",1000,,,"fe80::5512:f37f:bb03:5d9b"
 
@@ -445,10 +455,10 @@ TCP/IP AT 命令
 ::
 
     // 单连接：(AT+CIPMUX=0)
-    AT+CIPSTART=<"type">,<"remote host">,<remote port>[,<keep_alive>,<"local IP">]
+    AT+CIPSTART=<"type">,<"remote host">,<remote port>[,<keep_alive>,<"local IP">][,<timeout>]
 
     // 多连接：(AT+CIPMUX=1)
-    AT+CIPSTART=<link ID>,<"type">,<"remote host">,<remote port>[,<keep_alive>,<"local IP">]
+    AT+CIPSTART=<link ID>,<"type">,<"remote host">,<remote port>[,<keep_alive>,<"local IP">][,<timeout>]
 
 **响应：**
 
@@ -484,7 +494,8 @@ TCP/IP AT 命令
 
   -  本命令中的 ``<keep_alive>`` 参数与 :ref:`AT+CIPTCPOPT <cmd-TCPOPT>` 命令中的 ``<keep_alive>`` 参数相同，最终值由后设置的命令决定。如果运行本命令时不设置 ``<keep_alive>`` 参数，则默认使用上次配置的值。
 
--  **<"local IP">**：连接绑定的本机 IPv4 地址或 IPv6 地址，该参数在本地多网络接口时和本地多 IP 地址时非常有用。默认为禁用，如果您想使用，需自行设置，空值也为有效值
+-  **<"local IP">**：本地的 IPv4 地址或 IPv6 地址，用于绑定连接。使用多个网络接口或多个 IP 地址时，此参数非常有用。默认为禁用。如需使用请先自行设置。可设置为空。
+-  **<timeout>**：命令超时。单位：毫秒。默认值：0。范围：[0,60000]。设置为 0 时，命令的超时依赖于网络和 lwIP 协议栈；设置为非 0 时，命令会在指定超时内返回，但会多消耗约 5 KB 的堆空间。
 
 说明
 """"""
@@ -508,6 +519,9 @@ TCP/IP AT 命令
     AT+CIPSTART="SSL","iot.espressif.cn",8443
     AT+CIPSTART="SSL","192.168.101.110",1000,,"192.168.101.100" 
 
+    // 连接微软必应的 SSL 服务器，设置 5 秒超时
+    AT+CIPSTART="SSL","www.bing.com",443,,,5000
+
     // esp-at 已通过 AT+CWJAP 获取到 IPv6 全局地址
     AT+CIPSTART="SSLv6","240e:3a1:2070:11c0:6972:6f96:9147:d66d",1000,,"240e:3a1:2070:11c0:55ce:4e19:9649:b75"