FOTA AT commands

The following commands list contains AT commands related to firmware-over-the-air updates (FOTA) requests.

FOTA request #XFOTA

The #XFOTA command sends various types of FOTA requests, based on specific operation codes.

Set command

The set command allows you to send a FOTA request.

Syntax

AT#XFOTA=<op>,<file_url>[,<sec_tag>[,<pdn_id>]]

  • The <op> parameter can accept one of the following values:

    • 0 - Cancel FOTA (during download only).

    • 1 - Start FOTA for application update.

    • 2 - Start FOTA for modem delta update.

    • 6 - Read application image size and version (optional for application FOTA).

    • 7 - Read modem scratch space size and offset (optional for modem FOTA).

    • 8 - Erase mcuboot secondary slot (optional for application FOTA).

    • 9 - Erase modem scratch space (optional for modem FOTA).

  • The <file url> parameter is a string. It represents the full HTTP or HTTPS path of the target image to download.

  • The <sec_tag> parameter is an integer. It indicates to the modem the credential of the security tag used for establishing a secure connection for downloading the image. It is associated with the certificate or PSK. Specifying the <sec_tag> is mandatory when using HTTPS.

  • The <pdn_id> parameter is an integer. It represents the Packet Data Network (PDN) ID that can be used instead of the default PDN for downloading.

Response syntax

#XFOTA: <primary_partition_id>,<MCUBOOT_version>,<img_size>,<img_version>
#XFOTA: <secondary_partition_id>,<MCUBOOT_version>,<img_size>,<img_version>

  • The <primary_partition_id> and <secondary_partition_id> integers give the partition ID.

  • The <MCUBOOT_version> major version integer. Value 1 corresponds to MCUboot versions 1.x.y.

  • The <img_size> integer gives the size of the application image in this partition in bytes.

  • The <img_version> string gives the version of the application image as “<major>.<minor>.<revision>+<build_number>”.

#XFOTA: <size>,<offset>

  • The <size> integer gives the size of the modem DFU area in bytes.

  • The <offset> integer gives the offset of the firmware image in the modem DFU area.

Example

Read image size and version
at#xfota=6
#XFOTA: 3,1,295288,"0.0.0+0"
#XFOTA: 7,1,294376,"0.0.0+0"
OK

Application download and activate
AT#XFOTA=1,"http://remote.host/fota/slm_app_update.bin"
OK
#XFOTA: 1,0,0
...
#XFOTA:4,0
AT#XRESET
OK
READY
#XFOTA: 5,0

Erase previous image after FOTA
AT#XFOTA=8
OK

Read modem scratch space size and offset
at#xfota=7
#XFOTA: 368640,0
OK

Erase modem scratch space before FOTA
AT#XFOTA=9
OK

Modem download and activate
AT#XFOTA=2,"http://remote.host/fota/mfw_nrf9160_update_from_1.3.0_to_1.3.0-FOTA-TEST.bin"
OK
#XFOTA: 1,0,0
...
#XFOTA: 4,0
AT#XRESET
OK
READY
#XFOTA: 5,0

Unsolicited notification

#XFOTA: <fota_stage>,<fota_status>[,<fota_info>]

  • The <fota_stage> value is an integer and can assume one of the following values:

    • 0 - Init

    • 1 - Download

    • 2 - Download, erase pending (modem FOTA only)

    • 3 - Download, erased (modem FOTA only)

    • 4 - Downloaded, to be activated

    • 5 - Complete

  • The <fota_status> value is an integer and can assume one of the following values:

    • 0 - OK

    • 1 - Error

    • 2 - Cancelled

    • 3 - Reverted (application FOTA only)

  • The <fota_info> value is an integer. Its value can have different meanings based on the values assumed by <fota_stage> and <fota_status>. See the following table:

    <fota_stage> value

    <fota_status> value

    <fota_info> value

    1 (namely Download)

    0 (namely OK)

    Percentage of the download

    1 (namely Download)

    1 (namely ERROR)

    Error Code

    5 (namely Complete)

    1 (namely ERROR)

    Error Code

    1 (namely Download)

    2 (namely CANCELLED)

    0 - Downloading is cancelled before completion

    The error codes can be the following:

    • 1 - Download failed

    • 2 - Update image rejected (for example modem firmware version error)

    • 3 - Update image mismatch (for example <op> is 1 but <file_url> points to a modem image)

    For modem FOTA, the error codes can be the following:

    • 0x4400001u - The modem encountered a fatal internal error during firmware update.

    • 0x4400002u - The modem encountered a fatal hardware error during firmware update.

    • 0x4400003u - Modem firmware update failed, due to an authentication error.

    • 0x4400004u - Modem firmware update failed, due to UUID mismatch.

Read command

The read command is not supported.

Test command

The test command tests the existence of the command and provides information about the type of its subparameters.

Syntax

#XFOTA=?

Response syntax

#XFOTA: <list of op value>,<file_url>,<sec_tag>,<apn>

Examples

AT#XFOTA=?

#XFOTA: (0,1,2,6,7,8,9),<file_url>,<sec_tag>,<apn>

OK