SDK upgrade guide
ESP-IDF 4.4 to ESP-IDF 5.1: what needs attention
Migratorisk's knowledge base lists 80 documented changes between ESP-IDF 4.4 and ESP-IDF 5.1 across 2 releases. 58 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 esp-idf-4.4.0 --to esp-idf-5.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 insteadWhere the changes are
What changes between ESP-IDF 4.4 and ESP-IDF 5.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.
driver: functions removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer declares these driver functions from 4.4: adc1_config_channel_atten, adc1_config_width, adc1_pad_get_io_num, adc1_ulp_enable, adc2_config_channel_atten, adc2_get_raw… Calls fail to compile or link. Covers 131 names.
driver: types removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer defines these driver types from 4.4: adc1_channel_t, adc2_channel_t, adc_digi_configuration_t, adc_digi_init_config_t, adc_i2s_encode_t, can_general_config_t… Code using them fails with unknown type errors. Covers 52 names.
esp_serial_slave_link: functions removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer declares these esp_serial_slave_link functions from 4.4: essl_clear_intr, essl_get_intr, essl_get_intr_ena, essl_get_packet, essl_get_rx_data_size, essl_get_tx_buffer_num… Calls fail to compile or link. Covers 49 names.
Public headers removed in ESP-IDF 5.0
These headers existed in ESP-IDF 4.4 and are gone in 5.0: driver/adc_common.h, driver/adc_deprecated.h, driver/adc_types_deprecated.h, driver/can.h, driver/periph_ctrl.h, driver/rtc_cntl.h, driver/spi_common_internal.h, esp_additions/freertos/FreeRTOSConfig.h… Code that includes them stops compiling. Covers 47 names.
Peripherals: Legacy RMT Driver is Deprecated: Breaking Changes in Usage
Peripherals: Legacy RMT Driver is Deprecated: Breaking Changes in Usage Covers 40 names.
tcpip_adapter: functions removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer declares these tcpip_adapter functions from 4.4: tcpip_adapter_ap_input, tcpip_adapter_ap_start, tcpip_adapter_clear_default_eth_handlers, tcpip_adapter_clear_default_wifi_handlers, tcpip_adapter_compat_start_eth, tcpip_adapter_create_ip6_linklocal… Calls fail to compile or link. Covers 39 names.
mdns: functions removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer declares these mdns functions from 4.4: mdns_console_register, mdns_delegate_hostname_add, mdns_delegate_hostname_remove, mdns_free, mdns_handle_system_event, mdns_hostname_exists… Calls fail to compile or link. Covers 38 names.
openssl: functions removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer declares these openssl functions from 4.4: pkey_pm_free, pkey_pm_load, pkey_pm_new, ssl_cert_free, ssl_cert_new, ssl_mem_zalloc… Calls fail to compile or link. Covers 25 names.
Peripherals: Legacy MCPWM Driver is Deprecated: Breaking Changes in Usage
Peripherals: Legacy MCPWM Driver is Deprecated: Breaking Changes in Usage Covers 24 names.
Peripherals: Legacy PCNT Driver is Deprecated: Breaking Changes in Usage
Peripherals: Legacy PCNT Driver is Deprecated: Breaking Changes in Usage Covers 23 names.
Peripherals: ADC: API Changes
Peripherals: ADC: API Changes Covers 21 names.
esp_event: types removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer defines these esp_event types from 4.4: system_event_ap_probe_req_rx_t, system_event_ap_staconnected_t, system_event_ap_stadisconnected_t, system_event_ap_staipassigned_t, system_event_ftm_report_t, system_event_got_ip6_t… Code using them fails with unknown type errors. Covers 17 names.
esp_websocket_client: functions removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer declares these esp_websocket_client functions from 4.4: esp_websocket_client_close, esp_websocket_client_close_with_code, esp_websocket_client_destroy, esp_websocket_client_init, esp_websocket_client_is_connected, esp_websocket_client_send… Calls fail to compile or link. Covers 12 names.
Peripherals: DAC: Breaking Changes in Usage
Peripherals: DAC: Breaking Changes in Usage Covers 11 names.
Bluetooth Low Energy: Bluedroid
The following Bluedroid macros, types, and functions have been renamed: Covers 10 names.
tcpip_adapter: types removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer defines these tcpip_adapter types from 4.4: tcpip_adapter_dhcp_option_id_t, tcpip_adapter_dhcp_option_mode_t, tcpip_adapter_dhcp_status_t, tcpip_adapter_dhcps_lease_t, tcpip_adapter_dns_info_t, tcpip_adapter_dns_type_t… Code using them fails with unknown type errors. Covers 10 names.
Storage: Removed SDSPI Deprecated API: Legacy SPI Flash Driver
To make SPI flash drivers more stable, the legacy SPI flash driver is removed from v5.0. The legacy SPI flash driver refers to default spi_flash driver since v3.0, and the SPI flash driver with configuration option CONFIG_SPI_FLASH_USE_LEGACY_IMPL enabled since v4.0. The major breaking change here is that the legacy spi_flash driver is no longer supported from v5.0. Covers 8 names.
System: esp_hw_support
System: esp_hw_support Covers 7 names.
esp_event: functions removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer declares these esp_event functions from 4.4: esp_event_loop_init, esp_event_loop_set_cb, esp_event_process_default, esp_event_send, esp_event_send_internal, esp_event_set_default_eth_handlers… Calls fail to compile or link. Covers 7 names.
mdns: types removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer defines these mdns types from 4.4: mdns_if_t, mdns_ip_addr_t, mdns_ip_protocol_t, mdns_result_t, mdns_search_once_t, mdns_txt_item_t. Code using them fails with unknown type errors. Covers 6 names.
esp_netif: functions removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer declares these esp_netif functions from 4.4: esp_netif_get_sta_list, esp_netif_lwip_slip_raw_output, esp_netif_slip_set_ipv6, esp_netif_slip_set_params, esp_slip_get_ip6. Calls fail to compile or link. Covers 5 names.
esp_websocket_client: types removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer defines these esp_websocket_client types from 4.4: esp_websocket_client_config_t, esp_websocket_client_handle_t, esp_websocket_event_data_t, esp_websocket_event_id_t, esp_websocket_transport_t. Code using them fails with unknown type errors. Covers 5 names.
Peripherals: LCD
Peripherals: LCD Covers 4 names.
Peripherals: UART
Peripherals: UART Covers 4 names.
System: ESP Image
The image SPI speed enum definitions have been renamed. Covers 4 names.
Networking: Ethernet: KSZ8041/81 and LAN8720 Driver Update
The KSZ8041/81 and LAN8720 drivers are updated to support more devices (i.e., generations) from their associated product families. The drivers can recognize particular chip numbers and their potential support by the driver. Covers 3 names.
Protocols: Breaking Changes (Summary): Function Deprecations And Recommended Alternatives
Following table summarizes the deprecated functions removed and their alternatives to be used from ESP-IDF v5.0 onwards. Covers 3 names.
System: FreeRTOS: Port Macro API
The file portmacro_deprecated.h which was added to maintain backward compatibility for deprecated APIs is removed. Users are advised to use the alternate functions for the deprecated APIs as listed below: Covers 3 names.
System: esp_hw_support: PSRAM
System: esp_hw_support: PSRAM Covers 3 names.
esp_netif: types removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer defines these esp_netif types from 4.4: esp_netif_slip_config_t, esp_netif_sta_info_t, esp_netif_sta_list_t. Code using them fails with unknown type errors. Covers 3 names.
esp_serial_slave_link: types removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer defines these esp_serial_slave_link types from 4.4: essl_handle_t, essl_sdio_config_t, essl_spi_config_t. Code using them fails with unknown type errors. Covers 3 names.
Bluetooth Classic: Bluedroid
Along with this change, the `bt_bdaddr_t init` and `bt_bdaddr_t deinit` has been removed from `union btc_arg_t`. Covers 2 names.
Bluetooth Low Energy: ESP-BLE-MESH
The following ESP-BLE-MESH macro has been renamed: Covers 2 names.
Networking: Ethernet: ESP NETIF Glue Event Handlers
esp_eth_set_default_handlers() and esp_eth_clear_default_handlers() functions are removed. Registration of the default IP layer handlers for Ethernet is now handled automatically. If you have already followed the suggestion to fully initialize the Ethernet driver and network interface before registering their Ethernet/IP event handlers, then no action is required (except for deleting the affected functions). Covers 2 names.
Peripherals: I2C
Peripherals: I2C Covers 2 names.
Peripherals: SPI
Peripherals: SPI Covers 2 names.
Protocols: HTTP Server: Breaking Changes (Summary)
Protocols: HTTP Server: Breaking Changes (Summary) Covers 2 names.
Removed or Deprecated Components: Deprecated Components
The following components are removed since they were deprecated in ESP-IDF v4.x: tcpip_adapter. Please use the ESP-NETIF component instead; you can follow the tcpip-adapter. OpenSSL-API component is no longer supported. Covers 2 names.
Storage: Removed SDSPI Deprecated API
Structure sdspi_slot_config_t and function sdspi_host_init_slot() are removed, and replaced by structure sdspi_device_config_t and function sdspi_host_init_device() respectively. Covers 2 names.
Storage: Removed SDSPI Deprecated API: ROM SPI Flash
In versions before v5.0, ROM SPI flash functions were included via esp32**/rom/spi_flash.h. Thus, code written to support different ESP chips might be filled with ROM headers of different targets. Furthermore, not all of the APIs could be used on all ESP chips. Covers 2 names.
System: bootloader_support
* The function bootloader_common_get_reset_reason() has been removed. Please use the function esp_rom_get_reset_reason() in the ROM component. The functions esp_secure_boot_verify_sbv2_signature_block() and esp_secure_boot_verify_rsa_signature_block() have been removed without replacement. We do not expect users to use these directly. Covers 2 names.
Networking: Ethernet: PHY Address Auto-detect
The Ethernet PHY address auto-detect function esp_eth_detect_phy_addr() is renamed to esp_eth_phy_802_3_detect_phy_addr and its header declaration is moved to esp_eth/include/esp_eth_phy_802_3.h.
Networking: Updating Network Connection Code: Other tcpip_adapter API Replacement
All the tcpip_adapter functions have their esp-netif counter-part.
Peripherals: Dedicated GPIO Driver
Peripherals: Dedicated GPIO Driver
Peripherals: GPIO
Peripherals: GPIO
Peripherals: SDMMC
Peripherals: SDMMC
Protocols: Miscellaneous: Remove certs Module from X509 Library
Protocols: Miscellaneous: Remove certs Module from X509 Library
Storage: spi_flash_get_chip_size() removed
spi_flash_get_chip_size() no longer exists from ESP-IDF 5.0; code calling it fails with an implicit declaration error. The migration guide does not list it; confirmed by building with ESP-IDF 5.1.6.
System: FreeRTOS: FreeRTOS Asserts
Previously, FreeRTOS asserts were configured separately from the rest of the system using the FREERTOS_ASSERT kconfig option. This option has now been removed and the configuration is now done through COMPILER_OPTIMIZATION_ASSERTION_LEVEL.
System: FreeRTOS: Tasks Snapshot
The header task_snapshot.h has been removed from freertos/task.h. ESP-IDF developers should include freertos/task_snapshot.h if they need tasks snapshot API. The function vTaskGetSnapshot now returns BaseType_t.
System: SoC Dependency
System: SoC Dependency
System: eFuse
System: eFuse
esp_eth: functions removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer declares these esp_eth functions from 4.4: esp_eth_receive. Calls fail to compile or link.
esp_wifi: functions removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer declares these esp_wifi functions from 4.4: esp_wifi_set_connectionless_wake_interval. Calls fail to compile or link.
freertos: functions removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer declares these freertos functions from 4.4: xt_clock_freq. Calls fail to compile or link.
spi_flash: functions removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer declares these spi_flash functions from 4.4: spi_flash_init. Calls fail to compile or link.
usb: functions removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer declares these usb functions from 4.4: usb_print_descriptors. Calls fail to compile or link.
wifi_provisioning: functions removed in ESP-IDF 5.0
ESP-IDF 5.0 no longer declares these wifi_provisioning functions from 4.4: wifi_prov_mgr_event_handler. Calls fail to compile or link.
Kconfig options removed in ESP-IDF 5.0
These options exist in 4.4 and are gone in 5.0 without a rename: CONFIG_ADC_FORCE_XPD_FSM, CONFIG_APPTRACE_SV_TS_SOURCE_TIMER_00, CONFIG_APPTRACE_SV_TS_SOURCE_TIMER_01, CONFIG_APPTRACE_SV_TS_SOURCE_TIMER_10, CONFIG_APPTRACE_SV_TS_SOURCE_TIMER_11, CONFIG_ASIO_SSL_SUPPORT… ESP-IDF ignores them with a warning, so the behaviour they enabled is silently lost. Covers 175 names.
Peripherals: Legacy RMT Driver is Deprecated: Breaking Changes in Concepts
Peripherals: Legacy RMT Driver is Deprecated: Breaking Changes in Concepts Covers 13 names.
And 20 more changes, all checked by the scan.
What a scan of this path also reviews
Beyond the documented changes, Migratorisk reviews these upgrade risks for ESP-IDF projects on this path. Each one is reported only when the project shows the trigger.
The GNU Make build system was removed in ESP-IDF 5.0
When it applies: The project builds only with ESP-IDF's legacy GNU Make system (Makefile and component.mk), and the selected path crosses ESP-IDF 5.0.
Why it matters: ESP-IDF 5.0 removed GNU Make support. Nothing builds until every component is converted to CMake (CMakeLists.txt with idf_component_register).
What to do: Convert the project and each component.mk to CMakeLists.txt (idf_component_register with SRCS, INCLUDE_DIRS and REQUIRES) on the current ESP-IDF first, check it builds identically, then upgrade.
Devices in the field keep their old bootloader after an OTA update
When it applies: The project updates over the air, which replaces the application but not the second-stage bootloader.
Why it matters: Major releases change bootloader and image-format defaults; the new application must still boot from the bootloader already on each device, or the update bricks it.
What to do: Test the new application booting from the bootloader built with the current production ESP-IDF, including rollback if CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE is used. Check the bootloader compatibility notes for the target release.
Components without CMakeLists.txt are ignored by the CMake build
When it applies: Some components have only a GNU Make component.mk and no CMakeLists.txt.
Why it matters: The CMake build (idf.py, the only build system from ESP-IDF 5.0) silently skips them, so their sources are not compiled. This usually surfaces later as missing headers or undefined references.
What to do: Add a CMakeLists.txt with idf_component_register to each listed component, carrying over COMPONENT_SRCDIRS, COMPONENT_ADD_INCLUDEDIRS and any extra flags from component.mk.
Managed components must support the target ESP-IDF
When it applies: The project depends on components from the ESP Component Registry (idf_component.yml).
Why it matters: Each component declares the ESP-IDF versions it supports. Old pinned versions may not build with the new release, and newer versions can change their own APIs.
What to do: Check each dependency's supported ESP-IDF range, update version constraints, then regenerate dependencies.lock and review the changes.
Arduino core is used as an ESP-IDF component
When it applies: The project builds the Arduino core (arduino-esp32) as an ESP-IDF component.
Why it matters: Each Arduino core release supports only a specific ESP-IDF version. Upgrading ESP-IDF without a matching Arduino core release fails to build.
What to do: Pick the arduino-esp32 release that matches the target ESP-IDF version first, then upgrade both together.
Updated firmware must still fit the OTA slots of devices in the field
When it applies: The project ships firmware updates over the air into fixed OTA slots defined by its partition table.
Why it matters: Major releases remove legacy drivers and change system libraries, often growing the application noticeably; the partition table on deployed devices cannot follow.
What to do: Keep the partition table byte-for-byte identical for devices already deployed, and check the new application size against the smallest OTA slot after the first build.
Small application partition leaves little room for a larger ESP-IDF
When it applies: The smallest application partition is under 1.5 MB.
Why it matters: Newer ESP-IDF releases and toolchains often grow the application binary (Wi-Fi, Bluetooth, TLS and libc changes). If it no longer fits, the build fails or OTA updates are rejected, and the partition table cannot be changed on deployed devices without a risky migration.
What to do: Build with the target ESP-IDF early and compare the binary size with the partition. Plan size optimisations (CONFIG_COMPILER_OPTIMIZATION_SIZE, unused features off) before committing to the upgrade.
The application already nearly fills its partition
When it applies: The current build leaves less than 15% free space in the smallest application partition.
Why it matters: Any growth from the upgrade can make the image too large for the partition, which fails the build or the OTA update.
What to do: Measure the size with the target ESP-IDF first; reduce size or plan a partition-table migration before the upgrade.
A major ESP-IDF upgrade removes legacy drivers and APIs
When it applies: The selected path crosses a major ESP-IDF release.
Why it matters: Major releases remove APIs that were deprecated in the previous major line (legacy drivers, old headers and Kconfig options), change component dependencies and update FreeRTOS, networking and Bluetooth stacks. Code changes and full re-testing are expected.
What to do: Work through the migration guide of every major and minor release in the path, starting with build errors, then deprecation warnings, then behaviour changes on hardware.
Secure Boot or flash encryption is enabled
When it applies: The project enables Secure Boot, signed applications or flash encryption.
Why it matters: These settings are tied to eFuses already burned on deployed devices. A changed signing scheme, key or encryption mode makes updates fail or bricks devices, and mistakes cannot be undone on hardware.
What to do: Keep signing keys, scheme and flash-encryption mode identical to production. Test the full update path on a device with production eFuses before release.
The project keeps a full sdkconfig
When it applies: The project folder contains a complete sdkconfig (kept in version control or generated by earlier builds).
Why it matters: On the first build with a new ESP-IDF, renamed options are migrated automatically, but removed options are dropped and new options get defaults, quietly changing behaviour. The diff is easy to miss in a large file.
What to do: After the first build with the target version, review the sdkconfig diff line by line. Keep intentional settings in sdkconfig.defaults so they survive future upgrades.
New compiler version and warnings
When it applies: Major ESP-IDF releases move to a newer GCC and C library and tighten warnings.
Why it matters: New GCC versions add warnings and stricter checks. Code that built cleanly can fail where warnings are treated as errors, and undefined behaviour can surface at run time.
What to do: Build all targets and configurations with the target ESP-IDF, fix new warnings rather than silencing them, and rerun device tests.
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
- ESP-IDF 4.4 to ESP-IDF 5.0
- ESP-IDF 3.3 to ESP-IDF 4.4
- ESP-IDF 5.1 to ESP-IDF 5.5
- ESP-IDF 5.0 to ESP-IDF 5.1
- ESP-IDF 5.1 to ESP-IDF 6.0
- ESP-IDF 4.4 to ESP-IDF 5.5
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.