From 1dfafce06a55d87e5d83ab326f0e48e6f3aa4b09 Mon Sep 17 00:00:00 2001
From: Jonathan Swoboda <154711427+swoboda1337@users.noreply.github.com>
Date: Wed, 24 Jun 2026 21:05:29 -0400
Subject: [PATCH] [i2c][spi] Wire ESP32-S31/H4/H21 bus capabilities (#17188)

---
 esphome/components/esp32/gpio_esp32_s31.py | 17 +++++++++++++++--
 esphome/components/i2c/__init__.py         |  8 ++++++++
 esphome/components/spi/__init__.py         |  2 ++
 3 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/esphome/components/esp32/gpio_esp32_s31.py b/esphome/components/esp32/gpio_esp32_s31.py
index 6a19e3fee4..d49240723b 100644
--- a/esphome/components/esp32/gpio_esp32_s31.py
+++ b/esphome/components/esp32/gpio_esp32_s31.py
@@ -2,13 +2,16 @@ import logging
 from typing import Any
 
 import esphome.config_validation as cv
-from esphome.const import CONF_INPUT, CONF_MODE, CONF_NUMBER
+from esphome.const import CONF_INPUT, CONF_MODE, CONF_NUMBER, CONF_SCL, CONF_SDA
 from esphome.pins import check_strapping_pin
 
 # Per the ESP32-S31 datasheet (page 96):
 # https://documentation.espressif.com/esp32-s31_datasheet_en.pdf
 _ESP32S31_SPI_FLASH_PINS: set[int] = {27, 28, 29, 31, 32, 33}
-_ESP32S31_STRAPPING_PINS: set[int] = {60, 61}
+# GPIO60/GPIO61 set the boot mode; GPIO37 selects the JTAG signal source.
+_ESP32S31_STRAPPING_PINS: set[int] = {37, 60, 61}
+# LP I2C is fixed to GPIO6 (SCL) / GPIO7 (SDA) per the datasheet IO MUX table.
+_ESP32S31_I2C_LP_PINS = {"SDA": 7, "SCL": 6}
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -36,3 +39,13 @@ def esp32_s31_validate_supports(value: dict[str, Any]) -> dict[str, Any]:
 
     check_strapping_pin(value, _ESP32S31_STRAPPING_PINS, _LOGGER)
     return value
+
+
+def esp32_s31_validate_lp_i2c(value):
+    lp_sda_pin = _ESP32S31_I2C_LP_PINS["SDA"]
+    lp_scl_pin = _ESP32S31_I2C_LP_PINS["SCL"]
+    if int(value[CONF_SDA]) != lp_sda_pin or int(value[CONF_SCL]) != lp_scl_pin:
+        raise cv.Invalid(
+            f"Low power i2c interface is only supported on GPIO{lp_sda_pin} SDA and GPIO{lp_scl_pin} SCL for ESP32-S31"
+        )
+    return value
diff --git a/esphome/components/i2c/__init__.py b/esphome/components/i2c/__init__.py
index d9dd6d5ee2..eec2211a96 100644
--- a/esphome/components/i2c/__init__.py
+++ b/esphome/components/i2c/__init__.py
@@ -13,14 +13,18 @@ from esphome.components.esp32 import (
     VARIANT_ESP32C6,
     VARIANT_ESP32C61,
     VARIANT_ESP32H2,
+    VARIANT_ESP32H4,
+    VARIANT_ESP32H21,
     VARIANT_ESP32P4,
     VARIANT_ESP32S2,
     VARIANT_ESP32S3,
+    VARIANT_ESP32S31,
     get_esp32_variant,
 )
 from esphome.components.esp32.gpio_esp32_c5 import esp32_c5_validate_lp_i2c
 from esphome.components.esp32.gpio_esp32_c6 import esp32_c6_validate_lp_i2c
 from esphome.components.esp32.gpio_esp32_p4 import esp32_p4_validate_lp_i2c
+from esphome.components.esp32.gpio_esp32_s31 import esp32_s31_validate_lp_i2c
 from esphome.components.zephyr import (
     zephyr_add_overlay,
     zephyr_add_prj_conf,
@@ -72,14 +76,18 @@ ESP32_I2C_CAPABILITIES = {
     VARIANT_ESP32C6: {"NUM": 2, "HP": 1, "LP": 1},
     VARIANT_ESP32C61: {"NUM": 1, "HP": 1},
     VARIANT_ESP32H2: {"NUM": 2, "HP": 2},
+    VARIANT_ESP32H4: {"NUM": 2, "HP": 2},
+    VARIANT_ESP32H21: {"NUM": 2, "HP": 2},
     VARIANT_ESP32P4: {"NUM": 3, "HP": 2, "LP": 1},
     VARIANT_ESP32S2: {"NUM": 2, "HP": 2},
     VARIANT_ESP32S3: {"NUM": 2, "HP": 2},
+    VARIANT_ESP32S31: {"NUM": 3, "HP": 2, "LP": 1},
 }
 VALIDATE_LP_I2C = {
     VARIANT_ESP32C5: esp32_c5_validate_lp_i2c,
     VARIANT_ESP32C6: esp32_c6_validate_lp_i2c,
     VARIANT_ESP32P4: esp32_p4_validate_lp_i2c,
+    VARIANT_ESP32S31: esp32_s31_validate_lp_i2c,
 }
 LP_I2C_VARIANT = list(VALIDATE_LP_I2C.keys())
 
diff --git a/esphome/components/spi/__init__.py b/esphome/components/spi/__init__.py
index 33ccfbb5ee..d1961cec59 100644
--- a/esphome/components/spi/__init__.py
+++ b/esphome/components/spi/__init__.py
@@ -11,6 +11,7 @@ from esphome.components.esp32 import (
     VARIANT_ESP32C6,
     VARIANT_ESP32C61,
     VARIANT_ESP32H2,
+    VARIANT_ESP32H21,
     VARIANT_ESP32P4,
     VARIANT_ESP32S2,
     VARIANT_ESP32S3,
@@ -174,6 +175,7 @@ def get_hw_interface_list():
             VARIANT_ESP32C6,
             VARIANT_ESP32C61,
             VARIANT_ESP32H2,
+            VARIANT_ESP32H21,
         ]:
             return [["spi", "spi2"]]
         return [["spi", "spi2"], ["spi3"]]