Skip to content

Commit c1b50b3

Browse files
b-genteivindj-nordic
b-gent
authored and
eivindj-nordic
committed
doc: add migration guide from nrf5
Add first version of high-level migration guide from nRF5. Signed-off-by: Bartosz Gentkowski <[email protected]>
1 parent 3ccc0f9 commit c1b50b3

File tree

3 files changed

+263
-0
lines changed

3 files changed

+263
-0
lines changed

‎doc/nrf-bm/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,5 +46,6 @@ The |BMlong| is a distinct repository that incorporates elements from the existi
4646
samples.rst
4747
app_dev/dfu/index.rst
4848
release_notes.rst
49+
migration/nrf5_bm_migration.rst
4950
s115_docs.rst
5051
api/api.rst

‎doc/nrf-bm/links.txt

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,3 +70,7 @@
7070
.. _`nRF54L10`: https://docs.nordicsemi.com/category/nRF54L10-category
7171
.. _`nRF54L05`: https://docs.nordicsemi.com/category/nRF54L05-category
7272
.. _`nrfx documentation`: https://docs.nordicsemi.com/bundle/nrfx-apis-latest/page/index.html
73+
74+
.. ### Release notes and migration
75+
76+
.. _`nrfx migration guides`: https://github.com/NordicSemiconductor/nrfx/wiki/nrfx-2.11.0-to-3.0.0

‎doc/nrf-bm/migration/nrf5_bm_migration.rst

Lines changed: 258 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
.. _nrf5_bm_migration:
2+
3+
Migration notes - nRF5 SDK to nRF Connect SDK Bare Metal
4+
########################################################
5+
6+
This document outlines the high-level differences between nRF5 SDK and the |BMlong|.
7+
8+
It is meant to provide support when migrating an application built on nRF5 SDK to |BMshort|.
9+
10+
.. note::
11+
12+
This document is in development and being constantly updated.
13+
14+
Project files
15+
*************
16+
17+
In nRF5, project files are tightly coupled with the SDK directory structure.
18+
19+
Typically, projects are placed inside the :file:`examples` folder within the SDK and include header files, source files, and pre-built libraries in defined locations within the SDK.
20+
These projects rely on embedded IDEs project files, such Keil µVision or IAR, or GNU Makefiles, which all have very limited dependency management.
21+
Developers have to manually handle their project dependencies, adding libraries and their relative headers to their project by navigating the IDE’s menu, which can be tedious for large projects.
22+
23+
In an nRF5 SDK project, project configuration is achieved through the :file:`sdk_config.h` file, which sets the configuration options present in the nRF5 SDK that are applicable to a given project.
24+
When new dependencies are manually added to the project, their relative configuration entries in the project’s initial :file:`sdk_config.h` file are missing, and must also be added manually.
25+
26+
In |BMshort|, projects can be organized more freely and managed more easily thanks to the new build system based on CMake and west.
27+
An application can reside in any folder, and includes a :file:`CMakeLists.txt` build system configuration file (for CMake) and a :file:`prj.conf` project configuration file (for Kconfig, which is a tool that is part of the build system).
28+
29+
The purpose of the :file:`CMakeLists.txt` file is to define the structure of the project, such as source files, libraries, dependencies, and build targets.
30+
Specifically, this file is used to:
31+
32+
* Define the name of your project.
33+
* Add source files:
34+
35+
* Specify the source files for your application that need to be compiled.
36+
This includes main files, libraries, or any additional ``.c`` or ``.cpp`` code.
37+
38+
.. code-block:: cmake
39+
40+
target_sources(app PRIVATE src/main.c src/other_module.c)
41+
42+
* Include headers:
43+
44+
* Add directories for custom include paths to ensure header files are correctly found.
45+
46+
.. code-block:: cmake
47+
48+
target_include_directories(app PRIVATE include)
49+
50+
* Link libraries:
51+
52+
* Add external or custom libraries required for your project (such as math, custom vendor libraries).
53+
54+
.. code-block:: cmake
55+
56+
target_link_libraries(app PRIVATE libfoo)
57+
58+
* External modules and definitions:
59+
60+
* If your project relies on external modules or additional functionality, include them.
61+
62+
.. code-block:: cmake
63+
64+
add_subdirectory("path_to_directory")
65+
66+
Dependencies are added to the project configuration and incorporated into the build process automatically (you do not have to manually add files from specific locations), with the aid of a tool called Kconfig, in conjunction with CMake.
67+
That is done using the :file:`prj.conf` file that replaces the :file:`sdk_config.h` file from the nRF5 SDK.
68+
The entries in the :file:`prj.conf` file are referred to as **Kconfig options**.
69+
70+
Unlike the :file:`sdk_config.h` file that lists all the configuration options relevant for an application, even those whose values are unchanged from defaults, the :file:`prj.conf` file only contains entries whose values must be manually set or to override the default.
71+
72+
The configuration options whose values are left as default are not present in that file, although when a project is built, a file containing all configuration options pertaining to the application (called :file:`autoconf.h`) is created in the background.
73+
The build system and the |nRFVSC| extension both provide a way to conveniently browse and search all available project options and inspect their dependencies and read their help text (menuconfig/extension).
74+
75+
There is no distinction or taxonomy between Kconfig options that are applicable to regular |NCS| only and those that are only applicable to |BMlong|.
76+
Kconfig options that are applicable to the current application are shown and are selectable, while others are not.
77+
78+
There is no consistent mapping of the :file:`sdk_config.h` entries to Kconfig options.
79+
Some libraries that were ported from nRF5 have similar Kconfig options as the :file:`sdk_config.h` entries they had in nRF5, but it is not a consistent rule.
80+
81+
In nRF5, the same application/sample had a project file for each supported board and IDE/compiler.
82+
In |BMshort|, there is a single project file (consisting of :file:`CMakeLists.txt` and :file:`prj.conf`) that can be built for different boards with a different command-line instruction or by selecting a different board target in the VS Code extension.
83+
If necessary, Kconfig options can be specified in a different :file:`.conf` file that is then automatically appended to the default :file:`prj.conf` file, thus realizing a dedicated configuration for a specific board.
84+
Kconfig options appended in this way are referred to as **Kconfig fragments**.
85+
86+
Memory partitioning
87+
===================
88+
89+
In nRF5, memory partitioning was done using linker scripts.
90+
In |BMshort|, there are a few ready-made partitioning schemes that can be selected by compiling for specific board targets that cover the most common use cases.
91+
Partitioning can be tweaked by making simple changes to textual **Devicetree** files which define the layout of the memory.
92+
These can be edited in the board files, or applied to existing boards as **overlays**.
93+
94+
Libraries and drivers
95+
*********************
96+
97+
Whereas nRF5 supported different short range protocols such as Gazell, ESB, and Ant, those are not supported by |BMshort|.
98+
In general, |BMshort| support focuses on Bluetooth Low Energy.
99+
100+
Bluetooth LE libraries
101+
======================
102+
103+
Bluetooth LE features that are natively offered by the SoftDevice are mostly unchanged from the nRF5, and the SoftDevice documentation highlights any differences.
104+
As for the collection of Bluetooth LE libraries that were available in the nRF5, |BMshort| offers a limited subset, where each service may have slightly different API and functionality compared to their respective nRF5 implementation.
105+
106+
The Bluetooth LE services currently offered in |BMshort| are the following:
107+
108+
* Peripheral services:
109+
110+
* Heart Rate Monitor (peripheral)
111+
* Nordic UART (NUS) (peripheral)
112+
* Nordic LED Button (LBS) (peripheral)
113+
* Continuous Glucose Monitor (peripheral)
114+
* Battery (peripheral)
115+
116+
* MCUMgr service (DFU service)
117+
* Bond Management
118+
* Device Information
119+
120+
Utility libraries for Bluetooth LE are available in |BMshort|, though their collection may not be as complete, and their functionality and API may be slightly different than their respective nRF5 implementation.
121+
122+
See table below for a summary of supported libraries.
123+
124+
.. list-table:: Supported libraries
125+
:header-rows: 1
126+
127+
* - Name
128+
- Supported
129+
- New name
130+
- Planned
131+
- Comment
132+
* - ``ble_advertising``
133+
- Yes
134+
- ``ble_adv``
135+
-
136+
-
137+
* - ``ble_advdata``
138+
- Yes
139+
- Merged with ``ble_adv``
140+
-
141+
-
142+
* - ``ble_db_discovery``
143+
- No
144+
-
145+
- Yes
146+
-
147+
* - ``ble_conn_params``
148+
- Yes
149+
- Name unchanged
150+
-
151+
-
152+
* - ``ble_conn_state``
153+
- No
154+
-
155+
- Yes
156+
-
157+
* - ``ble_dtm``
158+
- No
159+
-
160+
- No
161+
- Out of scope
162+
* - ``ble_racp``
163+
- Yes
164+
- Name unchanged
165+
-
166+
-
167+
* - ``ble_srv_common``
168+
- No
169+
-
170+
- No
171+
- Using SoftDevice native API directly
172+
* - ``nrf_ble_gatt``
173+
- Yes
174+
- Merged with ``ble_conn_params``
175+
-
176+
-
177+
* - ``nrf_ble_gq``
178+
- Yes
179+
- ``ble_gq``
180+
-
181+
-
182+
* - ``nrf_ble_qwr``
183+
- Yes
184+
- ``ble_qwr``
185+
-
186+
-
187+
* - ``nrf_ble_scan``
188+
- No
189+
-
190+
- Yes
191+
-
192+
* - ``ble_link_ctx_manager``
193+
- No
194+
-
195+
- No
196+
- Functionality implemented manually where needed
197+
* - ``ble_radio_notification``
198+
- No
199+
-
200+
- Yes
201+
-
202+
* - ``peer_manager``
203+
- No
204+
- Unchanged
205+
- Yes
206+
-
207+
208+
Other libraries
209+
===============
210+
211+
Regarding other utility libraries unrelated to Bluetooth LE, like ``app_timer``, a limited selection is available, often with a different name and slightly different API than their nRF5 variant.
212+
213+
Although sometimes a pattern can emerge on how to port from one to the other, no general rule is available and this must be done on a case-by-case basis.
214+
This is due to several factors, including:
215+
216+
* Large number of libraries, with a mix of naming schemes such as ``ble_`` , ``nrf_``, no prefix.
217+
* Large set of API, developed over the course of several years with little overall consistency with regards to error spaces, asynchronous events.
218+
* Different project configuration mechanism, inherently affecting how libraries are configured.
219+
* Different coding standard in the |NCS| (for example, limited use of ``typedef``).
220+
221+
.. _nrf5_bm_migration_dfu:
222+
223+
DFU
224+
***
225+
226+
The DFU mechanism has changed from nRF5.
227+
Some of the core functionality remains, although implemented differently.
228+
229+
Firstly, |BMshort| supports single-bank DFU updates.
230+
It also supports SoftDevice updates as well as buttonless DFU.
231+
232+
In nRF5, the two major DFU components were the ``MBR`` firmware, (delivered beside the SoftDevice), and the nRF5 bootloader.
233+
The ``MBR`` acted as a very simple first-stage bootloader, only booting the application or the bootloader, and supporting basic copy functionality.
234+
The nRF5 bootloader had the capability to download new firmware, or SoftDevice + Bootloader images, which would then be verified and copied by the ``MBR``.
235+
236+
The bootloader has changed - |BMshort| uses the open-source MCUboot project as first-stage (immutable) bootloader, instead of the MBR.
237+
MCUboot is also used in the |NCS| and other open-source projects.
238+
239+
A major difference is that the nRF5 bootloader included the transport (such as BLE, UART), whereas MCUboot does not.
240+
MCUboot just decides which firmware to boot and verifies it before booting.
241+
242+
The actual download of the new firmware image is done by a dedicated firmware image called the Firmware Loader.
243+
This firmware is provided in |Bmshort|.
244+
In case of an application update, the Firmware Loader copies the new firmware in the application bank (or slot).
245+
MCUboot will then verify and boot the updated firmware.
246+
247+
In case of a SoftDevice or Firmware Loader application update, the Firmware Loader on the device receives an image called Installer which is bundled with the new SoftDevice and/or Firmware Loader application.
248+
The Installer firmware is also provided in |BMshort|.
249+
This image is saved in place of the application by the Firmware Loader.
250+
The Installer boots next after being verified by MCUboot, and proceeds to overwrite the Firmware Loader and SoftDevice as necessary.
251+
The new Firmware Loader boots next to receive a new application image.
252+
253+
The host and mobile tools for DFU have changed, and new versions of both are made available by Nordic.
254+
255+
Drivers
256+
*******
257+
258+
For migration of nrfx drivers, see `nrfx migration guides`_.

0 commit comments

Comments
 (0)