HTTP Client AT Commands#

This section describes AT commands for the Hypertext Transfer Protocol (HTTP) client in the SiWx91x network processor.

Commands#

http-client-init#

Initialize the HTTP client on the SiWx91x device.

Command Format#

at+http-client-init=<certificate-index>,<tls-version>,<http-version>,<https-enable>,<https-use-sni>,<ip-version>,<network-interface>

Related SDK API#

Pre-conditions#

http-client-mode

Parameters#

certificate-index#

The zero-based offset of the Credential ID relative to SL_NET_TLS_SERVER_CREDENTIAL_ID at which the CA certificate is saved using net-cred-signcert.

tls-version#

TLS version for the HTTP client. Contains a numeric value that corresponds to one of the values of the enum sl_http_client_tls_version_t.

http-version#

HTTP protocol version. Contains a numeric value that corresponds to one of the values of the enum sl_http_client_version_t.

https-enable#

Set to 0 to disable HTTPS and 1 to enable HTTPS.

https-use-sni#

Set to 0 to disable the use of Server Name Indication (SNI) extension in HTTPS and 1 to enable it.

ip-version#

IP version for the HTTP client. Contains a numeric value that corresponds to one of the values of the enum sl_ip_address_type_t.

network-interface#

Network interface for the HTTP client. Contains a numeric value that corresponds to one of the values of the enum sl_net_interface_t in sl_net_constants.h.

Response#

  • OK <client-instance-id> on success, where client-instance-id is a unique identifier for the HTTP client instance on the SiWx91x device.

  • ERROR <error code> in case of failure. Possible error codes are the same as those returned by the sl_http_client_init API.

Notes#

At present, you can call the http-client-init command only once unless you first call http-client-deinit. Only a single HTTP client instance is supported. The client-instance-id value is always returned as 0 and must be passed as 0 in all following http-client commands. The client-instance-id parameter is included for forward compatibility in case a future release adds support for multiple HTTP client instances.

Examples#

at+http-client-init=0,2,1,1,1,0,8        # Initialize HTTP client with certificate index 0, TLS 1.2, HTTP 1.1, HTTPS enabled, SNI enabled, IPv4, Wi-Fi client interface
OK 0

http-client-deinit#

De-initialize an HTTP client instance.

Command Format#

at+http-client-deinit=<client-instance-id>

Related SDK API#

sl_http_client_deinit

Pre-conditions#

http-client-init

Parameters#

client-instance-id#

The unique identifier of the HTTP client instance to de-initialize. Currently always set to 0 as there is only one HTTP client instance supported.

Response#

  • OK on success

  • ERROR <error code> in case of failure. Possible error codes are the same as those returned by the sl_http_client_deinit API.

Notes#

You can send the http-client-init command after this response to reinitialize the HTTP client.

Examples#

at+http-client-deinit=0        # De-initialize HTTP client instance 0 (the only supported instance)
OK

http-client-req-conncfg#

Configure an HTTP client request connection.

Command Format#

at+http-client-req-conncfg=<client-instance-id>,<request-id>,<method-type>,<ip-address>[,<host-name>][,<sni-extension>],<port>,<resource>

Related SDK API#

sl_http_client_request_t

Pre-conditions#

http-client-init

Parameters#

client-instance-id#

The unique identifier of the HTTP client instance. Currently always set to 0 as there is only one HTTP client instance supported.

request-id#

Reserved (not currently supported). A unique identifier for this HTTP request. Because only one HTTP request can be active at a time, the request-id parameter is ignored.

method-type#

HTTP request method type. Contains a numeric value that corresponds to one of the values of the enum sl_http_client_method_type_t.

Note: HEAD (2) and DELETE (4) methods are not currently supported.

ip-address#

IP address of the HTTP server as a string, for example, "192.168.1.1" for IPv4 or "2001:0db8:85a3:0000:0000:8a2e:0370:7334" for IPv6.

host-name#

Optional. Hostname of the HTTP server as specified in the request header. If omitted, the ip-address is used for the connection.

sni-extension#

Optional. Server Name Indication (SNI) extension to specify the hostname for servers hosting multiple domains on the same IP address. If ommitted, the host-name will be used as the SNI, provided that host-name is not equal to ip-address.

port#

Port number on which to send the HTTP request.

resource#

Full URL string for the requested resource, including the scheme (for example, http, https), domain, port, path, query parameters, and fragment. See the sl_http_client_request_t documentation for the permitted values of this field.

Note: Long HTTP URLs (feature bit SL_SI91X_FEAT_LONG_HTTP_URL) are not currently supported.

Response#

  • OK on success

  • ERROR 1 in case of failure

Notes#

  • When you send an at+http-client-req- configuration command for the first time, or immediately after the http-client-req-send command, the SiWx91x device does the following:

    • Initializes the sl_http_client_request_t structure with the initial values set to default values where applicable or empty values otherwise.

    • Overwrites the specific structure members in sl_http_client_request_t based on the parameters passed in this command.

  • When you send any subsequent configuration command beginning with at+http-client-req-, the SiWx91x device overwrites only the specified structure members.

  • The following are the HTTP client configuration commands:

  • Although the request-id parameter is ignored by this command, it is used by the http-client-req-send command to register a unique request that is later identified in the asynchronous [HTTP_CLIENT_RESPONSE] (#http-client-response) message. For readability and consistent command flow, pass the same request-id value to all related configuration commands and then to the http-client-req-send command.

Examples#

at+http-client-req-conncfg=0,1,0,"192.168.1.100","api.example.com","api.example.com",80,"http://api.example.com/data"        # Configure HTTP GET request for instance 0 and request ID 1 (ignored), connecting to 192.168.1.100:80 with hostname api.example.com
OK

http-client-req-geturl#

Query the resource URL for a specific HTTP request.

Command Format#

at+http-client-req-geturl=<client-instance-id>,<request-id>

Related SDK API#

sl_http_client_request_t::resource member

Pre-conditions#

http-client-req-conncfg

Parameters#

client-instance-id#

The unique identifier of the HTTP client instance. Currently always set to 0 as there is only one HTTP client instance supported.

request-id#

Reserved (not currently supported). A unique identifier for this HTTP request. Because only one HTTP request can be active at a time, the request-id parameter is ignored.

Response#

  • OK <resource-url> on success, where:

    • resource-url is the full URL string for the requested resource, including the scheme (for example, http, https), domain, port, path, query parameters, and fragment. This corresponds to the resource member of the sl_http_client_request_t structure.

  • ERROR 21 in case of invalid parameters (invalid client-instance-id)

  • ERROR 1 in case of other failures

Notes#

  • This command queries the resource URL that was previously configured using the http-client-req-conncfg command.

  • Although the request-id parameter is ignored by this command, it is used by the http-client-req-send command to register a unique request that is later identified in the asynchronous [HTTP_CLIENT_RESPONSE] (#http-client-response) message. For clarity and consistent command flow, pass the same request-id value to all related configuration commands and then to the http-client-req-send command.

Examples#

at+http-client-req-geturl=0,1        # Get URL for client instance 0, request ID 1 (ignored)
OK "http://api.example.com/data"

http-client-req-opt#

Configure HTTP client request options.

Command Format#

at+http-client-req-opt=<client-instance-id>,<request-id>,<timeout>,<retry-count>,<retry-period>,<tcp-connection-reuse>

Related SDK API#

sl_http_client_request_t

Pre-conditions#

http-client-init

Parameters#

client-instance-id#

The unique identifier of the HTTP client instance. Currently always set to 0 as there is only one HTTP client instance supported.

request-id#

Reserved (not currently supported). A unique identifier for this HTTP request. Because only one HTTP request can be active at a time, the request-id parameter is ignored.

timeout#

Reserved (not currently supported). Request timeout value in milliseconds. Specifies the maximum time to wait for a response from the HTTP server.

retry-count#

Number of retry attempts for failed HTTP requests. Set to 0 to disable retries.

retry-period#

Time interval between retry attempts in milliseconds. This parameter is only used when retry-count is greater than 0.

tcp-connection-reuse#

Set to 0 to disable TCP connection reuse and 1 to enable it. When enabled, the same TCP connection can be reused for multiple HTTP requests to the same server.

Response#

  • OK on success

  • ERROR 1 in case of failure

Notes#

  • It is optional to send this command before sending the http-client-req-send command. If omitted, the default values set in the sl_http_client_request_t structure are used for the HTTP request (see the following points).

  • When you send a configuration command beginning with at+http-client-req- for the first time, or immediately after the http-client-req-send command, the SiWx91x device does the following:

  • When you send any subsequent configuration command beginning with at+http-client-req-, the SiWx91x device overwrites only the specific structure members.

  • The following are the HTTP client configuration commands:

  • Although the request-id parameter is ignored by this command, it is used by the http-client-req-send command to register a unique request that is later identified in the asynchronous [HTTP_CLIENT_RESPONSE] (#http-client-response) message. For readability and consistent command flow, pass the same request-id to all related configuration commands and then to the http-client-req-send command.

Examples#

at+http-client-req-opt=0,1,30000,3,5000,1        # Configure HTTP request options for instance 0, request ID 1 (ignored), with 30-second timeout, 3 retries, 5-second retry period, and TCP connection reuse enabled
OK

http-client-req-body#

Configure HTTP client request body.

Command Format#

at+http-client-req-body=<client-instance-id>,<request-id>,<body-length>

Related SDK API#

sl_http_client_request_t

Pre-conditions#

http-client-init

Parameters#

client-instance-id#

The unique identifier of the HTTP client instance. Currently always set to 0 as there is only one HTTP client instance supported.

request-id#

Reserved (not currently supported). A unique identifier for this HTTP request. Because only one HTTP request can be active at a time, the request-id parameter is ignored.

body-length#

Length of the HTTP request body in bytes.

Response#

  • ERROR 1 on failing to enter data mode.

  • OK on successfully entering data mode.

    • On receiving this response, you must transmit body-length number of characters.

    • As soon as the given number of characters are transmitted, the HTTP request body will be updated and one of the following responses sent back:

      • OK on success

      • ERROR 1 in case of failure

Notes#

  • It is optional to send this command before sending the http-client-req-send command. If omitted, the HTTP request will be sent without a body.

    • If the method-type of the HTTP request requires a body (e.g. HTTP POST), the http-client-req-send command will return an error if a request body has not been set using this command.

  • When any configuration command beginning with at+http-client-req- is sent for the first time or immediately after the http-client-req-send command, the SiWx91x device will:

    • Initialize the sl_http_client_request_t structure with the initial values set to default values where applicable or empty values otherwise.

    • Overwrite the specific structure members in sl_http_client_request_t based on the parameters passed in this command.

  • When any subsequent configuration command beginning with at+http-client-req- is sent, the SiWx91x device will perform the second step given above i.e. just overwrite specific structure members.

  • The following are the HTTP client configuration commands:

  • Even though the request-id parameter is ignored by this command, it is utilized by the http-client-req-send command to register a unique request which is later identified in the asynchronous [HTTP_CLIENT_RESPONSE] (#http-client-response) message. Therefore, it is recommended for the sake of the readibility of commands that the same request-id be passed for these commands which will later be passed to the http-client-req-send command.

Examples#

at+http-client-req-body=0,1,1024        # HTTP request body for instance 0, request ID 1 (ignored), with a 1024-byte body
OK                                      # Successfully entered data mode
<transmit 1024 characters>              # Transmit exactly 1024 characters as the HTTP request body
OK                                      # HTTP request body successfully updated

http-client-req-body-len#

Configure HTTP client request body length without providing the body content.

Command Format#

at+http-client-req-body-len=<client-instance-id>,<request-id>,<body-length>

Related SDK API#

sl_http_client_request_t

Pre-conditions#

http-client-init

Parameters#

client-instance-id#

The unique identifier of the HTTP client instance. Currently always set to 0 as there is only one HTTP client instance supported.

request-id#

Reserved (not currently supported). A unique identifier for this HTTP request. Because only one HTTP request can be active at a time, the request-id parameter is ignored.

body-length#

Length of the HTTP request body in bytes.

Response#

  • OK on success

  • ERROR 1 in case of failure

  • ERROR 21 if the body-length is longer than the body-length of the content set by the http-client-req-body command

Notes#

  • This command sets the body length for the HTTP request without requiring the actual body content to be transmitted.

  • This command should be used instead of the http-client-req-body command for HTTP PUT requests.

  • If the method-type of the HTTP request requires a body (e.g. HTTP POST), the http-client-req-send command will return an error if a body length has been set but the body content has not been set. The http-client-req-body command should be used instead of this command for such requests.

  • It is optional to send this command before sending the http-client-req-send command. If omitted, the HTTP request will be sent with the body length set by the http-client-req-body command or a body length of 0 if http-client-req-body was not sent.

  • When any configuration command beginning with at+http-client-req- is sent for the first time or immediately after the http-client-req-send command, the SiWx91x device will:

    • Initialize the sl_http_client_request_t structure with the initial values set to default values where applicable or empty values otherwise.

    • Overwrite the specific structure members in sl_http_client_request_t based on the parameters passed in this command.

  • When any subsequent configuration command beginning with at+http-client-req- is sent, the SiWx91x device will perform the second step given above i.e. just overwrite specific structure members.

  • The following are the HTTP client configuration commands:

  • Even though the request-id parameter is ignored by this command, it is utilized by the http-client-req-send command to register a unique request which is later identified in the asynchronous [HTTP_CLIENT_RESPONSE] (#http-client-response) message. Therefore, it is recommended for the sake of the readability of commands that the same request-id be passed for these commands which will later be passed to the http-client-req-send command.

Examples#

at+http-client-req-body-len=0,1,1024        # Set HTTP request body length to 1024 bytes for instance 0, request ID 1 (ignored)
OK                                          # Body length successfully set

http-client-req-addhdr#

Add an extended header to an HTTP client request.

Command Format#

at+http-client-req-addhdr=<client-instance-id>,<request-id>,<key>,<value>

Related SDK API#

sl_http_client_add_header

Pre-conditions#

http-client-init

Parameters#

client-instance-id#

The unique identifier of the HTTP client instance. Currently always set to 0 as there is only one HTTP client instance supported.

request-id#

Reserved (not currently supported). A unique identifier for this HTTP request. Because only one HTTP request can be active at a time, the request-id parameter is ignored.

key#

A string denoting the header key (field name) to be added to the HTTP request.

value#

A string denoting the header value to be associated with the specified key.

Response#

  • OK on success

  • ERROR <error code> in case of failure. Possible error codes are the same as those returned by the sl_http_client_add_header API.

Notes#

Even though the request-id parameter is ignored by this command, it is utilized by the http-client-req-send command to register a unique request which is later identified in the asynchronous HTTP_CLIENT_RESPONSE message. Therefore, it is recommended for the sake of the readibility of commands that the same request-id be passed for these commands which will later be passed to the http-client-req-send command.

Examples#

at+http-client-req-addhdr=0,1,"Content-Type","application/json"       # Content-Type header for instance 0, request ID 1 (ignored)
OK

http-client-req-delhdr#

Delete a specified header from an HTTP client request.

Command Format#

at+http-client-req-delhdr=<client-instance-id>,<request-id>,<key>

Related SDK API#

sl_http_client_delete_header

Pre-conditions#

http-client-req-addhdr for the same key

Parameters#

client-instance-id#

The unique identifier of the HTTP client instance. Currently always set to 0 as there is only one HTTP client instance supported.

request-id#

Reserved (not currently supported). A unique identifier for this HTTP request. Because only one HTTP request can be active at a time, the request-id parameter is ignored.

key#

A string denoting the header key (field name) to be deleted from the HTTP request.

Response#

  • OK on success

  • ERROR <error code> in case of failure. Possible error codes are the same as those returned by the sl_http_client_delete_header API.

Notes#

Even though the request-id parameter is ignored by this command, it is utilized by the http-client-req-send command to register a unique request which is later identified in the asynchronous [HTTP_CLIENT_RESPONSE] (#http-client-response) message. Therefore, it is recommended for the sake of the readibility of commands that the same request-id be passed for these commands which will later be passed to the http-client-req-send command.

Examples#

at+http-client-req-delhdr=0,1,"Content-Type"        # Delete Content-Type header for instance 0, request ID 1 (ignored)
OK

http-client-req-delallhd#

Delete all headers from an HTTP client request.

Command Format#

at+http-client-req-delallhd=<client-instance-id>,<request-id>

Related SDK API#

sl_http_client_delete_all_headers

Pre-conditions#

http-client-req-addhdr for any header

Parameters#

client-instance-id#

The unique identifier of the HTTP client instance. Currently always set to 0 as there is only one HTTP client instance supported.

request-id#

Reserved (not currently supported). A unique identifier for this HTTP request. Because only one HTTP request can be active at a time, the request-id parameter is ignored.

Response#

Notes#

Even though the request-id parameter is ignored by this command, it is utilized by the http-client-req-send command to register a unique request which is later identified in the asynchronous [HTTP_CLIENT_RESPONSE] (#http-client-response) message. Therefore, it is recommended for the sake of the readibility of commands that the same request-id be passed for these commands which will later be passed to the http-client-req-send command.

Examples#

at+http-client-req-delallhd=0,1        # Delete all headers for instance 0, request ID 1 (ignored)
OK

http-client-req-getallhd#

Query all headers from an HTTP client request.

Command Format#

at+http-client-req-getallhd=<client-instance-id>,<request-id>

Related SDK API#

sl_http_client_request_t::extended_headermember

Pre-conditions#

http-client-init

Parameters#

client-instance-id#

The unique identifier of the HTTP client instance. Currently always set to 0 as there is only one HTTP client instance supported.

request-id#

Reserved (not currently supported). A unique identifier for this HTTP request. Because only one HTTP request can be active at a time, the request-id parameter is ignored.

Response#

  • OK <count> <key1> <value1> <key2> <value2> ... <keyN> <valueN> on success, where:

    • <count> is the number of headers

    • <key1> to <keyN> are strings denoting the header keys, where N = count

    • <value1> to <valueN> are strings denoting the header values for each corresponding <key>

  • OK 0 when no headers are configured

  • ERROR 21 in case of invalid parameters (invalid client-instance-id)

  • ERROR 1 in case of other failures

Notes#

Although the request-id parameter is ignored by this command, it is used by the http-client-req-send command to register a unique request that is later identified in the asynchronous [HTTP_CLIENT_RESPONSE] (#http-client-response) message. For readability and consistent command flow, pass the same request-id to all related configuration commands and then to the http-client-req-send command.

Examples#

at+http-client-req-getallhd=0,1        # Query all headers for instance 0, request ID 1 (ignored)
OK 2 "Content-Type" "application/json" "Authorization" "Bearer token123"

http-client-req-send#

Send an HTTP request.

Command Format#

at+http-client-req-send=<client-instance-id>,<request-id>

Related SDK APIs#

Pre-conditions#

http-client-req-conncfg

Parameters#

client-instance-id#

The unique identifier of the HTTP client instance. Currently always set to 0 as there is only one HTTP client instance supported.

request-id#

A unique identifier for this HTTP request. This identifier is used to register a unique request in order to identify it in the asynchronous [HTTP_CLIENT_RESPONSE] (#http-client-response) message.

Response#

Notes#

  • If you use the HTTP PUT method (method-type = 3), send the http-client-send-chunk command after this command.

  • This command invokes the following APIs:

    • sl_http_client_request_init to initialize the request:

      • The configuration previously set by the following commands is passed in the request API parameter:

      • A common sl_http_client_event_handler_t response callback is set for all requests through the event_handler API parameter. Use this callback to send back the asynchronous [HTTP_CLIENT_RESPONSE] (#http-client-response) message.

      • The request-id parameter value from this command is passed in the request_context API parameter. This results in the sl_http_client_event_handler_t response callback returning the same request-id value in its request_context parameter.

      • The request-id passed to this command will not be validated for uniqueness. The caller must ensure that a unique request-id is passed for each request.

    • sl_http_client_send_request to transmit the request to the HTTP server.

Examples#

at+http-client-req-send=0,1        # Send HTTP request for instance 0, request ID 1
OK

http-client-send-chunk#

Send HTTP POST and PUT chunked data.

Command Format#

at+http-client-send-chunk=<client-instance-id>,<flush>,<chunk-size>

Related SDK API#

sl_http_client_write_chunked_data

Pre-conditions#

http-client-req-send

Parameters#

client-instance-id#

The unique identifier of the HTTP client instance. Currently always set to 0 as there is only one HTTP client instance supported.

flush#

Reserved (not currently supported). Set to 0 to disable immediate flushing and 1 to enable it.

chunk-size#

Length of the data chunk to be sent in bytes.

Response#

  • ERROR 1 on failing to enter data mode.

  • OK on successfully entering data mode.

    • On receiving this response, you must transmit chunk-size number of characters.

    • As soon as the given number of characters are transmitted, the chunked data will be sent and one of the following responses sent back:

Notes#

  • This command sends a chunk of data as part of an HTTP POST or PUT request.

  • The data can be sent in multiple chunks by sending this command multiple times.

Examples#

at+http-client-send-chunk=0,0,512        # Send 512-byte chunk for instance 0 without immediate flushing
OK                                       # Successfully entered data mode
<transmit 512 characters>                # Transmit exactly 512 characters as the chunked data
OK                                       # Chunked data successfully sent

Events#

  • [HTTP_CLIENT_RESPONSE] (#http-client-response)

HTTP_CLIENT_RESPONSE#

Event sent by the SiWx91x device with the content of an HTTP response received from the server.

Event Message Format#

at+HTTP_CLIENT_RESPONSE=<client-instance-id>,<request-id>,<event>,<status>,<http-response-code>,<http-version>,<response-headers-count>,<key1>,<value1>,<key2>,<value2>,...,<keyN>,<valueN>,<end-of-response-body>,<response-body-length>,<response-body>

Related SDK APIs#

Parameters#

client-instance-id#

The unique identifier of the HTTP client instance that has received a response. Currently always set to 0 as there is only one HTTP client instance supported.

request-id#

The unique identifier of the HTTP request for which this response is being sent. This will match the request-id passed to the http-client-req-send command.

event#

The type of HTTP client event that occurred. Contains a numeric value that corresponds to one of the values of the enum sl_http_client_event_t.

status#

Numeric status code indicating the success or error status of the HTTP request. Contains one of the status codes described in the Status Codes section.

http-response-code#

Numeric value indicating the HTTP standard response code returned by the HTTP server. For e.g. an HTTP code of 404 indicates that the requested resource was not found.

Note: This is not currently supported for the HTTP PUT method. http-response-code is set to 0 for such a request.

http-version#

Reserved (not currently supported). The HTTP version used by the HTTP server for the response. Because this field is not supported, this value is always set to 0.

response-headers-count#

Reserved (not currently supported). Number of headers in the HTTP response. Because headers are not supported, this value is always set to 0.

key1 to keyN#

Reserved (not currently supported). Strings indicating the keys in the headers in the HTTP response, where N = response-headers-count. Because headers are not supported, these parameters are not part of this event message.

value1 to valueN#

Reserved (not currently supported). Strings indicating the values for the corresponding keys in the headers in the HTTP response, where N = response-headers-count. Because headers are not supported, these parameters are not part of this event message.

end-of-response-body#

Set to 1 to indicate the end of the HTTP response body or 0 to indicate that there is another HTTP_CLIENT_RESPONSE message expected with the next chunk of the HTTP response body.

response-body-length#

The length in bytes of the chunk of the HTTP response body included with this event message.

response-body#

The chunk of the HTTP response body included with this event message. This event message is terminated by exactly response-body-length characters following the comma after the response-body-length parameter value.

Examples#

at+HTTP_CLIENT_RESPONSE=0,1,0,0,200,0,0,1,23,HTTP/1.1 200 OK\r\n\r\n    # HTTP GET response event for instance 0, request ID 1 with status 0, response code 200 and a 23-byte response body, and this is the end of the response body
``