Skip to content

Commit c7c8bb7

Browse files
ahasztagrlubos
ahasztag
authored and
rlubos
committed
samples: dfu: Add A/B sample
This sample demonstrates how to use the A/B functionality with MCUBoot. Signed-off-by: Artur Hadasz <[email protected]>
1 parent 101efdd commit c7c8bb7

File tree

15 files changed

+698
-1
lines changed

15 files changed

+698
-1
lines changed

‎CODEOWNERS‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -504,6 +504,7 @@
504504
/samples/debug/ppi_trace/ @nordic-krch
505505
/samples/dect/dect_phy/dect_shell/ @nrfconnect/ncs-modem-tre
506506
/samples/dect/dect_phy/hello_dect/ @nrfconnect/ncs-modem
507+
/samples/dfu/ab/ @nrfconnect/ncs-charon
507508
/samples/dfu/dfu_target/ @nrfconnect/ncs-charon
508509
/samples/dfu/dfu_multi_image/ @nrfconnect/ncs-charon
509510
/samples/edge_impulse/ @nrfconnect/ncs-si-muffin
@@ -629,6 +630,7 @@
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/ab/*.rst @nrfconnect/ncs-charon-doc
632634
/samples/dfu/dfu_target/*.rst @nrfconnect/ncs-charon-doc
633635
/samples/dfu/dfu_multi_image/*.rst @nrfconnect/ncs-charon-doc
634636
/samples/esb/**/*.rst @nrfconnect/ncs-si-muffin-doc

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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -396,7 +396,10 @@ DECT NR+ samples
396396
DFU samples
397397
-----------
398398

399-
* Added the :ref:`dfu_multi_image_sample` sample to demonstrate how to use the :ref:`lib_dfu_target` library.
399+
* Added:
400+
401+
* The :ref:`dfu_multi_image_sample` sample to demonstrate how to use the :ref:`lib_dfu_target` library.
402+
* The :ref:`ab_sample` sample to demonstrate how to implement the A/B firmware update strategy using :ref:`MCUboot <mcuboot_index_ncs>`.
400403

401404
Edge Impulse samples
402405
--------------------

‎samples/dfu/ab/CMakeLists.txt‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
#
2+
# Copyright (c) 2025 Nordic Semiconductor ASA
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
8+
cmake_minimum_required(VERSION 3.20.0)
9+
10+
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
11+
project(ab)
12+
13+
target_sources(app PRIVATE src/main.c)
14+
target_sources(app PRIVATE src/ab_utils.c)
15+
16+
target_include_directories(
17+
app PRIVATE
18+
${ZEPHYR_MCUBOOT_MODULE_DIR}/boot/bootutil/include
19+
${ZEPHYR_MCUBOOT_MODULE_DIR}/boot/zephyr/include
20+
${ZEPHYR_BASE}/samples/subsys/mgmt/mcumgr/smp_svr/src
21+
)
22+
23+
target_sources_ifdef(CONFIG_MCUMGR_TRANSPORT_BT app PRIVATE
24+
${ZEPHYR_BASE}/samples/subsys/mgmt/mcumgr/smp_svr/src/bluetooth.c)

‎samples/dfu/ab/Kconfig‎

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 ASA
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
config N_BLINKS
8+
int "Number of fast blinks"
9+
default 1
10+
11+
config EMULATE_APP_HEALTH_CHECK_FAILURE
12+
bool "Blocks confirmation of being healthy after the update"
13+
14+
source "Kconfig.zephyr"

‎samples/dfu/ab/README.rst‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
.. _ab_sample:
2+
3+
A/B with MCUboot
4+
################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
The A/B with MCUboot sample demonstrates how to configure the application for updates using the A/B method using MCUboot.
11+
It also includes an example to perform a device health check before confirming the image after the update.
12+
13+
You can update the sample using the Simple Management Protocol (SMP) with UART or Bluetooth® Low Energy.
14+
15+
Requirements
16+
************
17+
18+
The sample supports the following development kits:
19+
20+
.. table-from-sample-yaml::
21+
22+
You need the nRF Device Manager app for update over Bluetooth Low Energy:
23+
24+
* `nRF Device Manager mobile app for Android`_
25+
* `nRF Device Manager mobile app for iOS`_
26+
27+
28+
Overview
29+
********
30+
31+
This sample demonstrates firmware update using the A/B method.
32+
This method allows two copies of the application in the NVM memory.
33+
It is possible to switch between these copies without performing a swap, which significantly reduces time of device's unavailability during the update.
34+
The switch between images can be triggered by the application or, for example, by a hardware button.
35+
36+
This sample implements an SMP server.
37+
SMP is a basic transfer encoding used with the MCUmgr management protocol.
38+
For more information about MCUmgr and SMP, see :ref:`device_mgmt`.
39+
40+
The sample supports the following MCUmgr transports by default:
41+
42+
* Bluetooth
43+
* Serial (UART)
44+
45+
User interface
46+
**************
47+
48+
LED 0:
49+
This LED indicates that the application is running from slot A.
50+
It is controlled as active low, meaning it will turn on once the application is booted and blinks (turns off) in short intervals.
51+
The number of short blinks is configurable using the :kconfig:option:`CONFIG_N_BLINKS` Kconfig option.
52+
It will remain off if the application is running from slot B.
53+
54+
LED 1:
55+
This LED indicates that the application is running from slot B.
56+
It is controlled as active low, meaning it will turn on once the application is booted and blinks (turns off) in short intervals.
57+
The number of short blinks is configurable using the :kconfig:option:`CONFIG_N_BLINKS` Kconfig option.
58+
It will remain off if the application is running from slot A.
59+
60+
Button 0:
61+
By pressing this button, the non-active slot will be selected as the preferred slot on the next reboot.
62+
This preference applies only to the next boot and is cleared after the subsequent reset.
63+
64+
Configuration
65+
*************
66+
67+
|config|
68+
69+
Configuration options
70+
=====================
71+
72+
Check and configure the following configuration option for the sample:
73+
74+
.. _CONFIG_N_BLINKS:
75+
76+
CONFIG_N_BLINKS - The number of blinks.
77+
This configuration option sets the number of times the LED corresponding to the currently active slot blinks (LED0 for slot A, LED1 for slot B).
78+
The default value of the option is set to ``1``, causing a single blink to indicate *Version 1*.
79+
You can increment this value to represent an update, such as set it to ``2`` to indicate *Version 2*.
80+
81+
.. _CONFIG_EMULATE_APP_HEALTH_CHECK_FAILURE:
82+
83+
CONFIG_EMULATE_APP_HEALTH_CHECK_FAILURE - Enables emulation of a broken application that fails the self-test.
84+
This configuration option emulates a broken application that does not pass the self-test.
85+
86+
Additional configuration
87+
========================
88+
89+
Check and configure the :kconfig:option:`CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION` library Kconfig option specific to the MCUboot library.
90+
This configuration option sets the version to pass to imgtool when signing.
91+
To ensure the updated build is preferred after a DFU, set this option to a higher version than the version currently running on the device.
92+
93+
Building and running
94+
********************
95+
96+
.. |sample path| replace:: :file:`samples/dfu/ab`
97+
98+
.. include:: /includes/build_and_run.txt
99+
100+
Testing
101+
=======
102+
103+
To perform DFU using the `nRF Connect Device Manager`_ mobile app, complete the following steps:
104+
105+
.. include:: /app_dev/device_guides/nrf52/fota_update.rst
106+
:start-after: fota_upgrades_over_ble_nrfcdm_common_dfu_steps_start
107+
:end-before: fota_upgrades_over_ble_nrfcdm_common_dfu_steps_end
108+
109+
Dependencies
110+
************
111+
112+
This sample uses the following |NCS| library:
113+
114+
* :ref:`MCUboot <mcuboot_index_ncs>`

‎samples/dfu/ab/boards/nrf54h20dk_nrf54h20_cpuapp.overlay‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
/*
2+
* Copyright (c) 2025 Nordic Semiconductor ASA
3+
*
4+
* SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
*/
6+
7+
#include "../sysbuild/nrf54h20dk_nrf54h20_memory_map.dtsi"
8+
9+
/ {
10+
chosen {
11+
zephyr,boot-mode = &boot_request;
12+
};
13+
};

‎samples/dfu/ab/prj.conf‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Enable MCUmgr and dependencies.
2+
CONFIG_NET_BUF=y
3+
CONFIG_ZCBOR=y
4+
CONFIG_CRC=y
5+
CONFIG_MCUMGR=y
6+
CONFIG_STREAM_FLASH=y
7+
CONFIG_FLASH_MAP=y
8+
9+
# Some command handlers require a large stack.
10+
CONFIG_SYSTEM_WORKQUEUE_STACK_SIZE=2304
11+
CONFIG_MAIN_STACK_SIZE=2176
12+
13+
# Ensure an MCUboot-compatible binary is generated.
14+
CONFIG_BOOTLOADER_MCUBOOT=y
15+
16+
# Enable flash operations.
17+
CONFIG_FLASH=y
18+
19+
# Required by the `taskstat` command.
20+
CONFIG_THREAD_MONITOR=y
21+
22+
# Support for taskstat command
23+
CONFIG_MCUMGR_GRP_OS_TASKSTAT=y
24+
25+
# Enable statistics and statistic names.
26+
CONFIG_STATS=y
27+
CONFIG_STATS_NAMES=y
28+
29+
# Enable most core commands.
30+
CONFIG_FLASH=y
31+
CONFIG_IMG_MANAGER=y
32+
CONFIG_MCUMGR_GRP_IMG=y
33+
CONFIG_MCUMGR_GRP_OS=y
34+
CONFIG_MCUMGR_GRP_STAT=y
35+
36+
# Enable logging
37+
CONFIG_LOG=y
38+
CONFIG_MCUBOOT_UTIL_LOG_LEVEL_WRN=y
39+
40+
# Disable debug logging
41+
CONFIG_LOG_MAX_LEVEL=3
42+
43+
# Enable boot requests through retained memory.
44+
CONFIG_RETAINED_MEM=y
45+
CONFIG_RETENTION=y
46+
CONFIG_NRF_MCUBOOT_BOOT_REQUEST=y
47+
48+
CONFIG_RETENTION_BOOT_MODE=y
49+
CONFIG_MCUMGR_GRP_OS_RESET_BOOT_MODE=y
50+
51+
# Enable DK LED/button library
52+
CONFIG_DK_LIBRARY=y
53+
54+
# Configure bluetooth
55+
56+
CONFIG_BT=y
57+
CONFIG_BT_PERIPHERAL=y
58+
59+
# Allow for large Bluetooth data packets.
60+
CONFIG_BT_L2CAP_TX_MTU=498
61+
CONFIG_BT_BUF_ACL_RX_SIZE=502
62+
CONFIG_BT_BUF_ACL_TX_SIZE=502
63+
CONFIG_BT_CTLR_DATA_LENGTH_MAX=251
64+
65+
# Enable the Bluetooth mcumgr transport (unauthenticated).
66+
CONFIG_MCUMGR_TRANSPORT_BT=y
67+
CONFIG_MCUMGR_TRANSPORT_BT_CONN_PARAM_CONTROL=y
68+
69+
# Enable the Shell mcumgr transport.
70+
CONFIG_BASE64=y
71+
CONFIG_CRC=y
72+
CONFIG_SHELL=y
73+
CONFIG_SHELL_BACKEND_SERIAL=y
74+
CONFIG_MCUMGR_TRANSPORT_SHELL=y
75+
76+
# Enable the mcumgr Packet Reassembly feature over Bluetooth and its configuration dependencies.
77+
# MCUmgr buffer size is optimized to fit one SMP packet divided into five Bluetooth Write Commands,
78+
# transmitted with the maximum possible MTU value: 498 bytes.
79+
CONFIG_MCUMGR_TRANSPORT_BT_REASSEMBLY=y
80+
CONFIG_MCUMGR_TRANSPORT_NETBUF_SIZE=2475
81+
CONFIG_MCUMGR_GRP_OS_MCUMGR_PARAMS=y
82+
CONFIG_MCUMGR_TRANSPORT_WORKQUEUE_STACK_SIZE=4608
83+
84+
# Enable the LittleFS file system.
85+
CONFIG_FILE_SYSTEM=y
86+
CONFIG_FILE_SYSTEM_LITTLEFS=y
87+
88+
# Enable file system commands
89+
CONFIG_MCUMGR_GRP_FS=y
90+
91+
# Enable the storage erase command.
92+
CONFIG_MCUMGR_GRP_ZBASIC=y
93+
CONFIG_MCUMGR_GRP_ZBASIC_STORAGE_ERASE=y
94+
95+
# Disable Bluetooth ping support
96+
CONFIG_BT_CTLR_LE_PING=n
97+
98+
# Disable shell commands that are not needed
99+
CONFIG_CLOCK_CONTROL_NRF_SHELL=n
100+
CONFIG_DEVICE_SHELL=n
101+
CONFIG_DEVMEM_SHELL=n
102+
CONFIG_FLASH_SHELL=n

‎samples/dfu/ab/sample.yaml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
sample:
2+
description: AB update sample
3+
name: ab
4+
common:
5+
sysbuild: true
6+
build_only: true
7+
tags:
8+
- dfu_ab
9+
- ci_samples_dfu
10+
11+
tests:
12+
sample.dfu.ab:
13+
sysbuild: true
14+
platform_allow:
15+
- nrf54h20dk/nrf54h20/cpuapp
16+
integration_platforms:
17+
- nrf54h20dk/nrf54h20/cpuapp

0 commit comments

Comments
 (0)