MCUboot with decompression enabled

This sample demonstrates how to enable and use image compression within MCUboot, which allows for smaller application updates to be loaded to a device.

Requirements

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Board target
nRF7120 DK		nrf7120dk	nrf7120dk/nrf7120/cpuapp
nRF54LV10 DK	PCA10188	nrf54lv10dk	nrf54lv10dk/nrf54lv10a/cpuapp
nRF54LS05 DK	PCA10214	nrf54ls05dk	nrf54ls05dk/nrf54ls05b/cpuapp
nRF54LM20 DK	PCA10184	nrf54lm20dk	nrf54lm20dk/nrf54lm20b/cpuapp nrf54lm20dk/nrf54lm20a/cpuapp
nRF54L15 DK	PCA10156	nrf54l15dk	nrf54l15dk/nrf54l15/cpuapp
nRF5340 DK	PCA10095	nrf5340dk	nrf5340dk/nrf5340/cpuapp
nRF52840 DK	PCA10056	nrf52840dk	nrf52840dk/nrf52840

Overview

This sample is using the nRF Compression library.

The sample’s default configuration has the following features enabled:

• MCUboot in the upgrade-only mode with the Kconfig option CONFIG_BOOT_UPGRADE_ONLY set to y.

• Single-update image with the Kconfig option CONFIG_UPDATEABLE_IMAGE_NUMBER set to 1.

When the sample is built, the build system automatically generates the update binary files with compressed image data and flags set. These files match the requirements for MCUboot image compression.

Configuration

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

See Configuring Kconfig for information about the different ways you can set Kconfig options in the nRF Connect SDK.

Configuration options

CONFIG_OUTPUT_BOOT_MESSAGE

(bool) Output message on boot

Will output a dummy message on boot, this is to allow for generating a different image that can be used to test the compressed firmware update.

Building and running

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

To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

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.

To upload MCUboot and the bundle of images to the device, program the sample by using the flash command without erase.

Testing over Bluetooth LE

The testing scenario uses the FOTA over Bluetooth LE method to load the firmware update to the device. For the testing scenario to work, make sure you meet the following requirements:

• Your update image differs from the base image so that the update can be applied.

• Change the firmware version by setting CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION to "2.0.0".

• Set the CONFIG_OUTPUT_BOOT_MESSAGE Kconfig option to y.

• You are familiar with the FOTA over Bluetooth LE method (see the guide for the nRF52840 DK, the guide for the nRF5340 DK, and the guide for the nRF54L15 DK).

• You have the nRF Connect Device Manager mobile app installed on your smartphone to update your device with the new firmware over Bluetooth LE.

Meeting these requirements requires rebuilding the sample.

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 serial port. Serial ports are referred to as COM ports on Windows, /dev/ttyACM devices on Linux, and /dev/tty devices on macOS. To list Nordic Semiconductor devices connected to your computer together with their serial ports, open a terminal and run the nrfutil device list command. Alternatively, check your operating system’s device manager or its equivalent.

2. Connect to the kit with a terminal emulator (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.

3. Start the nRF Connect Device Manager mobile app.

4. Follow the testing steps for the FOTA over Bluetooth LE. See the following sections of the documentation:

   • Testing steps for FOTA over Bluetooth LE with nRF52840

   • Testing steps for FOTA over Bluetooth LE with nRF5340

   • Testing steps for FOTA over Bluetooth LE with nRF54L15

5. Once the firmware update has been loaded, check the UART output. See the following Sample output section.

6. Reboot the device. The compressed firmware update will be applied to the device and it will boot into it.

   Note

   At this point, the compressed flags will not be present in the running application image, as the firmware update has been decompressed whilst copying to the primary slot.

Sample output

After a firmware update has been loaded, the UART will output the information on the image which will be one of the following:

LZMA2 with ARM

The following output is logged:

Secondary slot image is LZMA2 compressed with ARM thumb filter applied

This indicates that the loaded firmware update has been compressed using LZMA2 and had the ARM thumb filter applied. This offers the best compression ratio and is recommended for general usage.

LZMA2 only

The following output is logged:

Secondary slot image is LZMA2 compressed

This indicates that the loaded firmware update has been compressed using LZMZ2. This offers a good compression ratio but is not optimal.

No LZMA2

The following output is logged:

Secondary slot image is uncompressed

This indicates that the loaded firmware update has not been compressed at all. This is a suboptimal and incorrect update.

For information about how these compression types are configured in the nRF Compression library, see Compression types configuration in its documentation.

Dependencies

The sample uses the following Zephyr library:

• MCUmgr

It also uses the following nRF Connect SDK library:

• Partition Manager

• nRF Compression