Skip to content

Latest commit

 

History

History
256 lines (164 loc) · 12.6 KB

fota_update.rst

File metadata and controls

256 lines (164 loc) · 12.6 KB

FOTA updates on nRF54L Series devices

|fota_upgrades_def| You can also use FOTA updates to replace the application. See the :ref:`app_dfu` page for general Device Firmware Update (DFU) information, such as supported methods for sending and receiving updates on the device. Currently, FOTA updates are supported only for the application core. For more information about introducing immutable MCUboot bootloader, refer to :ref:`ug_bootloader_adding_sysbuild_immutable_mcuboot`.

Note

The nRF54L SoC's support hardware Key Management Unit (KMU), designed to provide authentication keys for DFU purposes. Ensure you complete the :ref:`KMU provisioning<ug_nrf54l_developing_provision_kmu>` during your device's DFU setup with KMU enabled. Failing to do so may prevent your application from booting properly.

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 (:kconfig:option:`CONFIG_BT_PERIPHERAL`).

By default, the application supports SMP handlers related to:

  • Image management
  • Operating System (OS) management, which is used to reboot the device after completing firmware uploads
  • Erasing the settings partition to prevent booting a new application with incompatible content that was written by the previous application

To enable support for FOTA updates, do the following:

If necessary, you can modify any of the implied options or defaulted values introduced by the :kconfig:option:`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 :ref:`peripheral_lbs` sample:

 west build -b board_target -- -DSB_CONFIG_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 :zephyr:code-sample:`smp-svr`.

Testing steps

To perform a FOTA update, complete the following steps:

  1. Locate the :file:`dfu_application.zip` archive in the build directory. The archive is automatically generated after adding the DFU configuration and building your project.

    Note

    For each image included in the DFU-generated package, use a higher version number than your currently active firmware. You can do this by modifying the VERSION file in the application directory or by making changes to the application code. For the semantic versioning, modify the :kconfig:option:`CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION` Kconfig option. For the monotonic counter (HW), modify the SB_CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_VALUE Kconfig option. Otherwise, the DFU target may reject the FOTA process due to a downgrade prevention mechanism.

  2. Download the :file:`dfu_application.zip` archive to your mobile phone. See :ref:`app_build_output_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 :file:`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 :guilabel:`Image` tab.

    4. Tap the :guilabel:`SELECT FILE` button and select the :file:`dfu_application.zip` archive.

    5. Tap the :guilabel:`START` button.

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

      • If you are using an Android phone or tablet, select a mode in the dialog window, and tap the :guilabel:`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 new application works properly by observing the new device name visible in the Device Manager app.

FOTA update sample

The :zephyr:code-sample:`smp-svr` demonstrates how to set up your project to support FOTA updates.

When working in the |NCS| environment, ignore the part of the sample documentation that describes the building and programming steps. In |NCS|, you can build and program the :zephyr:code-sample:`smp-svr` as any other sample using the following commands:

.. tabs::

    .. group-tab:: nRF54L SoCs

        .. parsed-literal::
           :class: highlight

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

    .. group-tab:: nRF54L SoCs with HW cryptography support

        .. parsed-literal::
           :class: highlight

            west build -b *board_target* -- -DEXTRA_CONF_FILE=overlay-bt.conf -DSB_CONFIG_BOOT_SIGNATURE_TYPE_ED25519=y -DSB_CONFIG_BOOT_SIGNATURE_TYPE_PURE=y -Dmcuboot_CONFIG_PM_PARTITION_SIZE_MCUBOOT=0x10000 -DSB_CONFIG_MCUBOOT_SIGNATURE_USING_KMU=y
            west flash


    .. group-tab:: nRF54L15 DK with SPI Flash as update image bank

        .. parsed-literal::
           :class: highlight

            west build -b nrf54l15dk/nrf54l15/cpuapp -T sample.mcumgr.smp_svr.bt.nrf54l15dk.ext_flash
            west flash

    .. group-tab:: nRF54l15 DK with SPI Flash as update image (DTS partitioning)

       To build with the DTS partitioning, run the following command:

        .. parsed-literal::
           :class: highlight

            west build -b nrf54l15dk/nrf54l15/cpuapp -d build/smp_svr_54l_d zephyr/samples/subsys/mgmt/mcumgr/smp_svr -T sample.mcumgr.smp_svr.bt.nrf54l15dk.ext_flash.pure_dts

Make sure to indicate the :file:`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.

Provisioning of keys for Hardware KMU

In case of FOTA implementations using the MCUboot bootloader, which includes hardware cryptography and KMU, you must complete key provisioning before booting any application. Otherwise, the bootloader :ref:`may not boot the firmware setup and might take unwanted actions<ug_nrf54l_developing_basics_kmu_provisioning_keys>`. Refer to :ref:`ug_nrf54l_developing_provision_kmu` for detailed description.

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 :doc:`mcuboot:design` page.

Note

Direct-xip mode cannot be combined with image encryption. In addition, when building a project with direct-xip for the nRF54L SoC targets, a static partition manager file is required for partitioning. See NCSDK-30119 issue on the :ref:`known_issues` 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 :ref:`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 :ref:`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 with MCUboot in direct-xip mode with revert mechanism support, the signed image intended for flashing is automatically marked as confirmed (Pre-confirmation). Without this configuration, the application will fail to boot. Confirmation mark should not, however, be added 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 :ref:`app_build_mcuboot_output` 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.