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.
Requirements
The sample supports the following development kit:
Hardware platforms |
PCA |
Board name |
Board target |
|---|---|---|---|
PCA10175 |
|
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 an application 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 Configuring and building an application for your preferred building environment.
Note
When building workspace applications copied from nRF repositories, building with sysbuild is enabled by default.
If you work with out-of-tree freestanding applications, you need to manually pass --sysbuild to build commands.
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:
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.
Corrupt the currently running main application (for example by flashing a modified version of the application)
Open the Device Manager or the nRF Connect application, and observe the device advertising as “SUIT Recovery”
Recover the application using Device Manager in the same way as described in the
smp_transfersample 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>/recovery/src/recovery-build/DFU/application.suit.
See the smp_transfer sample documentation to see how to perform the update using the Device Manager application.