From be78b8011d214435f47cb5b406694aa5d310bdfd Mon Sep 17 00:00:00 2001
From: Jonathan Swoboda <154711427+swoboda1337@users.noreply.github.com>
Date: Wed, 29 Jul 2026 17:17:39 -0400
Subject: [PATCH] [esp32] Add platformio toolchain deprecation warning (#17947)

---
 esphome/components/esp32/__init__.py | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/esphome/components/esp32/__init__.py b/esphome/components/esp32/__init__.py
index 9f3d7f1dc9..67d4b76e44 100644
--- a/esphome/components/esp32/__init__.py
+++ b/esphome/components/esp32/__init__.py
@@ -1237,6 +1237,13 @@ def final_validate(config):
 
     from .gpio import final_validate_pins
 
+    # Remove before 2027.2.0
+    if CORE.using_toolchain_platformio:
+        _LOGGER.warning(
+            "The 'platformio' toolchain for ESP32 is deprecated and will be removed "
+            "in ESPHome 2027.2.0. Please use 'toolchain: esp-idf' instead."
+        )
+
     errs = []
     conf_fw = config[CONF_FRAMEWORK]
     advanced = conf_fw[CONF_ADVANCED]