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.

  • Requires a static Partition Manager file.

  • Must use Sysbuild.

Sample

For a demonstration of this feature, see the nRF Compression: MCUboot compressed update 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.

Static Partition Manager file for MCUboot

The static Partition Manager file should include the following partitions:

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

  • 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.

For more information about the static Partition Manager file, see Static and dynamic configuration in the Partition Manager documentation.

Example of static Partition Manager layout

The following shows an example static Partition Manager layout for image compression:

app:
  address: 0x10200
  end_address: 0xa2000
  region: flash_primary
  size: 0x91e00
EMPTY_1:
  address: 0x0
  end_address: 0x10200
  device: MX25R64
  region: external_flash
  size: 0x10200
compressed_app:
  address: 0x10200
  end_address: 0xa2000
  device: MX25R64
  region: external_flash
  size: 0x91e00
EMPTY_2:
  address: 0xa2000
  end_address: 0x800000
  device: MX25R64
  region: external_flash
  size: 0x75e000
mcuboot:
  address: 0x0
  end_address: 0x10000
  region: flash_primary
  size: 0x10000
mcuboot_pad:
  address: 0x10000
  end_address: 0x10200
  region: flash_primary
  size: 0x200
mcuboot_primary:
  address: 0x10000
  end_address: 0xa2000
  orig_span: &id001
  - mcuboot_pad
  - app
  region: flash_primary
  size: 0x92000
  span: *id001
mcuboot_primary_app:
  address: 0x10200
  end_address: 0xa2000
  orig_span: &id002
  - app
  region: flash_primary
  size: 0x91e00
  span: *id002
mcuboot_secondary:
  address: 0xa2000
  end_address: 0xf0000
  region: flash_primary
  size: 0x4e000
settings_storage:
  address: 0xf0000
  end_address: 0x100000
  region: flash_primary
  size: 0x10000

Required sysbuild configuration options

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

  • SB_CONFIG_BOOTLOADER_MCUBOOT

  • SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY

  • SB_CONFIG_MCUBOOT_COMPRESSED_IMAGE_SUPPORT

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