nRF Compression: MCUboot compressed update

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
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: When enabled, this optional configuration option outputs a message at run-time that allows for checking if the image has been updated successfully.

Building and running 

This sample can be found under samples/nrf_compress/mcuboot_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.
You changed the firmware version by setting CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION to "2.0.0".
You 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 and the guide for the nRF5340 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:

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.
Connect to the kit with a terminal emulator (for example, nRF Connect Serial Terminal). See Testing and optimization for the required settings and steps.
Start the nRF Connect Device Manager mobile app.
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
- Not yet available: Testing steps for FOTA over Bluetooth LE with nRF54L15
Once the firmware update has been loaded, check the UART output. See the following Sample output section.
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: