Skip to content

Commit bc2ef91

Browse files
nordicjmrlubos
nordicjm
authored and
rlubos
committed
samples: nrf_compress: mcuboot_update: Add README
Adds a README file to this sample Signed-off-by: Jamie McCrae <[email protected]>
1 parent 34ae146 commit bc2ef91

File tree

7 files changed

+233
-65
lines changed

7 files changed

+233
-65
lines changed

‎doc/nrf/app_dev/bootloaders_dfu/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,3 +52,4 @@ To learn more, refer to the following documentation pages:
5252
mcuboot_nsib/bootloader_mcuboot_nsib
5353
qspi_xip_split_image
5454
dfu_tools_mcumgr_cli
55+
mcuboot_image_compression

‎doc/nrf/app_dev/bootloaders_dfu/mcuboot_image_compression.rst‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
.. _mcuboot_image_compression:
2+
3+
MCUboot image compression
4+
#########################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
:ref:`MCUboot <mcuboot:mcuboot_wrapper>` in the |NCS| optionally supports compressed image updates.
11+
12+
The system includes the following features and limitation:
13+
14+
* Allows slot ``1`` to be approximately 70% the size of slot ``0``.
15+
* Supports a single-image only.
16+
It does not support network core updates for the nRF5340 SoC or :ref:`bootloader` updates.
17+
* Does not support reverting to previous versions.
18+
MCUboot must be configured for upgrade-only mode.
19+
* 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.
20+
* Does not support image encryption.
21+
* Uses LZMA2 compression with ARM thumb filter for compressed images.
22+
* Requires a static :ref:`Partition Manager <partition_manager>` file.
23+
* Must use :ref:`configuration_system_overview_sysbuild`.
24+
25+
Sample
26+
******
27+
28+
For a demonstration of this feature, see the :ref:`nrf_compression_mcuboot_compressed_update` sample.
29+
This sample already implements the configuration requirements mentioned in :ref:`mcuboot_image_compression_setup` below.
30+
31+
.. _mcuboot_image_compression_setup:
32+
33+
Required setup
34+
**************
35+
36+
You must meet the following configuration requirements for this feature to work.
37+
38+
Static Partition Manager file for MCUboot
39+
=========================================
40+
41+
The static Partition Manager file should include the following partitions:
42+
43+
* ``boot_partition`` - Requires a minimum size of 48 KiB for a minimal build without logging.
44+
* ``slot1_partition`` - Should be approximately 70% of the size of the slot ``0`` partition for optimal configuration, assuming that image savings will be 30%.
45+
The total compression depends on the data within the image.
46+
47+
For more information about the static Partition Manager file, see :ref:`ug_pm_static` in the Partition Manager documentation.
48+
49+
Example of static Partition Manager layout
50+
------------------------------------------
51+
52+
The following shows an example static Partition Manager layout for image compression:
53+
54+
.. tabs::
55+
56+
.. group-tab:: nRF52840
57+
58+
.. literalinclude:: ../../../../tests/subsys/nrf_compress/decompression/mcuboot_update/pm_static_nrf52840dk_nrf52840.yml
59+
:language: yaml
60+
61+
.. group-tab:: nRF5340
62+
63+
.. literalinclude:: ../../../../tests/subsys/nrf_compress/decompression/mcuboot_update/pm_static_nrf5340dk_nrf5340_cpuapp.yml
64+
:language: yaml
65+
66+
.. group-tab:: nRF54L15
67+
68+
.. literalinclude:: ../../../../tests/subsys/nrf_compress/decompression/mcuboot_update/pm_static_nrf54l15dk_nrf54l15_cpuapp.yml
69+
:language: yaml
70+
71+
Required sysbuild configuration options
72+
=======================================
73+
74+
The following :ref:`configuration_system_overview_sysbuild` Kconfig options are required to enable support for compressed images:
75+
76+
* :kconfig:option:`SB_CONFIG_BOOTLOADER_MCUBOOT`
77+
* :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY`
78+
* :kconfig:option:`SB_CONFIG_MCUBOOT_COMPRESSED_IMAGE_SUPPORT`
79+
80+
See :ref:`configuring_kconfig` for different methods of configuring these options.
81+
You want to have the following configuration in your application:
82+
83+
.. code-block:: cfg
84+
85+
SB_CONFIG_BOOTLOADER_MCUBOOT=y
86+
SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY=y
87+
SB_CONFIG_MCUBOOT_COMPRESSED_IMAGE_SUPPORT=y

‎doc/nrf/app_dev/device_guides/nrf52/fota_update.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ See the :ref:`app_dfu` page for general Device Firmware Update (DFU) information
1818

1919
.. fota_upgrades_intro_end
2020
21+
.. _ug_nrf52_developing_ble_fota_steps:
22+
2123
FOTA over Bluetooth Low Energy
2224
******************************
2325

@@ -125,6 +127,8 @@ To read about the files that are built when the option is enabled, refer to the
125127
126128
.. fota_upgrades_over_ble_mcuboot_direct_xip_information_end
127129
130+
.. _ug_nrf52_developing_ble_fota_steps_testing:
131+
128132
Testing steps
129133
=============
130134

‎doc/nrf/app_dev/device_guides/nrf53/fota_update_nrf5340.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ FOTA updates with nRF5340 DK
1111
:start-after: fota_upgrades_intro_start
1212
:end-before: fota_upgrades_intro_end
1313

14+
.. _ug_nrf53_developing_ble_fota_steps:
15+
1416
FOTA over Bluetooth Low Energy
1517
******************************
1618

@@ -28,6 +30,8 @@ Bluetooth buffers configuration introduced by the :kconfig:option:`CONFIG_NCS_SA
2830
:start-after: fota_upgrades_over_ble_additional_information_start
2931
:end-before: fota_upgrades_over_ble_additional_information_end
3032

33+
.. _ug_nrf53_developing_ble_fota_steps_testing:
34+
3135
Testing steps
3236
=============
3337

‎doc/nrf/libraries/others/mcuboot_image_compression.rst‎

Lines changed: 0 additions & 65 deletions
This file was deleted.

‎samples/nrf_compress/mcuboot_update/README.rst‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
.. _nrf_compression_mcuboot_compressed_update:
2+
3+
nRF Compression: MCUboot compressed update
4+
##########################################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
This sample demonstrates how to enable and use :ref:`image compression within MCUboot <mcuboot_image_compression>`, which allows for smaller application updates to be loaded to a device.
11+
12+
Requirements
13+
************
14+
15+
The sample supports the following development kits:
16+
17+
.. table-from-sample-yaml::
18+
19+
Overview
20+
********
21+
22+
This sample is using the :ref:`nrf_compression` library.
23+
24+
The sample's default configuration has the following features enabled:
25+
26+
* MCUboot in the upgrade-only mode with the Kconfig option :kconfig:option:`CONFIG_BOOT_UPGRADE_ONLY` set to ``y``.
27+
* Single-update image with the Kconfig option :kconfig:option:`CONFIG_UPDATEABLE_IMAGE_NUMBER` set to ``1``.
28+
29+
When the sample is built, the build system automatically generates the update binary files with compressed image data and flags set.
30+
These files match the :ref:`requirements for MCUboot image compression <mcuboot_image_compression_setup>`.
31+
32+
Configuration
33+
*************
34+
35+
|config|
36+
37+
See :ref:`configuring_kconfig` for information about the different ways you can set Kconfig options in the |NCS|.
38+
39+
Configuration options
40+
=====================
41+
42+
.. _CONFIG_OUTPUT_BOOT_MESSAGE:
43+
44+
CONFIG_OUTPUT_BOOT_MESSAGE
45+
When enabled, this optional configuration option outputs a message at run-time that allows for checking if the image has been updated successfully.
46+
47+
Building and running
48+
********************
49+
50+
.. |sample path| replace:: :file:`samples/nrf_compress/mcuboot_update`
51+
52+
.. include:: /includes/build_and_run.txt
53+
54+
To upload MCUboot and the bundle of images to the device, program the sample by using the :ref:`flash command without erase <programming_params_no_erase>`.
55+
56+
Testing over Bluetooth LE
57+
=========================
58+
59+
The testing scenario uses the FOTA over Bluetooth LE method to load the firmware update to the device.
60+
For the testing scenario to work, make sure you meet the following requirements:
61+
62+
* Your update image differs from the base image so that the update can be applied.
63+
* You changed the firmware version by setting :kconfig:option:`CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION` to ``"2.0.0"``.
64+
* You set the :kconfig:option:`CONFIG_OUTPUT_BOOT_MESSAGE` Kconfig option to ``y``.
65+
* You are familiar with the FOTA over Bluetooth LE method (see :ref:`the guide for the nRF52840 DK <ug_nrf52_developing_ble_fota_steps>` and :ref:`the guide for the nRF5340 DK <ug_nrf53_developing_ble_fota_steps>`).
66+
* You have the `nRF Connect Device Manager`_ mobile app installed on your smartphone to update your device with the new firmware over Bluetooth LE.
67+
68+
Meeting these requirements requires rebuilding the sample.
69+
70+
|test_sample|
71+
72+
#. |connect_kit|
73+
#. |connect_terminal|
74+
#. Start the `nRF Connect Device Manager`_ mobile app.
75+
#. Follow the testing steps for the FOTA over Bluetooth LE.
76+
See the following sections of the documentation:
77+
78+
* :ref:`Testing steps for FOTA over Bluetooth LE with nRF52840 <ug_nrf52_developing_ble_fota_steps_testing>`
79+
* :ref:`Testing steps for FOTA over Bluetooth LE with nRF5340 <ug_nrf53_developing_ble_fota_steps_testing>`
80+
* *Not yet available*: Testing steps for FOTA over Bluetooth LE with nRF54L15
81+
82+
#. Once the firmware update has been loaded, check the UART output.
83+
See the following `Sample output`_ section.
84+
#. Reboot the device.
85+
The compressed firmware update will be applied to the device and it will boot into it.
86+
87+
.. note::
88+
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.
89+
90+
Sample output
91+
=============
92+
93+
After a firmware update has been loaded, the UART will output the information on the image which will be one of the following:
94+
95+
LZMA2 with ARM
96+
The following output is logged:
97+
98+
.. code-block:: console
99+
100+
Secondary slot image is LZMA2 compressed with ARM thumb filter applied
101+
102+
This indicates that the loaded firmware update has been compressed using LZMA2 and had the ARM thumb filter applied.
103+
This offers the best compression ratio and is recommended for general usage.
104+
105+
LZMA2 only
106+
The following output is logged:
107+
108+
.. code-block:: console
109+
110+
Secondary slot image is LZMA2 compressed
111+
112+
This indicates that the loaded firmware update has been compressed using LZMZ2.
113+
This offers a good compression ratio but is not optimal.
114+
115+
No LZMA2
116+
The following output is logged:
117+
118+
.. code-block:: console
119+
120+
Secondary slot image is uncompressed
121+
122+
This indicates that the loaded firmware update has not been compressed at all.
123+
This is a suboptimal and incorrect update.
124+
125+
For information about how these compression types are configured in the :ref:`nrf_compression` library, see :ref:`nrf_compression_config_compression_types` in its documentation.
126+
127+
Dependencies
128+
************
129+
130+
The sample uses the following Zephyr library:
131+
132+
* :ref:`zephyr:mcu_mgr`
133+
134+
It also uses the following |NCS| library:
135+
136+
* :ref:`partition_manager`
137+
* :ref:`nrf_compression`

‎samples/nrf_compress/mcuboot_update/testcase.yaml‎ renamed to ‎samples/nrf_compress/mcuboot_update/sample.yaml‎

File renamed without changes.

0 commit comments

Comments
 (0)