ESPHome 命令行入门

ESPHome 是为您的 ESP8266/ESP32 开发板创建自定义固件的完美解决方案。在本指南中，我们将通过几个简单的步骤介绍如何设置基本的”节点”。

安装

如果您熟悉 Docker，可以改用它！请注意，在 macOS 上 Docker 无法传递 USB 设备。您将无法在 Mac 上通过 USB 刷写 ESP 设备，所有其他功能都可以工作。使用 web 仪表板刷写仍然是可能的。

我们的镜像支持 AMD64、ARM 和 ARM64 (AARCH64)，可以使用以下命令下载：

docker pull ghcr.io/esphome/esphome

如果您想改用 docker-compose，这里有一个示例文件：

services:
  esphome:
    container_name: esphome
    image: ghcr.io/esphome/esphome
    volumes:
      - /path/to/esphome/config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: always
    privileged: true
    network_mode: host
    environment:
      - USERNAME=test
      - PASSWORD=ChangeMe

NOTE

如果您使用 NFS 共享作为容器的配置卷后端，可能需要使用 nolock 选项挂载卷，否则 platformio 可能会在容器启动时冻结，如 platformio/platformio-core#3089 所述

WARNING

在 WSL2 上的 Docker 中运行 ESPHome 可能比原生 Linux 或传统 VM 慢得多（10 倍或更多），这是由于在访问 Windows 驱动器上的文件时文件系统性能问题。为了获得更好的性能，请将您的 ESPHome 文件存储在 WSL2 文件系统中（例如 ~/esphome/...），而不是 Windows 挂载上（例如 /mnt/c/...）。有关更多详情，请参阅 esphome#12568。

项目提供多个 docker 标签；请选择最适合您的：

latest 和 stable 指向可用的最新稳定版本。不建议基于这些标签自动更新容器，因为版本之间可能存在破坏性更改。
版本跟踪标签 YEAR.MONTH（例如 2022.8）指向所需版本中可用的最新稳定补丁版本。基于此类标签升级容器时应该不会有破坏性更改。
beta 指向最新发布的 beta 版本，当没有新的 beta 版本时指向最新稳定版本。
dev 是前沿版本；基于 dev 分支的最新更改每日构建。

连接 ESP 设备

按照物理设备连接中的说明连接到您的 ESP 设备。

NOTE

设置新 ESPHome 设备最困难的部分是初始安装。安装需要您的 ESP 设备通过线缆连接到计算机。以后的更新可以无线安装。

创建项目

现在让我们设置一个配置文件。幸运的是，ESPHome 有一个友好的设置向导，将引导您创建第一个配置文件。例如，如果您想创建一个名为 livingroom.yaml 的配置文件：

esphome wizard livingroom.yaml
# 在 Docker 上：
docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome wizard livingroom.yaml

在此步骤结束时，您将准备好第一个 YAML 配置文件。它还没有做什么，只是让您的设备连接到 WiFi 网络，但这仍然是第一步。

添加一些功能

现在您应该有一个名为 livingroom.yaml（或类似）的文件。在您选择的编辑器中打开该文件，让我们向我们的应用程序添加一个简单的 GPIO 开关。

switch:
  - platform: gpio
    name: "Living Room Dehumidifier"
    pin: GPIO5

配置格式应该立即让您感觉熟悉。ESPHome 尝试使其尽可能接近 Home Assistant 的 configuration.yaml 模式。在上面的示例中，我们只是添加了一个名为 “Living Room Dehumidifier” 的开关（实际上可以控制任何东西，例如灯）并连接到引脚 GPIO5。ESPHome 的好处是它还会自动尝试根据开发板为您翻译引脚编号。例如，在上面的配置中，如果使用 NodeMCU 开发板，您也可以将 pin: 选项设置为 D1。

首次上传

现在您可以继续添加更多组件。一旦您觉得有想要上传到 ESP 开发板的内容，只需通过 USB 插入设备并输入以下命令（将 livingroom.yaml 替换为您的配置文件）：

esphome run livingroom.yaml

您应该看到 ESPHome 验证配置并告诉您潜在问题。然后 ESPHome 将继续编译并上传自定义固件。您还会看到 ESPHome 创建了一个以您的节点命名的文件夹。这是一个新的 PlatformIO 项目，您可以在之后修改和尝试。

如果您在 Linux 上运行 docker，可以将 --device=/dev/ttyUSB0 添加到您的 docker 命令以映射本地 USB 设备。Mac 上的 Docker 无法访问主机 USB 设备。

docker run --rm --privileged -v "${PWD}":/config --device=/dev/ttyUSB0 -it ghcr.io/esphome/esphome run livingroom.yaml

NOTE

或者，您可以使用 ESPHome Web 或 esptool 刷写二进制文件。

现在，当您进入 Home Assistant Integrations 屏幕（在 Configuration 面板下）时，您应该看到 ESPHome 设备出现在发现部分（尽管这可能需要最多 5 分钟）。或者，您可以通过在 ESPHome 集成上点击 CONFIGURE 并输入 <NODE_NAME>.local 作为主机来手动添加设备。

首次上传后，您可能永远不需要再次使用 USB 线缆，因为 ESPHome 的所有功能也可以远程启用。不再需要打开藏在难以触及的地方的隐藏盒子。太好了！

添加二进制传感器

接下来，我们将添加一个非常简单的二进制传感器，定期检查特定 GPIO 引脚是被拉高还是拉低 — GPIO BinarySensor。

binary_sensor:
  - platform: gpio
    name: "Living Room Window"
    pin:
      number: 16
      inverted: true
      mode:
        input: true
        pullup: true

这是 ESPHome 的高级功能。几乎所有引脚都可以选择使用更复杂的配置模式，包含反转和 pinMode 选项 — Pin Schema。

这次上传时，您不需要再次通过 USB 插入设备。上传将”通过空中”神奇地进行。直接使用 ESPHome 时，这与 USB 线缆相同，但对于 docker，您需要提供额外的参数：

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

下一步去哪里

太棒了🎉！您现在已经成功设置了您的第一个 ESPHome 项目并将第一个 ESPHome 自定义固件上传到您的节点。您还学会了如何通过配置文件启用一些基本组件。

现在是查看组件的好时机。希望您能在那里找到您需要的所有传感器/输出等。如果您遇到任何问题或想要新功能，请在 GitHub issue tracker 上创建新 issue 或在 Discord 聊天上找到我们（也请务必阅读 FAQ）。

额外：ESPHome Device Builder

ESPHome Device Builder 允许您从漂亮的 web 界面轻松管理您的节点。它主要是作为 Home Assistant 插件设计的，但可以在 Docker 中独立于 Home Assistant 运行。

要启动 ESPHome Device Builder，只需使用以下命令启动 ESPHome（config/ 指向您要存储配置的目录）：

# 安装仪表板依赖项
pip install tornado esptool

# 启动仪表板
esphome dashboard config

# 在 Docker 上，需要主机网络模式才能显示在线状态指示器
docker run --rm --net=host -v "${PWD}":/config -it ghcr.io/esphome/esphome

# 在 Docker 与 MacOS 上，主机网络选项无法按预期工作。如果您是 MacOS 用户，可以使用以下替代命令。
docker run --rm -p 6052:6052 -e ESPHOME_DASHBOARD_USE_PING=true -v "${PWD}":/config -it ghcr.io/esphome/esphome

之后，您将能够在 localhost:6052 访问 ESPHome Device Builder。

日志级别可以通过环境变量 ESPHOME_LOG_LEVEL 设置（默认为 INFO）。

ESPHome 命令行入门

安装

连接 ESP 设备

创建项目

添加一些功能

首次上传

添加二进制传感器

下一步去哪里

额外：ESPHome Device Builder

另见