Migration guide for nRF Connect SDK v2.6.0

This document describes the changes required or recommended when migrating your application from nRF Connect SDK v2.5.0 to nRF Connect SDK v2.6.0.

Required changes

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

Samples and applications

This section describes the changes related to samples and applications.

Serial LTE Modem (SLM)

  • The Zephyr settings backend has been changed from FCB to NVS. Because of this, one setting is restored to its default value after the switch if you are using the LwM2M carrier library. The setting controls whether the SLM connects automatically to the network on startup. You can read and write it using the AT#XCARRIER="auto_connect" command.

  • The AT#XCMNG AT command, which is activated with the overlay-native_tls.conf overlay file, has been changed from using modem certificate storage to Zephyr settings storage. You need to use the AT#XCMNG command to store previously stored credentials again.

  • The CONFIG_SLM_WAKEUP_PIN Kconfig option was renamed to CONFIG_SLM_POWER_PIN. If you have defined it separately from the default configurations, you need to update its name accordingly.

Matter

  • For the Matter samples and applications using Intermittently Connected Devices configuration (formerly called Sleepy End Devices):

    • The naming convention for the energy-optimized devices has been changed from Sleepy End Devices (SED) to Intermittently Connected Devices (ICD). Because of this, the Kconfig options used to manage this configuration have been aligned as well. If your application uses the following Kconfig options, they require name changes:

  • For Matter over Thread samples, starting from this release, the cryptography backend enabled by default is PSA Crypto API instead of Mbed TLS. Be aware of the change and consider the following when migrating to nRF Connect SDK v2.6.0:

    • You can keep using Mbed TLS API as the cryptography backend by disabling PSA Crypto API. You can disable it by setting the CONFIG_CHIP_CRYPTO_PSA Kconfig option to n.

    • Thread libraries will be built with PSA Crypto API enabled without Mbed TLS support. This means that if you set the CONFIG_CHIP_CRYPTO_PSA Kconfig option to n, you must also build the Thread libraries from sources.

      To inherit Thread certification from Nordic Semiconductor, you must use the PSA Crypto API backend.

    • The device can automatically migrate all operational keys from the Matter’s generic persistent storage to the PSA ITS secure storage. This means that all keys needed to establish the secure connection between Matter nodes will be moved to the PSA ITS secure storage. To enable operational keys migration, set the CONFIG_NCS_SAMPLE_MATTER_OPERATIONAL_KEYS_MIGRATION_TO_ITS Kconfig option to y.

      The default reaction to migration failure in nRF Connect SDK Matter samples is a factory reset of the device. To change the default reaction, set the CONFIG_NCS_SAMPLE_MATTER_FACTORY_RESET_ON_KEY_MIGRATION_FAILURE Kconfig option to n and implement the reaction in your Matter event handler.

    • When the Device Attestation Certificate (DAC) private key exists in the factory data set, it can migrate to the PSA ITS secure storage.

      You can also have the DAC private key replaced by zeros in the factory data partition by setting the CONFIG_CHIP_CRYPTO_PSA_MIGRATE_DAC_PRIV_KEY Kconfig option to y. This functionality is experimental.

  • For the Matter samples and applications using the samples/matter/common directory:

    • The structure of the files located in the common directory has been changed. Align the appropriate paths in your application’s CMakeLists.txt file and source files, including header files located in the common directory.

    • The event_types.h header file was removed. If your application uses it, add the event_types.h file in your application’s src directory with the following code in the file:

      #pragma once

struct AppEvent; /* needs to be implemented in the application code */
using EventHandler = void (*)(const AppEvent &);

    • The board_util.h header file was renamed to board_config.h and moved to the samples/matter/common/src/board directory. Align any source files that include it to use the new name.

    • The new Nrf and Matter namespaces have been added to the files located in the common directory. Align the source files using these files to use the appropriate namespaces.

Wi-Fi®

  • For samples using Wi-Fi features:

    • A few Kconfig options related to scan operations have been removed in the current release.

      If your application uses scan operations, they need to be updated to remove the dependency on the following options:

      • CONFIG_WIFI_MGMT_SCAN_BANDS

      • CONFIG_WIFI_MGMT_SCAN_SSID_FILT

      • CONFIG_WIFI_MGMT_SCAN_CHAN

    • Instead of the CONFIG_WIFI_MGMT_SCAN_MAX_BSS_CNT Kconfig option, a new CONFIG_NRF_WIFI_SCAN_MAX_BSS_CNT Kconfig option is added.

    • The Wi-Fi interface is now renamed from wlan0 to nordic_wlan0, and for easier fetching of the handler, an entry in the DTS file is added zephyr_wifi.

      If your application was using device_get_binding("wlan0"), replace with DEVICE_DT_GET(DT_CHOSEN(zephyr_wifi)).

      Optionally, you can override the label zephyr_wifi in the DTS file with a different Wi-Fi interface name.

Libraries

Modem library integration layer

  • For applications using Modem library integration layer:

    • The lte_connectivity module is renamed to lte_net_if. Make sure that all references are updated accordingly, including function names and Kconfig options.

    • If your application is using the lte_net_if (formerly lte_connectivity) without disabling CONFIG_NRF_MODEM_LIB_NET_IF_AUTO_START, CONFIG_NRF_MODEM_LIB_NET_IF_AUTO_CONNECT, and CONFIG_NRF_MODEM_LIB_NET_IF_AUTO_DOWN Kconfig options, changes are required as the default values are changed from enabled to disabled.

      • Consider using the conn_mgr_all_if_up(), conn_mgr_if_connect() and conn_mgr_if_disconnect() functions instead of enabling the Kconfig options to have better control of the initialization and connection establishment.

    • The Release Assistance Indication (RAI) socket options have been deprecated and replaced with a new consolidated socket option. If your application uses SO_RAI_* socket options, you need to update your socket configuration as follows:

      1. Replace the deprecated socket options SO_RAI_NO_DATA, SO_RAI_LAST, SO_RAI_ONE_RESP, SO_RAI_ONGOING, and SO_RAI_WAIT_MORE with the new SO_RAI option.

      2. Set the optval parameter of the SO_RAI socket option to one of the new values RAI_NO_DATA, RAI_LAST, RAI_ONE_RESP, RAI_ONGOING, or RAI_WAIT_MORE to specify the desired indication.

      Example of migration:

      /* Before migration. */
setsockopt(socket_fd, SOL_SOCKET, SO_RAI_LAST, NULL, 0);

/* After migration. */
int rai_option = RAI_LAST;
setsockopt(socket_fd, SOL_SOCKET, SO_RAI, &rai_option, sizeof(rai_option));

nRF Cloud

  • The nrf_cloud_obj_location_request_create() function has changed. The parameter const bool request_loc has been changed to const struct nrf_cloud_location_config *const config.

  • To migrate to the new API, you need to declare a nrf_cloud_location_config structure and set the structure’s do_reply variable to the value used for request_loc. Set the two remaining structure variables, hi_conf and fallback, according to your application’s needs. You also must provide a pointer to the structure to the nrf_cloud_obj_location_request_create() function instead of the boolean value.

Security

  • For samples using CONFIG_NRF_SECURITY:

    • RSA keys are no longer enabled by default. This reduces the code size by 30 kB if not using RSA keys. This also breaks the configuration if using the RSA keys without explicitly enabling an RSA key size. Enable the required key size to fix the configuration, for example by setting the Kconfig option CONFIG_PSA_WANT_RSA_KEY_SIZE_2048 if 2048-bit RSA keys are required.

    • The PSA config is now validated by the ncs/nrf/ext/oberon/psa/core/library/check_crypto_config.h file. Users with invalid configurations must update their PSA configuration according to the error messages that the check_crypto_config.h file provides.

  • For the Crypto: Persistent key storage sample:

    • The Kconfig option CONFIG_PSA_NATIVE_ITS is replaced by the Kconfig option CONFIG_TRUSTED_STORAGE, which enables the new Trusted storage library. The Trusted storage library provides the PSA Internal Trusted Storage (ITS) API for board targets without TF-M. It is not backward compatible with the previous PSA ITS implementation. Migrating from the PSA ITS implementation, enabled by the CONFIG_PSA_NATIVE_ITS option, to the new Trusted storage library requires manual data migration.

  • For Wi-Fi credentials library and Wi-Fi samples:

    • CONFIG_WIFI_CREDENTIALS_BACKEND_PSA_UID_OFFSET has been removed because it was specific to the previous solution that used PSA Protected Storage instead of PSA Internal Trusted Storage (ITS). Use CONFIG_WIFI_CREDENTIALS_BACKEND_PSA_OFFSET to specify the key offset for PSA ITS. Be aware that Wi-Fi credentials stored in Protected Storage will not appear in ITS when switching. To avoid re-provisioning Wi-Fi credentials, manually read out the old credentials from Protected Storage in the previously used UID and store to ITS.

zcbor

  • If you have zcbor-generated code that relies on the zcbor libraries through Zephyr, you must regenerate the files using zcbor 0.8.1. Note that the names of generated types and members has been overhauled, so the code using the generated code must likely be changed.

    For example:

    • Leading single underscores and all double underscores are largely gone.

    • Names sometimes gain suffixes like _m or _l for disambiguation.

    • All enum (choice) names have now gained a _c suffix, so the enum name no longer matches the corresponding member name exactly (because this broke C++ namespace rules).

  • The function zcbor_new_state(), zcbor_new_decode_state() and the macro ZCBOR_STATE_D have gained new parameters related to decoding of unordered maps. Unless you are using that new functionality, these can all be set to NULL or 0.

  • The functions zcbor_bstr_put_term() and zcbor_tstr_put_term() have gained a new parameter maxlen, referring to the maximum length of the parameter str. This parameter is passed directly to strnlen() under the hood.

  • The function zcbor_tag_encode() has been renamed to zcbor_tag_put().

  • Printing has been changed significantly, for example, zcbor_print() is now called zcbor_log(), and zcbor_trace() with no parameters is gone, and in its place are zcbor_trace_file() and zcbor_trace(), both of which take a state parameter.