SDK upgrade guide
ESP-IDF 5.1 to ESP-IDF 5.5: what needs attention
Migratorisk's knowledge base lists 8 documented changes between ESP-IDF 5.1 and ESP-IDF 5.5 across 3 releases. 3 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-5.1.0 --to esp-idf-5.5.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 5.1 and ESP-IDF 5.5
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.
Peripherals: I2C: Major Changes in Usage
Peripherals: I2C: Major Changes in Usage Covers 8 names.
Storage: VFS
The UART implementation of VFS operators has been moved from `vfs` component to `esp_driver_uart` component. APIs with `esp_vfs_dev_uart_` prefix are all deprecated, replaced with new APIs in `uart_vfs.h` starting with `uart_vfs_dev_` prefix. Specifically, For compatibility, `vfs` component still registers `esp_driver_uart` as its private dependency. Covers 5 names.
Bluetooth Classic: Bluedroid
Bluetooth Classic: Bluedroid Covers 3 names.
System: Time
* {IDF_TARGET_NAME}/rtc.h is deprecated, include the replacement esp_rtc_time.h instead. Covers 10 names.
Peripherals: I2C: Major Changes in Concepts
Peripherals: I2C: Major Changes in Concepts
Peripherals: I2S
Due to the cumbersome usage of the secondary pointer of DMA buffer, the data field in the callback event i2s_event_data_t is deprecated, please use the newly added first-level pointer dma_buf instead.
Peripherals: UART
Peripherals: UART
System: Power Management
* esp_sleep_enable_ext1_wakeup_with_level_mask is deprecated, use esp_sleep_enable_ext1_wakeup_io and esp_sleep_disable_ext1_wakeup_io instead.
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.
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.
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.
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.
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: Minor releases can change bootloader features and image format options; the new application must still boot from the bootloader already on each device.
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.
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.
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: Minor releases change drivers, Wi-Fi and Bluetooth stacks and libraries, which usually changes the application size; 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 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: Minor ESP-IDF releases often move to a newer GCC version.
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.1
- ESP-IDF 5.0 to ESP-IDF 5.1
- ESP-IDF 5.5 to ESP-IDF 6.0
- 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.