跳转到内容
ESPHome - 让智能家居更简单2026.7.0

Debug 组件

debug 组件可用于排查 ESPHome 的问题。在启动时，它会打印 一系列有用的信息，如复位原因、空闲堆大小、ESPHome 版本等。 它还允许您以文本传感器的形式获取相同信息，并监控 ESP 堆内存的状态（空闲空间、最大空闲块大小和碎片化程度）以及主循环的时序。可通过 logger 或 Web 服务器组件（如果已配置）进行监控。

debug 组件输出示例。
# Example configuration entry
debug:
  update_interval: 5s


text_sensor:
  - platform: debug
    device:
      name: "Device Info"
    reset_reason:
      name: "Reset Reason"


sensor:
  - platform: debug
    free:
      name: "Heap Free"
    block:
      name: "Heap Max Block"
    min_free:
      name: "Heap Min Free"
    fragmentation:
      name: "Heap Fragmentation"
    loop_time:
      name: "Loop Time"
    psram:
      name: "Free PSRAM"
    cpu_frequency:
      name: "CPU Frequency"

文本传感器

Section titled “文本传感器”

配置变量

Section titled “配置变量”

  • device (可选)：报告以下设备信息：

    • ESPHome 版本

    • 启动时空闲的堆大小

    • 闪存芯片的大小、速度和模式

    • ESP32：

      • 芯片型号、核心数、修订版本
      • 芯片特性（BLE / BT / WiFi_BGN / EMB_FLASH / EMB_PSRAM / …）
      • ESP-IDF 版本
      • EFuse MAC
      • 复位原因
      • 唤醒原因

    • ESP8266：

      • 芯片 ID、频率
      • 闪存 ID
      • SDK、Core 与 Boot 版本
      • 复位原因与信息

    接受文本传感器的所有选项。

  • reset_reason (可选)：以人类可读的形式报告最近一次的复位原因。接受文本传感器的所有选项。

传感器

Section titled “传感器”

配置变量

Section titled “配置变量”

  • free (可选)：报告空闲堆大小，单位为字节。传感器的所有选项。

  • block (可选)：报告堆上最大的连续空闲 RAM 块，单位为字节。传感器的所有选项。

  • min_free (可选)：报告自启动以来最小的空闲堆大小，单位为字节。这对于检测内存泄漏或高水位线使用情况很有用。仅 ESP32 和 LibreTiny 可用。传感器的所有选项。

  • fragmentation (可选)：报告堆的碎片化指标 （0% 表示干净，超过约 50% 可能导致分配失败）。在运行 Arduino 2.5.2 及以上版本的 ESP8266 和 ESP32 上可用。 传感器的所有选项。

  • loop_time (可选)：报告主循环连续两次迭代之间的最长耗时。传感器的所有选项。

  • psram (可选)：报告空闲的 PSRAM，单位为字节。仅 ESP32 可用。传感器的所有选项。

  • cpu_frequency (可选)：报告 CPU 频率，单位为 Hz。传感器的所有选项。

Zephyr

Section titled “Zephyr”

该组件为运行在 Zephyr RTOS 上的 ESPHome 设备启用调试功能。 它有助于通过 SWD（串行线调试，Serial Wire Debug） 进行底层固件调试。它启用：

  • GDB 中的线程感知 在 Zephyr 中注入线程元数据，以便通过 SWD 连接后可以在 GDB 中检查所有活动线程。

  • 通过 RTT 的实时日志 启用通过 SEGGER RTT（实时传输，Real Time Transfer）输出日志，允许通过 SWD 进行非侵入式调试日志。

另请参阅

Section titled “另请参阅”