Home › SDK migration

SDK upgrade guide

ESP-IDF 3.3 to ESP-IDF 4.4: what needs attention

Migratorisk's knowledge base lists 53 documented changes between ESP-IDF 3.3 and ESP-IDF 4.4 across 5 releases. 28 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.

53documented changes
28rated will or likely to break
803SDK names, settings and components covered
13review 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 esp-idf-3.3.0 --to esp-idf-4.4.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

Application code · 33Peripheral drivers · 10Build settings · 10

What changes between ESP-IDF 3.3 and ESP-IDF 4.4

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

ethernet: functions removed in ESP-IDF 4.0

Application code · ESP-IDF 4.0.0 · Source

ESP-IDF 4.0 no longer declares these ethernet functions from 3.3: esp_eth_deinit, esp_eth_disable, esp_eth_enable, esp_eth_free_rx_buf, esp_eth_get_mac, esp_eth_get_speed… Calls fail to compile or link. Covers 36 names.

Likely to break

esp32: functions removed in ESP-IDF 4.0

Application code · ESP-IDF 4.0.0 · Source

ESP-IDF 4.0 no longer declares these esp32 functions from 3.3: esp_aes_decrypt, esp_aes_encrypt, esp_deep_sleep_enable_ext0_wakeup, esp_deep_sleep_enable_ext1_wakeup, esp_deep_sleep_enable_touchpad_wakeup, esp_deep_sleep_get_touchpad_wakeup_status… Calls fail to compile or link. Covers 22 names.

Likely to break

Public headers removed in ESP-IDF 4.0

Application code · ESP-IDF 4.0.0 · Source

These headers existed in ESP-IDF 3.3 and are gone in 4.0: esp_brownout.h, esp_cache_err_int.h, esp_crosscore_int.h, esp_dbg_stubs.h, esp_deep_sleep.h, esp_deepsleep.h, esp_dport_access.h, esp_wifi_internal.h… Code that includes them stops compiling. Covers 16 names.

Likely to break

esp_wifi: functions removed in ESP-IDF 4.3

Application code · ESP-IDF 4.3.0 · Source

ESP-IDF 4.3 no longer declares these esp_wifi functions from 4.2: coex_bb_reset_lock, coex_bb_reset_unlock, coex_bt_release, coex_bt_request, coex_pause, coex_register_bt_cb… Calls fail to compile or link. Covers 13 names.

Likely to break

driver: functions removed in ESP-IDF 4.2

Peripheral drivers · ESP-IDF 4.2.0 · Source

ESP-IDF 4.2 no longer declares these driver functions from 4.1: touch_pad_filter_read_baseline, touch_pad_filter_reset_baseline, touch_pad_get_inactive_connect, touch_pad_proximity_data_get, touch_pad_proximity_get_config, touch_pad_proximity_read_meas_cnt… Calls fail to compile or link. Covers 11 names.

Likely to break

Public headers removed in ESP-IDF 4.4

Application code · ESP-IDF 4.4.0 · Source

These headers existed in ESP-IDF 4.3 and are gone in 4.4: esp32/brownout.h, esp32/cache_err_int.h, esp32c3/brownout.h, esp32c3/cache_err_int.h, esp32s2/brownout.h, esp32s2/cache_err_int.h, esp32s3/brownout.h, esp32s3/cache_err_int.h… Code that includes them stops compiling. Covers 10 names.

Likely to break

driver: functions removed in ESP-IDF 4.0

Peripheral drivers · ESP-IDF 4.0.0 · Source

ESP-IDF 4.0 no longer declares these driver functions from 3.3: adc1_get_voltage, dac_out_voltage, i2s_pop_sample, i2s_push_sample, i2s_read_bytes, i2s_write_bytes… Calls fail to compile or link. Covers 10 names.

Likely to break

esp32: types removed in ESP-IDF 4.0

Application code · ESP-IDF 4.0.0 · Source

ESP-IDF 4.0 no longer defines these esp32 types from 3.3: esp_deep_sleep_pd_domain_t, esp_deep_sleep_pd_option_t, esp_deep_sleep_wakeup_cause_t, esp_ext1_wakeup_mode_t, esp_wpa2_config_t, mesh_event_t… Code using them fails with unknown type errors. Covers 10 names.

Likely to break

esp32: functions removed in ESP-IDF 4.4

Application code · ESP-IDF 4.4.0 · Source

ESP-IDF 4.4 no longer declares these esp32 functions from 4.3: esp_brownout_disable, esp_brownout_init, esp_cache_err_get_cpuid, esp_cache_err_int_init, ssc_attach, ssc_param_len… Calls fail to compile or link. Covers 9 names.

Likely to break

Public headers removed in ESP-IDF 4.2

Application code · ESP-IDF 4.2.0 · Source

These headers existed in ESP-IDF 4.1 and are gone in 4.2: driver/adc2_wifi_internal.h, esp32s2beta/brownout.h, esp32s2beta/cache_err_int.h, esp32s2beta/clk.h, esp32s2beta/dport_access.h, esp32s2beta/pm.h, esp32s2beta/spiram.h. Code that includes them stops compiling. Covers 7 names.

Likely to break

ethernet: types removed in ESP-IDF 4.0

Application code · ESP-IDF 4.0.0 · Source

ESP-IDF 4.0 no longer defines these ethernet types from 3.3: eth_clock_mode_t, eth_config_t, eth_duplex_mode_t, eth_mode_t, eth_phy_base_t, eth_speed_mode_t. Code using them fails with unknown type errors. Covers 6 names.

Likely to break

tcpip_adapter: types removed in ESP-IDF 4.1

Application code · ESP-IDF 4.1.0 · Source

ESP-IDF 4.1 no longer defines these tcpip_adapter types from 4.0: tcpip_adapter_api_msg_t, tcpip_adapter_dns_param_t, tcpip_adapter_ip6_info_t, tcpip_adapter_ip_lost_timer_t, tcpip_adapter_option_id_t, tcpip_adapter_option_mode_t. Code using them fails with unknown type errors. Covers 6 names.

Likely to break

esp32s2: functions removed in ESP-IDF 4.3

Application code · ESP-IDF 4.3.0 · Source

ESP-IDF 4.3 no longer declares these esp32s2 functions from 4.2: esp_memprot_get_ena_reg, esp_memprot_get_intr_memtype, esp_memprot_is_assoc_intr, esp_memprot_is_assoc_intr_any. Calls fail to compile or link. Covers 4 names.

Likely to break

driver: functions removed in ESP-IDF 4.3

Peripheral drivers · ESP-IDF 4.3.0 · Source

ESP-IDF 4.3 no longer declares these driver functions from 4.2: spicommon_dma_chan_claim, spicommon_dma_chan_free, spicommon_dma_chan_in_use. Calls fail to compile or link. Covers 3 names.

Likely to break

tcpip_adapter: functions removed in ESP-IDF 4.1

Application code · ESP-IDF 4.1.0 · Source

ESP-IDF 4.1 no longer declares these tcpip_adapter functions from 4.0: tcpip_adapter_get_mac, tcpip_adapter_set_mac, tcpip_adapter_test_start. Calls fail to compile or link. Covers 3 names.

Likely to break

Public headers removed in ESP-IDF 4.3

Application code · ESP-IDF 4.3.0 · Source

These headers existed in ESP-IDF 4.2 and are gone in 4.3: freertos/StackMacros.h, freertos/porttrace.h. Code that includes them stops compiling. Covers 2 names.

Likely to break

driver: functions removed in ESP-IDF 4.4

Peripheral drivers · ESP-IDF 4.4.0 · Source

ESP-IDF 4.4 no longer declares these driver functions from 4.3: spicommon_slave_dma_chan_alloc, spicommon_slave_free_dma. Calls fail to compile or link. Covers 2 names.

Likely to break

esp_adc_cal: functions removed in ESP-IDF 4.0

Application code · ESP-IDF 4.0.0 · Source

ESP-IDF 4.0 no longer declares these esp_adc_cal functions from 3.3: adc1_to_voltage, esp_adc_cal_get_characteristics. Calls fail to compile or link. Covers 2 names.

Likely to break

esp_wifi: types removed in ESP-IDF 4.3

Application code · ESP-IDF 4.3.0 · Source

ESP-IDF 4.3 no longer defines these esp_wifi types from 4.2: modem_sleep_module_t, phy_rf_module_t. Code using them fails with unknown type errors. Covers 2 names.

Likely to break

Public headers removed in ESP-IDF 4.1

Application code · ESP-IDF 4.1.0 · Source

These headers existed in ESP-IDF 4.0 and are gone in 4.1: tcpip_adapter_internal.h. Code that includes them stops compiling.

Likely to break

driver: types removed in ESP-IDF 4.1

Peripheral drivers · ESP-IDF 4.1.0 · Source

ESP-IDF 4.1 no longer defines these driver types from 4.0: touch_isr_handle_t. Code using them fails with unknown type errors.

Likely to break

esp32: types removed in ESP-IDF 4.4

Application code · ESP-IDF 4.4.0 · Source

ESP-IDF 4.4 no longer defines these esp32 types from 4.3: ssc_cmd_t. Code using them fails with unknown type errors.

Likely to break

esp_ringbuf: types removed in ESP-IDF 4.0

Application code · ESP-IDF 4.0.0 · Source

ESP-IDF 4.0 no longer defines these esp_ringbuf types from 3.3: ringbuf_type_t. Code using them fails with unknown type errors.

Likely to break

esp_wifi: functions removed in ESP-IDF 4.2

Application code · ESP-IDF 4.2.0 · Source

ESP-IDF 4.2 no longer declares these esp_wifi functions from 4.1: esp_coex_ble_conn_dynamic_prio_enable. Calls fail to compile or link.

Likely to break

spi_flash: functions removed in ESP-IDF 4.2

Application code · ESP-IDF 4.2.0 · Source

ESP-IDF 4.2 no longer declares these spi_flash functions from 4.1: esp_flash_app_init_os_functions. Calls fail to compile or link.

Likely to break

spi_flash: functions removed in ESP-IDF 4.3

Application code · ESP-IDF 4.3.0 · Source

ESP-IDF 4.3 no longer declares these spi_flash functions from 4.2: spi_flash_generic_wait_host_idle. Calls fail to compile or link.

Likely to break

spi_flash: types removed in ESP-IDF 4.3

Application code · ESP-IDF 4.3.0 · Source

ESP-IDF 4.3 no longer defines these spi_flash types from 4.2: memspi_host_data_t. Code using them fails with unknown type errors.

Likely to break

vfs: functions removed in ESP-IDF 4.2

Application code · ESP-IDF 4.2.0 · Source

ESP-IDF 4.2 no longer declares these vfs functions from 4.1: esp_vfs_poll. Calls fail to compile or link.

Needs attention

Kconfig options removed in ESP-IDF 4.0

Build settings · ESP-IDF 4.0.0 · Source

These options exist in 3.3 and are gone in 4.0 without a rename: CONFIG_A2DP_SINK_TASK_STACK_SIZE, CONFIG_A2DP_SOURCE_TASK_STACK_SIZE, CONFIG_AWS_IOT_MQTT_HOST, CONFIG_AWS_IOT_MQTT_MAX_RECONNECT_WAIT_INTERVAL, CONFIG_AWS_IOT_MQTT_MIN_RECONNECT_WAIT_INTERVAL, CONFIG_AWS_IOT_MQTT_NUM_SUBSCRIBE_HANDLERS… ESP-IDF ignores them with a warning, so the behaviour they enabled is silently lost. Covers 40 names.

Needs attention

Kconfig options removed in ESP-IDF 4.4

Build settings · ESP-IDF 4.4.0 · Source

These options exist in 4.3 and are gone in 4.4 without a rename: CONFIG_BTDM_COEX_BLE_ADV_HIGH_PRIORITY, CONFIG_BTDM_COEX_BT_OPTIONS, CONFIG_BT_CTRL_COEX_PARAMETERS_ENABLE, CONFIG_BT_CTRL_COEX_USE_HOOKS, CONFIG_BT_CTRL_ESP32, CONFIG_BT_CTRL_ESP32C3… ESP-IDF ignores them with a warning, so the behaviour they enabled is silently lost. Covers 25 names.

Needs attention

Headers deprecated in ESP-IDF 4.0

Application code · ESP-IDF 4.0.0 · Source

Including these headers prints a deprecation warning from 4.0 on: esp_intr.h, rom/aes.h, rom/bigint.h, rom/cache.h, rom/crc.h, rom/efuse.h, rom/ets_sys.h, rom/gpio.h… They are usually removed in the next major release. Covers 20 names.

Needs attention

Kconfig options removed in ESP-IDF 4.2

Build settings · ESP-IDF 4.2.0 · Source

These options exist in 4.1 and are gone in 4.2 without a rename: CONFIG_ESP32S2_BETA_VERSION_A, CONFIG_ESP32S2_BETA_VERSION_B, CONFIG_ESP32S2_BETA_VERSION_MARLIN3, CONFIG_ESP32S2_BROWNOUT_DET_LVL_SEL_0, CONFIG_ESP32S2_DATA_CACHE_4WAYS, CONFIG_ESP32S2_DATA_CACHE_8WAYS… ESP-IDF ignores them with a warning, so the behaviour they enabled is silently lost. Covers 19 names.

Needs attention

driver: functions deprecated in ESP-IDF 4.4

Peripheral drivers · ESP-IDF 4.4.0 · Source

ESP-IDF 4.4 marks these driver functions as deprecated: adc_arbiter_config, adc_digi_controller_config, adc_digi_deinit, adc_digi_init, adc_digi_intr_clear, adc_digi_intr_disable… They still build with a warning and are removed in a later major release. Covers 16 names.

Needs attention

Kconfig options removed in ESP-IDF 4.3

Build settings · ESP-IDF 4.3.0 · Source

These options exist in 4.2 and are gone in 4.3 without a rename: CONFIG_BTDM_LPCLK_SEL_EXT_32K_XTAL, CONFIG_BTDM_LPCLK_SEL_MAIN_XTAL, CONFIG_BTDM_MODEM_SLEEP, CONFIG_BTDM_MODEM_SLEEP_MODE_EVED, CONFIG_BTDM_MODEM_SLEEP_MODE_ORIG, CONFIG_BT_HCI_UART_BAUDRATE… ESP-IDF ignores them with a warning, so the behaviour they enabled is silently lost. Covers 13 names.

Needs attention

Kconfig options removed in ESP-IDF 4.1

Build settings · ESP-IDF 4.1.0 · Source

These options exist in 4.0 and are gone in 4.1 without a rename: CONFIG_BLE_MESH_MAX_STORED_NODES, CONFIG_ESP32_APPTRACE_POSTMORTEM_FLUSH_THRESH, CONFIG_ESP32_WIFI_SW_COEXIST_PREFERENCE_BALANCE, CONFIG_ESP32_WIFI_SW_COEXIST_PREFERENCE_BT, CONFIG_ESP32_WIFI_SW_COEXIST_PREFERENCE_VALUE, CONFIG_ESP32_WIFI_SW_COEXIST_PREFERENCE_WIFI… ESP-IDF ignores them with a warning, so the behaviour they enabled is silently lost. Covers 9 names.

Needs attention

driver: functions deprecated in ESP-IDF 4.3

Peripheral drivers · ESP-IDF 4.3.0 · Source

ESP-IDF 4.3 marks these driver functions as deprecated: adc_power_off, adc_power_on, rmt_clr_intr_enable_mask, rmt_memory_rw_rst, rmt_set_intr_enable_mask. They still build with a warning and are removed in a later major release. Covers 5 names.

Needs attention

esp_event: functions deprecated in ESP-IDF 4.1

Application code · ESP-IDF 4.1.0 · Source

ESP-IDF 4.1 marks these esp_event functions as deprecated: esp_event_loop_init, esp_event_loop_set_cb, esp_event_process_default, esp_event_send, esp_event_set_default_wifi_handlers. They still build with a warning and are removed in a later major release. Covers 5 names.

Needs attention

Headers deprecated in ESP-IDF 4.1

Application code · ESP-IDF 4.1.0 · Source

Including these headers prints a deprecation warning from 4.1 on: esp_event_loop.h, tcpip_adapter.h. They are usually removed in the next major release. Covers 2 names.

Needs attention

vfs: functions deprecated in ESP-IDF 4.3

Application code · ESP-IDF 4.3.0 · Source

ESP-IDF 4.3 marks these vfs functions as deprecated: esp_vfs_dev_uart_set_rx_line_endings, esp_vfs_dev_uart_set_tx_line_endings. They still build with a warning and are removed in a later major release. Covers 2 names.

Needs attention

Headers deprecated in ESP-IDF 4.2

Application code · ESP-IDF 4.2.0 · Source

Including these headers prints a deprecation warning from 4.2 on: driver/can.h. They are usually removed in the next major release.

Needs attention

driver: functions deprecated in ESP-IDF 4.0

Peripheral drivers · ESP-IDF 4.0.0 · Source

ESP-IDF 4.0 marks these driver functions as deprecated: spi_cal_clock. They still build with a warning and are removed in a later major release.

Needs attention

driver: functions deprecated in ESP-IDF 4.1

Peripheral drivers · ESP-IDF 4.1.0 · Source

ESP-IDF 4.1 marks these driver functions as deprecated: uart_enable_pattern_det_intr. They still build with a warning and are removed in a later major release.

Needs attention

driver: functions deprecated in ESP-IDF 4.2

Peripheral drivers · ESP-IDF 4.2.0 · Source

ESP-IDF 4.2 marks these driver functions as deprecated: adc2_vref_to_gpio. They still build with a warning and are removed in a later major release.

Needs attention

esp_eth: functions deprecated in ESP-IDF 4.3

Application code · ESP-IDF 4.3.0 · Source

ESP-IDF 4.3 marks these esp_eth functions as deprecated: esp_eth_receive. They still build with a warning and are removed in a later major release.

Needs attention

esp_eth: functions deprecated in ESP-IDF 4.4

Application code · ESP-IDF 4.4.0 · Source

ESP-IDF 4.4 marks these esp_eth functions as deprecated: esp_eth_set_default_handlers. They still build with a warning and are removed in a later major release.

Needs attention

mdns: functions deprecated in ESP-IDF 4.1

Application code · ESP-IDF 4.1.0 · Source

ESP-IDF 4.1 marks these mdns functions as deprecated: mdns_handle_system_event. They still build with a warning and are removed in a later major release.

Needs attention

tcpip_adapter: functions deprecated in ESP-IDF 4.1

Application code · ESP-IDF 4.1.0 · Source

ESP-IDF 4.1 marks these tcpip_adapter functions as deprecated: tcpip_adapter_init. They still build with a warning and are removed in a later major release.

Needs attention

wifi_provisioning: functions deprecated in ESP-IDF 4.0

Application code · ESP-IDF 4.0.0 · Source

ESP-IDF 4.0 marks these wifi_provisioning functions as deprecated: wifi_prov_mgr_event_handler. They still build with a warning and are removed in a later major release.

Worth checking

Kconfig options renamed in ESP-IDF 4.0

Build settings · ESP-IDF 4.0.0 · Source

362 options were renamed in 4.0, for example CONFIG_A2DP_ENABLE -> CONFIG_BT_A2DP_ENABLE, CONFIG_A2D_INITIAL_TRACE_LEVEL -> CONFIG_BT_LOG_A2D_TRACE_LEVEL, CONFIG_A2D_TRACE_LEVEL_API -> CONFIG_BT_LOG_A2D_TRACE_LEVEL_API. ESP-IDF migrates them automatically on the first build (sdkconfig.rename). Covers 362 names.

Worth checking

Kconfig options renamed in ESP-IDF 4.4

Build settings · ESP-IDF 4.4.0 · Source

53 options were renamed in 4.4, for example CONFIG_ESP32C3_LIGHTSLEEP_GPIO_RESET_WORKAROUND -> CONFIG_ESP_SLEEP_GPIO_RESET_WORKAROUND, CONFIG_ESP32_PHY_CALIBRATION_AND_DATA_STORAGE -> CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE, CONFIG_ESP32_PHY_INIT_DATA_ERROR -> CONFIG_ESP_PHY_INIT_DATA_ERROR. ESP-IDF migrates them automatically on the first build (sdkconfig.rename). Covers 53 names.

Worth checking

Kconfig options renamed in ESP-IDF 4.3

Build settings · ESP-IDF 4.3.0 · Source

20 options were renamed in 4.3, for example CONFIG_ESP32S2_ALLOW_RTC_FAST_MEM_AS_HEAP -> CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP, CONFIG_ESP32S2_MEMPROT_FEATURE -> CONFIG_ESP_SYSTEM_MEMPROT_FEATURE, CONFIG_ESP32S2_MEMPROT_FEATURE_LOCK -> CONFIG_ESP_SYSTEM_MEMPROT_FEATURE_LOCK. ESP-IDF migrates them automatically on the first build (sdkconfig.rename). Covers 20 names.

Worth checking

Kconfig options renamed in ESP-IDF 4.2

Build settings · ESP-IDF 4.2.0 · Source

11 options were renamed in 4.2, for example CONFIG_BLE_MESH_ALLOC_FROM_PSRAM_FIRST -> CONFIG_BLE_MESH_MEM_ALLOC_MODE_EXTERNAL, CONFIG_ESP32S2_PANIC_GDBSTUB -> CONFIG_ESP_SYSTEM_PANIC_GDBSTUB, CONFIG_ESP32S2_PANIC_PRINT_HALT -> CONFIG_ESP_SYSTEM_PANIC_PRINT_HALT. ESP-IDF migrates them automatically on the first build (sdkconfig.rename). Covers 11 names.

Worth checking

Kconfig options renamed in ESP-IDF 4.1

Build settings · ESP-IDF 4.1.0 · Source

9 options were renamed in 4.1, for example CONFIG_ESP32_APPTRACE_DEST_NONE -> CONFIG_APPTRACE_DEST_NONE, CONFIG_ESP32_APPTRACE_DEST_TRAX -> CONFIG_APPTRACE_DEST_TRAX, CONFIG_ESP32_APPTRACE_ENABLE -> CONFIG_APPTRACE_ENABLE. ESP-IDF migrates them automatically on the first build (sdkconfig.rename). Covers 9 names.

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.

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.

Toolchain jump from GCC 5 to GCC 8 in ESP-IDF 4.0

When it applies: The selected path crosses ESP-IDF 4.0, which moved from the GCC 5.2 toolchain to GCC 8.

Why it matters: GCC 8 enables new warnings (several treated as errors by the ESP-IDF build), changes C++ defaults and code size, and 4.0 also renamed hundreds of Kconfig options.

What to do: Install the toolchain for the target release with the ESP-IDF install script, then fix new warnings and errors before looking at behaviour changes.

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.

CMake replaces GNU Make as the default build system

When it applies: The project builds only with GNU Make, and the selected path crosses ESP-IDF 4.0, where CMake (idf.py) becomes the default and GNU Make is deprecated.

Why it matters: GNU Make still works in 4.x but receives no new features and is removed in 5.0; component.mk settings do not carry over automatically.

What to do: Add CMakeLists.txt files alongside component.mk during the 4.x upgrade so the later move to 5.x is not blocked.

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 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.