Migration notes for nRF Connect SDK v3.0.0

This document describes the changes required or recommended when migrating your application from nRF Connect SDK v2.9.0 to nRF Connect SDK v3.0.0.

Required changes

The following changes are mandatory to make your application work in the same way as in previous releases.

IDE, OS, and tool support

The nRF Command Line Tools have been archived and replaced by nRF Util. No further updates will be made to the nRF Command Line Tools. Last supported operating systems are Windows 10, Linux Ubuntu 22.04, and macOS 13. The nRF Command Line Tools will remain available for download, but do not install the SEGGER J-Link version they provide if you have a newer version installed.

It is recommended to install the latest version of nRF Util, as listed in the Install prerequisites section of the installation page.

Installation of the SDK and toolchain

Starting from the nRF Connect SDK v3.0.0, the Toolchain Manager app no longer provides the latest toolchain and nRF Connect SDK versions for installation.

Use one of the two installation methods to manage the toolchain and SDK versions, either the recommended nRF Connect for VS Code or the command line with nRF Util.

Build system

  • The default runner for the west flash command has been changed to use nRF Util instead of nrfjprog that is part of the archived nRF Command Line Tools. This affects all boards that used nrfjprog as the west runner backend for programming the following SoCs and SiPs:

    • nRF91 Series (including nRF91x1)

    • nRF7002

    • nRF5340 (including nRF5340 Audio DK)

    • Nordic Thingy:53

    • nRF52 Series

    • nRF21540

    This change is made to ensure that the programming process is consistent across all boards and to provide a more robust programming experience. The west flash command now uses the nrfutil device subcommand by default to flash the application to the board.

    Note

    For nRF Connect SDK 3.0.0, use the nrfutil-device v2.8.8.

    It is recommended to install nRF Util to avoid potential issues during programming. Complete the following steps:

    1. Follow the steps for Installing nRF Util in its official documentation.

    2. Install the nrfutil device using the following command:

      nrfutil install device=2.8.8 --force

    If you prefer to continue using nrfjprog for programming devices, specify the west runner with west flash.

  • Erasing the external memory when programming a new firmware image with the west flash series now always correctly honors the --erase flag (and its absence) both when using the nrfjprog and nrfutil backends. Before this release, the nrjfprog backend would always erase only the sectors of the external flash used by the new firmware, and the nrfutil backend would always erase the whole external flash.

Application development

The following are the changes required to migrate your applications to the nRF Connect SDK 3.0.0.

ZMS settings backend

The new settings backend for ZMS is not compatible with the old version.

To keep using the legacy backend, enable the CONFIG_SETTINGS_ZMS_LEGACY Kconfig option.

To migrate from the legacy backend to the new backend remove the Kconfig options CONFIG_SETTINGS_ZMS_NAME_CACHE and CONFIG_SETTINGS_ZMS_NAME_CACHE_SIZE from your conf files.

Bluetooth® LE legacy pairing

Support for Bluetooth LE legacy pairing is no longer enabled by default because it is not secure. The CONFIG_BT_SMP_SC_PAIR_ONLY Kconfig option is enabled by default in Zephyr. If you still need to support the Bluetooth LE legacy pairing and you accept the security risks, disable the option in the configuration.

Caution

Using Bluetooth LE legacy pairing introduces, among others, a risk of passive eavesdropping. Supporting Bluetooth LE legacy pairing makes devices vulnerable to downgrade attacks.

CRACEN initialization

In the nRF Connect SDK versions 2.8.0 and 2.9.0, you must explicitly configure the CRACEN initialization. It is done by adding the CONFIG_CRACEN_LOAD_MICROCODE Kconfig option to the image configuration. This option allows to select the given image to initialize CRACEN.

However, from nRF Connect SDK 3.0.0, CRACEN is automatically initialized. The new build configuration option (SB_CONFIG_CRACEN_MICROCODE_LOAD_ONCE) now controls this process at the sysbuild level. When enabled, the build system automatically determines which image must handle the initialization of CRACEN.

Unlike in the nRF Connect SDK versions 2.8.0 and 2.9.0, where CRACEN initialization is disabled by default in the MCUboot configuration, CRACEN is initialized by the earliest bootloader by default in the nRF Connect SDK 3.0.0. This change can lead to scenarios where CRACEN might be initialized twice or not initialized at all. When migrating from the nRF Connect SDK v2.9.0 to v3.0.0, you must analyze which image is responsible for initializing CRACEN before and after the firmware update to ensure correct operation. Make sure to adjust your bootloader or application upgrade path accordingly to avoid any issues related to CRACEN initialization.

nRF54H20

This section describes the changes specific to the nRF54H20 SoC and DK support in the nRF Connect SDK.

Dependencies

The following required dependencies for the nRF54H20 SoC and DK have been updated.

nRF Util

  • nrfutil has been updated to v7.13.0.

    Install nRF Util v7.13.0 as follows:

    1. Download the nRF Util executable file from the nRF Util development tool product page.

    2. Add nRF Util to the system path on Linux and macOS, or environment variables on Windows, to run it from anywhere on the system. On Linux and macOS, use one of the following options:

      • Add nRF Util’s directory to the system path.

      • Move the file to a directory in the system path.

    3. On macOS and Linux, give nrfutil execute permissions by typing chmod +x nrfutil in a terminal or using a file browser. This is typically a checkbox found under file properties.

    4. On macOS, to run the nRF Util executable, you need to allow it in the system settings.

    5. Verify the version of the nRF Util installation on your machine by running the following command:

      nrfutil --version

    6. If your version is lower than 7.13.0, run the following command to update nRF Util:

      nrfutil self-upgrade

    For more information, see the nRF Util documentation.

nRF Util device

  • nRF Util device command has been updated to v2.8.8.

    Install the nRF Util device command v2.8.8 as follows:

    nrfutil install device=2.8.8 --force

    For more information, consult the nRF Util documentation.

nRF Util trace

  • nRF Util trace command has been updated to v3.3.0. Install the nRF Util trace command v3.3.0 as follows:

    nrfutil install trace=3.3.0 --force

    For more information, consult the nRF Util documentation.

nRF Util suit

  • nRF Util suit command has been updated to v0.9.0. Install the nRF Util suit command v0.9.0 as follows:

    nrfutil install suit=0.9.0 --force

    For more information, consult the nRF Util documentation.

nRF54H20 BICR

  • The nRF54H20 BICR has been updated (from the one supporting nRF Connect SDK v2.9.0 as well as nRF Connect SDK v2.9.0-nRF54H20-1). To update the BICR of your development kit while in Root of Trust, do the following:

    1. Build your application using nRF Connect SDK v3.0.0.

    2. Connect the nRF54H20 DK to your computer using the DEBUGGER port on the DK.

      Note

      On MacOS, connecting the DK might repeatedly trigger a popup displaying the message Disk Not Ejected Properly. To disable this, run JLinkExe, then run MSDDisable in the J-Link Commander interface.

    3. List all the connected development kits to see their serial number (matching the one on the DK’s sticker):

      nrfutil device list

    4. Program the BICR by running nRF Util from your application folder using the following command:

      nrfutil device program --options chip_erase_mode=ERASE_NONE --firmware ./build/<your_application_name>/zephyr/bicr.hex --core Application --serial-number <serial_number>
nRF54H20 SoC binaries

  • The nRF54H20 SoC binaries bundle has been updated to version 0.9.6.

    Caution

    If migrating from nRF Connect SDK v2.9.0 or lower, you must follow steps from Migration notes for nRF Connect SDK v2.9.0-nRF54H20-1 to update the nRF54H20 SoC binaries bundle to version 0.9.2.

    Note

    The nRF54H20 SoC binaries only support specific versions of the nRF Connect SDK and do not support rollbacks to a previous version. Upgrading the nRF54H20 SoC binaries on your development kit might break the DK’s compatibility with applications developed for previous versions of the nRF Connect SDK. For more information, see IronSide SE ABI compatibility.

    To update the SoC binaries bundle of your development kit while in Root of Trust, do the following:

    1. Download the nRF54H20 SoC binaries v0.9.6.

      Note

      On macOS, ensure that the ZIP file is not unpacked automatically upon download.

    2. Purge the device as follows:

      nrfutil device recover --core Application --serial-number <serial_number>
nrfutil device recover --core Network --serial-number <serial_number>
nrfutil device reset --reset-kind RESET_PIN --serial-number <serial_number>

    3. Run west update.

    4. Move the correct .zip bundle to a folder of your choice, then run nRF Util to program the binaries using the following command:

      nrfutil device x-suit-dfu --firmware nrf54h20_soc_binaries_v0.9.6.zip --serial-number <serial_number>

    5. Purge the device again as follows:

      nrfutil device recover --core Application --serial-number <serial_number>
nrfutil device recover --core Network --serial-number <serial_number>
nrfutil device reset --reset-kind RESET_PIN --serial-number <serial_number>
SDK and toolchain

  • To update the SDK and the toolchain, do the following:

    1. Open Toolchain Manager in nRF Connect for Desktop.

    2. Click SETTINGS in the navigation bar to specify where you want to install the nRF Connect SDK.

    3. In SDK ENVIRONMENTS, click the Install button next to the nRF Connect SDK version v3.3.0.

Application development

The following are the changes required to migrate your applications to the nRF Connect SDK 3.0.0.

Entropy source for radio applications

  • The default entropy source was changed to use the SSF service. As a result, the communication channel as well as RAM regions, dedicated to communicate with the SDFW are now enabled by default. This can result in incompatible UICRs if your application relies on the defaults. If UICRs are incompatible, the application cannot be upgraded using DFU, but must be programmed using the DEBUGGER port. If you want to update your application using DFU, add the following overlay to your radio application if you want to maintain UICR compatibility:

    /* Switch back to the pseudo-random entropy source. */
/ {
   chosen {
     zephyr,entropy = &prng;
   };
   /delete-node/ psa-rng;
   prng: prng {
      compatible = "nordic,entropy-prng";
      status = "okay";
   };
};
/* Disable IPC between cpusec <-> cpurad. */
&cpusec_cpurad_ipc {
   status = "disabled";
};
&cpurad_ram0x_region {
   status = "disabled";
};
&cpusec_bellboard {
   status = "disabled";
};
SUIT MPI configuration

The SUIT MPI configuration has been moved from local Kconfig options to sysbuild. To migrate your application, move all CONFIG_MPI_* options from the application configuration into the sysbuild.conf file. For example, to migrate the root manifest vendor ID, remove the following line from the prj.conf file:

CONFIG_SUIT_MPI_ROOT_VENDOR_NAME="acme.corp"

And add the following line inside the sysbuild.conf file:

SB_CONFIG_SUIT_MPI_ROOT_VENDOR_NAME="acme.corp"

If your project does not use the sysbuild.conf file, you must create one.

Samples and applications

This section describes the changes related to samples and applications.

Asset Tracker v2

nRF Desktop

  • The default device names (the CONFIG_DESKTOP_DEVICE_PRODUCT Kconfig option) have been updated to remove the “52” infix, because the nRF Desktop application supports other SoC Series also. As a result of this change, peripherals using firmware from nRF Connect SDK 3.0.0 (or newer) will not pair with dongles using firmware from an older nRF Connect SDK release, and the other way around. Also aligned the 99-hid.rules file inside the HID Configurator script. The HID Configurator rule will not work with old device names.

    To keep backwards compatibility, revert locally, the changes introduced by commit hash 5b80e46478462907a3cc4fd1686e241591775ffe:

    • The CONFIG_DESKTOP_DEVICE_PRODUCT Kconfig option defines the device name used by HID peripheral.

    • The peer_name array inside the ble_scan_def.h file determines device name filters used by HID dongle while scanning for unpaired HID peripherals.

    • The 99-hid.rules file allows HID configurator Python script to configure nRF Desktop devices without root access.

nRF5340 Audio applications

Libraries

This section describes the changes related to libraries.

Google Fast Pair

For applications and samples using the Google Fast Pair Service (GFPS) library:

  • If you use sysbuild for generating a hex file with the Fast Pair provisioning data, you must align your application with the new approach for passing the provisioning parameters (the Model ID and the Anti-Spoofing Private Key). The FP_MODEL_ID and FP_ANTI_SPOOFING_KEY CMake variables are replaced by the corresponding SB_CONFIG_BT_FAST_PAIR_MODEL_ID and SB_CONFIG_BT_FAST_PAIR_ANTI_SPOOFING_PRIVATE_KEY Kconfig options that are defined at the sysbuild level. The following additional build parameters for Fast Pair are no longer valid:

    -DFP_MODEL_ID=0xFFFFFF -DFP_ANTI_SPOOFING_KEY=AbAbAbAbAbAbAbAbAbAbAbAbAbAbAbAbAbAbAbAbAbA=

    You must replace them with the new sysbuild Kconfig options. You can provide them as additional build parameters to the build command as follows:

    -DSB_CONFIG_BT_FAST_PAIR_MODEL_ID=0xFFFFFF -DSB_CONFIG_BT_FAST_PAIR_ANTI_SPOOFING_PRIVATE_KEY='\"AbAbAbAbAbAbAbAbAbAbAbAbAbAbAbAbAbAbAbAbAbA=\"'

    You can replace this exemplary method with any other configuration method that is supported by sysbuild.

    Note

    To avoid build failures, you must surround the string value for the Anti-Spoofing Private Key parameter with the special character sequence instead of the typical " character. The surrounding characters depend on your operating system:

    1. Replace the standard " character with the \" characters.

    2. Surround the modified string value with the ' character.

    The special character sequence is only required when you pass the SB_CONFIG_BT_FAST_PAIR_ANTI_SPOOFING_PRIVATE_KEY Kconfig option as an additional build parameter.

  • You must remove the SB_CONFIG_BT_FAST_PAIR Kconfig option from the sysbuild configuration in your project. The SB_CONFIG_BT_FAST_PAIR option no longer exists in this nRF Connect SDK release. Additionally, if you rely on the SB_CONFIG_BT_FAST_PAIR Kconfig option to set the CONFIG_BT_FAST_PAIR Kconfig option in the main image configuration of your application, you must align your main image configuration and set the CONFIG_BT_FAST_PAIR Kconfig option explicitly.

  • If your Fast Pair application uses the Find My Device (FMD) extension, you must update your application code to correctly track the FMDN provisioning state. From this nRF Connect SDK release, you must not rely on the bt_fast_pair_fmdn_info_cb.provisioning_state_changed callback to report the initial provisioning state right after the Fast Pair module is enabled with the bt_fast_pair_enable() function call. Instead, you must use the bt_fast_pair_fmdn_is_provisioned() function to initialize the FMDN provisioning state right after the bt_fast_pair_enable() function call. For more details, see the Provisioning state section in the Fast Pair integration guide.

nRF Cloud library

For applications and samples using the nRF Cloud library:

  • You must set the CONFIG_NRF_CLOUD Kconfig option to access the nRF Cloud libraries. This option is now disabled by default to prevent the unintended inclusion of nRF Cloud Kconfig variables in non-nRF Cloud projects, addressing a previous issue.

Location library

For applications and samples using the Location library:

  • Support for HERE location services and the CONFIG_LOCATION_SERVICE_HERE Kconfig option has been removed. To use external location services, enable the CONFIG_LOCATION_SERVICE_EXTERNAL option and implement the required APIs.

  • The service parameter in location_cellular_config and location_wifi_config has been removed. The library supports only one location service, so the service parameter is no longer needed.