.. _SM_AT_FOTA: FOTA AT commands **************** .. contents:: :local: :depth: 2 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=[,[,[,]]] * The ```` 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 :file:`overlay-full-fota.conf` configuration file and :file:`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 ```` 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 ```` 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 ```` 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 :ref:`SM_AT_SOCKET_RAW_SOCKET_LIMITATION` 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 |SM|, it is set to ``40`` by default. Response syntax ~~~~~~~~~~~~~~~ :: AT#XFOTA=7 #XFOTA: , * The ```` integer gives the size of the modem DFU area in bytes. * The ```` 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: ,[,] * The ```` 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 ```` parameter is an integer and can return one of the following values: * ``0`` - OK * ``1`` - Error * ``2`` - Cancelled * ``3`` - Reverted (application FOTA only) * The ```` parameter is an integer. Its value can have different meanings based on the values returned by ```` and ````. See the following table: +-------------------------+----------------------------+----------------------------------------------------+ |```` |```` | ```` | +=========================+============================+====================================================+ |``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 ```` is ``1`` but ```` 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: ,,, Examples ~~~~~~~~ :: AT#XFOTA=? #XFOTA: (0,1,2,3,5,7,9),,, OK