Set command

nRF93M1 Cellular AT Commands

The set command downloads a firmware update package from an HTTP or HTTPS server and triggers a firmware update.

For HTTP and HTTPS error codes and server response codes, see HTTP and HTTPS error codes.

Syntax:

%HTTPFOTADL=<HTTP_URL>[,<download_URC_max>]

The set command parameters and their defined values are the following:

<HTTP_URL>
String. Maximum length 255 characters. URL of the firmware update package. Must start with http:// or https://.
<download_URC_max>
Integer, 0 and 50–100. Maximum download progress reporting.
0 – Do not report download progress.
50–100 – Maximum download progress percentage to report.

During download and verification, the following Unsolicited Result Code (URC)s are sent:

%HTTPURC: "FOTA","DOWNLOAD START"
%HTTPURC: "FOTA","DOWNLOADING",<percent>
%HTTPURC: "FOTA","DOWNLOADED"
%HTTPURC: "FOTA","VERIFIED"
<percent>
Integer, 0–100. Download progress.

"DOWNLOADED" indicates that the entire package is received but not yet verified. "VERIFIED" indicates that the package passed verification and is going to be applied.

If the download or verification fails, one of the following URCs is sent:

%HTTPURC: "FOTA","DOWNLOAD ERROR",<cause>,<detail>
%HTTPURC: "FOTA","VERIFICATION FAILURE",<cause>,<detail>

The error notification parameters and their defined values are the following:

<cause>
Integer, 1–7. Error cause.
1 – HTTP error. The server responded with a status other than 200.
2 – Transport error.
3 – Socket error.
4 – Flash error.
5 – Verify error.
6 – TLS error.
7 – Package size error.
<detail>
Integer. Error detail. The meaning depends on <cause>. 0 indicates that no further information is available.

When <cause> is 1, <detail> is the HTTP status code as received.

When <cause> is 2, the values of <detail> are the following:

<detail>
8 – No such file.
9 – Out of memory.
10 – SSL configuration error.
11 – URL parse error.
12 – DNS resolution failed.
13 – Protocol error.
14 – Socket error.
15 – Bind failed.
16 – Connection timeout.
17 – Connection error.
18 – Server closed the connection.
20 – Request timeout.
21 – Internal error.
23 – TLS is not supported.

When <cause> is 3, the values of <detail> are the following:

<detail>
34 – I/O error.
103 – Connection aborted locally.
104 – Connection reset by peer.
107 – Not connected.

When <cause> is 4, the values of <detail> are the following:

<detail>
-2 – Offset past the end of the delta partition.
-8 – Flash write failed.
-17 – No delta partition registered.
-19 – Writing the delta partition is not permitted.

When <cause> is 5, the values of <detail> are the following:

<detail>
1 – Delta package was not found.
2 – Delta is incomplete.
3 – Delta is invalid.
4 – Wrong base image.
5 – Unmatched new image.
6 – Patching failed.
7 – Signature check failed.
8 – Delta state is unavailable.

When <cause> is 6, a negative <detail> from -32767 to –1 is an Mbed TLS return code as a decimal number. Negative values outside that range are modem-specific:

<detail>
-65537 – The peer closed the TLS record layer during a read.
-65538 – The configured PSK key could not be decoded from hexadecimal.

A positive <detail> is an X.509 verification bitmask that can combine several of the following values.:

<detail>
1 – Certificate is expired.
2 – Certificate is revoked.
4 – CN mismatch.
8 – Untrusted CA.
16 – CRL is not trusted.
32 – CRL is expired.
64 – Certificate is missing.
128 – Verification was skipped.
256 – Other reason.
512 – Certificate is not yet valid.
1024 – CRL is from the future.
2048 – keyUsage mismatch.
4096 – extendedKeyUsage mismatch.
8192 – nsCertType mismatch.
16384 – Unacceptable certificate signature hash.
32768 – Unacceptable certificate signature algorithm.
65536 – Unacceptable certificate key.
131072 – Unacceptable CRL signature hash.
262144 – Unacceptable CRL signature algorithm.
524288 – Unacceptable CRL key.

For example, <detail> 12 indicates an untrusted CA (8) and a CN mismatch (4)

Note: If the failure is reported immediately before any TLS traffic is exchanged and the certificate configured with %SSLCFG is a PEM bundle containing multiple certificates, a positive <detail> indicates the number of certificate blocks that failed to parse.

When <cause> is 7, <detail> is the attempted package size in bytes.

When the download and the verification complete successfully, the module reboots and applies the delta update during the bootloader phase.

The following command example downloads a firmware update package with progress reporting:

AT%HTTPFOTADL="http://example.com/delta.binpkg",100
OK
%HTTPURC: "FOTA","DOWNLOAD START"
%HTTPURC: "FOTA","DOWNLOADING",10
%HTTPURC: "FOTA","DOWNLOADING",30
%HTTPURC: "FOTA","DOWNLOADING",50
%HTTPURC: "FOTA","DOWNLOADING",80
%HTTPURC: "FOTA","DOWNLOADING",100
%HTTPURC: "FOTA","DOWNLOADED"
%HTTPURC: "FOTA","VERIFIED"

The following command example shows a download failure caused by the server not having the package:

> AT%HTTPFOTADL="http://example.com/delta.binpkg"
OK
%HTTPURC: "FOTA","DOWNLOAD ERROR",1,404