SUIT: Device firmware update on the nRF54H20 SoC

The sample demonstrates how to update and boot the nRF54H20 System-on-Chip (SoC) using the Software Update for Internet of Things (SUIT) procedure on the application and radio cores of the SoC. The update on the nRF54H20 SoC can be done over Bluetooth® Low Energy or UART.

Requirements

The sample supports the following development kit:

Hardware platforms

PCA

Board name

Board target

nRF54H20 DK

PCA10175

nrf54h20dk

nrf54h20dk/nrf54h20/cpuapp

You need the nRF Device Manager app for SUIT update over Bluetooth Low Energy:

For a SUIT update over UART, you need to install MCUmgr, a tool that can be used to upload SUIT envelopes through the SMP protocol.

Overview

The sample uses one of the following methods to perform a firmware update on the nRF54H20 SoC, featuring Nordic Semiconductor’s implementation of the SUIT procedure:

  • Bluetooth Low Energy and the nRF Device Manager app

  • UART and MCUmgr

The sample demonstrates how to perform a DFU of the application and radio firmware.

SUIT is the only DFU procedure supported for the nRF54H20 SoCs. To read more about the SUIT procedure, see Introduction to SUIT.

User interface

LED 0:

The number of blinks indicates the application SUIT envelope sequence number. The default is set to 1 to blink once, indicating “Version 1”.

Configuration

See Configuring and building for information about how to permanently or temporarily change the configuration.

The default configuration uses UART with sequence number 1 (shown as Version 1 in the nRF Device Manager app).

To change the sequence number of the application, configure the APP_ROOT_SEQ_NUM inside the VERSION file, used for Application version management in Zephyr and the nRF Connect SDK. It sets the sequence number of the SUIT envelope’s manifest. If you do not provide the VERSION file, the sample is built with sequence number set to 1 (shown as Version 1 in the nRF Device Manager app).

To change the number of blinks on LED 0, configure the CONFIG_N_BLINKS Kconfig option. If you do not specify this configuration, the sample is built with the number of blinks set to 1.

Configuration options

Check and configure the following configuration option for the sample:

Modify partition sizes

You can also modify the size and location of the partitions. This is done by modifying the values for the desired location and size of the partition in the devicetree .overlay files.

  • To modify the application core’s partition size, modify the values for cpuapp_slot0_partition defined in the nrf/samples/suit/smp_transfer/sysbuild/nrf54h20dk_nrf54h20_memory_map.dtsi.

  • To modify the DFU partition, modify the values for dfu_partition defined in samples/suit/smp_transfer/boards/nrf54h20dk_nrf54h20_cpuapp.overlay. This partition is where the update candidate is stored before the update process begins.

Manifest template files

The SUIT DFU procedure requires an envelope to transport the firmware update, and SUIT envelopes require a SUIT manifest template as a source file. All required manifest template files (used to later create SUIT envelopes) are automatically created during the first sample build, and are the following:

  • The root manifest - root_hierarchical_envelope.yaml.jinja2

  • The application domain manifest - app_envelope.yaml.jinja2

  • The radio domain manifest - rad_envelope.yaml.jinja2

See SUIT output build files for a full table of SUIT-generated output files.

Note

The radio domain manifest template (radio.suit) is only created when building the Bluetooth Low Energy version of the sample, and not the UART version. Currently, it is not needed for the UART version.

If you want to make modifications to how the DFU is executed in this sample, you can do so by editing the manifest templates, or generating your own custom manifests. See the How to customize the SUIT DFU process user guide for instructions and examples.

External flash support

You can enable the external flash support by setting the following FILE_SUFFIX=extflash parameter:

west build -p -b nrf54h20dk/nrf54h20/cpuapp -- -DFILE_SUFFIX="extflash"

With this configuration, the sample is configured to use UART as the transport and the external flash is enabled.

To enable both the external flash and the BLE transport, use the following command:

west build -p -b nrf54h20dk/nrf54h20/cpuapp -- -DFILE_SUFFIX="extflash" -DOVERLAY_CONFIG="sysbuild/smp_transfer_bt.conf" -DSB_OVERLAY_CONFIG="sysbuild_bt.conf"

Building and running

This sample can be found under samples/suit/smp_transfer in the nRF Connect SDK folder structure.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

Building and programming using the command line

To build and program the sample to the nRF54H20 DK, complete the following steps:

  1. Start the toolchain environment in a terminal window.

  2. Navigate to samples/suit/smp_transfer.

  3. Build the sample using the following command, with the following Kconfig options set:

    west build -p -b nrf54h20dk/nrf54h20/cpuapp -- -DFILE_SUFFIX=bt -DCONFIG_N_BLINKS=1

    The output build files can be found in the build/DFU directory, including the SUIT output build files. For more information on the contents of the build directory, see Build Directory Contents in the Zephyr documentation. For more information on the directory contents and structure provided by sysbuild, see Sysbuild (System build) in the Zephyr documentation.

  4. Connect the DK to your computer using a USB cable.

  5. Power on the DK.

  6. Program the sample to the kit (see Programming an application for instructions).

  7. Update the SUIT envelope sequence number, by appending the following line to the VERSION file:

    APP_ROOT_SEQ_NUM = 2

  8. Update the number of LED blinks, by rebuilding the sample with the following Kconfig options set:

    west build -b nrf54h20dk/nrf54h20/cpuapp -- -DFILE_SUFFIX=bt -DCONFIG_N_BLINKS=2

    Another root.suit file is created after running this command, that contains the updated firmware. You must manually transfer this file onto the same mobile device you will use with the nRF Device Manager app.

Testing

After programming the sample to your development kit and updating the sequence number of the SUIT envelope, complete the following steps to test it.

  1. Upload the signed envelope onto your mobile phone:

    1. Open the nRF Device Manager app on your mobile phone.

    2. Select the device SUIT SMP Sample. You should see the following:

      Select SUIT SMP Sample

    3. From the SUIT SMP Sample screen, on the Images tab at the bottom of the screen, click on ADVANCED in the upper right corner of the app to open a new section called Images.

      Select ADVANCED

    4. Click on the READ button within the Images section.

      Select READ from Images

      You should now see that “Version: 1” is printed in the Images section of the mobile app.

    5. From the Firmware Upload section, click on SELECT FILE and select the root.suit file from your mobile device.

      Note

      As described in Step 1, you must manually add the root.suit file to the same mobile device you are using for nRF Device Manager.

      Select Firmware Upload and Select File

    6. Click on UPLOAD to upload the root.suit file.

      You should see an upload progress bar below the “UPLOADING…” text in the Firmware Upload section.

      Firmware UPLOADING

      The text “UPLOAD COMPLETE” appears in the Firmware Upload section once completed.

      Firmware UPLOAD COMPLETE

  2. Reconnect your device.

  3. Select the device SUIT SMP Sample once again.

    Images Version 2

  4. Under the Images section, click on READ.

    You should see that “Version: 2” is now printed in the Images section of the mobile app.

    Additional, LED 0 now flashes twice now to indicate “Version 2” of the firmware.