Skip to content

Commit f5bbad1

Browse files
ahasztagrlubos
ahasztag
authored and
rlubos
committed
samples: Added dfu_multi_image sample
Added a sample allowing to test the DFU multi-image library. Currently only MCUBOOT targets are supported. Ref: NCSDK-34853 Signed-off-by: Artur Hadasz <[email protected]>
1 parent 94521ce commit f5bbad1

File tree

20 files changed

+646
-2
lines changed

20 files changed

+646
-2
lines changed

‎CODEOWNERS‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -506,6 +506,7 @@
506506
/samples/dect/dect_phy/dect_shell/ @nrfconnect/ncs-modem-tre
507507
/samples/dect/dect_phy/hello_dect/ @nrfconnect/ncs-modem
508508
/samples/dfu/dfu_target/ @nrfconnect/ncs-charon
509+
/samples/dfu/dfu_multi_image/ @nrfconnect/ncs-charon
509510
/samples/edge_impulse/ @nrfconnect/ncs-si-muffin
510511
/samples/esb/ @nrfconnect/ncs-si-muffin
511512
/samples/event_manager_proxy/ @nrfconnect/ncs-si-muffin
@@ -629,6 +630,8 @@
629630
/samples/debug/ppi_trace/*.rst @nrfconnect/ncs-doc-leads
630631
/samples/dect/dect_phy/dect_shell/*.rst @nrfconnect/ncs-iot-positioning-doc
631632
/samples/dect/dect_phy/hello_dect/*.rst @nrfconnect/ncs-modem-doc
633+
/samples/dfu/dfu_target/*.rst @nrfconnect/ncs-charon-doc
634+
/samples/dfu/dfu_multi_image/*.rst @nrfconnect/ncs-charon-doc
632635
/samples/esb/**/*.rst @nrfconnect/ncs-si-muffin-doc
633636
/samples/edge_impulse/**/*.rst @nrfconnect/ncs-si-muffin-doc
634637
/samples/event_manager_proxy/*.rst @nrfconnect/ncs-si-muffin-doc

‎doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -282,6 +282,11 @@ DECT NR+ samples
282282

283283
|no_changes_yet_note|
284284

285+
DFU samples
286+
-----------
287+
288+
* Added the :ref:`dfu_multi_image_sample` sample to demonstrate how to use the :ref:`lib_dfu_target` library.
289+
285290
Edge Impulse samples
286291
--------------------
287292

‎doc/nrf/samples/dfu.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,4 @@ This page lists |NCS| samples demonstrating the use of Device Firmware Update (D
1616
:caption: Subpages
1717
:glob:
1818

19-
../../../samples/dfu/dfu_target/README
19+
../../../samples/dfu/*/README

‎samples/dfu/dfu_multi_image/CMakeLists.txt‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
#
2+
# Copyright (c) 2025 Nordic Semiconductor ASA
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
cmake_minimum_required(VERSION 3.20.0)
8+
9+
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
10+
project(dfu_multi_image)
11+
12+
target_sources(app PRIVATE src/main.c src/dfu_multi_image_shell.c)

‎samples/dfu/dfu_multi_image/README.rst‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
.. _dfu_multi_image_sample:
2+
3+
DFU Multi-image
4+
###############
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
The DFU Multi-image sample demonstrates the use of the Device Firmware Update (DFU) multi-image functionality in the |NCS|.
11+
Currently, it only supports DFU targets for MCUboot as its backend.
12+
13+
Requirements
14+
************
15+
16+
The sample supports the following development kits:
17+
18+
.. table-from-sample-yaml::
19+
20+
Overview
21+
********
22+
23+
The sample does not include a transport layer for uploading a new image.
24+
Instead, a partition labeled ``dfu_multi_image_helper`` is reserved in the board overlays.
25+
26+
.. note::
27+
You must manually upload an image to this partition using ``nrfutil device`` command.
28+
29+
30+
Once the image has been uploaded, you can use the shell commands from the ``dfu_multi_image`` group provided by this sample to test DFU multi image operations.
31+
32+
User interface
33+
**************
34+
35+
The sample's interface is implemented using shell commands, which are accessible through the serial port.
36+
37+
Building and running
38+
********************
39+
40+
.. |sample path| replace:: :file:`samples/dfu/dfu_multi_image`
41+
42+
.. include:: /includes/build_and_run.txt
43+
44+
Testing
45+
=======
46+
47+
|test_sample|
48+
49+
1. |connect_terminal_specific|
50+
#. Reset the development kit.
51+
#. Observe the following message on the terminal of the application core:
52+
53+
.. code-block:: console
54+
55+
Starting dfu_multi_image sample, build time: <BUILD TIME>
56+
57+
And the following message on the terminal of the network core:
58+
59+
.. code-block:: console
60+
61+
Network core build time: <BUILD_TIME>
62+
63+
``<BUILD TIME>`` indicates the build time.
64+
It will be used later to verify the update.
65+
66+
#. Build a second version of the sample.
67+
For simplicity, it is assumed to be built in the :file:`build_v2` directory.
68+
69+
#. Use the ``arm-zephyr-eabi-objcopy`` command to link the contents of the :file:`dfu_multi_image.bin` file to the appropriate address:
70+
71+
.. code-block:: console
72+
73+
arm-zephyr-eabi-objcopy -I binary -O ihex --change-address <DFU_MULTI_IMAGE_HELPER_ADDRESS> build_v2/dfu_multi_image.bin package_v2.hex
74+
75+
Replace ``<DFU_MULTI_IMAGE_HELPER_ADDRESS>`` with the address of the ``dfu_multi_image_helper`` partition.
76+
Specifically, the address values are the following:
77+
78+
+-------------------+------------------+
79+
| Development kit | Address |
80+
+===================+==================+
81+
| nRF5340 DK | ``0xb8000`` |
82+
+-------------------+------------------+
83+
84+
#. Upload the second version of the images to the device using ``nrfutil device``:
85+
86+
.. code-block:: console
87+
88+
nrfutil device program --firmware package_v2.hex --options chip_erase_mode=ERASE_NONE
89+
90+
#. Reset the development kit.
91+
92+
#. Perform the update using one of the following methods:
93+
94+
* Single-step update, running the following command::
95+
96+
dfu_multi_image full_update <package_size>
97+
98+
``<package_size>`` is the size, in bytes, of the file :file:`build_v2/dfu_multi_image.bin`.
99+
100+
* Step-by-step update:
101+
102+
1. Write the image either at once or in chunks:
103+
104+
* To write the entire image at once, run the following command:
105+
106+
.. code-block:: console
107+
108+
dfu_multi_image write 0 0 <package_size>
109+
110+
``<package_size>`` is the size, in bytes, of the file :file:`build_v2/dfu_multi_image.bin`.
111+
112+
* To write the image in chunks, run the following commands as many times as there are chunks:
113+
114+
.. code-block:: console
115+
116+
dfu_multi_image write <read_offset> <write_offset> <chunk_size>
117+
118+
The ``<read_offset>`` is the offset in the ``dfu_multi_image_helper`` partition from which a chunk of data is read.
119+
The ``<write_offset>`` is the offset to pass to the :ref:`lib_dfu_multi_image` library, representing the offset in the package.
120+
This is useful when skipping some of the images.
121+
See the documentation of the ``dfu_multi_image_write`` function in the :file:`dfu_multi_image.h` file for more details.
122+
123+
#. If the write commands for all chunks complete without errors, finish writing with ``dfu_multi_image done success`` command.
124+
#. Schedule the update for the next reboot using ``dfu_multi_image schedule_update`` command.
125+
#. Reboot the device.
126+
127+
#. After the update completes, observe the following message on the terminal of the application core:
128+
129+
.. code-block:: console
130+
131+
Starting dfu_multi_image sample, build time: <BUILD TIME>
132+
133+
Observe the following message on the terminal of the network core:
134+
135+
.. code-block:: console
136+
137+
Network core build time: <BUILD_TIME>
138+
139+
The build time should reflect the new version in both cases.
140+
141+
#. (Optional) To make the update permanent, use the ``dfu_multi_image mcuboot_confirm`` command.
142+
Without this step, the device will revert to the previous image on the next reboot.
143+
For nRF5340, the radio core is confirmed automatically, which is not the case for the application core.
144+
145+
Dependencies
146+
************
147+
148+
This sample uses the following |NCS| libraries:
149+
150+
* :ref:`lib_dfu_target`
151+
* :ref:`lib_dfu_multi_image`
152+
* :ref:`MCUboot <mcuboot_index_ncs>`

‎samples/dfu/dfu_multi_image/modules/net_build_time_log/zephyr/CMakeLists.txt‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
#
2+
# Copyright (c) 2025 Nordic Semiconductor
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
cmake_minimum_required(VERSION 3.20.0)
8+
9+
if (CONFIG_NET_BUILD_TIME_LOG)
10+
11+
zephyr_library()
12+
zephyr_library_sources(src/net_build_time_log.c)
13+
14+
endif()

‎samples/dfu/dfu_multi_image/modules/net_build_time_log/zephyr/Kconfig‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
#
2+
# Copyright (c) 2025 Nordic Semiconductor
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
config NET_BUILD_TIME_LOG
8+
bool "Makes the net core log print its build time at startup"

‎samples/dfu/dfu_multi_image/modules/net_build_time_log/zephyr/module.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
build:
2+
cmake: zephyr
3+
kconfig: zephyr/Kconfig

‎samples/dfu/dfu_multi_image/modules/net_build_time_log/zephyr/src/net_build_time_log.c‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
/*
2+
* Copyright (c) 2025 Nordic Semiconductor ASA
3+
*
4+
* SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
*/
6+
7+
#include <stdio.h>
8+
#include <zephyr/init.h>
9+
10+
static int net_build_time_log(void)
11+
{
12+
printf("Network core build time: %s %s\n", __DATE__, __TIME__);
13+
14+
return 0;
15+
}
16+
17+
SYS_INIT(net_build_time_log, APPLICATION, CONFIG_APPLICATION_INIT_PRIORITY);

‎samples/dfu/dfu_multi_image/pm_static_nrf5340dk_nrf5340_cpuapp.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
mcuboot:
2+
address: 0x0
3+
region: flash_primary
4+
size: 0xc000
5+
mcuboot_pad:
6+
address: 0xc000
7+
region: flash_primary
8+
size: 0x200
9+
app:
10+
address: 0xc200
11+
region: flash_primary
12+
size: 0x35e00
13+
mcuboot_primary:
14+
address: 0xc000
15+
orig_span: &id001
16+
- mcuboot_pad
17+
- app
18+
region: flash_primary
19+
size: 0x36000
20+
span: *id001
21+
mcuboot_primary_app:
22+
address: 0xc200
23+
orig_span: &id002
24+
- app
25+
region: flash_primary
26+
size: 0x35e00
27+
span: *id002
28+
mcuboot_secondary:
29+
address: 0x42000
30+
region: flash_primary
31+
size: 0x36000
32+
mcuboot_secondary_1:
33+
address: 0x78000
34+
region: flash_primary
35+
size: 0x40000
36+
dfu_multi_image_helper:
37+
address: 0xb8000
38+
region: flash_primary
39+
size: 0x48000

0 commit comments

Comments
 (0)