From d4b642608793a06249656ea16f26d5d97bcb58e6 Mon Sep 17 00:00:00 2001
From: "Thomas A." <arthofer.thomas@gmail.com>
Date: Thu, 18 Jun 2026 05:12:22 +0200
Subject: [PATCH] [esp32] Pin Names for Seeed XIAO C3 / C6 / S3 (#17002)

Co-authored-by: Thomas A <1294885+zeroflow@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
---
 esphome/components/esp32/boards.py | 90 +++++++++++++++++++++++++++++-
 1 file changed, 88 insertions(+), 2 deletions(-)

diff --git a/esphome/components/esp32/boards.py b/esphome/components/esp32/boards.py
index 6062631d98..729b0c89ab 100644
--- a/esphome/components/esp32/boards.py
+++ b/esphome/components/esp32/boards.py
@@ -1240,6 +1240,43 @@ ESP32_BOARD_PINS = {
         "LED_BUILTINB": 4,
     },
     "sensesiot_weizen": {},
+    # Source: https://wiki.seeedstudio.com/XIAO_ESP32C3_Getting_Started/
+    # The XIAO ESP32-C3 has no user-controllable LED (only a hardwired charge
+    # LED), so LED/LED_BUILTIN are intentionally omitted. The Ax keys override
+    # the incorrect ESP32_BASE_PINS A* fallback (which otherwise makes pin: A0
+    # resolve to phantom GPIO36 and pin: A1/A2 raise cv.Invalid).
+    "seeed_xiao_esp32c3": {
+        "D0": 2,
+        "D1": 3,
+        "D2": 4,
+        "D3": 5,
+        "D4": 6,
+        "D5": 7,
+        "D6": 21,
+        "D7": 20,
+        "D8": 8,
+        "D9": 9,
+        "D10": 10,
+        "MTDO": 7,
+        "MTCK": 6,
+        "MTDI": 5,
+        "MTMS": 4,
+        "BOOT": 9,
+        "TX": 21,
+        "RX": 20,
+        "SDA": 6,
+        "SCL": 7,
+        "SCK": 8,
+        "MISO": 9,
+        "MOSI": 10,
+        "A0": 2,
+        "A1": 3,
+        "A2": 4,
+        "A3": 5,
+    },
+    # Source: https://wiki.seeedstudio.com/xiao_esp32c6_getting_started/
+    # The Ax keys override the incorrect ESP32_BASE_PINS A* fallback (which
+    # otherwise makes pin: A0 resolve to phantom GPIO36).
     "seeed_xiao_esp32c6": {
         "D0": 0,
         "D1": 1,
@@ -1257,10 +1294,59 @@ ESP32_BOARD_PINS = {
         "MTDI": 5,
         "MTMS": 4,
         "BOOT": 9,
-        "LED": 8,
-        "LED_BUILTIN": 8,
+        "LED": 15,  # Bugfix: was GPIO8; the yellow user LED is GPIO15
+        "LED_BUILTIN": 15,  # Bugfix: was GPIO8; the yellow user LED is GPIO15
         "RF_SWITCH_EN": 3,
         "RF_ANT_SELECT": 14,
+        "TX": 16,
+        "RX": 17,
+        "SDA": 22,
+        "SCL": 23,
+        "SCK": 19,
+        "MISO": 20,
+        "MOSI": 18,
+        "A0": 0,
+        "A1": 1,
+        "A2": 2,
+    },
+    # Source: https://wiki.seeedstudio.com/xiao_esp32s3_getting_started/
+    # LED (GPIO21) is active-LOW; BOOT=GPIO0 is the standard ESP32-S3 strapping
+    # pin. The Ax keys override the incorrect ESP32_BASE_PINS A* fallback for the
+    # published silkscreen set. A6/A7 are intentionally absent (D6/D7 = GPIO43/44
+    # have no ADC); because ESP32_BASE_PINS already defines A6=34/A7=35, pin: A6/A7
+    # still resolve to those classic-ESP32 phantom values via the base-pins
+    # fallback (a disclosed residual, not fixable without editing ESP32_BASE_PINS).
+    "seeed_xiao_esp32s3": {
+        "D0": 1,
+        "D1": 2,
+        "D2": 3,
+        "D3": 4,
+        "D4": 5,
+        "D5": 6,
+        "D6": 43,
+        "D7": 44,
+        "D8": 7,
+        "D9": 8,
+        "D10": 9,
+        "BOOT": 0,
+        "LED": 21,
+        "LED_BUILTIN": 21,
+        "TX": 43,
+        "RX": 44,
+        "SDA": 5,
+        "SCL": 6,
+        "SCK": 7,
+        "MISO": 8,
+        "MOSI": 9,
+        "A0": 1,
+        "A1": 2,
+        "A2": 3,
+        "A3": 4,
+        "A4": 5,
+        "A5": 6,
+        "A8": 7,
+        "A9": 8,
+        "A10": 9,
     },
     "sg-o_airMon": {},
     "sparkfun_lora_gateway_1-channel": {"MISO": 12, "MOSI": 13, "SCK": 14, "SS": 16},