From 3f01f9895f0c98179d8301dbed46aa02801d7f77 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Sun, 16 Aug 2026 12:44:49 -0700
Subject: [PATCH] [esp32_hosted] Require ESP-IDF 5.3 or newer (#18417)

---
 esphome/components/esp32_hosted/__init__.py   | 34 ++++++++++++------
 .../component_tests/esp32_hosted/__init__.py  |  0
 .../component_tests/esp32_hosted/test_init.py | 35 +++++++++++++++++++
 3 files changed, 59 insertions(+), 10 deletions(-)
 create mode 100644 tests/component_tests/esp32_hosted/__init__.py
 create mode 100644 tests/component_tests/esp32_hosted/test_init.py

diff --git a/esphome/components/esp32_hosted/__init__.py b/esphome/components/esp32_hosted/__init__.py
index c6a714aace..d3432fb461 100644
--- a/esphome/components/esp32_hosted/__init__.py
+++ b/esphome/components/esp32_hosted/__init__.py
@@ -16,8 +16,10 @@ from esphome.const import (
     CONF_VARIANT,
 )
 from esphome.cpp_generator import add_define
+from esphome.types import ConfigType
 
 CODEOWNERS = ["@swoboda1337"]
+DEPENDENCIES = ["esp32"]
 # esp32_ble raises the task watchdog around the remote BT controller bring-up
 AUTO_LOAD = ["watchdog"]
 
@@ -124,6 +126,22 @@ CONFIG_SCHEMA = cv.typed_schema(
 )
 
 
+def _final_validate(config: ConfigType) -> ConfigType:
+    # The esp_hosted releases compatible with older ESP-IDF versions crash at
+    # boot with a heap double free in the SDIO RX path (fixed in esp_hosted
+    # 2.11.0, which requires ESP-IDF 5.3), so reject them at validation time.
+    if (idf_ver := esp32.idf_version()) < cv.Version(5, 3, 0):
+        raise cv.Invalid(
+            f"esp32_hosted requires ESP-IDF 5.3 or newer, got {idf_ver}. "
+            "Remove the framework version from your configuration to use the "
+            "recommended version, or pin a version at or above 5.3."
+        )
+    return config
+
+
+FINAL_VALIDATE_SCHEMA = _final_validate
+
+
 def _configure_sdio(config):
     slot = config[CONF_SLOT]
     esp32.add_idf_sdkconfig_option(
@@ -251,18 +269,14 @@ async def to_code(config):
     if config[CONF_USE_PSRAM]:
         esp32.add_idf_sdkconfig_option("CONFIG_ESP_HOSTED_MEMPOOL_PREFER_SPIRAM", True)
 
-    # Library versions
+    # Library versions; this component set requires ESP-IDF 5.3 or newer,
+    # which is enforced at validation time.
     idf_ver = esp32.idf_version()
     os.environ["ESP_IDF_VERSION"] = f"{idf_ver.major}.{idf_ver.minor}"
-    if idf_ver >= cv.Version(5, 5, 0):
-        esp32.add_idf_component(name="espressif/esp_wifi_remote", ref="1.6.3")
-        esp32.add_idf_component(name="espressif/wifi_remote_over_eppp", ref="0.3.3")
-        esp32.add_idf_component(name="espressif/eppp_link", ref="1.1.5")
-        esp32.add_idf_component(name="espressif/esp_hosted", ref="2.12.12")
-    else:
-        esp32.add_idf_component(name="espressif/esp_wifi_remote", ref="0.13.0")
-        esp32.add_idf_component(name="espressif/eppp_link", ref="0.2.0")
-        esp32.add_idf_component(name="espressif/esp_hosted", ref="2.0.11")
+    esp32.add_idf_component(name="espressif/esp_wifi_remote", ref="1.6.3")
+    esp32.add_idf_component(name="espressif/wifi_remote_over_eppp", ref="0.3.3")
+    esp32.add_idf_component(name="espressif/eppp_link", ref="1.1.5")
+    esp32.add_idf_component(name="espressif/esp_hosted", ref="2.12.12")
     esp32.add_extra_script(
         "post",
         "esp32_hosted.py",
diff --git a/tests/component_tests/esp32_hosted/__init__.py b/tests/component_tests/esp32_hosted/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/tests/component_tests/esp32_hosted/test_init.py b/tests/component_tests/esp32_hosted/test_init.py
new file mode 100644
index 0000000000..cec81e4e83
--- /dev/null
+++ b/tests/component_tests/esp32_hosted/test_init.py
@@ -0,0 +1,35 @@
+"""Tests for the esp32_hosted ESP-IDF version gate."""
+
+import pytest
+
+from esphome import config_validation as cv
+from esphome.components.esp32 import KEY_IDF_VERSION
+from esphome.components.esp32_hosted import _final_validate
+from esphome.const import PlatformFramework
+
+from ..types import SetCoreConfigCallable
+
+
+@pytest.mark.parametrize("idf", ["5.3.0", "5.4.2", "5.5.5"])
+def test_final_validate_accepts_supported_idf(
+    set_core_config: SetCoreConfigCallable, idf: str
+) -> None:
+    """ESP-IDF 5.3 and newer passes validation unchanged."""
+    set_core_config(
+        PlatformFramework.ESP32_IDF,
+        platform_data={KEY_IDF_VERSION: cv.Version.parse(idf)},
+    )
+    assert _final_validate({}) == {}
+
+
+@pytest.mark.parametrize("idf", ["5.0.0", "5.2.2"])
+def test_final_validate_rejects_old_idf(
+    set_core_config: SetCoreConfigCallable, idf: str
+) -> None:
+    """ESP-IDF older than 5.3 is rejected with a clear error."""
+    set_core_config(
+        PlatformFramework.ESP32_IDF,
+        platform_data={KEY_IDF_VERSION: cv.Version.parse(idf)},
+    )
+    with pytest.raises(cv.Invalid, match="requires ESP-IDF 5.3 or newer"):
+        _final_validate({})