故障排除

Edit this page on GitHub

故障排除

本指南帮助您诊断和调试 ESPHome 设备问题，特别是崩溃和启动失败。无论您遇到随机复位、看门狗超时，还是需要分析堆栈跟踪，本指南都提供了逐步说明，用于捕获和理解崩溃数据。

ℹ️ Note

本指南假定您已安装 ESPHome 并对命令行有基本的熟悉。有关安装说明，请参阅 手动安装 ESPHome。

从崩溃中获取堆栈跟踪

当您的 ESPHome 设备崩溃时，您可以获取解码的堆栈跟踪，以帮助识别原因。这需要：

  1. 本地编译固件（以匹配调试符号）
  2. 通过 USB 线连接设备以进行串行控制台访问
  3. 运行日志命令以捕获和解码崩溃

获取堆栈跟踪的步骤

  1. 本地编译：在您的本地计算机上构建您的配置，以确保您有匹配的调试符号。

    如果您使用 ESPHome 设备构建器网页界面：

    • 点击您设备旁边的溢出菜单（三个点）
    • 选择“下载 YAML”以获取您的配置文件
    • 将其保存到本地目录

    然后，使用命令行界面（有关完整详细信息，请参阅 命令行界面 指南）：

    esphome compile your-device.yaml
esphome upload your-device.yaml

ℹ️ Note

虽然您可以使用 OTA 进行上传，但在下一步中捕获崩溃输出时，您仍然需要 USB 连接，因此通过 USB 上传通常更方便。

  1. 通过 USB 连接：使用 USB 线将您的设备连接到计算机。设备必须通过串行控制台（而不是通过 WiFi/OTA）连接，以捕获崩溃输出。

  2. 监控日志：运行日志命令以监控设备输出：

    esphome logs your-device.yaml

  3. 等待崩溃：当设备崩溃时，ESPHome 将自动检测并解码堆栈跟踪。您将看到类似以下输出：

    [08:17:06]E (5906) task_wdt: Task watchdog got triggered. The following tasks/users did not reset the watchdog in time:
[08:17:06]E (5906) task_wdt:  - loopTask (CPU 0)
[08:17:06]E (5906) task_wdt: Tasks currently running:
[08:17:06]E (5906) task_wdt: CPU 0: esp_timer
[08:17:06]E (5906) task_wdt: CPU 1: IDLE1
[08:17:06]E (5906) task_wdt: Aborting.
[08:17:06]E (5906) task_wdt: Print CPU 0 (current core) backtrace

[08:17:06]Backtrace: 0x4013d30e:0x3ffbac20 0x4013d383:0x3ffbac40 0x4014b23e:0x3ffbac70
WARNING Found stack trace! Trying to decode it
WARNING Decoded 0x4013d30e: touch_ll_is_measure_done at /Users/bdraco/.platformio/packages/framework-espidf/components/hal/esp32/include/hal/touch_sensor_ll.h:505
      (inlined by) _touch_pad_read at /Users/bdraco/.platformio/packages/framework-espidf/components/driver/touch_sensor/esp32/touch_sensor.c:365
WARNING Decoded 0x4013d383: touch_pad_filter_cb at /Users/bdraco/.platformio/packages/framework-espidf/components/driver/touch_sensor/esp32/touch_sensor.c:108
      (inlined by) touch_pad_filter_cb at /Users/bdraco/.platformio/packages/framework-espidf/components/driver/touch_sensor/esp32/touch_sensor.c:98
WARNING Decoded 0x4014b23e: timer_process_alarm at /Users/bdraco/.platformio/packages/framework-espidf/components/esp_timer/src/esp_timer.c:456
      (inlined by) timer_task at /Users/bdraco/.platformio/packages/framework-espidf/components/esp_timer/src/esp_timer.c:482

    解码的堆栈跟踪显示：

    • 崩溃发生的确切函数名称和源文件
    • 源代码中的行号
    • 导致崩溃的调用堆栈

    ℹ️ Note

    重要：在捕获崩溃之前，您必须本地编译并上传固件。调试符号必须与正在运行的固件匹配，才能正确解码堆栈跟踪。

常见问题

  • 没有解码输出：确保您在捕获崩溃之前本地编译并上传了固件
  • 无法连接：确保您使用的是 USB 数据线（而不仅仅是充电线）并选择了正确的串行端口

替代方案：基于网络的堆栈跟踪解码器

如果您已经有了堆栈跟踪但需要解码，您可以使用 ESP 堆栈跟踪解码器网页工具：

  1. 下载 .elf 文件：从 ESPHome 仪表板中，点击您的设备卡片旁边的溢出菜单（三个点）并选择“下载 .elf 文件”

    ℹ️ Note

    .elf 文件必须来自与当前运行在您设备上的固件相同的编译。如果您在擦除后重新编译，调试符号将不匹配。

  2. 打开解码器：导航到 https://esphome.github.io/esp-stacktrace-decoder/

  3. 上传文件：

    • 在“ELF 文件”下点击“选择文件”并选择您下载的 .elf 文件
    • 将您的堆栈跟踪粘贴到文本区域
    • 点击“解码堆栈跟踪”

  4. 查看结果：该工具将解码地址并显示您函数名称、文件路径和行号

    ℹ️ Note

    此工具完全在您的浏览器中运行——没有数据发送到任何服务器，确保您的固件和调试信息保持私密。

性能故障排除

如果您的设备遇到性能问题，例如：

  • 响应时间慢
  • 丢失传感器读数
  • 连接问题
  • 组件未按预期更新

Runtime Statistics 组件可以帮助您识别哪些组件消耗了最多的处理时间或阻塞了事件循环。有关详细的使用说明和示例，请参阅 runtime_stats 文档。

参见

故障排除

Edit this page on GitHub