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:

• nRF Device Manager mobile app for Android (The minimum required version is v2.0.)

• nRF Device Manager mobile app for iOS (The minimum required version is v1.7.)

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 an application 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 SB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM sysbuild Kconfig option. This also changes the number of blinks on LED 0 and sets the sequence number of the SUIT envelope’s manifest.

To use this configuration, build the sample with Sysbuild and set the SB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM sysbuild Kconfig option to x, where x is the version number. For example:

west build -b nrf54h20dk/nrf54h20/cpuapp -- -DSB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM=2

If you do not specify this configuration, the sample is built with sequence number 1 (shown as Version 1 in the nRF Device Manager app).

Configuration options

Check and configure the following configuration option for the sample:

SB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM - Configuration for the sequence number.

The sample configuration updates the sequence number of the SUIT envelope, which is reflected as the version of the application in the nRF Device Manager app. The default value is 1.

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:

Over Bluetooth Low EnergyOver UART

1. Open a terminal window in samples/suit/smp_transfer.

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

   west build -p -b nrf54h20dk/nrf54h20/cpuapp -- -DFILE_SUFFIX=bt -DSB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM=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.

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

4. Power on the DK.

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

6. Update the SUIT envelope sequence number, by rebuilding the sample with an updated sequence number:

   west build -b nrf54h20dk/nrf54h20/cpuapp -- -DFILE_SUFFIX=bt -DSB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM=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.

Over Bluetooth Low EnergyOver UART

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:

      

   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.

      

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

      

      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.

      

   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.

      

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

      

2. Reconnect your device.

3. Select the device SUIT SMP Sample once again.

   

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.