[esp32] Allow variant in place of board (#9427)

Co-authored-by: J. Nick Koston <nick@koston.org>
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

esphome/components/esp32/__init__.py

@@ -39,7 +39,7 @@ import esphome.final_validate as fv
 from esphome.helpers import copy_file_if_changed, mkdir_p, write_file_if_changed
 from esphome.types import ConfigType
 
-from .boards import BOARDS
+from .boards import BOARDS, STANDARD_BOARDS
 from .const import (  # noqa
     KEY_BOARD,
     KEY_COMPONENTS,
@@ -487,25 +487,32 @@ def _platform_is_platformio(value):
 
 
 def _detect_variant(value):
-    board = value[CONF_BOARD]
-    if board in BOARDS:
-        variant = BOARDS[board][KEY_VARIANT]
-        if CONF_VARIANT in value and variant != value[CONF_VARIANT]:
+    board = value.get(CONF_BOARD)
+    variant = value.get(CONF_VARIANT)
+    if variant and board is None:
+        # If variant is set, we can derive the board from it
+        # variant has already been validated against the known set
+        value = value.copy()
+        value[CONF_BOARD] = STANDARD_BOARDS[variant]
+    elif board in BOARDS:
+        variant = variant or BOARDS[board][KEY_VARIANT]
+        if variant != BOARDS[board][KEY_VARIANT]:
             raise cv.Invalid(
                 f"Option '{CONF_VARIANT}' does not match selected board.",
                 path=[CONF_VARIANT],
             )
         value = value.copy()
         value[CONF_VARIANT] = variant
+    elif not variant:
+        raise cv.Invalid(
+            "This board is unknown, if you are sure you want to compile with this board selection, "
+            f"override with option '{CONF_VARIANT}'",
+            path=[CONF_BOARD],
+        )
     else:
-        if CONF_VARIANT not in value:
-            raise cv.Invalid(
-                "This board is unknown, if you are sure you want to compile with this board selection, "
-                f"override with option '{CONF_VARIANT}'",
-                path=[CONF_BOARD],
-            )
         _LOGGER.warning(
-            "This board is unknown. Make sure the chosen chip component is correct.",
+            "This board is unknown; the specified variant '%s' will be used but this may not work as expected.",
+            variant,
         )
     return value
 
@@ -676,7 +683,7 @@ CONF_PARTITIONS = "partitions"
 CONFIG_SCHEMA = cv.All(
     cv.Schema(
         {
-            cv.Required(CONF_BOARD): cv.string_strict,
+            cv.Optional(CONF_BOARD): cv.string_strict,
             cv.Optional(CONF_CPU_FREQUENCY): cv.one_of(
                 *FULL_CPU_FREQUENCIES, upper=True
             ),
@@ -691,6 +698,7 @@ CONFIG_SCHEMA = cv.All(
     _detect_variant,
     _set_default_framework,
     set_core_data,
+    cv.has_at_least_one_key(CONF_BOARD, CONF_VARIANT),
 )
 
 

esphome/components/esp32/boards.py

@@ -2,13 +2,30 @@ from .const import (
     VARIANT_ESP32,
     VARIANT_ESP32C2,
     VARIANT_ESP32C3,
+    VARIANT_ESP32C5,
     VARIANT_ESP32C6,
     VARIANT_ESP32H2,
     VARIANT_ESP32P4,
     VARIANT_ESP32S2,
     VARIANT_ESP32S3,
+    VARIANTS,
 )
 
+STANDARD_BOARDS = {
+    VARIANT_ESP32: "esp32dev",
+    VARIANT_ESP32C2: "esp32-c2-devkitm-1",
+    VARIANT_ESP32C3: "esp32-c3-devkitm-1",
+    VARIANT_ESP32C5: "esp32-c5-devkitc-1",
+    VARIANT_ESP32C6: "esp32-c6-devkitm-1",
+    VARIANT_ESP32H2: "esp32-h2-devkitm-1",
+    VARIANT_ESP32P4: "esp32-p4-evboard",
+    VARIANT_ESP32S2: "esp32-s2-kaluga-1",
+    VARIANT_ESP32S3: "esp32-s3-devkitc-1",
+}
+
+# Make sure not missed here if a new variant added.
+assert all(v in STANDARD_BOARDS for v in VARIANTS)
+
 ESP32_BASE_PINS = {
     "TX": 1,
     "RX": 3,

tests/component_tests/esp32/test_esp32.py

@@ -0,0 +1,73 @@
+"""
+Test ESP32 configuration
+"""
+
+from typing import Any
+
+import pytest
+
+from esphome.components.esp32 import VARIANTS
+import esphome.config_validation as cv
+from esphome.const import PlatformFramework
+
+
+def test_esp32_config(set_core_config) -> None:
+    set_core_config(PlatformFramework.ESP32_IDF)
+
+    from esphome.components.esp32 import CONFIG_SCHEMA
+    from esphome.components.esp32.const import VARIANT_ESP32, VARIANT_FRIENDLY
+
+    # Example ESP32 configuration
+    config = {
+        "board": "esp32dev",
+        "variant": VARIANT_ESP32,
+        "cpu_frequency": "240MHz",
+        "flash_size": "4MB",
+        "framework": {
+            "type": "esp-idf",
+        },
+    }
+
+    # Check if the variant is valid
+    config = CONFIG_SCHEMA(config)
+    assert config["variant"] == VARIANT_ESP32
+
+    # Check that defining a variant sets the board name correctly
+    for variant in VARIANTS:
+        config = CONFIG_SCHEMA(
+            {
+                "variant": variant,
+            }
+        )
+        assert VARIANT_FRIENDLY[variant].lower() in config["board"]
+
+
+@pytest.mark.parametrize(
+    ("config", "error_match"),
+    [
+        pytest.param(
+            {"flash_size": "4MB"},
+            r"This board is unknown, if you are sure you want to compile with this board selection, override with option 'variant' @ data\['board'\]",
+            id="unknown_board_config",
+        ),
+        pytest.param(
+            {"variant": "esp32xx"},
+            r"Unknown value 'ESP32XX', did you mean 'ESP32', 'ESP32S3', 'ESP32S2'\? for dictionary value @ data\['variant'\]",
+            id="unknown_variant_config",
+        ),
+        pytest.param(
+            {"variant": "esp32s3", "board": "esp32dev"},
+            r"Option 'variant' does not match selected board. @ data\['variant'\]",
+            id="mismatched_board_variant_config",
+        ),
+    ],
+)
+def test_esp32_configuration_errors(
+    config: Any,
+    error_match: str,
+) -> None:
+    """Test detection of invalid configuration."""
+    from esphome.components.esp32 import CONFIG_SCHEMA
+
+    with pytest.raises(cv.Invalid, match=error_match):
+        CONFIG_SCHEMA(config)