使用 ESPHome 命令行入门

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

安装

如果您熟悉 Docker，您可以使用它！请注意，在 macOS 上 Docker 无法通过 USB 设备传递。您将无法通过 USB 闪存 ESP 设备，所有其他功能都将正常工作。仍然可以通过网页仪表板闪存。

我们的镜像支持 AMD64、ARM 和 ARM64 (AARCH64)，并可以通过以下方式下载：

docker pull ghcr.io/esphome/esphome

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

version: '3'
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-core 问题 3089

该项目提供多个 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 板，您同样可以将 D1 作为 pin: 选项设置。

第一次上传

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

esphome run livingroom.yaml

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

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

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

ℹ️ Note
或者，您可以使用 ESPHome 网页或 esptool 闪存二进制文件。

现在当您转到 Home Assistant 的集成屏幕（在配置面板下）时，您应该会在发现部分看到 ESPHome 设备出现（尽管这可能需要长达 5 分钟）。或者，您可以手动添加设备，方法是点击 ESPHome 集成的配置并将 <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 - 即引脚模式。

这次上传时，您不需要再次通过 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 问题跟踪器上创建一个新问题，要么在 Discord 聊天上找到我们（也请确保阅读常见问题解答）。

奖励：ESPHome 设备构建器

ESPHome 设备构建器允许您通过一个友好的网页界面轻松管理您的节点。它主要设计为 Home Assistant 插件，但可以在 Docker 中独立于 Home Assistant 运行。

要启动 ESPHome 设备构建器，只需使用以下命令启动 ESPHome（config/ 指向您想要存储配置的目录）：

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

# 启动仪表板
esphome dashboard config

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

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

之后，您将能够通过 localhost:6052 访问 ESPHome 设备构建器。

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