Migration notes for nRF Connect SDK v3.1.0

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

Required changes

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

Build system

  • In sysbuild, the following CMake extensions have been removed:

    • sysbuild_dt_nodelabel

    • sysbuild_dt_alias

    • sysbuild_dt_node_exists

    • sysbuild_dt_node_has_status

    • sysbuild_dt_prop

    • sysbuild_dt_comp_path

    • sysbuild_dt_num_regs

    • sysbuild_dt_reg_addr

    • sysbuild_dt_reg_size

    • sysbuild_dt_has_chosen

    • sysbuild_dt_chosen

    You must now use pre-existing devicetree extensions, such as dt_nodelabel, without the sysbuild_ prefix. To specify the sysbuild image, use the TARGET argument in place of IMAGE.

    The following example shows one of the removed functions:

    sysbuild_dt_chosen(
  flash_node
  IMAGE ${DEFAULT_IMAGE}
  PROPERTY "zephyr,flash"
)

    It should now be modified as follows:

    dt_chosen(
  flash_node
  TARGET ${DEFAULT_IMAGE}
  PROPERTY "zephyr,flash"
)

nRF54H20

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

nRF54H20 IronSide SE binaries

  • The nRF54H20 IronSide SE binaries have been updated to version v22.2.0+14. For more information, see IronSide SE ABI compatibility.

    Caution

    To program the nRF54H20 IronSide SE binaries on your nRF54H20 SoC-based device, your device must be in lifecycle state (LCS) EMPTY. Devices already provisioned using SUIT-based SoC binaries and in LCS RoT cannot be transitioned back to LCS EMPTY.

    For more information on provisioning devices, see Bring-up step: Disable onboard J-Link Mass Storage Device (MSD).

SUIT to IronSide SE migration

BICR migration from DTS to JSON

Samples and applications

This section describes the changes related to samples and applications.

Matter

  • For the Matter samples and applications:

  • For the Matter light bulb sample:

    • The deferred attribute persistence implementation has changed in the latest Matter version and you must align it as follows:

      • Remove the following lines from the app_task.cpp file located in the application’s src directory:

        #include <app/DeferredAttributePersistenceProvider.h>

DeferredAttributePersistenceProvider gDeferredAttributePersister(Server::GetInstance().GetDefaultAttributePersister(),
                                                                 Span<DeferredAttribute>(&gCurrentLevelPersister, 1),
                                                                 System::Clock::Milliseconds32(5000));

      • Add the following lines to the app_task.cpp file located in the application’s src directory:

        #include <app/util/persistence/DefaultAttributePersistenceProvider.h>
#include <app/util/persistence/DeferredAttributePersistenceProvider.h>

DefaultAttributePersistenceProvider gSimpleAttributePersistence;
DeferredAttributePersistenceProvider gDeferredAttributePersister(gSimpleAttributePersistence,
                                                                 Span<DeferredAttribute>(&gCurrentLevelPersister, 1),
                                                                 System::Clock::Milliseconds32(5000));

      • Modify the mPostServerInitClbk function passed to the Nrf::Matter::PrepareServer function in the app_task.cpp file should be modified to call additionally the gSimpleAttributePersistence.Init(Nrf::Matter::GetPersistentStorageDelegate()).

Thread

  • The OpenThread samples have been updated to directly use the OpenThread stack with the IEEE 802.15.4 radio driver. In this case, the Zephyr networking layer is disabled and its features are not available.

    The new architecture option has been enabled by default in the following samples:

    If you want to use the architecture option that uses the Zephyr networking layer, you need to manually enable the following Kconfig options in your application prj.conf file:

    Or use Snippet l2.

    For example, to enable the Zephyr networking layer in the Thread: CLI for the nRF54L15 DK, build the sample with the following command:

    west build -p -b nrf54l15dk/nrf54l15/cpuapp -- -Dcli_SNIPPET=l2

    Additionally, to enable logging from the Zephyr networking layer, you need to enable the following Kconfig options in your application prj.conf file:

    Or use snippet logging_l2.

    For example, to enable logging from the Zephyr networking layer in the Thread: CLI for the nRF54L15 DK, build the sample with the following command:

    west build -p -b nrf54l15dk/nrf54l15/cpuapp -- -Dcli_SNIPPET="l2;logging_l2"

nRF5340 Audio applications

  • The nRF Audio applications has been updated to use the Network Buffers API to handle audio data. This change requires you to update your application code to use the new APIs for audio data handling. See Changelog for nRF Connect SDK v3.3.99 for more information.

  • The audio devices are now identified by a location bitfield instead of a channel. This requires the location bitfield to be set according to your preference. If you are using the buildprog.py script, it will handle the correct write to UICR. You only need to update the locations in the devices.json file. The new format is: “location”: [“FRONT_LEFT”, “FRONT_RIGHT”]. The optional buildprog tool now uses nRF Util instead of nrfjprog, which has been archived.

    Note

    Support for multiple locations is still under development.

  • As a device can have multiple audio locations, the location name is no longer included in the advertised device name during DFU.

nRF Desktop

  • The HID state module has been updated to use the HID keymap utility to map an application-specific key ID to a HID report ID and HID usage ID pair. The CONFIG_DESKTOP_HID_STATE_HID_KEYMAP_DEF_PATH Kconfig option has been removed and needs to be replaced with the CONFIG_DESKTOP_HID_KEYMAP_DEF_PATH Kconfig option. The format of the configuration file remains the same.

Libraries

This section describes the changes related to libraries.

Drivers

This section provides detailed lists of changes by drivers.

ADC drivers

  • Starting with the nRF Connect SDK v3.1.0, the NRF_SAADC_GND analog input definition has been added. You can use it as zephyr,input-negative = <NRF_SAADC_GND>; to allow negative values in the buffer when using single-ended settings.