Skip to content

Commit 5f1e951

Browse files
ustccwustccw
committed
docs: add AT+HTTPCGET and AT+HTTPURLCFG command docs
1 parent e2baa28 commit 5f1e951

File tree

4 files changed

+217
-22
lines changed

4 files changed

+217
-22
lines changed

‎docs/en/AT_Command_Set/HTTP_AT_Commands.rst‎

Lines changed: 100 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,9 @@ HTTP AT Commands
77

88
- :ref:`AT+HTTPCLIENT <cmd-HTTPCLIENT>`: Send HTTP Client Request
99
- :ref:`AT+HTTPGETSIZE <cmd-HTTPGETSIZE>`: Get HTTP Resource Size
10+
- :ref:`AT+HTTPCGET <cmd-HTTPCGET>`: Get HTTP Resource
1011
- :ref:`AT+HTTPCPOST <cmd-HTTPCPOST>`: Post HTTP data of specified length
12+
- :ref:`AT+HTTPURLCFG <cmd-HTTPURLCFG>`: Set/Get long HTTP URL
1113
- :ref:`HTTP AT Error Codes <cmd-HTTPErrCode>`
1214

1315
.. _cmd-HTTPCLIENT:
@@ -63,6 +65,7 @@ Parameters
6365

6466
Notes
6567
^^^^^
68+
- If the length of the entire command containing the URL exceeds 256 bytes, please use the :ref:`AT+HTTPURLCFG <cmd-HTTPURLCFG>` command to preset the URL first, and then set the <"url"> parameter of this command to ``""``.
6669
- If the ``url`` parameter is not null, HTTP client will use it and ignore the ``host`` parameter and ``path`` parameter; If the ``url`` parameter is omited or null string, HTTP client will use ``host`` parameter and ``path`` parameter.
6770
- In some released firmware, HTTP client commands are not supported (see :doc:`../Compile_and_Develop/esp-at_firmware_differences`), but you can enable it by ``./build.py menuconfig`` > ``Component config`` > ``AT`` > ``AT http command support`` and build the project (see :doc:`../Compile_and_Develop/How_to_clone_project_and_compile_it`).
6871

@@ -93,7 +96,7 @@ Set Command
9396

9497
::
9598

96-
AT+HTTPGETSIZE=<url>
99+
AT+HTTPGETSIZE=<"url">
97100

98101
**Response:**
99102

@@ -105,12 +108,13 @@ Set Command
105108

106109
Parameters
107110
^^^^^^^^^^
108-
- **<url>**: HTTP URL.
111+
- **<"url">**: HTTP URL. It is a string parameter and should be enclosed with quotes.
109112
- **<size>**: HTTP resource size.
110113

111114
Note
112115
^^^^^
113116

117+
- If the length of the entire command containing the URL exceeds 256 bytes, please use the :ref:`AT+HTTPURLCFG <cmd-HTTPURLCFG>` command to preset the URL first, and then set the <"url"> parameter of this command to ``""``.
114118
- In some released firmware, HTTP client commands are not supported (see :doc:`../Compile_and_Develop/esp-at_firmware_differences`), but you can enable it by ``./build.py menuconfig`` > ``Component config`` > ``AT`` > ``AT http command support`` and build the project (see :doc:`../Compile_and_Develop/How_to_clone_project_and_compile_it`).
115119

116120
Example
@@ -120,6 +124,39 @@ Example
120124

121125
AT+HTTPGETSIZE="http://www.baidu.com/img/bdlogo.gif"
122126

127+
.. _cmd-HTTPCGET:
128+
129+
:ref:`AT+HTTPCGET <HTTP-AT>`: Get HTTP Resource
130+
-----------------------------------------------
131+
132+
Set Command
133+
^^^^^^^^^^^
134+
135+
**Command:**
136+
137+
::
138+
139+
AT+HTTPCGET=<"url">[,<tx size>][,<rx size>][,<timeout>]
140+
141+
**Response:**
142+
143+
::
144+
145+
+HTTPCGET:<size>,<data>
146+
OK
147+
148+
Parameters
149+
^^^^^^^^^^
150+
- **<"url">**: HTTP URL. It is a string parameter and should be enclosed with quotes.
151+
- **<tx size>**: HTTP send buffer size. Unit: byte. Default: 2048. Range: [0,10240].
152+
- **<rx size>**: HTTP receive buffer size. Unit: byte. Default: 2048. Range: [0,10240].
153+
- **<timeout>**: Network timeout. Unit: millisecond. Default: 5000. Range: [0,180000].
154+
155+
Note
156+
^^^^^
157+
158+
- If the length of the entire command containing the URL exceeds 256 bytes, please use the :ref:`AT+HTTPURLCFG <cmd-HTTPURLCFG>` command to preset the URL first, and then set the <"url"> parameter of this command to ``""``.
159+
123160
.. _cmd-HTTPCPOST:
124161

125162
:ref:`AT+HTTPCPOST <HTTP-AT>`: Post HTTP data of specified length
@@ -132,13 +169,14 @@ Set Command
132169

133170
::
134171

135-
AT+HTTPCPOST=<url>,<length>[,<http_req_header_cnt>][,<http_req_header>..<http_req_header>]
172+
AT+HTTPCPOST=<"url">,<length>[,<http_req_header_cnt>][,<http_req_header>..<http_req_header>]
136173

137174
**Response:**
138175

139176
::
140177

141178
OK
179+
142180
>
143181

144182
The symbol ``>`` indicates that AT is ready for receiving serial data, and you can enter the data now. When the requirement of message length determined by the parameter ``<length>`` is met, the transmission starts.
@@ -157,11 +195,69 @@ Otherwise, it returns:
157195

158196
Parameters
159197
^^^^^^^^^^
160-
- **<url>**: HTTP URL.
198+
- **<"url">**: HTTP URL. It is a string parameter and should be enclosed with quotes.
161199
- **<length>**: HTTP data length to POST. The maximum length is equal to the system allocable heap size.
162200
- **<http_req_header_cnt>**: the number of <http_req_header> parameters.
163201
- **[<http_req_header>]**: you can send more than one request header to the server.
164202

203+
Note
204+
^^^^^
205+
206+
- If the length of the entire command containing the URL exceeds 256 bytes, please use the :ref:`AT+HTTPURLCFG <cmd-HTTPURLCFG>` command to preset the URL first, and then set the <"url"> parameter of this command to ``""``.
207+
208+
.. _cmd-HTTPURLCFG:
209+
210+
:ref:`AT+HTTPURLCFG <HTTP-AT>`: Set/Get long HTTP URL
211+
-----------------------------------------------------
212+
213+
Query Command
214+
^^^^^^^^^^^^^
215+
216+
**Command:**
217+
218+
::
219+
220+
AT+HTTPURLCFG?
221+
222+
**Response:**
223+
224+
::
225+
226+
[+HTTPURLCFG:<url length>,<data>]
227+
OK
228+
229+
Set Command
230+
^^^^^^^^^^^
231+
232+
**Command:**
233+
234+
::
235+
236+
AT+HTTPURLCFG=<url length>
237+
238+
**Response:**
239+
240+
::
241+
242+
OK
243+
244+
>
245+
246+
This response indicates that AT is ready for receiving serial data. You should enter the URL now, and when the URL length reaches the ``<url length>`` value, the system returns:
247+
248+
::
249+
250+
SET OK
251+
252+
Parameters
253+
^^^^^^^^^^
254+
- **<url length>**: HTTP URL length. Unit: byte.
255+
256+
- 0: clean the HTTP URL configuration.
257+
- [8,8192]: set the HTTP URL configuration.
258+
259+
- **<data>**: HTTP URL data.
260+
165261
.. _cmd-HTTPErrCode:
166262

167263
:ref:`HTTP AT Error Codes <HTTP-AT>`

‎docs/en/AT_Command_Set/index.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,8 @@ There are two types of ESP-AT messages returned from the ESP-AT command port:
132132
- Data has been sent to the protocol stack (specific to :ref:`AT+CIPSEND <cmd-SEND>` and :ref:`AT+CIPSENDEX <cmd-SENDEX>` command). It doesn't mean that the data has been sent to the opposite end
133133
* - SEND FAIL
134134
- Error occurred during sending the data to the protocol stack (specific to :ref:`AT+CIPSEND <cmd-SEND>` and :ref:`AT+CIPSENDEX <cmd-SENDEX>` command
135+
* - SET OK
136+
- The URL has been set successfully (specific to :ref:`AT+HTTPURLCFG <cmd-HTTPURLCFG>` command)
135137
* - +<Command Name>:``...``
136138
- Response to the sender that describes AT command process results in details
137139

‎docs/zh_CN/AT_Command_Set/HTTP_AT_Commands.rst‎

Lines changed: 113 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,9 @@ HTTP AT 命令集
77

88
- :ref:`AT+HTTPCLIENT <cmd-HTTPCLIENT>`：发送 HTTP 客户端请求
99
- :ref:`AT+HTTPGETSIZE <cmd-HTTPGETSIZE>`：获取 HTTP 资源大小
10+
- :ref:`AT+HTTPCGET <cmd-HTTPCGET>`：获取 HTTP 资源
1011
- :ref:`AT+HTTPCPOST <cmd-HTTPCPOST>`：Post 指定长度的 HTTP 数据
12+
- :ref:`AT+HTTPURLCFG <cmd-HTTPURLCFG>`：设置/获取长的 HTTP URL
1113
- :ref:`HTTP AT 错误码 <cmd-HTTPErrCode>`
1214

1315
.. _cmd-HTTPCLIENT:
@@ -37,33 +39,33 @@ HTTP AT 命令集
3739

3840
- **<opt>**：HTTP 客户端请求方法：
3941

40-
- 1: HEAD
41-
- 2: GET
42-
- 3: POST
43-
- 4: PUT
44-
- 5: DELETE
42+
- 1：HEAD
43+
- 2：GET
44+
- 3：POST
45+
- 4：PUT
46+
- 5：DELETE
4547

4648
- **<content-type>**：客户端请求数据类型：
4749

48-
- 0: ``application/x-www-form-urlencoded``
49-
- 1: ``application/json``
50-
- 2: ``multipart/form-data``
51-
- 3: ``text/xml``
50+
- 0：``application/x-www-form-urlencoded``
51+
- 1：``application/json``
52+
- 2：``multipart/form-data``
53+
- 3：``text/xml``
5254

5355
- **<"url">**：HTTP URL，当后面的 ``<host>`` 和 ``<path>`` 参数为空时，本参数会自动覆盖这两个参数。
5456
- **<"host">**：域名或 IP 地址。
5557
- **<"path">**：HTTP 路径。
5658
- **<transport_type>**：HTTP 客户端传输类型，默认值为 1：
5759

58-
- 1: ``HTTP_TRANSPORT_OVER_TCP``
59-
- 2: ``HTTP_TRANSPORT_OVER_SSL``
60+
- 1：``HTTP_TRANSPORT_OVER_TCP``
61+
- 2：``HTTP_TRANSPORT_OVER_SSL``
6062

61-
- **<"data">**: 当 ``<opt>`` 是 POST 请求时，本参数为发送给 HTTP 服务器的数据。当 ``<opt>`` 不是 POST 请求时，这个参数不存在（也就是，不需要输入逗号来表示有这个参数）。
62-
- **<"http_req_header">**: 可发送多个请求头给服务器。
63+
- **<"data">**：当 ``<opt>`` 是 POST 请求时，本参数为发送给 HTTP 服务器的数据。当 ``<opt>`` 不是 POST 请求时，这个参数不存在（也就是，不需要输入逗号来表示有这个参数）。
64+
- **<"http_req_header">**：可发送多个请求头给服务器。
6365

6466
说明
6567
^^^^
66-
68+
- 如果包含 URL 的整条命令的长度超过了 256 字节，请先使用 :ref:`AT+HTTPURLCFG <cmd-HTTPURLCFG>` 命令预配置 URL，然后本命令里的 <"url"> 参数需要设置为 ``""``。
6769
- 如果 ``url`` 参数不为空，HTTP 客户端将使用它并忽略 ``host`` 参数和 ``path`` 参数；如果 ``url`` 参数被省略或字符串为空，HTTP 客户端将使用 ``host`` 参数和 ``path`` 参数。
6870
- 某些已发布的固件默认不支持 HTTP 客户端命令（详情请见 :doc:`../Compile_and_Develop/esp-at_firmware_differences`），但是可通过以下方式使其支持该命令：``./build.py menuconfig`` > ``Component config`` > ``AT`` > ``AT http command support``，然后编译项目（详情请见 :doc:`../Compile_and_Develop/How_to_clone_project_and_compile_it`）。
6971

@@ -94,7 +96,7 @@ HTTP AT 命令集
9496

9597
::
9698

97-
AT+HTTPGETSIZE=<url>
99+
AT+HTTPGETSIZE=<"url">
98100

99101
**响应：**
100102

@@ -106,12 +108,13 @@ HTTP AT 命令集
106108

107109
参数
108110
^^^^
109-
- **<url>**：HTTP URL。
111+
- **<"url">**：HTTP URL。
110112
- **<size>**：HTTP 资源大小。
111113

112114
说明
113115
^^^^
114116

117+
- 如果包含 URL 的整条命令的长度超过了 256 字节，请先使用 :ref:`AT+HTTPURLCFG <cmd-HTTPURLCFG>` 命令预配置 URL，然后本命令里的 <"url"> 参数需要设置为 ``""``。
115118
- 某些已发布的固件默认不支持 HTTP 客户端命令（详情请见 :doc:`../Compile_and_Develop/esp-at_firmware_differences`），但是可通过以下方式使其支持该命令：``./build.py menuconfig`` > ``Component config`` > ``AT`` > ``AT http command support``，然后编译项目（详情请见 :doc:`../Compile_and_Develop/How_to_clone_project_and_compile_it`）。
116119

117120
示例
@@ -121,6 +124,39 @@ HTTP AT 命令集
121124

122125
AT+HTTPGETSIZE="http://www.baidu.com/img/bdlogo.gif"
123126

127+
.. _cmd-HTTPCGET:
128+
129+
:ref:`AT+HTTPCGET <HTTP-AT>`：获取 HTTP 资源
130+
-----------------------------------------------
131+
132+
设置命令
133+
^^^^^^^^^^^
134+
135+
**命令：**
136+
137+
::
138+
139+
AT+HTTPCGET=<"url">[,<tx size>][,<rx size>][,<timeout>]
140+
141+
**响应：**
142+
143+
::
144+
145+
+HTTPCGET:<size>,<data>
146+
OK
147+
148+
参数
149+
^^^^^^^^^^
150+
- **<"url">**：HTTP URL。
151+
- **<tx size>**：HTTP 发送缓存大小。单位：字节。默认值：2048。范围：[0,10240]。
152+
- **<rx size>**：HTTP 接收缓存大小。单位：字节。默认值：2048。范围：[0,10240]。
153+
- **<timeout>**：网络超时。单位：毫秒。默认值：5000。范围：[0,180000]。
154+
155+
说明
156+
^^^^^
157+
158+
- 如果包含 URL 的整条命令的长度超过了 256 字节，请先使用 :ref:`AT+HTTPURLCFG <cmd-HTTPURLCFG>` 命令预配置 URL，然后本命令里的 <"url"> 参数需要设置为 ``""``。
159+
124160
.. _cmd-HTTPCPOST:
125161

126162
:ref:`AT+HTTPCPOST <HTTP-AT>`：Post 指定长度的 HTTP 数据
@@ -133,13 +169,14 @@ HTTP AT 命令集
133169

134170
::
135171

136-
AT+HTTPCPOST=<url>,<length>[,<http_req_header_cnt>][,<http_req_header>..<http_req_header>]
172+
AT+HTTPCPOST=<"url">,<length>[,<http_req_header_cnt>][,<http_req_header>..<http_req_header>]
137173

138174
**响应：**
139175

140176
::
141177

142178
OK
179+
143180
>
144181

145182
符号 ``>`` 表示 AT 准备好接收串口数据，此时您可以输入数据，当数据长度达到参数 ``<length>`` 的值时，传输开始。
@@ -158,11 +195,69 @@ HTTP AT 命令集
158195

159196
参数
160197
^^^^
161-
- **<url>**：HTTP URL。
198+
- **<"url">**：HTTP URL。
162199
- **<length>**：需 POST 的 HTTP 数据长度。最大长度等于系统可分配的堆空间大小。
163200
- **<http_req_header_cnt>**：``<http_req_header>`` 参数的数量。
164201
- **[<http_req_header>]**：可发送多个请求头给服务器。
165202

203+
说明
204+
^^^^^
205+
206+
- 如果包含 URL 的整条命令的长度超过了 256 字节，请先使用 :ref:`AT+HTTPURLCFG <cmd-HTTPURLCFG>` 命令预配置 URL，然后本命令里的 <"url"> 参数需要设置为 ``""``。
207+
208+
.. _cmd-HTTPURLCFG:
209+
210+
:ref:`AT+HTTPURLCFG <HTTP-AT>`：设置/获取长的 HTTP URL
211+
----------------------------------------------------------
212+
213+
查询命令
214+
^^^^^^^^^^^^^
215+
216+
**命令：**
217+
218+
::
219+
220+
AT+HTTPURLCFG?
221+
222+
**响应：**
223+
224+
::
225+
226+
[+HTTPURLCFG:<url length>,<data>]
227+
OK
228+
229+
设置命令
230+
^^^^^^^^^^^
231+
232+
**命令：**
233+
234+
::
235+
236+
AT+HTTPURLCFG=<url length>
237+
238+
**响应：**
239+
240+
::
241+
242+
OK
243+
244+
>
245+
246+
符号 > 表示 AT 准备好接收串口数据，此时您可以输入 URL，当数据长度达到参数 ``<url length>`` 的值时，系统返回：
247+
248+
::
249+
250+
SET OK
251+
252+
参数
253+
^^^^^^^^^^
254+
- **<url length>**：HTTP URL 长度。单位：字节。
255+
256+
- 0：清除 HTTP URL 配置。
257+
- [8,8192]：设置 HTTP URL 配置。
258+
259+
- **<data>**： HTTP URL 数据。
260+
166261
.. _cmd-HTTPErrCode:
167262

168263
:ref:`HTTP AT 错误码 <HTTP-AT>`

‎docs/zh_CN/AT_Command_Set/index.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,8 @@ AT 消息
132132
- 数据已发送到协议栈（针对于 :ref:`AT+CIPSEND <cmd-SEND>` 和 :ref:`AT+CIPSENDEX <cmd-SENDEX>` 命令），但不代表数据已经发到对端
133133
* - SEND FAIL
134134
- 向协议栈发送数据时发生错误（针对于 :ref:`AT+CIPSEND <cmd-SEND>` 和 :ref:`AT+CIPSENDEX <cmd-SENDEX>` 命令）
135+
* - SET OK
136+
- URL 已经成功设置（针对于 :ref:`AT+HTTPURLCFG <cmd-HTTPURLCFG>` 命令）
135137
* - +<Command Name>:``...``
136138
- 详细描述 AT 命令处理结果
137139

0 commit comments

Comments
 (0)