常见问题

我应该为项目选择哪个 ESP？

我们经常被问到这个问题。与所有工程问题一样，“视情况而定”。ESP32 是大多数新开发工作的领先平台。根据 ESPHome 当前硬件支持的状况，以下是我们建议的：

推荐

• ESP32（原始版本，非变体）

  • 支持最好/最成熟。
  • 包含一套出色的内置硬件外设，非常强大且灵活。
  • 由于其内置的以太网 MAC，可直接连接到 PHY 芯片，因此是有线以太网连接的最佳选择。其他变体需要基于 SPI 的以太网控制器，增加了延迟。

• ESP32-S3

  • 原始 ESP32 的更新版本，具有略微修改的硬件外设集。
  • 具有内置的 USB 外设/接口（而不是依赖外部 USB 转串行芯片）。
  • 具有指令集扩展，使其更适合需要某种机器学习的应用（例如微唤醒词）。
  • 如果需要原始计算能力，这是最佳选择，具有更好的整体性能和更低的延迟。

• ESP32-C3

  • 通常（根据 Espressif 的说法）旨在取代广为人知的 ESP8266。
  • 适合较简单的项目：单核 RISC-V、更少的 GPIO 引脚，但成本和功耗低于双核 ESP32(-Sx) 变体。

• ESP32-C6

  • 类似于 ESP32-C3，但具有额外的连接选项，包括 Thread（通过 OpenThread）。
  • 适合新项目的好选择。

不推荐用于新项目

• ESP8266

  对于新项目，我们推荐使用价格相近的 ESP32-C3 替代。与 ESP8266 相比，所有 ESP32 变体具有：

  • 大约 5 倍的 RAM 量。某些组件，如大尺寸显示屏和某些传感器，可能无法在 ESP8266 上正常工作。
  • 显著更多的闪存。大多数 ESP8266 开发板有 1-2 MB，而大多数 ESP32 变体有 4 MB 或更多。
  • 更多的 GPIO 引脚和更好的硬件外设集。

  ESP8266 不符合为 ESPHome 打造的要求。

  原始的 NodeMCU、D1-Mini 和 ESP-01 是使用 ESP8266 的开发板示例。请注意，这些开发板有引脚兼容的版本，使用更现代的 ESP32 变体替代。

  尽管如此，现有的 ESP8266 设备运行良好，并将在未来几年继续得到支持。 最近的内存优化显著提高了 ESP8266 上的可用堆空间，使之前不可靠的设备现在变得稳定。如果你的 ESP8266 设备正在工作，则无需更换。

LibreTiny (BK72xx, RTL87xx, LN882x)

如果你有一个现成的智能家居设备，带有 Beken、Realtek 或 Lightning Semi 芯片， LibreTiny 使其能够在上面运行 ESPHome。这些芯片通常 不是直接购买的。相反，用户刷写包含这些芯片的现有设备。

LibreTiny 的支持已经显著成熟，这些设备通常工作良好。然而，LibreTiny 不如 ESP8266 或 ESP32 的支持成熟。

其他微控制器

对 ESP32-H2、RP2040 和其他较新芯片的支持不太成熟，因此你更有可能遇到 问题。为了获得最佳的 ESPHome 体验，我们推荐上述列出的芯片。

随着对较新微控制器的支持成熟，我们将在此更新我们的建议。

如何将 ESPHome 安装到我的设备上？

你可以直接使用 ESPHome 设备构建器；在按照你的喜好编辑设备配置后，点击”安装”并按照提示操作。请注意，首次将 ESPHome 安装到（新）设备上时，需要使用（USB）线缆连接它；此安装方法需要支持 WebSerial 的浏览器，如 Firefox、Google Chrome 或 Microsoft Edge。

如果你更喜欢手动方式：

1. 你需要获取要安装的固件文件：

   • 使用 ESPHome CLI

     构建完成后，文件位于 <CONFIG_DIR>/<NODE_NAME>/.pioenvs/<NODE_NAME>/firmware.bin 目录中。

   • 使用 ESPHome 仪表板

     1. 点击设备的三点菜单
     2. 选择”安装”
     3. 选择”手动下载”

2. 在某些开发板上，你可能需要强制微控制器进入其编程模式。 在大多数现代开发板/设备上通常不需要这样做，但如果遇到问题，值得一试。

3. 最后，要安装固件文件，你可以使用：

   • ESPHome Web，我们的基于 Web 的安装程序。这是最简单的方法，但需要支持 WebSerial 的浏览器，如 Firefox、Google Chrome 或 Microsoft Edge。

     1. 将开发板连接到计算机，确保它被检测为串行端口，然后点击连接。

     2. 如果提示，在出现的弹出窗口中允许浏览器请求的权限。

     3. 选择与你的开发板关联的串行设备

     4. 点击安装并浏览选择你之前下载的二进制文件（如上所述）。

     请注意，该文件在本地处理，不会上传到任何云服务。

   • esptool 来自 GitHub 仓库。它可能作为操作系统的软件包提供，或者你可以尝试使用 pip install esptool 安装（在 Linux 的情况下）。

什么是 esptool？

esptool 是一个命令行/终端应用程序，可用于在 Espressif 微控制器上执行各种任务。它不是最用户友好的方法，但功能相当强大，如果遇到问题可能会很有用。

NOTE

使用 esptool 之前，请确保你知道你的开发板/串行适配器连接到了哪个串行端口！

• 在 Linux 中，将设备插入 USB 端口后，可以使用 dmesg 命令查看（新）串行端口的名称。

• 在 Windows 中，查看设备管理器，看插入时是否出现新的串行端口，并记下（新）端口的 COM 编号。

擦除闪存

这将擦除微控制器的闪存——什么（设置、数据等）都不会保留！

esptool --port /dev/ttyUSB0 erase_flash

写入闪存

这将安装（“刷写”）你的二进制文件（ESPHome）到微控制器上。

esptool --port /dev/ttyUSB0 write_flash 0x0 your_node_firmware.bin

我无法通过 USB 安装成功

导致这种情况的原因有很多。

常见问题

• 你没有使用 USB 数据线。 为了降低成本，许多 USB 线缆仅设计用于电池充电，它们无法建立与开发板通信所需的数据连接。

• ESPHome 依赖于你的计算机操作系统（OS）来启用编程工具（例如 esptool.py）与微控制器板进行通信；你可能需要安装适当的驱动程序。

• 如果你尝试从 Docker 容器中将 ESPHome 安装到设备上，请确保使用 --device=/dev/ttyUSB0 将设备挂载到容器中。

esptool 故障排除

如果你只看到屏幕上显示 Connecting....____....，然后安装（“刷写”）失败：

• 验证设备端口的名称没有改变；如果你断开连接后重新连接得太快，可能会发生这种情况（例如，它可能从 /dev/ttyUSB0 变为 /dev/ttyUSB1）。

• 如果你使用外部 USB 转串行适配器，请确认线缆连接正确。适配器的接收（RX）线应连接到开发板的发送（TX）线（另一条线反之亦然）。

• 某些设备可能需要你保持 GPIO0 和 GND 连接，至少直到刷写开始。

• 某些设备可能需要你在擦除闪存后重新上电以重新启动编程模式；它们不会自动复位。

• 某些设备可能需要你双击 RST 或复位按钮。将 RST 连接到 GND，断开，然后快速重新连接并再次断开也可能有效。

• 最后但同样重要的是，这可能是你的微控制器有缺陷、损坏或无法编程的迹象。:(

如果你处于嘈杂的电气/RF 环境中，或者使用了异常长的线缆/导线，安装可能在传输过程中失败。不用担心——只需重试，也许使用较低的波特率以获得更安全的传输：

esptool.py --port /dev/ttyUSB0 --baud 115200 write_flash 0x0 your_node_firmware.bin

如果仍然无法正常工作，你可能需要重新查看上述的我无法通过 USB 安装成功部分。

使用 ESPHome 的技巧

• ESPHome 支持（大部分）Home Assistant 的 YAML 配置指令，如 !include 和 !secret。 这允许你将你的密钥（例如 Wi-Fi 密码和 API 密钥）存储在名为 secrets.yaml 的文件中，只要该文件与你的 ESPHome 配置文件位于同一目录即可。

  我们增强了 ESPHome 的 !include 指令，使其接受一个变量列表，可以在包含的文件中替换这些变量。例如：

    binary_sensor:
      - platform: gpio
        id: button1
        pin: GPIOXX
        on_multi_click: !include { file: on-multi-click.yaml, vars: { id: 1 } } # 行内语法
      - platform: gpio
        id: button2
        pin: GPIOXX
        on_multi_click: !include
          # 多行语法
          file: on-multi-click.yaml
          vars:
            id: 2

on-multi-click.yaml ：

    - timing: !include click-single.yaml
      then:
        - mqtt.publish:
            topic: ${device_name}/button${id}/status
            payload: single
    - timing: !include click-double.yaml
      then:
        - mqtt.publish:
            topic: ${device_name}/button${id}/status
            payload: double

• 你可以使用替换来构建上述示例，减少配置文件中的重复。

• 如果你想查看 ESPHome 如何解释你的配置，请运行：

    esphome config livingroom.yaml

• 要查看 ESPHome 节点的日志而不上传，请运行：

    esphome logs livingroom.yaml

• 你始终可以在 <NODE_NAME>/src/ 目录中找到 ESPHome 生成的源代码。

• 你可以在此查看命令行界面选项的完整列表：CLI

帮助！有些东西不起作用

这不太好。以下是一些解决某些问题的步骤：

• 如果你遇到 Wi-Fi 问题：请参见我的节点不断随机重新连接。
• 在你的 ESPHome 设备的 logger: 部分启用详细日志。
• 如果你的设备崩溃：请参见故障排除指南，了解如何获取回溯信息。
• 仍然看到错误？ 检查 ESPHome 问题跟踪器中是否有已知问题。如果没有，你可以创建一个新问题来描述你的问题。我们会尽快查看。谢谢！

如何报告问题？

ESPHome 是一个大型项目，许多方面已被广泛使用且已知运行良好。也就是说，某些部分使用频率较低，因此测试较少。我们尽力进行尽可能多的测试，但我们根本没有 ESPHome 支持/实现的每一种硬件。我们严重依赖社区和贡献者的测试。随着我们进行更改，某些地方可能会出现问题。问题报告是我们跟踪并（希望/最终）修复问题的重要方式。

提交问题时，尽可能详细地描述非常重要——但应避免过多无关信息。如果你希望问题快速解决：

• 仅仅写”X 不起作用”或”X 有 bug”是没有帮助的！！！ 说真的，仅凭这些信息你期望如何得到帮助？

• 提供触发问题的代码/配置片段；我们可能想要尝试重现它。请阅读如何创建最小、完整且可验证的示例。

• 如果是硬件通信问题（例如与 I²C 或 SPI 设备），尝试将日志级别设置为 VERY_VERBOSE，因为它可能提供更好的洞察。

• 请描述你已经尝试过的故障排除步骤，这也有助于我们追踪问题。

你可以在 GitHub 上找到我们的问题跟踪器。

如何更新到最新版本？

在 Home Assistant 中，当有可用更新时，会显示更新通知（与所有应用一样）。

如果你独立于 Home Assistant 运行 Docker 容器，请运行：

pip3 install -U esphome
# 从 docker：
docker pull ghcr.io/esphome/esphome:stable

如何更新到最新的测试版？

ESPHome 有测试版发布周期，以便在更改部署到稳定频道之前轻松测试新版本。你可以通过安装测试版来帮助测试 ESPHome（并使用新功能）：

• 对于 Home Assistant 监督安装，在应用商店中搜索”ESPHome”。请注意，应用名称相应命名；对于测试版，你需要”ESPHome 设备构建器（测试版）”。

• 如果你独立于 Home Assistant 在 Docker 中运行容器：

    # 基于 pip 的安装
    pip3 install --pre -U esphome

    # 基于 docker 的安装
    docker run [...] -it ghcr.io/esphome/esphome:beta run livingroom.yaml

测试版文档可在 beta.esphome.io 获取。

如何使用最新的前沿版本？

首先，提醒一下，最新的前沿版本并不总是稳定的。你可能会遇到不寻常的问题和/或未记录/未预期的更改。我们通常不支持运行 ESPHome dev——这通常是只有开发人员使用的东西。

除此之外，如果你想安装 ESPHome 的 dev 版本：

• 对于 Home Assistant 监督安装，在应用商店中搜索”ESPHome”。请注意，应用名称相应命名；对于开发版本，你需要”ESPHome 设备构建器（dev）”。

• 从 pip ：

    pip3 install https://github.com/esphome/esphome/archive/dev.zip

• 从 docker，使用 ghcr.io/esphome/esphome:dev 镜像。

    docker run [...] -it ghcr.io/esphome/esphome:dev livingroom.yaml compile

开发文档可在 next.esphome.io 获取。

如何使用我的 Home Assistant secrets.yaml 文件？

如果你想将所有密钥放在一个地方，在 esphome 目录中创建一个 secrets.yaml 文件，内容如下：

<<: !include ../secrets.yaml

这将从父目录中”拉入”你的 Home Assistant secrets.yaml 文件的内容。

ESPHome 是否支持[这个设备/功能]？

如果它不在组件索引中，则（官方）不支持。但是，我们一直在添加对新功能的支持。

在某些情况下，社区提供的外部组件可用；请记住，这些组件不受 ESPHome 官方支持，因此，如果你遇到问题，需要联系你正在使用的外部组件的开发者寻求帮助。

你也可以在我们的 ESPHome 功能请求跟踪器 中创建功能请求。

我有一个问题……如何联系你们？

当然！我们很乐意提供帮助 :) 你可以通过以下方式联系我们：

• Discord

• Home Assistant 社区论坛

• ESPHome 问题和功能请求跟踪器。最好仅用于问题和功能请求。

• 如果你的咨询与支持无关，你可以给我们发送电子邮件。

我的节点不断随机重新连接

这是一个已知问题，但似乎是非常底层的问题（换句话说，不是 ESPHome 特有的问题），我们不太清楚如何解决。我们正在尝试找出解决方法，但目前没有单一的、具体的解决方案。

以下是一些可能有助于缓解问题的步骤：

• 如果你使用隐藏的 Wi-Fi 网络，请确保在设备的 Wi-Fi 配置中启用 fast_connect 模式。请注意，这也可能对非隐藏网络有帮助。

• 为你的 ESPHome 设备分配一个静态 IP。

• 在 wifi: 配置中将 power_save_mode 设置为 light。但请注意，在某些情况下这可能会加剧问题。请参见省电模式。

• 问题似乎更频繁地发生在”廉价”开发板上——尤其是来自 eBay 的”廉价”NodeMCU 开发板，它们有时天线质量较差。

• ESPHome 会在特定情况下在配置的持续时间后有意重启，例如当 Wi-Fi 连接无法建立、API 连接丢失或 MQTT 连接丢失时。要禁用此行为，你需要在相关组件上显式设置 reboot_timeout 选项为 0s。

• 如果你在日志中看到 Error: Disconnecting <NODE_NAME>，ESPHome 正在主动关闭原生 API 客户端连接。你需要建立与设备的串行连接以确定原因。如果在断开连接前立即看到 ack timeout 4，这可能是由于 AsyncTCP 库中的一个错误，该错误已在 ESPHome 1.18.0 版本中修复。如果你运行的 ESPHome 版本低于 1.18.0，应升级 ESPHome 并为设备构建新的固件。

• 我们发现当日志级别设置为 VERY_VERBOSE 时，断开连接的情况增多，尤其是在单核设备上，日志代码可能干扰网络代码的运行。因此，我们建议在生产环境中使用较低的日志级别。

• 同时连接到设备上原生 API 服务器的客户端过多也可能导致此行为。例如，Home Assistant ESPHome 集成和 ESPHome 设备构建器上的日志查看器都会建立与设备的连接。在生产环境中，你可能只有来自 Home Assistant 的单个连接，因此这不太成问题。但仍需注意，附加日志查看器可能会产生影响。

• 减少 Wi-Fi 接入点中的传输流量指示消息（DTIM）间隔可能有助于提高 Wi-Fi 可靠性和响应速度。这将使处于省电模式的 Wi-Fi 设备更频繁地唤醒。这可能会减少断开连接，但代价是增加其他也使用省电模式的设备的功耗（可能还有电池消耗）。

“检测到欠压检测器”

此消息表示你的 ESP32 电压降至安全水平以下，通常在 Wi-Fi 传输突发期间，电流可能飙升到 300-500mA。最常见的原因：

• 电源不足——USB 端口、细线缆或廉价适配器可能无法提供足够的电流。
• 长距离或细线缆——电压随距离下降，尤其是细 USB 线缆。
• 其他外设消耗电力——共享同一电源的传感器、LED 或继电器。

快速修复

1. 降低 Wi-Fi 发射功率——这是最有效的单一更改。请参见 Wi-Fi 组件页面上的 output_power 了解完整范围：

wifi:
  output_power: 13dB  # 默认值为 20dB

2. 降低 CPU 频率——在 ESP32 上，电流消耗大致与时钟速度成比例。如果你无法更改上游电源硬件（例如改装的消费设备或连接到现有电路的开发板），降低 CPU 频率可以将瞬态电流保持在稳压器可以提供的范围内。允许的值因变体而异；请参见 ESP32 平台页面上的 cpu_frequency，了解你的芯片支持的值：

esp32:
  cpu_frequency: 160MHz

3. 使用优质电源——专用的 5V/2A 电源，配有短而粗的 USB 线缆。

4. 添加电容器——在 3.3V 和 GND 引脚之间跨接一个 100-1000µF 的电解电容器可以吸收短暂的电流尖峰。

组件状态在重启后未恢复

某些组件，例如 climate 和 switch 组件，能够在微控制器重启/断电后恢复其状态。如果你为某个组件配置了此功能但发现其状态未按预期恢复，或者设备日志中定期出现 ESP_ERR_NVS_NOT_ENOUGH_SPACE 错误，可能是闪存的 NVS 部分已满。这可能由多种原因造成，但无论如何，你可以尝试使用以下命令擦除 NVS 分区：

dd if=/dev/zero of=nvs_zero bs=1 count=20480
esptool.py --chip esp32 --port /dev/ttyUSB0 write_flash 0x009000 nvs_zero

将上面的 /dev/ttyUSB0 改为你的串行端口。如果你更改了分区布局，需要相应地调整上述偏移量和大小。

Docker 参考

从官方容器镜像运行 ESPHome 在在 Docker 中运行 ESPHome 中介绍：镜像标签、运行设备构建器、Compose 文件、USB 直通以及 mDNS 依赖的主机网络。

NOTE

ESPHome 使用 mDNS 发现设备并解析其 .local 名称，ESPHome 设备构建器 通过这种方式跟踪设备是否在线。任何阻止多播到达 ESPHome 的情况都会破坏它：在没有主机网络的情况下在 Docker 中运行（参见在 Docker 中运行 ESPHome），或者网络中的服务器和设备位于不同子网或 VLAN 中。

在 mDNS 无法到达的地方，定期 ICMP ping 扫描仍然会跟踪每个设备，因此只要设备的地址能通过其他方式解析——文字 IP、或由常规 DNS 提供的主机名——它仍然可见。.local 名称可能仍然有效，因为设备构建器会重试不带后缀的裸主机名，你的 DNS 可能提供该名称。无法以其他方式解析地址的设备将显示为离线。

要为设备提供不依赖 mDNS 的地址，manual_ip 为其分配静态 IP，use_address 覆盖用于连接到它的地址。

如果你的路由器支持 Avahi，你可以使 mDNS 跨子网工作。例如，在 OpenWRT 或 pfSense 中：

1. 在两个子网上启用 Avahi（在 OpenWRT 或 pfSense 上安装 Avahi 模块）。
2. 允许从 ESPHome 设备的子网到 224.0.0.251/32 端口 5353 的 UDP 流量。

另请参见 https://github.com/esphome/issues/issues/641#issuecomment-534156628。

关于禁用 mDNS 的说明

ESPHome 的某些功能依赖于 mDNS，因此，禁用它将导致这些功能停止工作。

一般来说，在不设置静态 IP 地址（或静态 DHCP 租约）的情况下禁用 mDNS 必然会导致问题——mDNS 用于确定每个 ESPHome 节点的 IP 地址。

如果禁用 mDNS，预计会有以下影响：

• 你将无法使用节点的主机名进行 ping、查找其 IP 地址或以其他方式连接到它，除非你的常规 DNS 也提供该主机名。

• 使用原生 API 时，Home Assistant 中的自动发现依赖于 mDNS 广播消息来检测新的 ESPHome 节点。如果需要在禁用 mDNS 的情况下使用原生 API，则必须使用静态 IP 地址并手动添加 ESPHome 组件及其（静态）IP 地址。

• ESPHome 设备构建器中的状态检测在可用时使用 mDNS，但无论节点如何，都会运行定期 ICMP ping 扫描，因此禁用 mDNS 的节点只要其地址能通过其他方式解析，仍然会被跟踪——请参见 Docker 参考部分中的说明。地址完全无法解析的节点将显示为”离线”。

配置文件可以从设备恢复吗？

ESPHome YAML 配置文件不存储在 ESPHome 设备上。如果你丢失了配置，无法从设备恢复；如果你在其他地方没有备份，则必须从头开始重新创建。

请始终备份你的文件！

为什么我不应该在设备名称中使用下划线？

你的 .yaml 配置文件中的顶层 name: 字段定义了本地网络上的节点名称（“主机名”）。根据 RFC1912，主机名中的下划线（_）字符无效。在实践中，某些 DNS/DHCP 设置可能能正确处理下划线，而其他则不能。如果你使用静态 IP 地址，不太可能遇到任何问题。在某些情况下，初始设置可能可行，但 Home Assistant 重启或更换路由器硬件时连接可能会失败。

我们建议使用连字符（-）代替下划线。

重要提示：请按照这些说明在重命名在线设备时使用 use_address 参数，因为连接到现有设备时只能使用旧名称，直到名称更改完成。

为什么我会收到关于启动引脚的警告？

大多数微控制器都有特殊的”启动引脚”，在启动过程中会被读取。引脚的状态决定启动过程的结果。微控制器实际上可以启动到两种”模式”：

• 正常模式
• “刷写”或”引导加载程序”模式

虽然在软件中使用这些引脚本身不是问题，但如果连接到这些引脚之一的外部硬件组件/设备任意改变引脚状态，可能会导致启动失败或其他难以诊断的行为。

我们建议避免使用这些引脚，除非绝对必要并且你完全理解这些引脚在启动时的预期状态。

某些开发板将 GPIO 0 连接到一个按钮，通常标记为”boot”。按住此按钮的同时给 ESP 上电/复位将使其进入引导加载程序模式。一旦 ESP 完全启动，此按钮可以安全地用作普通输入。

如果启动引脚仅连接到具有高阻抗输入且无上拉或下拉电阻的其他设备，通常可以安全地将其用作输出。请注意，I²C 时钟和数据线需要上拉电阻，因此不适合用于启动引脚。

如果你绝对确定使用启动引脚是安全的，并且想要抑制警告，可以在相关引脚配置中添加 ignore_strapping_warning: true。

如何测试拉取请求？

利用外部组件功能，只需在 YAML 中添加几行即可测试大多数拉取请求！你需要拉取请求的编号以及拉取请求添加或更改的组件（它们在 GitHub 拉取请求页面上以”integration:“标签列出）。然后，如果你向 YAML 配置添加一个代码块（类似于下面所示），重新编译并重新安装/更新 ESPHome 到设备，拉取请求中的代码将用于该拉取请求更改的组件。

external_components:
  # 将 1234 替换为拉取请求的编号
  - source: github://pr#1234
    components:
      # 在此列出此拉取请求修改的所有组件
      - ccs811

请注意，这仅适用于只更改组件内文件的拉取请求。如果 esphome/components/ 之外的任何文件被添加或更改，此方法将不起作用。这些拉取请求在 GitHub 上标记为”core”标签。

为什么在深度睡眠期间实体显示为”不可用”？

当设备首次添加到 Home Assistant 时，深度睡眠组件必须存在于设备的配置中。为防止实体显示为”不可用”，你可以在 Home Assistant 中移除并重新添加设备。

如何保护我的 ESPHome 设备？

请参阅全面的安全最佳实践指南，了解关于 API 加密、OTA 密码、网络分段、物理安全等方面的详细建议。

参见

• ESPHome 文档
• 开发者网站