Skip to content

Commit 9d34bd9

Browse files
annwojnordicjm
annwoj
authored and
nordicjm
committed
doc: add MCUboot serial recovery page
Moved and merged two mcuboot articles. Signed-off-by: Anna Wojdylo <[email protected]>
1 parent 3d5ef11 commit 9d34bd9

File tree

3 files changed

+178
-1
lines changed

3 files changed

+178
-1
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,5 +52,6 @@ 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_serial_recovery
5556
mcuboot_image_compression
5657
sysbuild_image_ids

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

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
.. _mcuboot_serial_recovery:
2+
3+
MCUboot serial recovery
4+
#######################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
MCUboot implements a Simple Management Protocol (SMP) server.
11+
SMP is a basic transfer encoding mechanism for use with the MCUmgr management protocol.
12+
See Zephyr's :ref:`Device Management <zephyr:device_mgmt>` documentation for more information about MCUmgr and SMP.
13+
14+
MCUboot supports the following subset of the MCUmgr commands:
15+
16+
* Echo (OS group)
17+
* Reset (OS group)
18+
* Image list (IMG group)
19+
* Image upload (IMG group)
20+
21+
If the ``CONFIG_ENABLE_MGMT_PERUSER`` Kconfig option is enabled, it can also support system-specific MCUmgr commands depending on the given MCUboot port.
22+
The serial recovery feature can use any serial interface provided by the system.
23+
24+
Uploading image
25+
***************
26+
27+
By default, uploading an image is targeted to the primary slot.
28+
You can load an image to other slots only if you have enabled the ``CONFIG_MCUBOOT_SERIAL_DIRECT_IMAGE_UPLOAD`` Kconfig option.
29+
To use progressive slot erasing during image upload, enable the ``CONFIG_BOOT_ERASE_PROGRESSIVELY`` Kconfig option.
30+
As a result, a device can receive images smoothly and can erase required part of a flash automatically.
31+
32+
Implementing serial recovery
33+
****************************
34+
35+
See the following subsections for information on how to configure and use the serial recovery feature in MCUboot, enabling firmware updates through serial interfaces.
36+
37+
Selecting interface
38+
===================
39+
40+
A serial recovery protocol is available over a hardware serial port or a USB CDC ACM virtual serial port.
41+
You can enable the :zephyr:code-sample:`smp-svr` implementation by setting the ``CONFIG_MCUBOOT_SERIAL`` Kconfig option.
42+
To set a type of an interface, use the ``BOOT_SERIAL_DEVICE_CHOICE`` Kconfig, and select either the ``CONFIG_BOOT_SERIAL_UART`` or the ``CONFIG_BOOT_SERIAL_CDC_ACM`` value.
43+
Specify the appropriate interface for the serial recovery protocol using the devicetree-chosen node:
44+
45+
* ``Zephyr,console`` - If you are using a hardware serial port.
46+
* ``Zephyr,cdc-acm-uart`` - If you are using a virtual serial port.
47+
48+
Entering the serial recovery mode
49+
=================================
50+
51+
To enter the serial recovery mode, the device must first initiate rebooting, and a triggering event must occur (for example, pressing a button).
52+
53+
By default, the serial recovery GPIO pin active state enters the serial recovery mode.
54+
Use the ``mcuboot_button0`` devicetree button alias to assign the GPIO pin to the MCUboot.
55+
56+
Alternatively, MCUboot can be configured to wait for a limited time at startup to check if DFU is invoked through an MCUmgr command.
57+
To enable this mode, set the ``CONFIG_BOOT_SERIAL_WAIT_FOR_DFU`` Kconfig option.
58+
The duration of this wait period in milliseconds is defined by the ``CONFIG_BOOT_SERIAL_WAIT_FOR_DFU_TIMEOUT`` Kconfig option.
59+
60+
Additionally, you can enable the following options:
61+
62+
* Entering recovery mode (``CONFIG_BOOT_SERIAL_BOOT_MODE``) - This option uses Zephyr's boot mode retention system to enter the serial recovery mode.
63+
An application must set the :ref:`boot mode<zephyr:retention_api>` to ensure MCUboot stays in the serial recovery mode after reboot.
64+
To activate this feature, use the boot mode API call ``bootmode_set(BOOT_MODE_TYPE_BOOTLOADER);``.
65+
* Entering recovery mode by resetting the serial pin (``CONFIG_BOOT_SERIAL_PIN_RESET``) - This option verifies if the SoC reset was triggered by a pin reset.
66+
If confirmed, the device automatically enters the recovery mode.
67+
68+
For details on other available configuration options for the serial recovery protocol, refer to the Kconfig options in the :file:`menuconfig` file.
69+
70+
Using serial recovery mode
71+
**************************
72+
73+
Complete the following steps to use the serial recovery mode in MCUboot, enabling communication with the device's SMP server for firmware management and updates.
74+
75+
Installing MCUmgr CLI
76+
=====================
77+
78+
MCUmgr command-line tool can be used as an SMP client for evaluation purposes.
79+
To start using it, complete the :ref:`installation instructions <dfu_tools_mcumgr_cli>`.
80+
81+
Configuring connection
82+
======================
83+
84+
Run the following command to configure the connection:
85+
86+
.. tabs::
87+
88+
.. group-tab:: Windows
89+
90+
.. parsed-literal::
91+
:class: highlight
92+
93+
mcumgr conn add serial_1 type="serial" connstring="COM1,baud=115200"
94+
95+
.. group-tab:: Linux
96+
97+
.. parsed-literal::
98+
:class: highlight
99+
100+
mcumgr conn add serial_1 type="serial" connstring="dev=/dev/ttyACM0,baud=115200"
101+
102+
Managing direct image upload
103+
============================
104+
105+
By default, the SMP server uses the first slot.
106+
To upload to a different slot, use the image upload MCUmgr command with a selected image number, ensuring the ``CONFIG_MCUBOOT_SERIAL_DIRECT_IMAGE_UPLOAD`` Kconfig option is enabled.
107+
The ``CONFIG_UPDATEABLE_IMAGE_NUMBER`` Kconfig option adjusts the number of image pairs supported.
108+
109+
See the image number to partition mapping:
110+
111+
* 0 and 1 - image-0, primary slot of the first image
112+
* 2 - image-1, the secondary slot of the first image
113+
* 3 - image-2
114+
* 4 - image-3
115+
* 0 - the default upload target when no selection is made
116+
117+
System-specific commands
118+
========================
119+
120+
By setting the ``CONFIG_ENABLE_MGMT_PERUSER`` Kconfig option, you can enable additional commands.
121+
If you want to enable erasing the storage partition, set the ``CONFIG_BOOT_MGMT_CUSTOM_STORAGE_ERASE`` Kconfig option.
122+
123+
Image management examples
124+
=========================
125+
126+
The SMP protocol, when implemented through MCUboot, operates identically to its implementation through an application, using the same set of commands.
127+
Ensure you have established the connection configuration to manage your images.
128+
129+
* To upload an image, run the following command:
130+
131+
.. parsed-literal::
132+
:class: highlight
133+
134+
mcumgr image upload *path_to_signed_image_bin_file* -c serial_1
135+
136+
You should see the output:
137+
138+
.. parsed-literal::
139+
:class: highlight
140+
141+
20.25 KiB / 20.25 KiB [=================================] 100.00% 3.08 KiB/s 6s
142+
Done
143+
144+
* To list all images, run the following command:
145+
146+
.. parsed-literal::
147+
:class: highlight
148+
149+
mcumgr image list -c serial_1
150+
151+
The terminal will return the output:
152+
153+
.. parsed-literal::
154+
:class: highlight
155+
156+
Images:
157+
image=0 slot=0
158+
version: 0.0.0.0
159+
bootable: false
160+
flags:
161+
hash: Unavailable
162+
Split status: N/A (0)
163+
164+
Resetting the device
165+
====================
166+
167+
The device must be reset after updating or uploading a new firmware image through the serial recovery mode by running the following command:
168+
169+
.. parsed-literal::
170+
:class: highlight
171+
172+
mcumgr reset -c serial_1

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -922,6 +922,10 @@ cJSON
922922
Documentation
923923
=============
924924

925-
* Added the :ref:`log_rpc` library documentation page.
925+
* Added:
926+
927+
* The :ref:`log_rpc` library documentation page.
928+
* The :ref:`mcuboot_serial_recovery` documentation page, based on the official Zephyr documentation, which discusses the implementation and usage of the serial recovery.
929+
926930
* Removed the Getting started with nRF7002 DK and Getting started with other DKs pages from the :ref:`gsg_guides` section.
927931
These pages were no longer relevant as the `Quick Start app`_ now also supports the nRF7002 DK.

0 commit comments

Comments
 (0)