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, radio, and Nordic-controlled 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.2.1.)

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

To perform a SUIT update over UART using the SMP protocol, install SUIT commands in nrfutil by running the nrfutil install suit command (requires nrfutil version 0.8.1 or higher).

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 nrfutil suit commands

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 CONFIG_N_BLINKS Kconfig option sets the number of blinks. The default is set to 1, causing a single blink to indicate Version 1. This value can be incremented to represent an update, such as setting it to 2 to indicate Version 2.

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:

CONFIG_N_BLINKS - Configuration for the number of blinks.

The sample configuration change the number of blinks on LED 0. The default value is 1.

CONFIG_BT_DEVICE_NAME - Configuration for Bluetooth Device Name.

The sample configuration changes the advertised Bluetooth name. Its default value is SUIT SMP 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 build the application with external flash support by running the following command from the sample directory:

west build -b nrf54h20dk/nrf54h20/cpuapp -T ./sample.suit.smp_transfer.cache_push.extflash

With this configuration, the sample is configured to use UART as the transport and the external flash is enabled. To see which Kconfig options are needed to achieve that, see the sample.suit.smp_transfer.cache_push.extflash configuration in the samples/suit/sample.yaml file.

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

west build -b nrf54h20dk/nrf54h20/cpuapp -T ./sample.suit.smp_transfer.cache_push.extflash.bt

Note

This way of building the application will enable the push scenario for updating from external flash. It will also extract the image to a DFU cache partition file. For more information, see How to push SUIT payloads to multiple partitions.

Building and running

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

Note

When using the nRF54H20 DK Engineering B (from v0.8.0 to 0.8.2), you must build samples and applications using the board revision 0.8.0 with the <board>@<revision> syntax. For example, nrf54h20dk@0.8.0/nrf54h20/cpuapp when building for the application core, or nrf54h20dk@0.8.0/nrf54h20/cpurad when building for the radio core.

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. 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
   

   See Configuring and building for information on additional configuration options.

   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 changing 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.

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, Tap on ADVANCED in the upper right corner of the app to open a new section called Images.

      

   4. Tap on the Read button within the Images section.

      

      After the list of SUIT manifests appears in the section, scroll down to verify that Sequence number: 0x1 is displayed for APP_ROOT.

      

   5. From the Firmware Upload section, tap 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. Tap 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. Tap on the Confirm button within the Images section

   

3. The update is now applied, and LED 0 flashes twice to indicate Version 2 of the firmware.

4. Under the Images section, tap on Read.

   In the section displaying the SUIT manifests list, scroll to the bottom to verify that “Sequence number: 0x2” is shown for APP_ROOT.