From d7c42bc9ec72f02ca802f75152bb869734e30d05 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Sat, 14 Mar 2026 13:38:51 -1000
Subject: [PATCH] [debug] Fix ESP-IDF 6.0 compatibility for wakeup cause API
 (#14812)

---
 esphome/components/debug/debug_esp32.cpp | 85 ++++++++++++++++++------
 1 file changed, 64 insertions(+), 21 deletions(-)

diff --git a/esphome/components/debug/debug_esp32.cpp b/esphome/components/debug/debug_esp32.cpp
index c9df4fdf21..aa379599c6 100644
--- a/esphome/components/debug/debug_esp32.cpp
+++ b/esphome/components/debug/debug_esp32.cpp
@@ -5,6 +5,7 @@
 #include "esphome/core/log.h"
 #include "esphome/core/hal.h"
 #include <esp_sleep.h>
+#include <esp_idf_version.h>
 
 #include <esp_heap_caps.h>
 #include <esp_system.h>
@@ -82,32 +83,74 @@ const char *DebugComponent::get_reset_reason_(std::span<char, RESET_REASON_BUFFE
   return buf;
 }
 
+#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(6, 0, 0)
 static const char *const WAKEUP_CAUSES[] = {
-    "undefined",
-    "undefined",
-    "external signal using RTC_IO",
-    "external signal using RTC_CNTL",
-    "timer",
-    "touchpad",
-    "ULP program",
-    "GPIO",
-    "UART",
-    "WIFI",
-    "COCPU int",
-    "COCPU crash",
-    "BT",
+    "undefined",                       // ESP_SLEEP_WAKEUP_UNDEFINED (0)
+    "undefined",                       // ESP_SLEEP_WAKEUP_ALL (1)
+    "external signal using RTC_IO",    // ESP_SLEEP_WAKEUP_EXT0 (2)
+    "external signal using RTC_CNTL",  // ESP_SLEEP_WAKEUP_EXT1 (3)
+    "timer",                           // ESP_SLEEP_WAKEUP_TIMER (4)
+    "touchpad",                        // ESP_SLEEP_WAKEUP_TOUCHPAD (5)
+    "ULP program",                     // ESP_SLEEP_WAKEUP_ULP (6)
+    "GPIO",                            // ESP_SLEEP_WAKEUP_GPIO (7)
+    "UART",                            // ESP_SLEEP_WAKEUP_UART (8)
+    "UART1",                           // ESP_SLEEP_WAKEUP_UART1 (9)
+    "UART2",                           // ESP_SLEEP_WAKEUP_UART2 (10)
+    "WIFI",                            // ESP_SLEEP_WAKEUP_WIFI (11)
+    "COCPU int",                       // ESP_SLEEP_WAKEUP_COCPU (12)
+    "COCPU crash",                     // ESP_SLEEP_WAKEUP_COCPU_TRAP_TRIG (13)
+    "BT",                              // ESP_SLEEP_WAKEUP_BT (14)
+    "VAD",                             // ESP_SLEEP_WAKEUP_VAD (15)
+    "VBAT under voltage",              // ESP_SLEEP_WAKEUP_VBAT_UNDER_VOLT (16)
 };
+#else
+static const char *const WAKEUP_CAUSES[] = {
+    "undefined",                       // ESP_SLEEP_WAKEUP_UNDEFINED (0)
+    "undefined",                       // ESP_SLEEP_WAKEUP_ALL (1)
+    "external signal using RTC_IO",    // ESP_SLEEP_WAKEUP_EXT0 (2)
+    "external signal using RTC_CNTL",  // ESP_SLEEP_WAKEUP_EXT1 (3)
+    "timer",                           // ESP_SLEEP_WAKEUP_TIMER (4)
+    "touchpad",                        // ESP_SLEEP_WAKEUP_TOUCHPAD (5)
+    "ULP program",                     // ESP_SLEEP_WAKEUP_ULP (6)
+    "GPIO",                            // ESP_SLEEP_WAKEUP_GPIO (7)
+    "UART",                            // ESP_SLEEP_WAKEUP_UART (8)
+    "WIFI",                            // ESP_SLEEP_WAKEUP_WIFI (9)
+    "COCPU int",                       // ESP_SLEEP_WAKEUP_COCPU (10)
+    "COCPU crash",                     // ESP_SLEEP_WAKEUP_COCPU_TRAP_TRIG (11)
+    "BT",                              // ESP_SLEEP_WAKEUP_BT (12)
+};
+#endif
 
 const char *DebugComponent::get_wakeup_cause_(std::span<char, WAKEUP_CAUSE_BUFFER_SIZE> buffer) {
-  const char *wake_reason;
-  unsigned reason = esp_sleep_get_wakeup_cause();
-  if (reason < sizeof(WAKEUP_CAUSES) / sizeof(WAKEUP_CAUSES[0])) {
-    wake_reason = WAKEUP_CAUSES[reason];
-  } else {
-    wake_reason = "unknown source";
+  static constexpr auto NUM_CAUSES = sizeof(WAKEUP_CAUSES) / sizeof(WAKEUP_CAUSES[0]);
+#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(6, 0, 0)
+  // IDF 6.0+ returns a bitmap of all wakeup sources
+  uint32_t causes = esp_sleep_get_wakeup_causes();
+  if (causes == 0) {
+    return WAKEUP_CAUSES[0];  // "undefined"
   }
-  // Return the static string directly - no need to copy to buffer
-  return wake_reason;
+  char *p = buffer.data();
+  char *end = p + buffer.size();
+  *p = '\0';
+  const char *sep = "";
+  for (unsigned i = 0; i < NUM_CAUSES && p < end; i++) {
+    if (causes & (1U << i)) {
+      size_t needed = strlen(sep) + strlen(WAKEUP_CAUSES[i]);
+      if (p + needed >= end) {
+        break;
+      }
+      p += snprintf(p, end - p, "%s%s", sep, WAKEUP_CAUSES[i]);
+      sep = ", ";
+    }
+  }
+  return buffer.data();
+#else
+  unsigned reason = esp_sleep_get_wakeup_cause();
+  if (reason < NUM_CAUSES) {
+    return WAKEUP_CAUSES[reason];
+  }
+  return "unknown source";
+#endif
 }
 
 void DebugComponent::log_partition_info_() {