arduino-esp32 复位原因(Reset Reason)完全指南:用 rtc_get_reset_reason 与 esp_reset_reason 定位设备重启根因

原创2026-09-13 22:23:291,698 阅读
文章标签:嵌入式物联网固件硬件开发蓝牙网络

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

这里有两个工程细节值得展开:

  1. 休眠前先关闭外设电源域:通过 esp_sleep_pd_config() 在深度睡眠期间关闭 RTC_PERIPH(多数芯片)或 RC_FAST(ESP32-C3/H2)电源域,进一步降低休眠功耗,也让示例更接近真实低功耗产品的配置方式;
  2. 睡眠时长的换算: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 核心源码:

  1. 上电复位时多等 6 秒:ESP_RST_POWERON 场景下串口监视器通常还未连接,示例刻意等待 6 秒再打印,保证关键信息不丢失;
  2. 为什么不用 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() 软件重启。复位原因因此成为验证电源管理代码是否按预期执行的"事后证据"。

实际工程中的应用建议

综合上述原理,建议在真实固件中这样使用复位原因:

  1. 启动早期打印并归档:在 setup() 最开头(串口就绪后)打印复位原因,配合 rst:0x 引导日志交叉验证;对 ESP_RST_POWERON 可适当延迟等待串口监视器连接;
  2. 按原因分流处理:例如根据复位原因决定是否执行某些初始化(欠压复位后降频、崩溃复位后记录错误标志等);
  3. 区分可预期与异常复位:DEEPSLEEP_RESET 属于正常唤醒路径,而持续出现的 TG0WDT_SYS_RESET、ESP_RST_TASK_WDT 往往意味着固件存在任务饿死或死循环,需要优先排查;
  4. 多芯片兼容:参考 ResetReason.ino 中按 CONFIG_IDF_TARGET_* 条件包含不同 ROM 头文件的做法,保证代码在不同 ESP32 型号间可移植。

延伸阅读

需要说明的是,本文对应的官方文档页面仍标注为"work in progress"状态,正文核心内容即文档中嵌入的 ResetReason 示例;本文在此基础上结合仓库源码与第二个示例进行了完整展开,帮助你无需等待文档完善即可直接上手。

登录后查看全文
arduino-esp32