MCUboot image compression

MCUboot in the nRF Connect SDK optionally supports compressed image updates.

The system includes the following features and limitation:

  • Allows slot 1 to be approximately 70% the size of slot 0.

  • Supports a single-image only. It does not support network core updates for the nRF5340 SoC or nRF Secure Immutable Bootloader updates.

  • Does not support reverting to previous versions. MCUboot must be configured for upgrade-only mode.

  • Validates the compressed image during the update process before the main image is erased, ensuring the update does not lead to a bricked module due to un-loadable firmware.

  • Does not support image encryption.

  • Uses LZMA2 compression with ARM thumb filter for compressed images.

  • Must use Sysbuild.

Sample

For a demonstration of this feature, see the MCUboot with decompression enabled sample. This sample already implements the configuration requirements mentioned in Required setup below.

Required setup

You must meet the following configuration requirements for this feature to work.

Devicetree partitioning for MCUboot

The devicetree NVM partitioning for the board file should include the following partitions:

  • boot_partition - Requires a minimum size of 48 KiB for a minimal build without logging.

  • slot0_partition - Should be able to fit the largest image, including signing/imgtool overheads.

  • slot1_partition - Should be approximately 70% of the size of the slot 0 partition for optimal configuration, assuming that image savings will be 30%. The total compression depends on the data within the image.

Example layout

The following shows example partitioning for image compression:

&flash0 {
	partitions {
		ranges;
		#address-cells = <1>;
		#size-cells = <1>;

		boot_partition: partition@0 {
			compatible = "zephyr,mapped-partition";
			label = "mcuboot";
			reg = <0x00000000 0x00010000>;
		};

		slot0_partition: partition@10000 {
			compatible = "zephyr,mapped-partition";
			label = "image-0";
			reg = <0x00010000 0x00083000>;
		};

		slot1_partition: partition@93000 {
			compatible = "zephyr,mapped-partition";
			label = "image-1";
			reg = <0x00093000 0x0005d000>;
		};

		storage_partition: partition@f0000 {
			compatible = "zephyr,mapped-partition";
			label = "storage";
			reg = <0x000f0000 0x00010000>;
		};
	};
};

Required sysbuild configuration options

The following Sysbuild Kconfig options are required to enable support for compressed images:

See Configuring Kconfig for different methods of configuring these options. You want to have the following configuration in your application:

SB_CONFIG_BOOTLOADER_MCUBOOT=y
SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY=y
SB_CONFIG_MCUBOOT_COMPRESSED_IMAGE_SUPPORT=y