arduino-esp32 复位原因(Reset Reason)完全指南:用 rtc_get_reset_reason 与 esp_reset_reason 定位设备重启根因
arduino-esp32 复位原因(Reset Reason)完全指南:用 rtc_get_reset_reason 与 esp_reset_reason 定位设备重启根因
导读
在 ESP32 系列开发中,设备意外重启、反复复位是定位难度最高的故障之一:是上电复位、看门狗超时、深度睡眠唤醒,还是电压跌落?本指南以 arduino-esp32 核心的 reset_reason 官方文档 为骨架,结合仓库自带的 ResetReason.ino 与 ResetReason2.ino 两个官方示例,完整讲解两类复位原因查询 API、16 种底层复位原因码的对照关系,以及它们在深度睡眠唤醒、看门狗复位等真实场景中的使用方式。读完本文,你将能在自己的固件中快速打印并解读设备每一次重启的真正原因。
Reset Reason:为什么需要知道设备为何重启
嵌入式设备的重启原因五花八门,但多数开发者往往只注意到"设备又重启了",却难以回答"它为什么重启"。ESP32 的 ROM 与 RTC 模块在硬件层面记录了最近一次复位的原因,这些信息在芯片复位后依然保留,使得我们可以在固件启动早期查询到本次启动的来龙去脉。
在 arduino-esp32 中,读取复位原因最直接的两个入口分别是:
rtc_get_reset_reason(int cpu):读取指定 CPU 内核(0 或 1)的底层复位原因码,属于 ROM 层 API,返回 1~16 的整数码;esp_reset_reason():ESP-IDF 系统层的封装 API,返回esp_reset_reason_t枚举,语义更贴近开发者直觉。
两个官方示例分别演示了这两条路径,这也是本文讲解的两条主线。
示例一:ResetReason.ino —— 读取并打印两个 CPU 的复位原因
ResetReason.ino 是仓库中与文档直接关联的示例,其核心思路非常简洁:调用 rtc_get_reset_reason(0) 与 rtc_get_reset_reason(1) 分别获取 CPU0 与 CPU1 的复位原因,再通过两个 switch 函数将其翻译成人可读的文本输出到串口。
按芯片型号选择头文件
由于 ESP32 家族不同芯片的 ROM 头文件路径不同,示例开头用条件编译按目标芯片引入正确的头文件:
#if CONFIG_IDF_TARGET_ESP32 // ESP32/PICO-D4
#include "esp32/rom/rtc.h"
#elif CONFIG_IDF_TARGET_ESP32S2
#include "esp32s2/rom/rtc.h"
#elif CONFIG_IDF_TARGET_ESP32C2
#include "esp32c2/rom/rtc.h"
#elif CONFIG_IDF_TARGET_ESP32C3
#include "esp32c3/rom/rtc.h"
#elif CONFIG_IDF_TARGET_ESP32S3
#include "esp32s3/rom/rtc.h"
#elif CONFIG_IDF_TARGET_ESP32C6
#include "esp32c6/rom/rtc.h"
#elif CONFIG_IDF_TARGET_ESP32H2
#include "esp32h2/rom/rtc.h"
#elif CONFIG_IDF_TARGET_ESP32P4
#include "esp32p4/rom/rtc.h"
#elif CONFIG_IDF_TARGET_ESP32C5
#include "esp32c5/rom/rtc.h"
#elif CONFIG_IDF_TARGET_ESP32C61
#include "esp32c61/rom/rtc.h"
#else
#error Target CONFIG_IDF_TARGET is not supported
#endif
这段代码覆盖了 ESP32 / PICO-D4、ESP32-S2/S3、ESP32-C2/C3/C5/C6/C61/H2、ESP32-P4 等当前仓库支持的主要芯片型号,若目标型号不在列表中会直接触发编译错误 #error,避免在错误的头文件上静默失败。这一点在移植示例到新芯片时尤其值得注意。
print_reset_reason:短名称输出
示例提供了两种输出风格。第一种输出复位原因的短名称(即 IDF/ROM 中的宏名):
void print_reset_reason(int reason) {
switch (reason) {
case 1: Serial.println("POWERON_RESET"); break; /**<1, Vbat power on reset*/
case 3: Serial.println("SW_RESET"); break; /**<3, Software reset digital core*/
case 4: Serial.println("OWDT_RESET"); break; /**<4, Legacy watch dog reset digital core*/
case 5: Serial.println("DEEPSLEEP_RESET"); break; /**<5, Deep Sleep reset digital core*/
case 6: Serial.println("SDIO_RESET"); break; /**<6, Reset by SLC module, reset digital core*/
case 7: Serial.println("TG0WDT_SYS_RESET"); break; /**<7, Timer Group0 Watch dog reset digital core*/
case 8: Serial.println("TG1WDT_SYS_RESET"); break; /**<8, Timer Group1 Watch dog reset digital core*/
case 9: Serial.println("RTCWDT_SYS_RESET"); break; /**<9, RTC Watch dog Reset digital core*/
case 10: Serial.println("INTRUSION_RESET"); break; /**<10, Instrusion tested to reset CPU*/
case 11: Serial.println("TGWDT_CPU_RESET"); break; /**<11, Time Group reset CPU*/
case 12: Serial.println("SW_CPU_RESET"); break; /**<12, Software reset CPU*/
case 13: Serial.println("RTCWDT_CPU_RESET"); break; /**<13, RTC Watch dog Reset CPU*/
case 14: Serial.println("EXT_CPU_RESET"); break; /**<14, for APP CPU, reset by PRO CPU*/
case 15: Serial.println("RTCWDT_BROWN_OUT_RESET"); break; /**<15, Reset when the vdd voltage is not stable*/
case 16: Serial.println("RTCWDT_RTC_RESET"); break; /**<16, RTC Watch dog reset digital core and rtc module*/
default: Serial.println("NO_MEAN");
}
}
verbose_print_reset_reason:详细描述输出
第二种风格输出同一原因码的人类可读描述,便于直接阅读日志:
void verbose_print_reset_reason(int reason) {
switch (reason) {
case 1: Serial.println("Vbat power on reset"); break;
case 3: Serial.println("Software reset digital core"); break;
case 4: Serial.println("Legacy watch dog reset digital core"); break;
case 5: Serial.println("Deep Sleep reset digital core"); break;
case 6: Serial.println("Reset by SLC module, reset digital core"); break;
case 7: Serial.println("Timer Group0 Watch dog reset digital core"); break;
case 8: Serial.println("Timer Group1 Watch dog reset digital core"); break;
case 9: Serial.println("RTC Watch dog Reset digital core"); break;
case 10: Serial.println("Instrusion tested to reset CPU"); break;
case 11: Serial.println("Time Group reset CPU"); break;
case 12: Serial.println("Software reset CPU"); break;
case 13: Serial.println("RTC Watch dog Reset CPU"); break;
case 14: Serial.println("for APP CPU, reset by PRO CPU"); break;
case 15: Serial.println("Reset when the vdd voltage is not stable"); break;
case 16: Serial.println("RTC Watch dog reset digital core and rtc module"); break;
default: Serial.println("NO_MEAN");
}
}
setup 中的主流程
void setup() {
Serial.begin(115200);
delay(2000);
Serial.println("CPU0 reset reason:");
print_reset_reason(rtc_get_reset_reason(0));
verbose_print_reset_reason(rtc_get_reset_reason(0));
Serial.println("CPU1 reset reason:");
print_reset_reason(rtc_get_reset_reason(1));
verbose_print_reset_reason(rtc_get_reset_reason(1));
...
}
需要留意的是示例开头 delay(2000) 的作用:ESP32 复位后立即打印时,串口监视器往往尚未连接,两秒延迟可以保证日志被完整捕获(在 ResetReason2.ino 中甚至专门针对上电复位做了 delay(6000))。参数 0 表示 PRO CPU,1 表示 APP CPU;对单核芯片而言,CPU1 的查询仍然被保留,只是含义可能不适用。
底层复位原因码对照表
综合示例源码,rtc_get_reset_reason() 返回的整数原因码与含义对应关系如下(这是 ESP32 ROM 层的复位原因码,也是本文档与示例共同的核心内容):
| 原因码 | 宏名称 | 详细含义 |
|---|---|---|
| 1 | POWERON_RESET | Vbat 上电复位(芯片首次上电) |
| 3 | SW_RESET | 软件复位数字内核(如调用 esp_restart) |
| 4 | OWDT_RESET | 传统看门狗复位数字内核 |
| 5 | DEEPSLEEP_RESET | 深度睡眠唤醒导致的数字内核复位 |
| 6 | SDIO_RESET | 由 SLC 模块触发的数字内核复位 |
| 7 | TG0WDT_SYS_RESET | Timer Group 0 看门狗复位数字内核 |
| 8 | TG1WDT_SYS_RESET | Timer Group 1 看门狗复位数字内核 |
| 9 | RTCWDT_SYS_RESET | RTC 看门狗复位数字内核 |
| 10 | INTRUSION_RESET | 入侵(intrusion)测试复位 CPU |
| 11 | TGWDT_CPU_RESET | 定时器组看门狗复位 CPU |
| 12 | SW_CPU_RESET | 软件复位 CPU |
| 13 | RTCWDT_CPU_RESET | RTC 看门狗复位 CPU |
| 14 | EXT_CPU_RESET | APP CPU 被 PRO CPU 复位 |
| 15 | RTCWDT_BROWN_OUT_RESET | 电源电压(VDD)不稳定时触发复位 |
| 16 | RTCWDT_RTC_RESET | RTC 看门狗同时复位数字内核与 RTC 模块 |
| 其他 | NO_MEAN | 未知或未定义原因 |
实际使用中的几个高频项值得特别关注:
- 原因码 5(DEEPSLEEP_RESET):设备从深度睡眠被唤醒时必然出现,是判断"是否正常从睡眠唤醒"的直接依据;
- 原因码 9 / 7 / 8(各类看门狗复位):说明固件存在死循环或任务饥饿问题,需要结合看门狗配置排查;
- 原因码 15(BROWN_OUT_RESET):供电电压不稳定导致,通常是电源设计问题而非软件缺陷;
- 原因码 14(EXT_CPU_RESET):双核场景下 APP CPU 被 PRO CPU 复位,是 CPU1 最常见的复位来源。
运行输出解析:从串口日志看懂两次复位
示例文件末尾附带了完整的串口日志,直观展示了"上电复位 → 深度睡眠 → 再次唤醒"的完整过程。首次上电时的日志片段:
rst:0x10 (RTCWDT_RTC_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
...
CPU0 reset reason:
RTCWDT_RTC_RESET
RTC Watch dog reset digital core and rtc module
CPU1 reset reason:
EXT_CPU_RESET
for APP CPU, reset by PRO CPU
Going to sleep
注意启动首行的 rst:0x10 (RTCWDT_RTC_RESET) 是 ROM 引导打印的复位原因缩写,与代码中查询到的原因码 16 完全对应,两个信息来源可以互相印证。
进入深度睡眠 5 秒后再次唤醒,日志变为:
rst:0x5 (DEEPSLEEP_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
...
CPU0 reset reason:
DEEPSLEEP_RESET
Deep Sleep reset digital core
CPU1 reset reason:
EXT_CPU_RESET
for APP CPU, reset by PRO CPU
Going to sleep
这一组对比清楚地演示了:同一块板卡、同一份固件,仅仅因为"上次是怎么复位的"不同,rst:0x 与 rtc_get_reset_reason() 的结果就完全不同——这正是复位原因机制的价值所在。
深度睡眠触发部分的细节
示例在打印复位原因之后,主动让设备进入 5 秒深度睡眠,以便观察原因码从 RTCWDT_RTC_RESET 变为 DEEPSLEEP_RESET:
#define uS_TO_S_FACTOR 1000000 /* Conversion factor for micro seconds to seconds */
#ifndef CONFIG_IDF_TARGET_ESP32H2
// Set ESP32 to go to deep sleep to see a variation
// in the reset reason. Device will sleep for 5 seconds.
#if CONFIG_IDF_TARGET_ESP32C3 || CONFIG_IDF_TARGET_ESP32H2
esp_sleep_pd_config(ESP_PD_DOMAIN_RC_FAST, ESP_PD_OPTION_OFF);
#else
esp_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_OFF);
#endif
Serial.println("Going to sleep");
esp_deep_sleep(5 * uS_TO_S_FACTOR);
#endif
这里有两个工程细节值得展开:
- 休眠前先关闭外设电源域:通过
esp_sleep_pd_config()在深度睡眠期间关闭RTC_PERIPH(多数芯片)或RC_FAST(ESP32-C3/H2)电源域,进一步降低休眠功耗,也让示例更接近真实低功耗产品的配置方式; - 睡眠时长的换算:
esp_deep_sleep()的单位是微秒,示例用uS_TO_S_FACTOR(1000000)将 5 秒换算为5 * 1000000微秒传入。
需要注意的是,整个深度睡眠演示在 ESP32-H2 上被 #ifndef CONFIG_IDF_TARGET_ESP32H2 屏蔽——这是示例作者针对该芯片电源域差异(H2 同样走 RC_FAST 分支,条件编译内层也包含 H2)所作的兼容处理,迁移到其他芯片时应参考对应芯片的 ROM/电源管理文档。
示例二:ResetReason2.ino —— 使用 esp_reset_reason() 与任务看门狗
ResetReason2.ino 提供了另一种思路:调用 ESP-IDF 系统层的 esp_reset_reason() 获取 esp_reset_reason_t 枚举,并通过故意不喂狗的方式制造一次任务看门狗(Task WDT)复位,演示"崩溃/看门狗"类复位的识别。
esp_reset_reason_t 枚举对照
示例中的 resetReasonName() 函数将枚举翻译为字符串:
const char *resetReasonName(esp_reset_reason_t r) {
switch (r) {
case ESP_RST_UNKNOWN: return "Unknown";
case ESP_RST_POWERON: return "PowerOn"; //Power on or RST pin toggled
case ESP_RST_EXT: return "ExtPin"; //External pin - not applicable for ESP32
case ESP_RST_SW: return "Reboot"; //esp_restart()
case ESP_RST_PANIC: return "Crash"; //Exception/panic
case ESP_RST_INT_WDT: return "WDT_Int"; //Interrupt watchdog (software or hardware)
case ESP_RST_TASK_WDT: return "WDT_Task"; //Task watchdog
case ESP_RST_WDT: return "WDT_Other"; //Other watchdog
case ESP_RST_DEEPSLEEP: return "Sleep"; //Reset after exiting deep sleep mode
case ESP_RST_BROWNOUT: return "BrownOut"; //Brownout reset (software or hardware)
case ESP_RST_SDIO: return "SDIO"; //Reset over SDIO
default: return "";
}
}
与 ROM 层 16 个细粒度原因码不同,esp_reset_reason_t 将原因归并为 11 类更宏观的语义,其中几个对排障尤其关键:
ESP_RST_PANIC(Crash):发生异常/崩溃(panic)后复位,是最常见的"设备莫名其妙重启"元凶;ESP_RST_TASK_WDT(WDT_Task):任务看门狗超时复位,说明某个任务长时间占用 CPU 未让出;ESP_RST_INT_WDT(WDT_Int):中断看门狗复位;ESP_RST_BROWNOUT(BrownOut):欠压复位;ESP_RST_DEEPSLEEP(Sleep):深度睡眠唤醒复位。
打印复位原因并故意触发 WDT
void PrintResetReason(void) {
esp_reset_reason_t r = esp_reset_reason();
if (r == ESP_RST_POWERON) {
delay(6000); //Wait for serial monitor to connect
}
Serial.printf("\r\nReset reason %i - %s\r\n", r, resetReasonName(r));
}
void setup() {
Serial.begin(115200);
PrintResetReason();
//Start WDT monitor
if (esp_task_wdt_add(NULL) != ESP_OK) {
log_e("Failed to add current task to WDT");
}
}
//Enable esp_task_wdt_reset() below to prevent a WDT reset
void loop() {
Serial.printf("Alive %lums\r\n", millis());
//esp_task_wdt_reset();
delay(1000); //1s delay
}
这里的两个细节直接对应 arduino-esp32 核心源码:
- 上电复位时多等 6 秒:
ESP_RST_POWERON场景下串口监视器通常还未连接,示例刻意等待 6 秒再打印,保证关键信息不丢失; - 为什么不用 enableLoopWDT():示例注释明确指出,
enableLoopWDT()不可用于本演示,因为该函数会在 main.cpp 的loopTask()中周期性调用esp_task_wdt_reset()自动喂狗——从 main.cpp 源码可见,loopTask在loopTaskWDTEnabled标志开启时会于每次循环调用esp_task_wdt_reset()(见 main.cpp),这正是它"顺带把看门狗喂了"的原因。
示例先用 esp_task_wdt_add(NULL) 将当前(loop)任务注册进任务看门狗监控,然后在 loop() 中刻意不调用 esp_task_wdt_reset(),只打印 Alive xxxms 并延迟 1 秒。约 10 秒后任务看门狗超时,芯片复位;重启后 esp_reset_reason() 便会返回 ESP_RST_TASK_WDT,串口输出形如:
Reset reason 7 - WDT_Task
两种 API 的选型建议
| 维度 | rtc_get_reset_reason(cpu) | esp_reset_reason() |
|---|---|---|
| 来源层次 | ROM 层(RTC 寄存器) | ESP-IDF 系统层封装 |
| 返回值 | 1~16 整数原因码 | esp_reset_reason_t 枚举(11 类) |
| 粒度 | 细(区分 TG0/TG1/RTC 各看门狗、各 CPU) | 粗(归并为宏观类别) |
| 可读性 | 需自行映射为字符串 | 语义直观,便于打印 |
| 适用场景 | 深入排查硬件级复位细节、区分具体看门狗来源 | 快速判断崩溃、看门狗、深睡、欠压等大类原因 |
从源码结构看,rtc_get_reset_reason 直接读取 RTC 寄存器中的复位状态字,因此能区分"哪个看门狗、复位了哪个内核"这样的硬件细节;而 esp_reset_reason() 属于系统层 API,更适合在应用代码中快速获得一个可读、可归档的结论。两者打印的复位原因在正常情况下应互相印证(例如示例一日志中 rst:0x10 与原因码 16 的对应关系)。
与核心库的衔接:ESP.deepSleep 与重启
复位原因机制与 arduino-esp32 的电源管理 API 紧密相关。核心库在 Esp.cpp 中封装了 ESP 类:
void EspClass::deepSleep(uint64_t time_us) {
esp_deep_sleep(time_us);
}
void EspClass::restart(void) {
esp_restart();
}
可以看到 ESP.deepSleep() 直接透传调用 IDF 的 esp_deep_sleep(),而 ESP.restart() 调用 esp_restart()。理解这条调用链的意义在于:你可以通过复位原因反过来确认——若日志显示 DEEPSLEEP_RESET,说明设备确实经历了 esp_deep_sleep() 流程(无论该调用来自 ESP.deepSleep() 还是其他路径);若显示 SW_RESET(或 ESP_RST_SW),则对应 esp_restart()/ESP.restart() 软件重启。复位原因因此成为验证电源管理代码是否按预期执行的"事后证据"。
实际工程中的应用建议
综合上述原理,建议在真实固件中这样使用复位原因:
- 启动早期打印并归档:在
setup()最开头(串口就绪后)打印复位原因,配合rst:0x引导日志交叉验证;对ESP_RST_POWERON可适当延迟等待串口监视器连接; - 按原因分流处理:例如根据复位原因决定是否执行某些初始化(欠压复位后降频、崩溃复位后记录错误标志等);
- 区分可预期与异常复位:
DEEPSLEEP_RESET属于正常唤醒路径,而持续出现的TG0WDT_SYS_RESET、ESP_RST_TASK_WDT往往意味着固件存在任务饿死或死循环,需要优先排查; - 多芯片兼容:参考 ResetReason.ino 中按
CONFIG_IDF_TARGET_*条件包含不同 ROM 头文件的做法,保证代码在不同 ESP32 型号间可移植。
延伸阅读
- 复位原因官方文档:docs/en/api/reset_reason.rst
- 示例一(ROM 层 API):libraries/ESP32/examples/ResetReason/ResetReason/ResetReason.ino
- 示例二(系统层 API + 任务看门狗):libraries/ESP32/examples/ResetReason/ResetReason2/ResetReason2.ino
- 深度睡眠封装实现:cores/esp32/Esp.cpp
- 任务看门狗喂狗逻辑:cores/esp32/main.cpp
- 官方文档贡献指南:docs/en/contributing.rst
需要说明的是,本文对应的官方文档页面仍标注为"work in progress"状态,正文核心内容即文档中嵌入的 ResetReason 示例;本文在此基础上结合仓库源码与第二个示例进行了完整展开,帮助你无需等待文档完善即可直接上手。