Book a Technical Call
Book a Technical Call

Home › SDK migration

SDK upgrade guide

nRF Connect SDK 3.0 to nRF Connect SDK 3.1: what needs attention

Migratorisk's knowledge base lists 30 documented changes between nRF Connect SDK 3.0 and nRF Connect SDK 3.1 across 2 releases. 27 of them are rated likely to break code, configuration or builds that use them. Below is each change, what a scan also reviews on this path, and how to see which ones apply to your project.

30documented changes
27rated will or likely to break
8review checks on this path

Find which of these affect your firmware

Migratorisk scans your project on your own computer and reports only the changes your code, configuration and build actually touch. Your source code is not uploaded.

python -m pip install migratorisk
migratorisk scan --project ./your-firmware --from ncs-3.0.0 --to ncs-3.1.0 --out report.html

Requires Python 3.12 or newer. Results are free and complete without sign-up; sharing a report with us is optional.

Set up the local scanOr answer a few questions instead

Where the changes are

Hardware description · 17Build settings · 7Application code · 5Security and keys · 1

What changes between nRF Connect SDK 3.0 and nRF Connect SDK 3.1

Ordered by impact. Each item names the release that introduced it and links to the official source. A change only matters if your project uses what changed; the scan checks that.

Likely to break

Kconfig options CONFIG_DISABLE_SSBD and 1 more were removed

Build settings · Zephyr 4.1.0 · Source

Kconfigs CONFIG_DISABLE_SSBD and CONFIG_ENABLE_EXTENDED_IBRS have been deprecated since v3.7. These were removed. Use CONFIG_X86_DISABLE_SSBD and CONFIG_X86_ENABLE_EXTENDED_IBRS instead. Covers 2 names.

Likely to break

Kconfig options SB_CONFIG_MCUBOOT_MODE_SWAP_WITHOUT_SCRATCH and 1 more were replaced

Build settings · Zephyr 4.1.0 · Source

The Kconfig SB_CONFIG_MCUBOOT_MODE_SWAP_WITHOUT_SCRATCH has been deprecated and replaced with SB_CONFIG_MCUBOOT_MODE_SWAP_USING_MOVE, applications should be updated to select this new symbol if they were selecting the old symbol. Covers 2 names.

Likely to break

API MGMT_CB_ERROR_RET was removed

Application code · Zephyr 4.1.0 · Source

The deprecated macro MGMT_CB_ERROR_RET has been removed.

Likely to break

API stepper_enable_constant_velocity_mode was renamed

Application code · Zephyr 4.1.0 · Source

Renamed the stepper_enable_constant_velocity_mode function to stepper_run. The function does not take a velocity parameter anymore. Set the desired speed using the stepper_set_microstep_interval function beforehand.

Likely to break

API stepper_set_actual_position was renamed

Application code · Zephyr 4.1.0 · Source

Renamed the stepper_set_actual_position function to stepper_set_reference_position.

Likely to break

API stepper_set_max_velocity was renamed

Application code · Zephyr 4.1.0 · Source

Renamed the stepper_set_max_velocity function to stepper_set_microstep_interval. The function now takes the step interval in nanoseconds. This allows for a more precise control.

Likely to break

API stepper_set_target_position was renamed

Application code · Zephyr 4.1.0 · Source

Renamed the stepper_set_target_position function to stepper_move_to.

Likely to break

CONFIG_BT_CTLR deprecated in favour of HAS_BT_CTLR

Build settings · Zephyr 4.1.0 · Source

Zephyr 4.1 deprecates CONFIG_BT_CTLR; the link layer is now chosen by HCI driver options that select HAS_BT_CTLR. Setting CONFIG_BT_CTLR in prj.conf or a sysbuild image config fails on later releases.

Likely to break

Devicetree compatible nxp,imx-lpi2c was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from nxp,imx-lpi2c to nxp,lpi2c.

Likely to break

Devicetree compatible nxp,imx-lpspi was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from nxp,imx-lpspi to nxp,lpspi.

Likely to break

Devicetree compatible nxp,kinetis-adc12 was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from nxp,kinetis-adc12 to nxp,adc12.

Likely to break

Devicetree compatible nxp,kinetis-dspi was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from nxp,kinetis-dspi to nxp,dspi.

Likely to break

Devicetree compatible nxp,kinetis-ftm was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from nxp,kinetis-ftm to nxp,ftm and relocate it under dts/bindings/timer.

Likely to break

Devicetree compatible nxp,kinetis-ftm-pwm was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from nxp,kinetis-ftm-pwm to nxp,ftm-pwm.

Likely to break

Devicetree compatible nxp,kinetis-lpuart was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from nxp,kinetis-lpuart to nxp,lpuart.

Likely to break

Devicetree compatible nxp,kinetis-mpu was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from nxp,kinetis-mpu to nxp,sysmpu and added its corresponding binding.

Likely to break

Devicetree compatible nxp,kinetis-pinctrl was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from nxp,kinetis-pinctrl to nxp,port-pinctrl.

Likely to break

Devicetree compatible nxp,kinetis-pinmux was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from nxp,kinetis-pinmux to nxp,port-pinmux.

Likely to break

Devicetree compatible nxp,kinetis-rtc was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from nxp,kinetis-rtc to nxp,rtc.

Likely to break

Devicetree compatible nxp,kinetis-wdog32 was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from nxp,kinetis-wdog32 to nxp,wdog32.

Likely to break

Devicetree compatible renesas,ra8-pwm was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from renesas,ra8-pwm to renesas,ra-pwm.

Likely to break

Devicetree compatible silabs,gecko-spi-eusart was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from silabs,gecko-spi-eusart to silabs,eusart-spi.

Likely to break

Devicetree compatible silabs,gecko-spi-usart was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from silabs,gecko-spi-usart to silabs,usart-spi.

Likely to break

Devicetree compatible ti,ads114s0x-gpio was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from ti,ads114s0x-gpio to ti,ads1x4s0x-gpio.

Likely to break

Devicetree compatible zephyr,gpio-steppers was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from zephyr,gpio-steppers to zephyr,gpio-stepper.

Likely to break

Kconfig option CONFIG_MAX_FILES was renamed

Build settings · Zephyr 4.1.0 · Source

The EXT2 Kconfig symbol CONFIG_MAX_FILES has been renamed to CONFIG_EXT2_MAX_FILES.

Likely to break

Kconfig option CONFIG_SOC_SERIES_RP2XXX was renamed

Build settings · Zephyr 4.1.0 · Source

CONFIG_SOC_SERIES_RP2XXX is renamed to CONFIG_SOC_SERIES_RP2040.

Needs attention

CRACEN asymmetric encryption driver setting was renamed

Security and keys · nRF Connect SDK 3.1.0 · Source

NCS 3.1 replaces CONFIG_PSA_USE_CRACEN_ASYMMETRIC_DRIVER with a setting specific to asymmetric encryption.

Needs attention

nRF Desktop HID keymap setting was renamed

Build settings · nRF Connect SDK 3.1.0 · Source

NCS 3.1 replaces the HID state keymap path setting with the HID keymap module setting. The keymap file format stays the same.

Worth checking

Kconfig option CONFIG_NET_TC_SKIP_FOR_HIGH_PRIO is deprecated

Build settings · Zephyr 4.1.0 · Source

CONFIG_NET_TC_SKIP_FOR_HIGH_PRIO was deprecated in favour of CONFIG_NET_TC_TX_SKIP_FOR_HIGH_PRIO to avoid naming ambiguity.

What a scan of this path also reviews

Beyond the documented changes, Migratorisk reviews these upgrade risks for nRF Connect SDK projects on this path. Each one is reported only when the project shows the trigger.

Devicetree binding error found in NCS 3.1 migration build log

When it applies: Build log reports a devicetree binding error.

Why it matters: Board and overlay assumptions should be resolved before source-level cleanup.

What to do: Fix devicetree binding errors and verify custom board metadata.

Undefined Kconfig symbol found in NCS 3.1 migration build log

When it applies: Build log reports an undefined Kconfig symbol.

Why it matters: NCS 3.1 can expose Kconfig dependency changes in BLE, MCUboot, mcumgr, board, or SoC symbols.

What to do: Resolve undefined Kconfig symbols before chasing later cascading build errors.

Custom board needs NCS 3.1 hardware model review

When it applies: Project contains custom board files.

Why it matters: Custom boards should be checked against the target NCS hardware model and devicetree guidance before debugging source-level issues.

What to do: Review board directory layout, revision overlays, compatibles, chosen nodes, and pinctrl assumptions.

Static partition layout needs NCS 3.1 review

When it applies: pm_static.yml exists while targeting NCS 3.1.

Why it matters: Static layouts can hide image-size, MCUboot, settings-storage, or external-flash migration problems.

What to do: Compare generated partition output, slot sizes, and storage ownership after the upgraded build.

Sysbuild and multi-image configuration needs NCS 3.1 review

When it applies: Project has legacy child image configuration while targeting NCS 3.1.

Why it matters: NCS 3.0 to 3.1 migrations should keep sysbuild, MCUboot, and network-core ownership explicit before source cleanup.

What to do: Review child image settings and migrate only confirmed bootloader or image ownership into sysbuild-aware configuration.

West manifest references old SDK revision

When it applies: west.yml references an old NCS or Zephyr revision.

Why it matters: A stale manifest can prevent a meaningful NCS 3.1 migration build.

What to do: Update manifest revisions intentionally before debugging project-local failures.

Source API review pattern found

When it applies: Source uses APIs that deserve review during a NCS 3.1 migration.

Why it matters: This evidence is review-only unless paired with a concrete upgraded build failure.

What to do: Review source API usage after build system, Kconfig, devicetree, and partition issues are addressed.

First build-log migration error found

When it applies: Build log contains a first high-signal error for migration triage.

Why it matters: Early build errors often cause later cascading noise.

What to do: Fix this first error before treating later build-log lines as independent migration work.

VelocityCreate

Want us to handle the upgrade?

VelocityCreate can review your assessment, agree on the migration scope, and carry out the firmware changes and agreed verification. Discuss your deadline, hardware, and requirements with an embedded engineer.

Discuss my migrationBook a technical call

The initial discussion is free. Implementation is quoted separately.

Related upgrade paths

Generated from the rule catalog of Migratorisk 0.3.0. This is an automated summary of published SDK changes, not a review of your project, and it does not replace builds and device tests. How the scanner is validated.

Menu