SUIT: Recovery application

The SUIT recovery application is a minimal application that allows recovering the device firmware if the original firmware is damaged. It is to be used as a companion firmware to the main application that is using Software Update for Internet of Things (SUIT) procedure, rather than a stand-alone application.

The following limitations apply to this application:

  • The recovery firmware is only able to recover from a situation where the application or radio core are damaged. It does not recover from Nordic Semiconductor-controlled firmware failures.

  • The recovery firmware is not compatible with a main application that uses a external flash for update.

Requirements

The sample supports the following development kit:

Hardware platforms

PCA

Board name

Board target

nRF54H20 DK

PCA10175

nrf54h20dk

nrf54h20dk/nrf54h20/cpuapp

Overview

The application uses the SMP protocol through Bluetooth® Low Energy and SUIT to perform the recovery. It is optimized for memory usage and only contains the basic necessary functionalities.

Caution

This firmware is only able to recover from a situation where the application or radio core are damaged. It does not recover from Nordic Semiconductor-controlled firmware failures.

Configuration

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

As the recovery firmware is a companion image, it must be compatible with the main application in terms of hardware configuration (especially the memory partitions). To achieve this, the appropriate devicetree overlay files from the main application must be passed to the recovery application.

To do this, add the recovery.overlay and recovery_hci_ipc.ovelay files in the main application’s Sysbuild directory. The former file will be passed automatically to the recovery application image and the latter to the recovery radio image. These devicetree files must define the cpuapp_recovery_partition and cpurad_recovery_partition nodes respectively.` For an example, see the files in the samples/suit/smp_transfer sample.

Building and running

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

Including recovery application image with sysbuild

In standard applications, the recovery firmware is built as part of the main application build.

Apart from creating the mentioned recovery.overlay and recovery_hci_ipc.ovelay files, you must set the SB_CONFIG_SUIT_BUILD_RECOVERY sysbuild configuration option in the main application. This will cause the recovery firmware to be built automatically as part of the main application build.

To build the main application, follow the instructions in Building an application for your preferred building environment.

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.

For example, to build the Device firmware update on the nRF54H20 SoC sample with the recovery firmware on the command line, you can run the following command:

west build -b nrf54h20dk/nrf54h20/cpuapp -- -DFILE_SUFFIX=bt -DSB_CONFIG_SUIT_BUILD_RECOVERY=y

The recovery firmware will be flashed automatically from the main application directory.

See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Testing

After programming the sample to your development kit, complete the following steps to test it:

  1. Connect the kit to the computer using a USB cable. The kit is assigned a COM port (Windows) or ttyACM device (Linux), which is visible in the Device Manager.

  2. Corrupt the currently running main application (for example by flashing a modified version of the application)

  3. Open the Device Manager or the nRF Connect application, and observe the device advertising as “SUIT Recovery”

  4. Recover the application using Device Manager in the same way as described in the smp_transfer sample documentation.

Device firmware update for recovery firmware

To update the recovery firmware, perform a SUIT firmware update using the SUIT envelope found in <main_application_build_directory>/DFU/app_recovery.suit. For updating using the Device Manager application, you can also use the zip file found in <main_application_build_directory>/zephyr/dfu_suit_recovery.zip.

See SUIT: Device firmware update on the nRF54H20 SoC to see how to perform the update using the Device Manager application.