Migration notes for nRF Connect SDK v3.2.0

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

Required changes

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

nRF54L

This section describes the changes specific to the nRF54L series SoCs and DKs support in the nRF Connect SDK.

nRF54L pin cross power-domain use

  • You must enable the Constant Latency sub-power mode from the application to allow cross power-domain pin mapping. For details, see the nRF54L pin mapping page.

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 v23.1.1+20. Starting from the nRF Connect SDK v3.2.0, you should always upgrade your nRF54H20 IronSide SE binaries to the latest version.

    For more information, see:

nRF54H20 power management

  • The Kconfig options CONFIG_PM_S2RAM and CONFIG_PM_S2RAM_CUSTOM_MARKING have been reworked to be managed automatically based on the suspend-to-ram power-states in the devicetree. Any occurrences of CONFIG_PM_S2RAM=y and CONFIG_PM_S2RAM_CUSTOM_MARKING=y must be removed.

    The default value of CONFIG_PM_S2RAM has changed from n to y. If your application explicitly disables S2RAM or relies on S2RAM being disabled, remove any instance of CONFIG_PM_S2RAM=n and instead disable the s2ram power state in the devicetree.

    To disable the s2ram power state, see the following DTS example:

    &s2ram {
        status = "disabled";
};

  • For a correct configuration of power management on your custom nRF54H20-based device, you must define pm_ramfunc also for the radio core. For a configuration example, see the pm_ramfunc radio core configuration in the nrf54h20dk_nrf54h20_cpurad.dts file.

nRF54H20 entropy provider

  • PSA RNG is the new default Zephyr entropy provider for the nRF54H20 DK. It is recommended to use PSA RNG as your Zephyr entropy provider also on your custom nRF54H20-based device. For a configuration example, see the new PSA RNG configuration in DTS for both the application and radio cores of the nRF54H20 DK.

Samples and applications

This section describes the changes related to samples and applications.

nRF Desktop

  • The configuration of the nrf54h20dk/nrf54h20/cpuapp board target has been updated in the nRF Desktop application to migrate from the SUIT solution to the IronSide SE solution. To migrate the configuration for your nRF Desktop based application, complete the following steps:

    1. Remove the Kconfig options related to the SUIT solution in your project configuration files (for example, prj.conf).

    2. Configure the MCUboot bootloader in your sysbuild configuration file:

      Note

      The nRF Desktop configuration for the nrf54h20dk/nrf54h20/cpuapp board target uses the MCUboot bootloader in the direct-xip mode. You can configure other MCUboot bootloader modes (for example, the swap mode) in the nRF Desktop application, but they are not used as part of the nRF Desktop configuration for the nrf54h20dk/nrf54h20/cpuapp board target and are not covered by this migration guide. The nRF Desktop application also configures the MCUboot bootloader to use the merged image slot that combines both application and radio core images. The merged image slot is the default configuration for the direct-xip mode. Other ways of partitioning the application and radio core images are not covered by this migration guide.

    3. Add the configuration files for the MCUboot bootloader image to your application configuration. See the nrf/applications/nrf_desktop/configuration/nrf54h20dk_nrf54h20_cpuapp/images/mcuboot directory for an example.

      Note the following Kconfig options that are specific to the nRF54H configuration of the MCUboot bootloader:

      • CONFIG_SOC_EARLY_RESET_HOOK to y - This option is required to support the Suspend to RAM (S2RAM) functionality in the application. With this Kconfig option, the MCUboot bootloader can detect a wake-up from S2RAM and redirect the execution to the application’s resume routine.

      • CONFIG_POWER_DOMAIN to n - This option is required to disable the power domain management in the bootloader and simplify its configuration.

      • CONFIG_NRF_SECURITY, CONFIG_MULTITHREADING and CONFIG_PSA_SSF_CRYPTO_CLIENT to y - These options are required to support the hardware cryptography in the MCUboot bootloader and its dependencies.

    4. Since the MCUboot bootloader in the direct-xip mode uses a merged image slot for the nrf54h20dk/nrf54h20/cpuapp board target, define the custom memory layout in DTS (the partitions DTS node) and ensure that this DTS customization is propagated to every image that is built as part of the nRF Desktop application. See the nrf/applications/nrf_desktop/configuration/nrf54h20dk_nrf54h20_cpuapp/memory_map.dtsi file for an example of the memory layout file and the nrf/applications/nrf_desktop/configuration/nrf54h20dk_nrf54h20_cpuapp/images/mcuboot/app.overlay file for an example integration of the custom memory layout into the MCUboot bootloader image. Apart from the MCUboot bootloader image, include the custom memory layout in the following images:

      • The nrf_desktop image (the default application image)

      • The ipc_radio image

      • The uicr image

      To verify that the custom memory layout is propagated to all the images, use the <build_dir>/<image_name>/zephyr/zephyr.dts file and validate it for each image.

      Note

      The nRF Connect SDK v3.2.0 introduces a new image uicr for the nrf54h20dk/nrf54h20/cpuapp board target. Include the custom memory layout in the uicr image as well to prevent runtime issues. See the nrf/applications/nrf_desktop/configuration/nrf54h20dk_nrf54h20_cpuapp/images/uicr/app.overlay file for an example integration of the custom memory layout into the uicr image.

      Assign the secondary image partition to the secondary_app_partition DTS label in the DTS configuration of your primary image:

      • For the nrf_desktop (primary) image and the mcuboot_secondary_app (secondary) image, use the following DTS configuration:

        secondary_app_partition: &cpuapp_slot1_partition {};

      • For the ipc_radio (primary) image and the ipc_radio_secondary_app (secondary) image, use the following DTS configuration:

        secondary_app_partition: &cpurad_slot1_partition {};

    5. Optionally, you can enable the following Kconfig options to improve the HID report rate over USB by suspending Bluetooth when USB is connected:

      • CONFIG_DESKTOP_BLE_ADV_CTRL_ENABLE

      • CONFIG_DESKTOP_BLE_ADV_CTRL_SUSPEND_ON_USB

    6. Remove the usage of the following Kconfig options related to the S2RAM functionality:

      Note

      The S2RAM functionality is now enabled by default for the nrf54h20dk/nrf54h20/cpuapp board target when the CONFIG_PM Kconfig option is enabled. The setting of the CONFIG_PM_S2RAM Kconfig option is now controlled by the devicetree (DTS) description.

    7. Remove the pwmleds DTS node from the application configuration to prevent the CONFIG_LED_PWM and CONFIG_CAF_LEDS_PWM Kconfig options from being enabled for the nrf54h20dk/nrf54h20/cpuapp board target.

      / {
  /delete-node/ pwmleds;

  aliases {
    /delete-property/ pwm-led0;
  };
};

      Note

      The nRF Desktop configuration for the nrf54h20dk/nrf54h20/cpuapp board target relies on GPIO LEDs - the PWM LEDs are not used.

    8. Disable Link Time Optimization (LTO) as a workaround for linker warnings about the type mismatch (-Wlto-type-mismatch) that are caused by the device_deps.c file (used by the Zephyr power domain driver):

    9. Replace the interface-name property with the label property in all DTS nodes that set the compatible property to zephyr,hid-device. See the nrf/applications/nrf_desktop/configuration/nrf54h20dk_nrf54h20_cpuapp/app.overlay file for an example.

    For more information regarding differences between SUIT and IronSide SE solutions, see the Migrating applications from nRF Connect SDK v3.0.0 (SUIT) to nRF Connect SDK v3.1.0 (IronSide SE) on the nRF54H20 SoC document.

Matter

  • For the Matter samples and applications:

    • All Matter over Wi-Fi samples and applications now store a portion of the application code related to the nRF70 Series Wi-Fi firmware in external flash memory by default.

      There are two consequences of this change:

      • The partition map has been changed. You cannot perform DFU between the previous nRF Connect SDK versions and v3.2.0 unless you disable storing of the Wi-Fi firmware patch in external memory.

      • The application code size is reduced, but the programming process may take longer when performing the full erase, because the entire external flash memory is erased before programming the Wi-Fi firmware patch.

      When using the west flash command, the default behavior is to erase the entire external memory before programming the Wi-Fi firmware patch. To reduce programming time, you can add the --ext-erase-mode=ranges option to erase only the necessary memory ranges:

      west flash --ext-erase-mode=ranges

      The longer programming time also occurs when using the Erase and Flash to Board option in the nRF Connect for VS Code. To speed up the process in the nRF Connect for VS Code, use the Flash button instead of Erase and Flash to Board in the Actions View.

      To disable storing the Wi-Fi firmware patch in external memory and revert to the previous approach, complete the following steps:

      1. Remove the Wi-Fi firmware patch partition from the partition list.

      2. Set the SB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE Kconfig option to n.

      3. Set the SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_WIFI_FW_PATCH Kconfig option to n.

      4. Set the SB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES Kconfig option to 2.

    • The Kconfig options CONFIG_CHIP_SPI_NOR and CONFIG_CHIP_QSPI_NOR have been removed. Instead, use the standard options CONFIG_SPI_NOR and CONFIG_NORDIC_QSPI_NOR. The configuration system will now automatically enable these options when the corresponding SPI or QSPI device is specified in the devicetree. This change ensures more consistent configuration by relying on the standard Kconfig options when external NOR flash devices are present.

  • All Matter over Wi-Fi samples and applications now enable the CONFIG_CHIP_WIFI and CONFIG_WIFI_NRF70 Kconfig options, depending on the board used. Previously, CONFIG_CHIP_WIFI was enabled in the Matter stack configuration if the nRF7002 DK or nRF7002 EK was used, which caused issues when building the application with custom boards.

    To build your custom board with Wi-Fi support, set both the CONFIG_CHIP_WIFI and CONFIG_WIFI_NRF70 Kconfig options to y.

  • The Matter build system is transitioning to a code-driven approach for Data Model and Cluster configuration handling. This approach assumes gradual replacement of the configuration based on the ZAP files and the ZAP-generated code, and handling the configuration in the source code. This change has the following impacts:

    • The zap-generated directory now includes the CodeDrivenCallback.h and CodeDrivenInitShutdown.cpp files. Invoking the west zap-generate command removes command handler implementations from the existing IMClusterCommandHandler.cpp file. To fix this, you must now manually create the CodeDrivenCallback.h and CodeDrivenInitShutdown.cpp files, and implement the MatterClusterServerInitCallback and MatterClusterServerShutdownCallback callbacks to handle server initialization, shutdown, and Matter cluster commands. Ensure that these callbacks contain your application’s command handling logic.

    • The code-driven approach is not yet fully implemented for all available clusters, but the coverage will be increasing and it is used for the newly created clusters. The following clusters are already ported using the code-driven approach:

      • Access Control

      • Administrator Commissioning

      • Basic Information

      • Binding

      • Boolean State

      • Descriptor

      • Diagnostic Logs

      • Ethernet Network Diagnostics

      • Fixed Label

      • General Commissioning

      • General Diagnostics

      • Group Key Management

      • Groupcast

      • Identify

      • Localization Configuration

      • OTA Software Update Provider

      • Operational Credentials

      • Push AV Stream Transport

      • Software Diagnostics

      • Time Format Localization

      • User Label

      • Wi-Fi Network Diagnostics

      For the full list of clusters and their migration status, see the Matter Clusters Code-Driven support file.

    • By default, all the mandatory attributes are enabled for the cluster. To enable an optional attribute or set an optional feature in the feature map, you must do that in the source code by calling dedicated methods. For example, to enable the Positioning feature and the CountdownTime optional attribute for the Closure Control cluster, perform the following operations:

      • Implement a delegate class for the Closure Control cluster. See the samples/matter/closure/src/closure_control_endpoint.h file for an example.

      • Enable the attribute and set the feature on cluster initialization. See the ClosureControlEndpoint::Init function in the samples/matter/closure/src/closure_control_endpoint.cpp file for an example.

    • To enable an optional cluster, you must register it in the source code by calling a dedicated method. For example, to enable the Identify cluster, implement the following code:

      #include <data-model-providers/codegen/CodegenDataModelProvider.h>
#include <app/clusters/identify-server/IdentifyCluster.h>

chip::app::RegisteredServerCluster<chip::app::Clusters::IdentifyCluster> mIdentifyCluster;
chip::app::CodegenDataModelProvider::Instance().Registry().Register(mIdentifyCluster.Registration());

    • To enable a cluster extension for the cluster that is already implemented using the code-driven approach, you must inherit from this cluster delegate class and implement the methods to handle the customized part. You also have to unregister the original cluster delegate and register the customized one. For example, to enable a cluster extension for the Basic Information cluster, perform the following operations:

      • Inherit from the BasicInformationCluster class and override the methods to handle the customized part. See the samples/matter/manufacturer_specific/src/basic_information_extension.h file for an example.

      • Implement the body of overridden methods to handle the custom attributes, commands, and events. See the samples/matter/manufacturer_specific/src/basic_information_extension.cpp file for an example.

      • Unregister the original cluster delegate and register the customized one. See the AppTask::StartApp function in the samples/matter/manufacturer_specific/src/app_task.cpp file for an example.

  • Matter: Door lock sample:

    static uint32_t AuthAppPasskey(struct bt_conn *conn)
{
    return 123456;
}

static struct bt_conn_auth_cb sConnAuthCallbacks = {
    .app_passkey = AuthAppPasskey,
};

Serial LTE modem

  • The Serial LTE modem application has been removed. Instead, use Serial Modem, an nRF Connect SDK add-on application.

Libraries

This section describes the changes related to libraries.

Trusted Firmware-M

  • Trusted Firmware-M changed how data is stored and read in the Protected Storage partition. As a consequence, the applications that build with TF-M (*/ns board targets) and want to perform a firmware upgrade to this nRF Connect SDK release will not be able to read the existing Protected Storage data with the default configuration. To enable reading the Protected Storage data from a previous release, make sure that the application enables the CONFIG_TFM_PS_SUPPORT_FORMAT_TRANSITION Kconfig option.