SDK upgrade guide
Zephyr 3.7 to Zephyr 4.0: what needs attention
Migratorisk's knowledge base lists 13 documented changes between Zephyr 3.7 and Zephyr 4.0. 11 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.
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 zephyr-3.7.0 --to zephyr-4.0.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 insteadWhere the changes are
What changes between Zephyr 3.7 and Zephyr 4.0
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.
Devicetree compatibles microchip,mcp230xx and 1 more were removed
The devicetree bindings for the Microchip mcp23xxx series have been split up. Users of microchip,mcp230xx and microchip,mcp23sxx should change their devicetree compatible values to the specific chip variant, e.g. microchip,mcp23017. The ngpios devicetree property has been removed, since it is implied by the model name. Covers 2 names.
Kconfig options CONFIG_MBEDTLS_TLS_VERSION_1_0 and 1 more were removed
The Kconfig options CONFIG_MBEDTLS_TLS_VERSION_1_0 and CONFIG_MBEDTLS_TLS_VERSION_1_1 have been removed because Mbed TLS doesn't support TLS 1.0 and 1.1 anymore since v3.0. Covers 2 names.
API BT_AUDIO_BROADCAST_CODE_SIZE was removed
BT_AUDIO_BROADCAST_CODE_SIZE has been removed and BT_ISO_BROADCAST_CODE_SIZE should be used instead.
API NET_SOCKET_SERVICE_SYNC_DEFINE_STATIC was removed
The work_q parameter to NET_SOCKET_SERVICE_SYNC_DEFINE and NET_SOCKET_SERVICE_SYNC_DEFINE_STATIC has been removed as it was always ignored.
Devicetree compatible litex,eth0 was renamed
The compatible of the LiteX ethernet controller has been renamed from litex,eth0 to litex,liteeth.
Devicetree compatible litex,uart0 was renamed
The compatible of the LiteX uart controller has been renamed from litex,uart0 to litex,uart.
Devicetree compatible microchip,mcp9808 was renamed
The existing driver for the Microchip MCP9808 temperature sensor transformed and renamed to support all JEDEC JC 42.4 compatible temperature sensors. It now uses the jedec,jc-42.4-temp compatible string instead to the microchip,mcp9808 string.
Kconfig option CONFIG_MBEDTLS_SSL_EXPORT_KEYS was removed
The Kconfig option CONFIG_MBEDTLS_SSL_EXPORT_KEYS was removed because the corresponding build symbol was removed in Mbed TLS 3.1.0 and is now assumed to be enabled.
Kconfig option CONFIG_MCUBOOT_CMAKE_WEST_SIGN_PARAMS was removed
Removed the CONFIG_MCUBOOT_CMAKE_WEST_SIGN_PARAMS Kconfig option as west sign is no longer called by the build system when signing images for MCUboot.
Kconfig option CONFIG_SPI_NOR_IDLE_IN_DPD was removed
CONFIG_SPI_NOR_IDLE_IN_DPD has been removed from the CONFIG_SPI_NOR driver. An enhanced version of this functionality can be obtained by enabling pm-device-runtime on the device (Tunable with CONFIG_SPI_NOR_ACTIVE_DWELL_MS).
Kconfig option CONFIG_UART_LITEUART was renamed
LiteX: CONFIG_UART_LITEUART has been renamed to CONFIG_UART_LITEX.
Bluetooth automatic advertiser resumption macros deprecated
Zephyr 4.0 deprecates BT_LE_ADV_OPT_CONNECTABLE, BT_LE_ADV_OPT_ONE_TIME and BT_LE_ADV_CONN (automatic advertiser resumption); later releases drop the related shorthand macros. Covers 4 names.
Kconfig option CONFIG_NET_SOCKETS_POLL_MAX is deprecated
Deprecated the CONFIG_NET_SOCKETS_POLL_MAX option in favour of CONFIG_ZVFS_POLL_MAX.
What a scan of this path also reviews
Beyond the documented changes, Migratorisk reviews these upgrade risks for Zephyr projects on this path. Each one is reported only when the project shows the trigger.
Devicetree binding error found in Zephyr migration build log
When it applies: Build log reports a devicetree binding error.
Why it matters: Devicetree bindings and board model assumptions can change across Zephyr major versions.
What to do: Fix devicetree binding errors before treating source API findings as migration failures.
Undefined Kconfig symbol found in Zephyr migration build log
When it applies: Build log reports an undefined Kconfig symbol.
Why it matters: Zephyr major-version upgrades can remove, rename, or change dependencies for Kconfig symbols.
What to do: Resolve undefined Kconfig symbols before chasing later source or linker errors.
Custom board needs Zephyr 4.x devicetree and Kconfig review
When it applies: The project contains a custom board definition.
Why it matters: Board files track SoC devicetree, pinctrl, Kconfig and hardware model changes between releases.
What to do: Compare the custom board with a similar in-tree board in the target release (board.yml, chosen nodes, pinctrl, partitions, SoC Kconfig).
Hardcoded Zephyr path found
When it applies: CMake contains a hardcoded Zephyr or SDK path.
Why it matters: Hardcoded workspace paths often break when moving to a new Zephyr major-version workspace.
What to do: Replace hardcoded paths with west/CMake discovery mechanisms.
Verify OTA from the current field firmware
When it applies: The project uses MCUboot, so devices in the field keep their current bootloader after the upgrade.
Why it matters: The upgraded image must still be accepted by the existing bootloader (signature type, key, slot layout and image header).
What to do: Keep the signing key, signature type and slot layout unchanged, and test an OTA update from the current production image on hardware.
Missing header found in Zephyr migration build log
When it applies: Build log reports a missing header.
Why it matters: Missing headers can indicate moved APIs, missing modules, or include path changes after a major-version upgrade.
What to do: Identify whether the header moved, the module is missing, or the API was removed.
Undefined reference found in Zephyr migration build log
When it applies: Build log reports an undefined reference.
Why it matters: Link failures can be caused by missing modules, changed Kconfig dependencies, or removed APIs.
What to do: Resolve earlier Kconfig and devicetree errors first, then review the missing symbol owner.
West manifest references old Zephyr revision
When it applies: west.yml references an old Zephyr or NCS revision.
Why it matters: Manifest revisions control module versions and can block a clean major-version migration.
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 Zephyr 4.x migration.
Why it matters: This evidence is review-only unless the upgraded build log confirms a concrete missing symbol or header.
What to do: Review source API usage after west, Kconfig, and devicetree issues are addressed.
First Zephyr 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 callThe 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.