FOTA AT commands

This page describes AT commands related to Firmware Over-The-Air (FOTA) updates.

FOTA request #XFOTA

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

Set command

The set command performs FOTA-related operations.

Syntax

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

  • The <op> parameter must be one of the following values:

    • 0 - Stop FOTA (during download only). Can be used as a way to pause and resume the download, by issuing the same FOTA start command to resume.

    • 1 - Start FOTA for application update.

    • 2 - Start FOTA for modem delta update.

    • 3 - Start FOTA for full modem update. Can only be used when the overlay-full-fota.conf configuration file and overlay-full-fota.overlay devicetree overlay are used.

    • 5 - Start FOTA for MCUboot second-stage bootloader update. Only available when the device uses the NSIB (B0) and MCUboot as a second-stage bootloader.

      Not supported on the Thingy:91 X.

    • 7 - Read modem DFU area size and firmware image offset (for modem delta update).

    • 9 - Erase modem DFU area (for modem delta update).

  • The <file url> parameter is a string. It represents the full HTTP or HTTPS path of the target image to download. It must be provided to the start operations. For the MCUboot bootloader update, the target image must be the signed image for the inactive s0/s1 slot. You can use the AT#XBOOTINFO=1 command to query which slot is active.

  • 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. It must be provided to the start operations 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. It can be provided to the start operations.

    Note

    Raw sockets must not use the PDN connection at the same time. See Socket AT commands for more information.

After the #XFOTA: 4,0 notification indicating that the FOTA update is downloaded, it must be activated by resetting either the whole device with the AT#XRESET command, or in case of modem update only the modem with the AT#XMODEMRESET command.

Note

During a delta update to the modem, the modem DFU area is automatically erased as needed as part of the update process. Erasing this area manually is optional.

However, this leads to the command starting the update taking longer to complete, and also leaves the connection to the FOTA server idle while the area is being erased, which can provoke issues.

Note

The firmware image is stored in external flash memory during a full modem update. The external flash is erased automatically after a new firmware activation.

Activating the new modem firmware is done identically to a modem delta update, by resetting either the whole device or only the modem.

Note

For the MCUboot bootloader update, NSIB (B0) uses monotonic counter values to prevent rollback. This means that updates for MCUboot images are limited to the number of slots defined in the SB_CONFIG_SECURE_BOOT_NUM_VER_COUNTER_SLOTS Kconfig option. In Serial Modem, it is set to 40 by default.

Response syntax

AT#XFOTA=7
#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. It is 0 if no image is in the modem DFU area, and 2621440 (NRF_MODEM_DELTA_DFU_OFFSET_DIRTY) if the modem DFU area needs to be erased before a new firmware update can be received.

Example

application firmware download and update
AT#XFOTA=1,"http://remote.host/fota/sm_app_update.bin"
OK
#XFOTA: 1,0,0
...
#XFOTA: 4,0
AT#XRESET
OK
Ready
#XFOTA: 5,0

read modem DFU info
AT#XFOTA=7
#XFOTA: 294912,0
OK

modem firmware download and update
AT#XFOTA=2,"http://remote.host/fota/mfw_nrf9151_update_from_2.0.2_to_2.0.3.bin"
OK
#XFOTA: 1,0,0
...
#XFOTA: 4,0
AT#XMODEMRESET
#XFOTA: 5,0
#XMODEMRESET: 0
OK

read modem DFU info
AT#XFOTA=7
#XFOTA: 294912,2621440
OK

erase modem DFU area for next modem delta update (optional)
AT#XFOTA=9
OK

MCUboot bootloader update
AT#XBOOTINFO=1
#XBOOTINFO: 0
OK
AT#XFOTA=5,"https://remote.host/fota/signed_by_mcuboot_and_b0_s1_image.bin",42
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> parameter is an integer and can return one of the following values:

    • 0 - Init

    • 1 - Download

    • 2 - Download, erase pending (modem delta update only)

    • 3 - Download, erase complete (modem delta update only)

    • 4 - Downloaded, to be activated

    • 5 - Complete

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

    • 0 - OK

    • 1 - Error

    • 2 - Cancelled

    • 3 - Reverted (application FOTA only)

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

    <fota_stage>

    <fota_status>

    <fota_info>

    1 (namely Download)

    0 (namely OK)

    Percentage of the download

    1 (namely Download)

    1 (namely ERROR)

    Error Code

    1 (namely Download)

    2 (namely CANCELLED)

    0 - Downloading is cancelled before completion

    5 (namely Complete)

    1 (namely ERROR)

    Error Code

    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:

    • 71303169 (NRF_MODEM_DFU_RESULT_INTERNAL_ERROR) - The modem encountered a fatal internal error during firmware update.

    • 71303170 (NRF_MODEM_DFU_RESULT_HARDWARE_ERROR) - The modem encountered a fatal hardware error during firmware update.

    • 71303171 (NRF_MODEM_DFU_RESULT_AUTH_ERROR) - Modem firmware update failed due to an authentication error.

    • 71303172 (NRF_MODEM_DFU_RESULT_UUID_ERROR) - Modem firmware update failed due to UUID mismatch.

    • 71303173 (NRF_MODEM_DFU_RESULT_VOLTAGE_LOW) - Modem firmware update not executed due to low voltage. The modem will retry the update on reboot.

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

AT#XFOTA=?

Response syntax

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

Examples

AT#XFOTA=?

#XFOTA: (0,1,2,3,5,7,9),<file_url>,<sec_tag>,<pdn_id>

OK