Migration notes for nRF Connect SDK v3.5.0 (Working draft)

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

Required changes

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

Build and configuration system

This section describes the changes related to the build and configuration system.

  • Device Firmware Update (DFU) support for the nRF70 Series firmware patch has been removed, together with the following Kconfig options:

    • SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_WIFI_FW_PATCH

    • SB_CONFIG_DFU_ZIP_WIFI_FW_PATCH

    • CONFIG_NRF_WIFI_FW_PATCH_DFU

    If your application enabled any of these options, remove them. The nRF70 Series firmware patch is no longer allocated a separate MCUboot update slot. If you set the SB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES Kconfig option or a static partition layout explicitly for a firmware-patch build, reduce the number of updatable images by one and remove the now-unused update-slot partitions. Storing the nRF70 Series firmware patch in external flash using the SB_CONFIG_WIFI_PATCHES_EXT_FLASH_XIP or SB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE Kconfig option is not affected.

Samples and applications

This section describes the changes related to samples and applications.

Bluetooth Fast Pair samples

  • The Bluetooth Fast Pair: Locator tag and Bluetooth Fast Pair: Input device samples no longer support the nRF52 and nRF53 Series devices. The following board targets have been removed from both samples:

    • nrf52dk/nrf52832

    • nrf52840dk/nrf52840

    • nrf5340dk/nrf5340/cpuapp

    • nrf5340dk/nrf5340/cpuapp/ns

    Additionally, the following board targets have been removed from the Bluetooth Fast Pair: Locator tag sample:

    • nrf52833dk/nrf52833

    • thingy53/nrf5340/cpuapp

    • thingy53/nrf5340/cpuapp/ns

    If your application is based on one of these samples and targets an nRF52 or nRF53 Series device, continue using the nRF Connect SDK v3.4.0 release or migrate your design to a supported nRF54L Series device.

Matter

  • All Matter samples, shared sample code, devicetree partition files, and Matter-specific snippets have been moved from sdk-nrf to the separate Matter add-on repository (ncs-matter). The Matter bridge and Thingy:53 weather station reference applications are also relocated into the add-on under ncs-matter/samples/.

    If your project is based on a Matter sample or application from sdk-nrf v3.4.0 or earlier, you must migrate to the add-on structure to continue receiving sample updates. See Migrating Matter projects from sdk-nrf to Matter add-on for the full migration guide, including path mapping tables, Kconfig symbol renames, devicetree include updates, snippet name changes, and workspace setup instructions.

Libraries

This section describes the changes related to libraries.

  • Location library:

    • The library now always uses the chosen zephyr,wifi node to find the used Wi-Fi device. If your application uses the deprecated ncs,location-wifi node, you need to change it to use the zephyr,wifi node instead:

      chosen {
        zephyr,wifi = &mywifi;
};

  • Trusted storage library:

Drivers

This section describes the changes related to drivers.

Clock control nrf deprecation

The Clock Control driver has been updated for the following clocks on nRF52, nRF53, nRF91, and nRF54L Series devices:

  • HFCLK

  • LFCLK

  • XO

  • XO24M

  • HFCLK192M

  • HFCLKAUDIO

To restore the legacy driver implementation, set CONFIG_CLOCK_CONTROL_NRF to y.

To migrate your code from nRF Connect SDK v3.4.0 to nRF Connect SDK v3.5.0, complete the following steps:

  1. Enable each application-controlled clock in the application-specific or board-specific devicetree overlay file.

    This enables the corresponding clock driver. For example:

    /* if nRF54L XO is to be controlled */
&xo {
    status = "okay";
};

/* if nRF52, nRF53 HFCLK is to be controlled */
&hfclk {
    status = "okay";
};

/* if nRF52, nRF53, nRF91 or nRF54L LFCLK is to be controlled */
&lfclk {
    status = "okay";
};

/* if HFCLK192M is to be controlled */
&hfclk192m {
    status = "okay";
};

/* if XO24M is to be controlled */
&xo24m {
    status = "okay";
};

/* if HFCLKAUDIO is to be controlled */
&hfclkaudio {
    status = "okay";
};

  2. Rename the following Kconfig options:

  3. Move the following Kconfig options to the nordic,nrf-clock-lfclk devicetree node:

    • Replace CONFIG_CLOCK_CONTROL_NRF_K32SRC_FREQUENCY with the k32src-frequency property.

    • Replace CONFIG_CLOCK_CONTROL_NRF_SOURCE choice with the k32src enum property.

    • Replace CLOCK_CONTROL_NRF_K32SRC_RC and NRFX_CLOCK_LF_SRC_RC with the k32src = "rc".

    • Replace CLOCK_CONTROL_NRF_K32SRC_XTAL and NRFX_CLOCK_LF_SRC_XTAL with the k32src = "xtal".

    • Replace CLOCK_CONTROL_NRF_K32SRC_SYNTH and NRFX_CLOCK_LF_SRC_SYNTH with the k32src = "synth".

    • Replace CLOCK_CONTROL_NRF_K32SRC_EXT_LOW_SWING and NRFX_CLOCK_LF_SRC_LOW_SWING with the k32src = "ext_low_swing".

    • Replace CLOCK_CONTROL_NRF_K32SRC_EXT_FULL_SWING and NRFX_CLOCK_LF_SRC_FULL_SWING with the k32src = "ext_full_swing".

    • Replace CONFIG_CLOCK_CONTROL_NRF_ACCURACY_PPM choice with the k32src-accuracy-ppm enum property.

    • Replace CLOCK_CONTROL_NRF_K32SRC_500PPM with the k32src-accuracy-ppm = <500>.

    • Replace CLOCK_CONTROL_NRF_K32SRC_250PPM with the k32src-accuracy-ppm = <250>.

    • Replace CLOCK_CONTROL_NRF_K32SRC_150PPM with the k32src-accuracy-ppm = <150>.

    • Replace CLOCK_CONTROL_NRF_K32SRC_100PPM with the k32src-accuracy-ppm = <100>.

    • Replace CLOCK_CONTROL_NRF_K32SRC_75PPM with the k32src-accuracy-ppm = <75>.

    • Replace CLOCK_CONTROL_NRF_K32SRC_50PPM with the k32src-accuracy-ppm = <50>.

    • Replace CLOCK_CONTROL_NRF_K32SRC_30PPM with the k32src-accuracy-ppm = <30>.

    • Replace CLOCK_CONTROL_NRF_K32SRC_20PPM with the k32src-accuracy-ppm = <20>.

    • Replace CONFIG_NRFX_CLOCK_LFXO_TWO_STAGE_ENABLED with k32src = "xtal" or k32src = "ext_low_swing" or k32src = "ext_full_swing".

  4. Update your application to use the new clock control API.

    Use the following mapping when you update the API calls:

    • mgr is the on-off manager created for nordic,nrf-clock and obtained using z_nrf_clock_control_get_onoff.

    • dev is the device compatible with nordic,nrf-clock.

    • sys is the subsystem for nordic,nrf-clock.

      The new clocks implementation does not use it.

    • new_dev is the device that corresponds to the previously used sys value. It must be compatible with one of the following nodes:

      • nordic,nrf-clock-lfclk

      • nordic,nrf-clock-hfclk

      • nordic,nrf-clock-xo

      • nordic,nrf-clock-hfclk192m

      • nordic,nrf-clock-xo24m

      • nordic,nrf-clock-hfclkaudio

    The following example shows the deprecated API usage and the corresponding new API usage:

    // Old API usage (deprecated)
z_nrf_clock_calibration_init(&mgrs);    //1
onoff_release(mgr)                      //2
onoff_request(mgr, &cli);               //3
onoff_cancel_or_release(mgr, &cli);     //4
clock_control_on(dev,sys)               //5
clock_control_off(dev,sys)              //6
clock_control_async_on(dev,sys)         //7
clock_control_get_status(dev,sys)       //8
z_nrf_clock_control_get_onoff(sys)      //9

// New API usage
z_nrf_clock_calibration_init();                             //1
nrf_clock_control_release(new_dev, NULL);                   //2
nrf_clock_control_request(new_dev, NULL, &cli);             //3
nrf_clock_control_cancel_or_release(new_dev, NULL, &cli);   //4
clock_control_on(new_dev, NULL)                             //5
clock_control_off(new_dev, NULL)                            //6
clock_control_async_on(new_dev, NULL)                       //7
clock_control_get_status(new_dev, NULL)                     //8
// Remove all uses of z_nrf_clock_control_get_onoff         //9