Skip to content

Commit 027bf4b

Browse files
nvlsianpurlubos
nvlsianpu
authored and
rlubos
committed
doc/dev_guides/nrf54l: added fota_update guide
Added fota_update guide for nRF54l15 SoC based on the nRF52 doc. ref.: NCSDK-29601 Signed-off-by: Andrzej Puzdrowski <[email protected]> Signed-off-by: Anna Wojdylo <[email protected]> Signed-off-by: Omkar Kulkarni <[email protected]> (cherry picked from commit 54f8a63)
1 parent c7b4073 commit 027bf4b

File tree

3 files changed

+322
-0
lines changed

3 files changed

+322
-0
lines changed

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

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
.. _ug_nrf54l_developing_ble_fota:
2+
3+
FOTA updates on nRF54L Series devices
4+
#####################################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
.. fota_upgrades_intro_start
11+
12+
|fota_upgrades_def|
13+
You can also use FOTA updates to replace the application.
14+
See the :ref:`app_dfu` page for general Device Firmware Update (DFU) information, such as supported methods for sending and receiving updates on the device.
15+
Currently, FOTA updates are supported only for the application core.
16+
17+
.. note::
18+
For more information about introducing immutable MCUboot bootloader, refer to :ref:`ug_bootloader_adding_sysbuild_immutable_mcuboot`.
19+
20+
.. fota_upgrades_intro_end
21+
22+
.. _ug_nrf54l_developing_ble_fota_steps:
23+
24+
FOTA over Bluetooth Low Energy
25+
******************************
26+
27+
.. fota_upgrades_over_ble_intro_start
28+
29+
FOTA updates are supported using MCUmgr's Simple Management Protocol (SMP) over Bluetooth®.
30+
The application acts as a GATT server and allows the connected Bluetooth Central device to perform a firmware update.
31+
To use FOTA over Bluetooth LE, samples must support Bluetooth peripheral role (:kconfig:option:`CONFIG_BT_PERIPHERAL`).
32+
33+
By default, the application supports SMP handlers related to:
34+
35+
* Image management
36+
* Operating System (OS) management, which is used to reboot the device after completing firmware uploads
37+
* Erasing the settings partition to prevent booting a new application with incompatible content that was written by the previous application
38+
39+
To enable support for FOTA updates, do the following:
40+
41+
* Enable the :kconfig:option:`CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU` Kconfig option, which implies configuration of the following:
42+
43+
* All of the SMP command handlers mentioned in the :ref:`ug_nrf54l_developing_ble_fota_steps` section
44+
* SMP BT reassembly feature
45+
* The :kconfig:option:`CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU_SPEEDUP` Kconfig option, which automatically extends the Bluetooth buffers to speed up the FOTA transfer over Bluetooth while also increasing RAM usage
46+
47+
.. note::
48+
The :kconfig:option:`CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU` Kconfig option enables the device to use MCUmgr for performing firmware over-the-air (FOTA) updates using Bluetooth LE.
49+
It can be used along with other samples, and is meant as a demonstration of the default DFU configuration over Bluetooth.
50+
51+
.. note::
52+
To prevent an unauthenticated access to the device over SMP, it is strongly recommended to enable the :kconfig:option:`CONFIG_MCUMGR_TRANSPORT_BT_PERM_RW_AUTHEN` option.
53+
This will enforce a remote device to initiate a pairing request before accessing SMP characteristics.
54+
55+
.. fota_upgrades_over_ble_intro_end
56+
57+
.. fota_upgrades_over_ble_mandatory_mcuboot_start
58+
59+
* Enable ``SB_CONFIG_BOOTLOADER_MCUBOOT`` option to use MCUboot as the immutable bootloader.
60+
For more information, go to the :ref:`ug_bootloader_adding_sysbuild_immutable_mcuboot` page.
61+
62+
.. fota_upgrades_over_ble_mandatory_mcuboot_end
63+
64+
.. fota_upgrades_over_ble_additional_information_start
65+
66+
If necessary, you can modify any of the implied options or defaulted values introduced by the :kconfig:option:`CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU` Kconfig option.
67+
68+
You can either add these Kconfig options to the configuration files of your application or have them inline in a project build command.
69+
Here is an example of how you can build for the :ref:`peripheral_lbs` sample:
70+
71+
.. parsed-literal::
72+
:class: highlight
73+
74+
west build -b *board_target* -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -DCONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU=y
75+
76+
When you connect to the device after the build has completed and the firmware has been programmed to it, the SMP Service is enabled with the ``UUID 8D53DC1D-1DB7-4CD3-868B-8A527460AA84``.
77+
If you want to add SMP Service to advertising data, refer to the :zephyr:code-sample:`smp-svr`.
78+
79+
.. fota_upgrades_over_ble_additional_information_end
80+
81+
.. _ug_nrf54l_developing_ble_fota_steps_testing:
82+
83+
Testing steps
84+
=============
85+
86+
.. fota_upgrades_outro_start
87+
88+
To perform a FOTA update, complete the following steps:
89+
90+
.. fota_upgrades_over_ble_nrfcdm_common_dfu_steps_start
91+
92+
1. Generate the DFU package by building your application with the FOTA support over Bluetooth Low Energy (:kconfig:option:`CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU`).
93+
You can find the generated :file:`dfu_application.zip` archive in the build directory.
94+
95+
.. note::
96+
For each image included in the DFU-generated package, use a higher version number than your currently active firmware.
97+
You can do this by modifying the VERSION file in the application directory or by making changes to the application code.
98+
Otherwise, the DFU target may reject the FOTA process due to a downgrade prevention mechanism.
99+
100+
#. Download the :file:`dfu_application.zip` archive to your mobile phone.
101+
See :ref:`app_build_output_files` for more information about the contents of update archive.
102+
103+
.. note::
104+
nRF Connect for Desktop does not currently support the FOTA process.
105+
106+
#. Use the `nRF Connect Device Manager`_ mobile app to update your device with the new firmware.
107+
108+
a. Ensure that you can access the :file:`dfu_application.zip` archive from your phone or tablet.
109+
#. In the mobile app, scan and select the device to update.
110+
#. Switch to the :guilabel:`Image` tab.
111+
#. Tap the :guilabel:`SELECT FILE` button and select the :file:`dfu_application.zip` archive.
112+
#. Tap the :guilabel:`START` button.
113+
#. Initiate the DFU process of transferring the image to the device:
114+
115+
* If you are using an Android phone or tablet, select a mode in the dialog window, and tap the :guilabel:`START` button.
116+
* If you are using an iOS device, tap the selected mode in the pop-up window.
117+
118+
.. note::
119+
For samples using random HCI identities, the Test and Confirm mode should not be used.
120+
121+
#. Wait for the DFU to finish and then verify that the new application works properly by observing the new device name visible in the Device Manager app.
122+
123+
.. fota_upgrades_over_ble_nrfcdm_common_dfu_steps_end
124+
125+
.. fota_upgrades_outro_end
126+
127+
FOTA update sample
128+
******************
129+
130+
.. fota_upgrades_update_start
131+
132+
The :zephyr:code-sample:`smp-svr` demonstrates how to set up your project to support FOTA updates.
133+
134+
When working in the |NCS| environment, ignore the part of the sample documentation that describes the building and programming steps.
135+
In |NCS|, you can build and program the :zephyr:code-sample:`smp-svr` as any other sample using the following commands:
136+
137+
.. tabs::
138+
139+
.. group-tab:: nRF54L15 SoCs
140+
141+
.. parsed-literal::
142+
:class: highlight
143+
144+
west build -b *board_name*/nrf54l15/cpuapp -- -DEXTRA_CONF_FILE=overlay-bt.conf
145+
west flash
146+
147+
.. group-tab:: nRF54L15 SoCs with HW cryptography support
148+
149+
.. parsed-literal::
150+
:class: highlight
151+
152+
west build -b *board_name*/nrf54l15/cpuapp -- -DEXTRA_CONF_FILE=overlay-bt.conf -DSB_CONFIG_BOOT_SIGNATURE_TYPE_ED25519=y -DSB_CONFIG_BOOT_SIGNATURE_TYPE_PURE=y -Dmcuboot_CONFIG_PM_PARTITION_SIZE_MCUBOOT=0x10000 -DSB_CONFIG_MCUBOOT_SIGNATURE_USING_KMU=y
153+
west flash
154+
155+
156+
.. group-tab:: nRF54L15 DK with SPI Flash as update image bank
157+
158+
.. parsed-literal::
159+
:class: highlight
160+
161+
west build -b nrf54l15dk/nrf54l15/cpuapp -T sample.mcumgr.smp_svr.bt.nrf54l15dk.ext_flash
162+
west flash
163+
164+
Make sure to indicate the :file:`overlay-bt.conf` overlay configuration for the Bluetooth transport like in the command example.
165+
This configuration was carefully selected to achieve the maximum possible throughput of the FOTA update transport over Bluetooth with the help of the following features:
166+
167+
* Bluetooth MTU - To increase the packet size of a single Bluetooth packet transmitted over the air (:kconfig:option:`CONFIG_BT_BUF_ACL_RX_SIZE` and others).
168+
* Bluetooth connection parameters - To adaptively change the connection interval and latency on the detection of the SMP service activity (:kconfig:option:`CONFIG_MCUMGR_TRANSPORT_BT_CONN_PARAM_CONTROL`).
169+
* MCUmgr packet reassembly - To allow exchange of large SMP packets (:kconfig:option:`CONFIG_MCUMGR_TRANSPORT_BT_REASSEMBLY`, :kconfig:option:`CONFIG_MCUMGR_TRANSPORT_NETBUF_SIZE` and others).
170+
171+
Consider using these features in your project to speed up the FOTA update process.
172+
173+
.. fota_upgrades_update_end
174+
175+
.. _ug_nrf54l_developing_ble_fota_mcuboot_kmu:
176+
177+
Provisioning of keys for Hardware KMU
178+
*************************************
179+
180+
In case of FOTA implementations using the MCUboot bootloader, which includes hardware cryptography and KMU, you must complete key provisioning before booting any application.
181+
Refer to :ref:`ug_nrf54l_developing_provision_kmu` for detailed description.
182+
183+
.. _ug_nrf54l_developing_ble_fota_mcuboot_direct_xip_mode:
184+
185+
Build configuration additions for MCUboot in the direct-xip mode
186+
****************************************************************
187+
188+
.. fota_upgrades_over_ble_mcuboot_direct_xip_information_start
189+
190+
FOTA updates are also supported when MCUboot is in the direct-xip mode.
191+
In this mode, the MCUboot bootloader boots an image directly from a given slot, so the swap operation is not needed.
192+
It can be used either with or without the revert mechanism support.
193+
For more information about the direct-xip mode and the revert mechanism support, go to the Equal slots (direct-xip) section on the :doc:`mcuboot:design` page.
194+
195+
.. note::
196+
direct-xip mode can not be combined with the image encryption.
197+
198+
.. note::
199+
building a project with direct-xip for nRF54l15 SoC target mode requires static partition manager file for partitioning, see known issues.
200+
201+
To use MCUboot in the direct-xip mode together with FOTA updates, do the following:
202+
203+
* Enable the ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP`` Kconfig option in sysbuild.
204+
205+
See how to build the :ref:`peripheral_lbs` sample with MCUboot in the direct-xip mode when the revert mechanism support is disabled:
206+
207+
.. parsed-literal::
208+
:class: highlight
209+
210+
west build -b *board_target* -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -DSB_CONFIG_MCUBOOT_MODE_DIRECT_XIP=y -DCONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU=y
211+
212+
Optionally, if you want to enable the revert mechanism support, complete the following:
213+
214+
* Enable the ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT`` Kconfig option in sysbuild instead of ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP``.
215+
216+
See how to build the :ref:`peripheral_lbs` sample with MCUboot in direct-xip mode when the revert mechanism support is enabled:
217+
218+
.. parsed-literal::
219+
:class: highlight
220+
221+
west build -b *board_target* -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -DSB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT=y -DCONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU=y
222+
223+
.. note::
224+
When building the application with MCUboot in direct-xip mode with revert mechanism support, the signed image intended for flashing is automatically marked as confirmed (Pre-confirmation).
225+
Without this configuration, the application will fail to boot.
226+
Confirmation mark should not, however, be added when building update images.
227+
228+
Both the ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP`` and ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT`` Kconfig options automatically build application update images for both slots.
229+
To read about the files that are built when the option is enabled, refer to the :ref:`app_build_mcuboot_output` page.
230+
231+
.. fota_upgrades_over_ble_mcuboot_direct_xip_nrfcdm_note_start
232+
233+
.. note::
234+
Support for FOTA updates with MCUboot in the direct-xip mode is available since the following versions of the `nRF Connect Device Manager`_ mobile app:
235+
236+
* Version ``1.8.0`` on Android.
237+
* Version ``1.4.0`` on iOS.
238+
239+
.. fota_upgrades_over_ble_mcuboot_direct_xip_nrfcdm_note_end
240+
241+
.. fota_upgrades_over_ble_mcuboot_direct_xip_information_end

‎doc/nrf/app_dev/device_guides/nrf54l/index.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,8 @@ Ensure to check the revision of your nRF54L15 device to see if it is supported:
6060
features
6161
zms
6262
cryptography
63+
fota_update
64+
kmu_provision
6365
testing_dfu
6466
vpr_flpr
6567
building_nrf54l

‎doc/nrf/app_dev/device_guides/nrf54l/kmu_provision.rst‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
.. _ug_nrf54l_developing_provision_kmu:
2+
3+
4+
nRF54L15 KMU provisioning
5+
#########################
6+
7+
.. contents::
8+
:local:
9+
:depth: 2
10+
11+
The nRF54L15 DK is equipped with Hardware Key Management Unit (KMU), that requires provisioning when in use.
12+
The |NCS| provides a west command, ``ncs-provision``, allowing to upload keys to the device though the Serial Write Debug (SWD) interface.
13+
14+
Prerequisites
15+
*************
16+
17+
First, ensure that the nrfprovision script is installed.
18+
It should install automatically during the setup of the |NCS| working environment.
19+
If it was not installed, or if you wish to install it manually, run the following command:
20+
21+
.. parsed-literal::
22+
:class: highlight
23+
24+
pip install nrfprovision==0.9.0 --extra-index-url https://files.nordicsemi.com/artifactory/api/pypi/nordic-pypi/simple
25+
26+
27+
Key generation
28+
**************
29+
30+
If you need a new key, you can generate it using imgtool or another tool that produces the required kind and format of key.
31+
For instructions on how to generate a key, see the :doc:`imgtool page in the MCUboot documentation<mcuboot:imgtool>`.
32+
See the following example for generating a private key:
33+
34+
.. parsed-literal::
35+
:class: highlight
36+
37+
imgtool keygen -k my_ed25519_priv_key.pem -t ed25519
38+
39+
Provisioning keys to the board
40+
******************************
41+
42+
Before uploading keys, ensure that the SoC is unprovisioned.
43+
If the SoC has been previously provisioned and you need to use a different set of keys, you must first erase the SoC with the erase command:
44+
45+
.. tabs::
46+
47+
.. group-tab:: erase using nrfutil
48+
49+
.. parsed-literal::
50+
:class: highlight
51+
52+
nrfutil device erase
53+
54+
.. group-tab:: erase using nrfjprog
55+
56+
.. parsed-literal::
57+
:class: highlight
58+
59+
nrfjprog --eraseall
60+
61+
Once you have an unprovisioned SoC, upload keys to the board by running the following command:
62+
63+
.. parsed-literal::
64+
:class: highlight
65+
66+
west ncs-provision upload -s nrf54l15 -k ed25519.pem -k ed25519-1.pem -k ed25519-2.pem
67+
68+
* Parameter ``-s (-–soc)`` specifies the target device.
69+
Currently, only the nRF54L15 DK is supported.
70+
71+
* Parameter ``-k (-–key)`` specifies the private key PEM files to be provisioned to the SoC.
72+
You can specify up to three keys.
73+
74+
* Parameter ``--dev-id`` specifies the interface serial number and should be used if multiple J-link interfaces are connected to the development machine.
75+
76+
The script generates the public key for each private key and uploads them to your device.
77+
These public keys generate the verification keys for the application image, which are then used by MCUboot for validation.
78+
The first key specified in the command is used for signing the application image.
79+
Currently, the script supports only ED25519 Keys.

0 commit comments

Comments
 (0)