常见问题

我应该为我的项目选择哪种 ESP？

我们经常被问到这个问题。正如所有工程问题一样，“这取决于”。根据 ESPHome 目前对硬件的支持情况，以下是我们的一些建议：

不推荐

ESP8266
- 已有十多年历史，内置外设非常有限。
- 如果您认为 ESP32(-Sx) “性能过剩”或“过度”，请选择 ESP32-C3。
- 不符合为 ESPHome 提供支持的要求。
- 原始的 NodeMCU、D1-Mini 和 ESP-01 是使用 ESP8266 的开发板示例；请注意，这些开发板也有（引脚兼容的）版本使用了更现代的 ESP32 或其变体。

其他注意事项

这些建议主要针对刚入门或 ESPHome 新手。
许多人已经有一抽屉的 ESP8266 开发板——我们并不是要阻止您使用它们！但请不要再购买更多 ESP8266 开发板，并在购买新设备时考虑我们的建议。😉
“…但 [ESP8266 开发板] 更便宜！！！”…好吧，一分钱一分货。与 ESP8266 相比，所有 ESP32 及其变体具有：
- 更完善的外设，释放处理器核心以最大化性能。
- 更多的 GPIO 引脚。
- 大约 5 倍的内存。
  - 某些组件需要比 ESP8266 更多的内存——（大型）显示器和某些传感器经常在 ESP8266 上引发问题或崩溃。
  - 通常有变通方案，但不能假设这些方案永远有效，尤其是当您希望定期更新设备但依赖供应商提供/维护的某些功能库时。
- 显著更多的闪存。
  - 大多数 ESP8266 开发板只有 1 或 2 MB；而…
  - 大多数 ESP32 及其变体至少有 4 MB，有些甚至有 8、16 或 32 MB！
  更多的内存和/或闪存意味着您可以拥有更大/更复杂的 ESPHome 配置。
如果为了省几美元而选择更便宜的微控制器，请记住，当您发现便宜的开发板无法满足项目需求时，您将不得不购买另一块“更好”的开发板。这种方式最终会花费更多。如果可能，多花一点钱购买一块寿命更长、适用于更多项目的开发板！
ESP32-C6/ESP32-H2/[最新 Espressif 芯片]/RP2040/RP2350 怎么样？
- 对这些设备的支持尚不成熟，因此您更可能遇到问题。
- 我们建议坚持使用上述推荐的微控制器，以获得最佳 ESPHome 体验。
随着对新设备的支持增加或成熟，我们将更新这里的建议。

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

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

如果您更喜欢手动方式：

您需要获取要安装的固件文件：
- Using ESPHome CLI
  The file is available in the <CONFIG_DIR>/<NODE_NAME>/.pioenvs/<NODE_NAME>/firmware.bin directory after the build completes.
- Using ESPHome Dashboard
  1. Click on the three-dot menu for your device
  2. Select “Install”
  3. Choose “Manual download”
On some boards, you may need to force the microcontroller into its programming mode. This often isn’t necessary on most modern boards/devices, but it’s worth trying if you’re experiencing difficulties.
Finally, to install a firmware file, you can use:
- ESPHome Web，我们的基于 Web 的安装程序。这是最简单的方法，但需要支持 WebSerial 的浏览器，例如 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 连接。
某些设备在擦除闪存后可能需要重新上电以重新进入编程模式；它们不会自动重置。
最后，这可能是您的微控制器有缺陷、损坏或无法编程的迹象。:(

如果您处于嘈杂的电气/RF 环境中或使用异常长的线缆/电线，安装可能会在传输过程中失败。别担心——只需再试一次，可以尝试降低波特率以提高安全性：

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

如果仍然无法解决问题，您可能需要重新查看我无法通过 USB 安装成功部分。

使用 ESPHome 的技巧

ESPHome 支持（大部分）Home Assistant 的 YAML 配置指令，例如 !include and !secret. This allows you to store your secrets (for example, Wi-Fi passwords and API keys) in a file called secrets.yaml, as long as this file is in the same directory as your ESPHome configuration file.
We’ve enhanced ESPHome’s !include directive such that it accepts a list of variables that can be substituted within the included file. For example:

    binary_sensor:
      - platform: gpio
        id: button1
        pin: GPIOXX
        on_multi_click: !include { file: on-multi-click.yaml, vars: { id: 1 } } # inline syntax
      - platform: gpio
        id: button2
        pin: GPIOXX
        on_multi_click: !include
          # multi-line syntax
          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

您可以使用 Substitutions 基于上述示例减少配置文件的重复内容。
如果您想查看 ESPHome 如何解释您的配置，请运行：

    esphome config livingroom.yaml

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

    esphome logs livingroom.yaml

您始终可以在 <NODE_NAME>/src/ 目录中找到 ESPHome 生成的源代码。
您可以在此处查看完整的命令行界面选项列表：命令行界面

求助！某些功能无法正常工作

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

如果您遇到 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 Device Builder (beta)”。
如果您独立于 Home Assistant 运行 Docker 容器：

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

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

The beta documentation is available at beta.esphome.io.

How do I use the latest bleeding-edge version?

First, a fair warning that the latest bleeding-edge version is not always stable. You may encounter unusual problems and/or undocumented/unexpected changes. We do not generally support running ESPHome dev – it’s usually something only developers use.

That aside, if you want to install the dev version of ESPHome:

For Home Assistant supervised installs, search for “ESPHome” in the Add-on Store. Note that the add-ons are named accordingly; for the dev version, you’ll want “ESPHome Device Builder (dev)”.
From pip :

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

From docker, use the ghcr.io/esphome/esphome:dev image.

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

The dev documentation is available at next.esphome.io.

How do I use my Home Assistant `secrets.yaml` file?

If you want to keep all your secrets in one place, make a secrets.yaml file in your esphome directory with the following contents:

<<: !include ../secrets.yaml

This “pulls in” the contents of your Home Assistant secrets.yaml file from the parent directory.

Does ESPHome support [this device/feature]?

If it’s not in the docs, it’s not (officially) supported. However, we are always adding support for new features.

In some cases, community-provided External Components are available; keep in mind that these are not officially supported by ESPHome, so, if you run into problems, you’ll need to contact the developer of the external component you’re using for help.

You can also create a feature request in our ESPHome feature request tracker.

I have a question… How can I contact you?

Sure! We are happy to help :) You can contact us here:

Discord
Home Assistant Community Forums
ESPHome issue and feature request trackers. Preferably only for issues and feature requests.
If your inquiry is not regarding support, you can e-mail us.

My node keeps reconnecting randomly

This is a known issue but seems to be very low-level (in other words, not specifically an ESPHome problem) and we don’t really know how to solve it. We’re trying to identify workarounds for the issue, but there isn’t a single, specific solution right now.

Here are some steps that may help mitigate the issue:

If you’re using a hidden Wi-Fi network, make sure to enable fast_connect mode in your device’s Wi-Fi configuration. Note that this may help with non-hidden networks, as well.
Give your ESPHome device a static IP.
Set the power_save_mode to light in your wifi: configuration. Note, however, that this may exacerbate the problem in some situations. See Power Save Mode.
The issue seems to happen with “cheap” boards more frequently – especially the “cheap” NodeMCU boards from eBay which sometimes have bad antennas.
ESPHome intentionally reboots after a configured duration in specific situations, such as when the Wi-Fi connection cannot be made, API connection is lost or MQTT connection is lost. To disable this behavior, you’ll need to explicitly set the reboot_timeout option to 0s on the relevant components.
If you see Error: Disconnecting <NODE_NAME> in your logs, ESPHome is actively closing the native API client connection. You’ll need to establish a serial connection with your device to determine the reason. If you see ack timeout 4 immediately before the disconnect, this might be because of a bug in the AsyncTCP library, for which a fix was included in ESPHome version 1.18.0. If you are running an ESPHome version, prior to 1.18.0, you should upgrade ESPHome and build fresh firmware for your devices.
We’ve seen an increase in disconnects while the log level is set to VERY_VERBOSE, especially on single-core devices, where the logging code might be interfering with the operation of the networking code. For this reason, we advise using a lower log level for production purposes.
Too many clients simultaneously connected to the native API server on the device may also result in this behavior. For example, the Home Assistant ESPHome integration and the log viewer on the ESPHome Device Builder each establish a connection to the device. In production, you will likely only have a single connection from Home Assistant, making this less of an issue. Still, beware that attaching a log viewer might have an impact.
Reducing the Delivery Traffic Indication Message (DTIM) interval in the Wi-Fi access point may help improve Wi-Fi reliability and responsiveness. This will cause Wi-Fi devices in power save mode to wake up more frequently. This may mitigate disconnections at the expense of increasing power (and possibly battery) usage of other devices also using power save modes.

Component states not restored after reboot

Some components, such as climate and switch components, are able to restore their states following a reboot/power-cycle of the microcontroller. If you’ve configured this for a given component but find that its state is not restored as expected, or you get periodic ESP_ERR_NVS_NOT_ENOUGH_SPACE errors in your device’s log, it could be that the NVS portion of the flash memory is full. This can happen for a number of reasons, but, regardless, you can try wiping the NVS partition with the following commands:

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

Change /dev/ttyUSB0 above to your serial port. If you have changed the partition layout, you’ll need to adjust the above offsets and sizes accordingly.

Docker Reference

Install versions:

# Stable Release
docker pull ghcr.io/esphome/esphome
# Beta
docker pull ghcr.io/esphome/esphome:beta
# Dev version
docker pull ghcr.io/esphome/esphome:dev

ESPHome Command Reference:

# Start a new file wizard for file livingroom.yaml
docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome wizard livingroom.yaml

# Compile and upload livingroom.yaml
docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome run livingroom.yaml

# View logs
docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome logs livingroom.yaml

# Map /dev/ttyUSB0 into container
docker run --rm -v "${PWD}":/config --device=/dev/ttyUSB0 -it ghcr.io/esphome/esphome ...

# Start dashboard on port 6052 (general command)
# Warning: this command is currently not working with Docker on MacOS. (see note below)
docker run --rm -v "${PWD}":/config --net=host -it ghcr.io/esphome/esphome

# Start dashboard on port 6052 (MacOS specific command)
docker run --rm -p 6052:6052 -e ESPHOME_DASHBOARD_USE_PING=true -v "${PWD}":/config -it ghcr.io/esphome/esphome

# Setup a bash alias:
alias esphome='docker run --rm -v "${PWD}":/config --net=host -it ghcr.io/esphome/esphome'

Docker Compose example:

version: '3'

services:
  esphome:
    image: ghcr.io/esphome/esphome
    volumes:
      - ./:/config:rw
      # Use local time for logging timestamps
      - /etc/localtime:/etc/localtime:ro
    devices:
      # if needed, add esp device(s) as in command line examples above
      - /dev/ttyUSB0:/dev/ttyUSB0
      - /dev/ttyACM0:/dev/ttyACM0
    # The host networking driver only works on Linux hosts, but is available as a Beta feature,
    # on Docker Desktop version 4.29 and later.
    network_mode: host
    restart: always

ℹ️ Note
By default, ESPHome uses mDNS to resolve device IPs on the network; this is used to determine online/offline state in the ESPHome Device Builder. In order for this feature to work, you must use Docker’s host networking mode.
The host networking driver only works on Linux hosts; it is available on Docker Desktop version 4.29 and later.
If you don’t want to use the host networking driver, you have to use an alternate method as described below.
Note that mDNS might not work if your Home Assistant server and your ESPHome nodes are on different subnets and/or VLANs. If your router supports Avahi, you can configure mDNS to work across different subnets. For example, in OpenWRT or pfSense:
Enable Avahi on both subnets (install Avahi modules on OpenWRT or pfSense).
Enable UDP traffic from your ESPHome device’s subnet to 224.0.0.251/32 on port 5353.
Alternatively, you can configure the ESPHome Device Builder to use ICMP pings to check the status of devices by setting "status_use_ping": true or, with Docker: -e ESPHOME_DASHBOARD_USE_PING=true
See also https://github.com/esphome/issues/issues/641#issuecomment-534156628.

Notes on disabling mDNS

Some of ESPHome’s functionality relies on mDNS, so, naturally, disabling it will cause these features to stop working.

Generally speaking, disabling mDNS without setting a static IP address (or a static DHCP lease) is bound to cause problems – mDNS is used to determine the IP address of each ESPHome node.

If you disable mDNS, expect the following repercussions:

You will not be able to use the node’s hostname to ping, find it’s IP address or otherwise connect to it.
Automatic discovery in Home Assistant when using the native API relies on mDNS broadcast messages to detect the presence of new ESPHome nodes. If you need to use the native API with mDNS disabled, then you will have to use a static IP address and manually add the ESPHome component with its (static) IP address.
Because status detection in the ESPHome Device Builder uses mDNS by default, nodes with mDNS disabled will always appear as “offline”. This does not affect any functionality; however, if you want to see the online/offline status of your nodes, you may configure the ESPHome Device Builder to ping each node instead. See the notes in the Docker Reference section for more information.

Can configuration files be recovered from the device?

ESPHome YAML configuration files are not stored on ESPHome devices. If you lost your configuration(s), there’s no way to recover them from the device; you’ll have to recreate them from scratch if you don’t have a backup elsewhere.

Always back up your files!

Why shouldn’t I use underscores in my device name?

The top level name: field in your .yaml configuration file defines the node name (“hostname”) on the local network. According to RFC1912, underscore (_ ) characters in hostnames are not valid. In practice, some DNS/DHCP setups may work correctly with underscores while others will not. If you’re using static IP addresses, you’re unlikely to encounter any issues. In some cases, initial setup may work, but connections might fail when Home Assistant restarts or if you change router hardware.

We recommend using a hyphen (- ) instead of underscore.

Important: follow these instructions to use the use_address parameter when renaming a live device, as the connection to an existing device will only work with the old name until the name change is complete.

Why am I getting a warning about strapping pins?

Most microcontrollers have special “strapping pins” that are read during the boot-up procedure. The state of the pin(s) determines the outcome of the boot process. There are effectively two “modes” into which the microcontroller can boot:

Normal mode
“Flashing” or “bootloader” mode

While the use of these pins in software is not specifically a problem, if some external hardware component/device connected to one of these pins is arbitrarily changing the state of the pin, boot failures or other difficult-to-diagnose behavior may occur.

We recommended avoiding these pins unless absolutely necessary and you fully understand the expected state of these pins at boot.

Some development boards connect GPIO 0 to a button, often labeled “boot”. Holding this button while the ESP is powered on/reset will cause it to go into bootloader mode. Once the ESP is fully booted up, this button can safely be used as a normal input.

Strapping pins are generally safe to use as outputs if they are only connected to other devices that have high- impedance inputs with no pull-up or pull-down resistors. Note that I2C clock and data lines require pull-up resistors and are not safe on strapping pins.

If you are absolutely sure that your use of strapping pins is safe and you want to suppress the warning, you can add ignore_strapping_warning: true to the relevant pin configuration(s).

How can I test a pull request?

By leveraging the External Components feature, it’s possible to test most pull requests by simply adding a few lines to your YAML! You need the number of the pull request as well as the component(s) that have been added or changed by the pull request (they are listed with the “integration:” labels on the GitHub page of the pull request). Then, if you add a block of code (similar to that shown below) to your YAML configuration, recompile and reinstall/update ESPHome onto your device, the code from the pull request will be used for the component(s) changed by the pull request.

external_components:
  # replace 1234 with the number of the pull request
  - source: github://pr#1234
    components:
      # list all components modified by this pull request here
      - ccs811

Note that this only works for pull requests that only change files within components. If any files outside esphome/components/ are added or changed, this method won’t work. Those pull requests are labeled with the “core” label on GitHub.

Why do entities appear as “unavailable” during deep sleep?

The Deep Sleep component needs to be present within your device’s configuration when the device is first added to Home Assistant. To prevent entities from appearing as “unavailable”, you can remove and re-add the device in Home Assistant.

常见问题

常见问题

我应该为我的项目选择哪种 ESP？

推荐

不推荐

其他注意事项

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

什么是 esptool？

擦除闪存

写入闪存

我无法通过 USB 安装成功

常见问题

esptool 故障排除

使用 ESPHome 的技巧

求助！某些功能无法正常工作

如何报告问题？

如何更新到最新版本？

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

How do I use the latest bleeding-edge version?

How do I use my Home Assistant secrets.yaml file?

Does ESPHome support [this device/feature]?

I have a question… How can I contact you?

My node keeps reconnecting randomly

Component states not restored after reboot

Docker Reference

Notes on disabling mDNS

Can configuration files be recovered from the device?

Why shouldn’t I use underscores in my device name?

Why am I getting a warning about strapping pins?

How can I test a pull request?

Why do entities appear as “unavailable” during deep sleep?

See Also

常见问题

什么是 `esptool`？

`esptool` 故障排除

How do I use my Home Assistant `secrets.yaml` file?