[esp8266] Make the native arduino toolchain the default (#19886)

docker/test_configs/esp8266-arduino.yaml

@@ -3,5 +3,7 @@ esphome:
 
 esp8266:
   board: d1_mini
+  # The PlatformIO path stays covered whatever the default is
+  toolchain: platformio
 
 logger:

esphome/__main__.py

@@ -2367,7 +2367,8 @@ def parse_args(argv):
         metavar="{" + ",".join(t.value for t in Toolchain) + "}",
         help=(
             "Select toolchain for compiling. Overrides '<platform>.toolchain' in YAML. "
-            f"Default: {Toolchain.PLATFORMIO.value}."
+            "Default: the platform's native toolchain where it has one, else "
+            f"{Toolchain.PLATFORMIO.value}."
         ),
     )
 

esphome/components/esp8266/__init__.py

@@ -111,7 +111,18 @@ def set_core_data(config: ConfigType) -> ConfigType:
 
 _TOOLCHAINS = (Toolchain.PLATFORMIO, Toolchain.ARDUINO)
 _validate_toolchain = cv.toolchain_enum(_TOOLCHAINS)
-_resolve_toolchain = cv.resolve_toolchain("ESP8266", _TOOLCHAINS, Toolchain.PLATFORMIO)
+_resolve_toolchain = cv.resolve_toolchain("ESP8266", _TOOLCHAINS, Toolchain.ARDUINO)
+
+
+def _warn_platformio_toolchain(config: ConfigType) -> ConfigType:
+    # Remove before 2027.4.0
+    if CORE.using_toolchain_platformio:
+        _LOGGER.warning(
+            "The 'platformio' toolchain for ESP8266 is deprecated and will be "
+            "removed in ESPHome 2027.4.0; the native 'arduino' toolchain is the "
+            "default."
+        )
+    return config
 
 
 def _validate_native_toolchain(config: ConfigType) -> ConfigType:
@@ -319,6 +330,7 @@ CONFIG_SCHEMA = cv.All(
         }
     ),
     _resolve_toolchain,
+    _warn_platformio_toolchain,
     _validate_native_toolchain,
     set_core_data,
 )

tests/unit_tests/components/esp8266/test_toolchain_validation.py

@@ -14,6 +14,7 @@ from esphome.components.esp8266 import (
     ARDUINO_FRAMEWORK_SCHEMA,
     _resolve_toolchain,
     _validate_native_toolchain,
+    _warn_platformio_toolchain,
 )
 import esphome.config_validation as cv
 from esphome.const import (
@@ -125,10 +126,22 @@ def test_yaml_toolchain_key_resolves() -> None:
     assert CORE.using_toolchain_arduino
 
 
-def test_yaml_toolchain_key_defaults_to_platformio() -> None:
+@pytest.mark.parametrize(
+    ("config_toolchain", "expected"),
+    [
+        (None, Toolchain.ARDUINO),
+        # An explicit `toolchain:` still wins over the default
+        (Toolchain.PLATFORMIO, Toolchain.PLATFORMIO),
+        (Toolchain.ARDUINO, Toolchain.ARDUINO),
+    ],
+)
+def test_default_toolchain_is_arduino(
+    config_toolchain: Toolchain | None, expected: Toolchain
+) -> None:
     CORE.toolchain = None
-    _resolve_toolchain({})
-    assert CORE.toolchain == Toolchain.PLATFORMIO
+    config = {} if config_toolchain is None else {CONF_TOOLCHAIN: config_toolchain}
+    _resolve_toolchain(config)
+    assert CORE.toolchain == expected
 
 
 def test_decode_pc_native_missing_tools_warns_once(
@@ -198,3 +211,18 @@ def test_copy_files_native_skips_platformio_scripts(tmp_path: Path) -> None:
     CORE.build_path = tmp_path
     esp8266.copy_files()
     assert list(tmp_path.iterdir()) == []
+
+
+@pytest.mark.parametrize(
+    ("toolchain", "warns"),
+    [(Toolchain.PLATFORMIO, True), (Toolchain.ARDUINO, False)],
+)
+def test_platformio_toolchain_deprecation_warning(
+    toolchain: Toolchain, warns: bool, caplog: pytest.LogCaptureFixture
+) -> None:
+    CORE.toolchain = toolchain
+    config = _config()
+    assert _warn_platformio_toolchain(config) is config
+    assert (
+        "deprecated and will be removed in ESPHome 2027.4.0" in caplog.text
+    ) is warns

tests/unit_tests/test_vscode.py

@@ -58,7 +58,7 @@ esp8266:
   board: !secret my_secret_board
 """),
             # read_file secrets.yaml
-            _file_response("""my_secret_board: esp1f"""),
+            _file_response("""my_secret_board: d1_mini"""),
         ]
     )
 
@@ -83,7 +83,7 @@ esp8266:
   broad: !secret my_secret_board        # typo here
 """),
             # read_file secrets.yaml
-            _file_response("""my_secret_board: esp1f"""),
+            _file_response("""my_secret_board: d1_mini"""),
         ]
     )