From 3ca13cd583c234903b6ec9b76c5b74e805ea1892 Mon Sep 17 00:00:00 2001 From: Keith Burzinski Date: Thu, 12 Jun 2025 04:28:23 -0500 Subject: [PATCH 1/4] Add blog entry for sunsetting IDF 4.x support --- .../blog/posts/2025-06-14-sunsetting-idf-4.md | 46 +++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 docs/blog/posts/2025-06-14-sunsetting-idf-4.md diff --git a/docs/blog/posts/2025-06-14-sunsetting-idf-4.md b/docs/blog/posts/2025-06-14-sunsetting-idf-4.md new file mode 100644 index 0000000..3b99788 --- /dev/null +++ b/docs/blog/posts/2025-06-14-sunsetting-idf-4.md @@ -0,0 +1,46 @@ +--- +date: 2025-06-14 +authors: + - kbx81 +comments: true +--- + +# Sunsetting support for IDF 4.x + +At the beginning of this year, we made the transition from IDF 4.4 to IDF 5.1; this was a major upgrade and many +changes were necessary within ESPHome to achieve this. + +A long-standing (but largely undocumented -- until now) rule of the project is that we only support one major version +of [ESP-IDF](https://github.com/espressif/esp-idf) at a time. While it's technically _possible_ to support multiple +major versions, doing so introduces significant complexity within the codebase: + +- Code is more messy, complex and difficult to maintain +- Changes are more complex to test +- CI run durations are (significantly) longer + +As you may know, ESPHome supports using both [ESP-IDF](https://github.com/espressif/esp-idf) and +[Arduino](https://www.arduino.cc) as frameworks for projects built with Espressif's ESP32 family of microcontrollers. +Up to this point, we have been using Arduino 2.x, which is built on IDF 4.x; this effectively means we are still using +(and supporting) two different major versions of IDF. In the next release of ESPHome, we'll update the default Arduino +framework version to 3.x, which is built on IDF 5.x; this means we will no longer need to maintain compatibility with +IDF 4.x. + +Just prior to switching the default IDF version to 5.1, we were running our tests against both major versions -- but +this meant that our CI took over ten hours to complete for one single release! This isn't tenable in the long term and, +after making IDF 5.1 the default, we stopped running our tests against IDF 4.x in an effort to get our CI run duration +back down to "normal"...which is still often over five hours now. (We are looking for ways to improve this, but that's +a topic for another day.) + +Beyond this, maintaining a codebase with support for both major versions is just plain messy and complex. As Espressif +releases more and more new SoCs/microcontrollers, support for them won't be backported into IDF 4.x, which means that +you won't be able to use those new microcontrollers with IDF 4.x, anyway. Further, as new features and functionality +are introduced into IDF 5.x, they also won't be backported to IDF 4.x, so you won't be able to take advantage of these. + +Last, but not least, we've made a number of optimizations to reduce the memory (RAM and flash) footprint of ESPHome +in this (June) release; if you were experiencing issues with IDF 5.x before, please try it again as you're more likely +to be able to use it now. + +With these points in mind, we are officially sunsetting support for IDF 4.x in ESPHome. If you have kept your +project(s) back on IDF 4.x, you can continue to use versions of ESPHome prior to the July 2025 release, but you won't +be able to upgrade beyond that version. We encourage everybody to move to IDF 5.x -- specifically, in the June release, +we have switched the default IDF version to 5.3.2. From 90ef90168c1c793e1bc2e0745ac5aa0811ed92d6 Mon Sep 17 00:00:00 2001 From: Keith Burzinski Date: Thu, 12 Jun 2025 20:15:57 -0500 Subject: [PATCH 2/4] Add copy regarding faster IDF version adoption --- docs/blog/posts/2025-06-14-sunsetting-idf-4.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/blog/posts/2025-06-14-sunsetting-idf-4.md b/docs/blog/posts/2025-06-14-sunsetting-idf-4.md index 3b99788..5357a1e 100644 --- a/docs/blog/posts/2025-06-14-sunsetting-idf-4.md +++ b/docs/blog/posts/2025-06-14-sunsetting-idf-4.md @@ -43,4 +43,6 @@ to be able to use it now. With these points in mind, we are officially sunsetting support for IDF 4.x in ESPHome. If you have kept your project(s) back on IDF 4.x, you can continue to use versions of ESPHome prior to the July 2025 release, but you won't be able to upgrade beyond that version. We encourage everybody to move to IDF 5.x -- specifically, in the June release, -we have switched the default IDF version to 5.3.2. +we have switched the default IDF version to 5.3.2. In addition, we'd like to call out that we are working to accelerate +the adoption of new IDF versions; this helps us add support for new Espressif microcontrollers more quickly than we've +been able to in the past. From 3905253cac5210d7ac1f50d149e7c0eca2f9690b Mon Sep 17 00:00:00 2001 From: Keith Burzinski Date: Thu, 12 Jun 2025 20:18:27 -0500 Subject: [PATCH 3/4] Copy tweak --- docs/blog/posts/2025-06-14-sunsetting-idf-4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blog/posts/2025-06-14-sunsetting-idf-4.md b/docs/blog/posts/2025-06-14-sunsetting-idf-4.md index 5357a1e..e6dc41d 100644 --- a/docs/blog/posts/2025-06-14-sunsetting-idf-4.md +++ b/docs/blog/posts/2025-06-14-sunsetting-idf-4.md @@ -12,7 +12,7 @@ changes were necessary within ESPHome to achieve this. A long-standing (but largely undocumented -- until now) rule of the project is that we only support one major version of [ESP-IDF](https://github.com/espressif/esp-idf) at a time. While it's technically _possible_ to support multiple -major versions, doing so introduces significant complexity within the codebase: +major versions, doing so introduces some significant challenges: - Code is more messy, complex and difficult to maintain - Changes are more complex to test From 968252d415f9fb2844ed195605f04752a18d267e Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Wed, 18 Jun 2025 09:28:42 +1200 Subject: [PATCH 4/4] Update docs/blog/posts/2025-06-14-sunsetting-idf-4.md --- docs/blog/posts/2025-06-14-sunsetting-idf-4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blog/posts/2025-06-14-sunsetting-idf-4.md b/docs/blog/posts/2025-06-14-sunsetting-idf-4.md index e6dc41d..edb50f6 100644 --- a/docs/blog/posts/2025-06-14-sunsetting-idf-4.md +++ b/docs/blog/posts/2025-06-14-sunsetting-idf-4.md @@ -1,5 +1,5 @@ --- -date: 2025-06-14 +date: 2025-06-18 authors: - kbx81 comments: true