FOTA updates on nRF52 Series devices

You can update the firmware of the device over the air, thus without a wired connection. Such an update is called a FOTA (firmware over-the-air) update. You can also use FOTA updates to replace the application. See the MCUboot and NSIB page for general Device Firmware Update (DFU) information, such as supported methods for sending and receiving updates on the device.

Note

For the possibility of introducing an upgradable bootloader, refer to Enabling a bootloader chain using child and parent images (deprecated).

FOTA over Bluetooth Low Energy

FOTA updates are supported using MCUmgr’s Simple Management Protocol (SMP) over Bluetooth. The application acts as a GATT server and allows the connected Bluetooth Central device to perform a firmware update. To use FOTA over Bluetooth LE, samples must support Bluetooth peripheral role (CONFIG_BT_PERIPHERAL).

The application supports SMP handlers related to:

  • Image management.

  • Operating System (OS) management used to reboot the device after the firmware upload is complete.

  • Erasing settings partition used to ensure that a new application is not booted with incompatible content in the settings partition written by the previous application.

To enable support for FOTA updates, do the following:

  • Enable the CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU Kconfig option, which implies configuration of the following:

    • All of the SMP command handlers mentioned in the previous paragraph.

    • SMP BT reassembly feature.

    • The CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU_SPEEDUP Kconfig option automatically extends the Bluetooth buffers, which allows to speed up the FOTA transfer over Bluetooth, but also increases RAM usage.

Note

The CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU Kconfig option can be used devices to enable MCUmgr to perform firmware over-the-air (FOTA) updates using Bluetooth LE. It can be used along with other samples, and is meant as a demonstration of the default DFU configuration over Bluetooth.

If necessary, you can modify any of the implied options or defaulted values introduced by the CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU Kconfig option.

You can either add these Kconfig options to the configuration files of your application or have them inline in a project build command. Here is an example of how you can build for the Bluetooth: Peripheral LBS sample:

 west build -b board_target -- -DCONFIG_BOOTLOADER_MCUBOOT=y -DCONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU=y

When you connect to the device after the build has completed and the firmware has been programmed to it, the SMP Service is enabled with the UUID 8D53DC1D-1DB7-4CD3-868B-8A527460AA84. If you want to add SMP Service to advertising data, refer to the SMP server.

Build configuration additions for MCUboot in the direct-xip mode

FOTA updates are also supported when MCUboot is in the direct-xip mode. In this mode, the MCUboot bootloader boots an image directly from a given slot, so the swap operation is not needed. It can be used either with or without the revert mechanism support. For more information about the direct-xip mode and the revert mechanism support, go to the Equal slots (direct-xip) section on the Bootloader page.

To use MCUboot in the direct-xip mode together with FOTA updates, do the following:

  • Enable the SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP Kconfig option in sysbuild.

See how to build the Bluetooth: Peripheral LBS sample with MCUboot in the direct-xip mode when the revert mechanism support is disabled:

 west build -b board_target -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -DSB_CONFIG_MCUBOOT_MODE_DIRECT_XIP=y -DCONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU=y

Optionally, if you want to enable the revert mechanism support, complete the following:

  • Enable the SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT Kconfig option in sysbuild instead of SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP.

See how to build the Bluetooth: Peripheral LBS sample with MCUboot in direct-xip mode when the revert mechanism support is enabled:

 west build -b board_target -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -DSB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT=y -DCONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU=y

Note

When building the application for the first time with MCUboot in direct-xip mode and the revert mechanism support, use an additional option -DCONFIG_MCUBOOT_EXTRA_IMGTOOL_ARGS=\"--confirm\". This option will mark the application as confirmed during the image signing process. If the application is built without this option, it will fail to boot. It must, however, be disabled when building update images.

Both the SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP and SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT Kconfig options automatically build application update images for both slots. To read about the files that are built when the option is enabled, refer to the MCUboot output build files page.

Note

Support for FOTA updates with MCUboot in the direct-xip mode is available since the following versions of the nRF Connect Device Manager mobile app:

  • Version 1.8.0 on Android.

  • Version 1.4.0 on iOS.

Testing steps

To perform a FOTA update, complete the following steps:

  1. Generate the DFU package by building your application with the FOTA support over Bluetooth Low Energy. You can find the generated dfu_application.zip archive in the build directory.

    Note

    For each image included in the DFU-generated package, use a higher version number than your currently active firmware. Otherwise, the DFU target may reject the FOTA process due to a downgrade prevention mechanism.

  2. Download the dfu_application.zip archive to your device. See Output build files (image files) for more information about the contents of update archive.

    Note

    nRF Connect for Desktop does not currently support the FOTA process.

  3. Use the nRF Connect Device Manager mobile app to update your device with the new firmware.

    1. Ensure that you can access the dfu_application.zip archive from your phone or tablet.

    2. In the mobile app, scan and select the device to update.

    3. Switch to the Image tab.

    4. Tap the SELECT FILE button and select the dfu_application.zip archive.

    5. Tap the START button.

      Note

      When performing a FOTA update with the iOS app for samples using random HCI identities, ensure that the Erase application settings option is deselected before starting the procedure. Otherwise, the new image will boot with random IDs, causing communication issues between the app and the device.

    6. Initiate the DFU process of transferring the image to the device:

      • If you are using an Android device, select a mode in the dialog window, and tap the START button.

      • If you are using an iOS device, tap the selected mode in the pop-up window.

      Note

      For samples using random HCI identities, the Test and Confirm mode should not be used.

    7. Wait for the DFU to finish and then verify that the application works properly.

FOTA update sample

The SMP server demonstrates how to set up your project to support FOTA updates.

The sample documentation is from the Zephyr project and is incompatible with the Multi-image builds using child and parent images. When working in the nRF Connect SDK environment, ignore the part of the sample documentation that describes the building and programming steps. In nRF Connect SDK, you can build and program the SMP server as any other sample using the following commands:

 west build -b board_target -- -DEXTRA_CONF_FILE=overlay-bt.conf -DSB_CONFG_NETCORE_HCI_IPC=y
 west flash

Make sure to indicate the overlay-bt.conf overlay configuration for the Bluetooth transport like in the command example. This configuration was carefully selected to achieve the maximum possible throughput of the FOTA update transport over Bluetooth with the help of the following features:

Consider using these features in your project to speed up the FOTA update process.

FOTA in Bluetooth Mesh

When performing a FOTA update when working with the Bluetooth Mesh protocol, use one of the following DFU methods:

  • DFU over Bluetooth Mesh using the Zephyr Bluetooth Mesh DFU subsystem.

  • Point-to-point DFU over Bluetooth Low Energy as described in FOTA over Bluetooth Low Energy above. The Bluetooth Mesh samples use random HCI identities. See the related notes in the Testing steps section.

For more information about both methods, see Performing Device Firmware Updates (DFU) in Bluetooth Mesh.

FOTA in Matter

To perform a FOTA upgrade when working with the Matter protocol, use one of the following methods:

  • DFU over Bluetooth LE using either smartphone or PC command-line tool. Both options are similar to FOTA over Bluetooth Low Energy.

    Note

    This protocol is not part of the Matter specification.

  • DFU over Matter using Matter-compliant BDX protocol and Matter OTA Provider device. This option requires an OpenThread Border Router (OTBR) set up either in Docker or on a Raspberry Pi.

For more information about both methods, read the Performing Device Firmware Upgrade in the nRF Connect examples page in the Matter documentation.

FOTA over Thread

Thread does not offer a proprietary FOTA method.

FOTA over Zigbee

You can enable support for FOTA over the Zigbee network using the Zigbee FOTA library. For detailed information about how to configure the Zigbee FOTA library for your application, see Configuring Zigbee FOTA.