HTTPD AT 命令集

备注

HTTPD AT 命令默认未启用，且仅在**主控控制模式**下可用。
在 menuconfig 的 CONFIG SHELL → Enable ATCMD → Host Control Mode 中启用 Enable HTTPD (transparent HTTP server to host)。工程还需包含网络/LWIP 组件。
设备作为 HTTP/HTTPS server，将收到的请求上报给 host MCU，由 host 处理后使用 AT+HTTPDRSP 或 AT+HTTPDRSPRAW 回复。
启动 server 前，设备应已连接网络并获得 IP，且 client 能访问该 IP。使用 HTTPS 时，须预先将服务器证书套件放入 VFS 的 /CERT/ 目录，详情请参考 AT 安全证书。

AT+HTTPDCFG

功能说明

配置最大并发连接数、server 线程栈大小，以及等待 host 开始回复的超时时间。应在启动 server 前设置；配置会持续生效，直至再次修改或设备重启。

命令格式

AT+HTTPDCFG=<max_conn>[,<stack>][,<timeout_ms>]

响应格式

成功响应：

OK

错误响应：

ERROR: <error_no>

参数

<max_conn>:

最大并发连接数及待处理请求数。

范围：[1,4]
默认值：2
请求 ID 范围为 0 至 max_conn - 1。

<stack>:

HTTP 请求处理线程的栈大小，单位为字节。

最小值：2048 字节
默认值：4096 字节
若请求处理需要更多栈空间可适当增大；较大的值会占用更多 RAM。

<timeout_ms>:

等待 host 开始回复的时间，单位为毫秒。

范围：[1,120000]
默认值：10000
超时仅适用于 host 开始执行 AT+HTTPDRSP 或 AT+HTTPDRSPRAW 之前。RAW 传输开始后，传输时间不受此超时限制。

错误代码

1：参数缺失或无效
2：HTTPD server 正在运行；修改配置前须先停止 server

示例

将最大并发数设为 3，栈大小和超时沿用默认值：

AT+HTTPDCFG=3
OK

设置全部配置项：

AT+HTTPDCFG=2,4096,30000
OK

AT+HTTPDSTART

功能说明

在指定 TCP 端口启动 HTTP 或 HTTPS server。server 会将 GET、POST 和 PUT 请求转发给 host MCU；host 需要对每个请求进行回复。

命令格式

AT+HTTPDSTART=<port>,<conn_type>[,<cert_index>]

响应格式

成功响应：

[HTTPD][EVENT]:start
OK

错误响应：

ERROR: <error_no>

参数

<port>:

server 监听的 TCP 端口。

范围：[1,65535]
常用端口：HTTP 使用 80，HTTPS 使用 443。

<conn_type>:

传输类型及客户端证书校验策略。

1：普通 TCP/HTTP。
2：TLS/HTTPS；不校验客户端证书。
3：TLS/HTTPS；要求并校验客户端证书（双向 TLS 认证）。

<cert_index>:

服务器证书套件索引。conn_type 为 2 或 3 时必填，范围为 [1,10]。证书套件包含 /CERT/ 下的 server_cert_<index>.crt、server_key_<index>.key 和 server_ca_<index>.crt。两种 TLS 模式都会加载这三个文件；conn_type=3 时还会使用服务器 CA 校验客户端证书。

错误代码

1：参数无效，或 HTTPS 模式未提供有效的 cert_index
2：server 已在运行
3：内存分配失败或证书文件读取失败
4：HTTPD server 启动失败
5：TLS 证书配置或解析失败

示例

在 80 端口启动 HTTP server：

AT+HTTPDSTART=80,1
[HTTPD][EVENT]:start
OK

使用第 1 套服务器证书启动 HTTPS，不校验客户端证书：

AT+HTTPDSTART=443,2,1

启动 HTTPS 并要求客户端提供证书：

AT+HTTPDSTART=443,3,1

AT+HTTPDSTOP

功能说明

停止 HTTPD server。正在等待 host 回复的请求会被唤醒并关闭连接；停止操作中断的请求可能会收到 HTTP 500 响应。

命令格式

AT+HTTPDSTOP

响应格式

server 正在运行时：

[HTTPD][EVENT]:stop
OK

server 未运行时，命令直接返回 OK。

AT+HTTPDQUERY

功能说明

查询 server 状态、当前配置和占用中的请求槽。

命令格式

AT+HTTPDQUERY

响应格式

running: <0|1>
max_conn: <n>
stack: <bytes>
timeout_ms: <ms>
req_id <i>: state <s>     # 仅非空闲请求槽显示此行
OK

请求状态值：1 表示等待 host 回复，2 表示正在通过 RAW 传输响应 body，3 表示内联响应已就绪，4 表示 RAW 响应已发送、连接即将关闭。状态 4 可能只会短暂出现。

AT+HTTPDRSP

功能说明

通过 AT 命令携带响应 body，回复 HTTP 请求。适合空 body 或较短的文本 body。req_id 来自请求上报信息。

命令格式

AT+HTTPDRSP=<req_id>,<status>,<content_type>,<body_len>[,<body>]

响应格式

成功响应：

OK

错误响应：

ERROR: <error_no>

参数

<req_id>:: [HTTPD][REQ] 上报中的请求 ID；范围为 [0, max_conn - 1]。
<status>:: HTTP 状态码；范围为 [100,599]。
<content_type>:: HTTP Content-Type 响应头的值；最多 63 字节，且不能包含逗号。为空时默认为 text/plain。
<body_len>:: body 的字节数。空 body 使用 0。UTF-8 文本应填写编码后的字节数，而不是字符数。
<body>:: 可选的内联响应 body。body_len 大于 0 时必填。body 至少包含 body_len 字节，且不能包含逗号或 CR/LF；如果内容包含这些字符、是二进制数据或 body 较大，请使用 AT+HTTPDRSPRAW。

错误代码

1：参数无效，或内联 body 长度小于 body_len
2：请求 ID 无效，或请求已超时/停止
3：内存分配失败

示例

回复请求 ID 0，body 为 ok：

AT+HTTPDRSP=0,200,text/plain,2,ok
OK

返回空 body 的 404 响应：

AT+HTTPDRSP=0,404,text/plain,0
OK

AT+HTTPDRSPRAW

功能说明

通过透传（TT）模式发送 HTTP 响应 body。设备使用固定大小的中转缓冲区，将指定字节数的数据流式转发给 HTTP client，不需要在 RAM 中缓存完整 body。适用于大 body、二进制内容或包含逗号、换行符等分隔字符的内容。

命令格式

AT+HTTPDRSPRAW=<req_id>,<status>,<content_type>,<body_len>

命令执行后设备返回 >>>。host 随后必须通过 AT 数据通道发送恰好 body_len 字节的原始数据；传输完成后设备返回 OK。

参数

<req_id>:: [HTTPD][REQ] 上报中的请求 ID。
<status>:: HTTP 状态码；范围为 [100,599]。
<content_type>:: HTTP Content-Type 响应头的值；最多 63 字节且不能包含逗号。为空时默认为 application/octet-stream。
<body_len>:: 要发送的原始响应 body 字节数，必须大于 0。空 body 请使用 AT+HTTPDRSP。

错误代码

1：参数无效或 body 长度为 0
2：请求 ID 无效、请求已过期，或响应期间客户端连接失败
3：内存分配失败
4：TT 传输失败

示例

发送 27 字节 JSON body：

AT+HTTPDRSPRAW=0,200,application/json,27
>>>
{"status":"ok","code":200}
OK

设备主动上报

每收到一个受支持的 HTTP 请求，设备都会向 host 上报请求元信息：

[$][HTTPD][REQ][<req_id>][<method>][<path_len>][<query_len>][<content_len>]:<path>[?<query>]

<method> 为 GET、POST、PUT 或 OTHER；HTTPD AT handler 注册了 GET、POST 和 PUT 方法。各长度字段的单位均为字节。query_len 不包含开头的 ?。如果请求包含 body，设备会分一条或多条上报：

[$][HTTPD][BODY][<req_id>][<len>]:<body bytes>

host 应根据 req_id 将请求元信息与 body 上报对应起来。多个请求可以同时等待处理；回复时须使用对应请求的 ID。

server 状态及请求超时上报：

[HTTPD][EVENT]:start
[HTTPD][EVENT]:stop
[$][HTTPD][TIMEOUT][<req_id>]

如果 host 未能在 timeout_ms 到期前开始回复，设备会上报超时、向 client 返回 HTTP 500，并释放对应请求槽。

HTTP 请求/响应示例

以下示例中，client 请求 /hello，host 回复 ok：

AT+HTTPDSTART=80,1
[HTTPD][EVENT]:start
OK

# HTTP client: GET http://<device_ip>/hello
[$][HTTPD][REQ][0][GET][6][0][0]:/hello

AT+HTTPDRSP=0,200,text/plain,2,ok
OK

client 会收到 HTTP 200 响应，body 为 ok。不再需要 server 时将其停止：

AT+HTTPDSTOP
[HTTPD][EVENT]:stop
OK