RP2040 Framework Update: Pico-SDK 2.0 and GCC 14

Mar 12, 2026

The RP2040 platform has been updated to arduino-pico 5.5.0 (from 3.9.4), pico-sdk 2.1.0 (from 1.5.1), and GCC 14 (from GCC 12). Several hardware register names, API functions, and macros have changed. External components targeting RP2040 may need updates.

This is a breaking change for external components in ESPHome 2026.3.0 and later.

Background

PR #14328: Update RP2040 framework to arduino-pico 5.5.0 / pico-sdk 2.1.0

The RP2040 platform was running on significantly outdated tooling. The update brings:

arduino-pico: 3.9.4 → 5.5.0
pico-sdk: 1.5.1 → 2.1.0
GCC: 12 → 14

This is a major version bump for the pico-sdk (1.x → 2.x), which includes hardware register renames and API changes.

What’s Changing

Hardware register renames

Pico-SDK 2.0 renamed several hardware register accessor macros:

Before (pico-sdk 1.x)	After (pico-sdk 2.x)
`padsbank0_hw`	`pads_bank0_hw`

Backward compatibility shims exist in pico-sdk 2.0 for most register renames, so code using the old names will still compile with a deprecation warning.

SerialPIO constant

// Before
SerialPIO serial(txPin, SerialPIO::NOPIN);

// After — NOPIN is now a global macro
SerialPIO serial(txPin, NOPIN);

There is no backward compatibility shim for SerialPIO::NOPIN.

Filesystem API

// Before
FSInfo64 info;
LittleFS.info64(info);

// After — use FS::info instead
FSInfo info;
LittleFS.info(info);

FS::info64 has been removed. Use FS::info which now handles large filesystems.

Audio API return values

Audio APIs (I2S) now return bytes instead of frames. If your component uses I2S audio on RP2040, update calculations accordingly.

GCC 14 strictness

GCC 14 enforces stricter type checking and may produce new warnings or errors on code that compiled cleanly under GCC 12. Common issues include:

Implicit conversions between integer types of different sizes
Missing #include directives that were transitively included before
Stricter template argument deduction

Who This Affects

External components that:

Target RP2040 and use pico-sdk hardware register names directly
Use SerialPIO::NOPIN
Use FS::info64
Use I2S audio APIs on RP2040

Standard YAML configurations are not affected.

Migration Guide

Register renames

// Before
padsbank0_hw->io[pin] = ...;

// After
pads_bank0_hw->io[pin] = ...;

SerialPIO::NOPIN

// Before
SerialPIO serial(txPin, SerialPIO::NOPIN);

// After
SerialPIO serial(txPin, NOPIN);

Supporting Multiple ESPHome Versions

For SerialPIO::NOPIN (no backward compat shim):

#if ESPHOME_VERSION_CODE >= VERSION_CODE(2026, 3, 0)
  SerialPIO serial(txPin, NOPIN);
#else
  SerialPIO serial(txPin, SerialPIO::NOPIN);
#endif

For register renames, the pico-sdk 2.0 provides backward compat shims, so old names still work with warnings. No version guard needed unless you want to suppress warnings.

Timeline

ESPHome 2026.3.0 (March 2026): Framework updated, old APIs may break
No deprecation period — this is a toolchain update

Finding Code That Needs Updates

# Find old register names
grep -rn 'padsbank0_hw' your_component/

# Find SerialPIO::NOPIN
grep -rn 'SerialPIO::NOPIN' your_component/

# Find FS::info64
grep -rn 'info64' your_component/

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

Comments

Feel free to leave a comment here to discuss this post with others. You can ask questions, share your experience, or suggest improvements. If you have a question about a specific feature or issue, please consider using the ESPHome Discord. Stick to English and follow ESPHome's code of conduct. These comments exist on a discussion on GitHub, so you can also comment there directly if you prefer.