HTTPD AT Commands

Note

  • HTTPD AT commands are disabled by default and are available in Host Control Mode.

  • Enable Enable HTTPD (transparent HTTP server to host) under CONFIG SHELL → Enable ATCMD → Host Control Mode in menuconfig. The build must include the network/LWIP components.

  • The device acts as an HTTP/HTTPS server. It reports each request to the host MCU, which processes it and replies using AT+HTTPDRSP or AT+HTTPDRSPRAW.

  • Connect the device to a network and make its IP address reachable by clients before starting the server. For HTTPS, preload the server certificate suite in the VFS /CERT/ directory; see AT Security Certificates.

AT+HTTPDCFG

Function Description

Configure the maximum number of concurrent requests, the server thread stack size, and the timeout for the host to begin replying. Configure these values before starting the server. The settings remain active until changed or the device is rebooted.

Command Format

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

Response Format

Success Response:

OK

Error Response:

ERROR: <error_no>

Parameters

<max_conn>:

Maximum number of concurrent connections and pending requests.

  • Range: [1,4]

  • Default: 2

  • Request IDs range from 0 to max_conn - 1.

<stack>:

Stack size in bytes for HTTP request-processing threads.

  • Minimum: 2048 bytes

  • Default: 4096 bytes

  • Increase this value if request handling needs more stack; larger values consume more RAM.

<timeout_ms>:

Time to wait for the host to start a response, in milliseconds.

  • Range: [1,120000]

  • Default: 10000

  • The timeout applies until the host starts AT+HTTPDRSP or AT+HTTPDRSPRAW. Once a RAW transfer has started, its transfer time is not limited by this timeout.

Error Codes

  • 1: Invalid or missing parameter

  • 2: The HTTPD server is running; stop it before changing the configuration

Examples

Set the concurrency limit to 3 and use the default stack size and timeout:

AT+HTTPDCFG=3
OK

Set all configuration values:

AT+HTTPDCFG=2,4096,30000
OK

AT+HTTPDSTART

Function Description

Start an HTTP or HTTPS server listening on the specified TCP port. The server forwards GET, POST, and PUT requests to the host MCU. The host must reply to each request.

Command Format

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

Response Format

Success Response:

[HTTPD][EVENT]:start
OK

Error Response:

ERROR: <error_no>

Parameters

<port>:

TCP port on which the server listens.

  • Range: [1,65535]

  • Common ports: 80 for HTTP and 443 for HTTPS.

<conn_type>:

Transport and TLS client-certificate policy.

  • 1: Plain TCP/HTTP.

  • 2: TLS/HTTPS; do not verify a client certificate.

  • 3: TLS/HTTPS; require and verify a client certificate (mutual TLS).

<cert_index>:

Server certificate suite index. Required for conn_type 2 and 3; range [1,10]. The suite consists of server_cert_<index>.crt, server_key_<index>.key, and server_ca_<index>.crt in /CERT/. All three files are loaded for either TLS mode. For conn_type=3, the server CA is also used to verify the client’s certificate.

Error Codes

  • 1: Invalid parameter, or cert_index is missing/invalid for HTTPS

  • 2: The server is already running

  • 3: Memory allocation failed or a certificate file could not be loaded

  • 4: HTTPD server startup failed

  • 5: TLS certificate setup/parsing failed

Examples

Start an HTTP server on port 80:

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

Start HTTPS with the first server certificate suite, without client-certificate verification:

AT+HTTPDSTART=443,2,1

Start HTTPS and require a client certificate:

AT+HTTPDSTART=443,3,1

AT+HTTPDSTOP

Function Description

Stop the HTTPD server. Any request currently waiting for a host response is woken and its connection is closed; a request interrupted by the stop may receive an HTTP 500 response.

Command Format

AT+HTTPDSTOP

Response Format

When the server is running:

[HTTPD][EVENT]:stop
OK

When the server is not running, the command returns OK.

AT+HTTPDQUERY

Function Description

Query server state, current configuration, and any pending request slots.

Command Format

AT+HTTPDQUERY

Response Format

running: <0|1>
max_conn: <n>
stack: <bytes>
timeout_ms: <ms>
req_id <i>: state <s>     # Present only for a non-free request slot
OK

The request state values are 1 (waiting for the host), 2 (RAW response body is being streamed), 3 (inline response is ready), and 4 (RAW response has been sent and the connection is closing). The last state may be brief.

AT+HTTPDRSP

Function Description

Send an HTTP response with an inline body. Use this command for an empty or short text body. The req_id is provided in the request URC.

Command Format

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

Response Format

Success Response:

OK

Error Response:

ERROR: <error_no>

Parameters

<req_id>:

Request ID from the [HTTPD][REQ] notification; range [0, max_conn - 1].

<status>:

HTTP status code; range [100,599].

<content_type>:

Value for the HTTP Content-Type header. Maximum 63 bytes; it must not contain a comma. An empty value defaults to text/plain.

<body_len>:

Number of bytes in body. Use 0 for an empty body. For UTF-8 text, specify its encoded byte length, not its character count.

<body>:

Optional inline response body. Required when body_len is greater than 0. The body must contain at least body_len bytes and must not contain a comma or CR/LF; use AT+HTTPDRSPRAW for content with these characters, binary data, or larger responses.

Error Codes

  • 1: Invalid parameter, or inline body shorter than body_len

  • 2: Invalid request ID or the request has timed out/stopped

  • 3: Memory allocation failed

Example

Reply ok to request ID 0:

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

Return a 404 response with an empty body:

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

AT+HTTPDRSPRAW

Function Description

Send an HTTP response body through transparent transmission (TT). The device streams the specified number of bytes to the HTTP client using a fixed-size relay buffer, so the complete body does not need to fit in RAM. Use this command for large, binary, or delimiter-containing content.

Command Format

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

After the command, the device returns >>>. The host must then transmit exactly body_len raw bytes through the AT data channel; the device returns OK when the transfer completes.

Parameters

<req_id>:

Request ID from the [HTTPD][REQ] notification.

<status>:

HTTP status code; range [100,599].

<content_type>:

Value for the HTTP Content-Type header; maximum 63 bytes and no comma. An empty value defaults to application/octet-stream.

<body_len>:

Number of raw response bytes to transmit; must be greater than 0. Use AT+HTTPDRSP for an empty body.

Error Codes

  • 1: Invalid parameter or zero body length

  • 2: Invalid request ID, the request has expired, or the client connection failed during response

  • 3: Memory allocation failed

  • 4: TT transfer failed

Example

Send a JSON body (27 bytes):

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

Unsolicited Request Notifications

For each supported request, the device sends request metadata to the host:

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

<method> is GET, POST, PUT, or OTHER; the HTTPD AT handler is registered for GET, POST, and PUT. Length fields are byte counts. query_len excludes the leading ?. If the request has a body, the device reports it in one or more chunks:

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

The host should associate the request and body reports by req_id. Multiple requests can be pending at once; respond to each using its own request ID.

Server lifecycle and timeout notifications:

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

When the host does not start a response before timeout_ms, the device reports the timeout, returns HTTP 500 to the client, and frees that request slot.

HTTP Request/Response Example

The following example shows a client requesting /hello and the host replying with 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

The client receives an HTTP 200 response with the body ok. Stop the server when it is no longer needed:

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