ESPHome 与 Home Assistant 入门指南

在本指南中，我们将向您介绍如何使用作为 Home Assistant 插件安装的 ESPHome Device Builder 将 ESPHome 安装到设备/微控制器上。

这通常是开始使用 ESPHome 最简单的方式。

ESPHome 简介

ESPHome 允许您创建”配置”，使您能够将常见的微控制器转变为智能家居设备。

设备”配置”由一个或多个 YAML 文件 组成，ESPHome 根据文件内容创建自定义固件，您可以直接将其安装到设备上。配置中定义的硬件（如传感器、开关、灯等）将自动出现在 Home Assistant 的用户界面中。

请注意，ESPHome 有两个”部分”：

• 运行在设备/微控制器上的部分，以及…
• 运行在您的计算机系统上的部分，无论是单板计算机（SBC）（如 Raspberry Pi）还是笔记本/台式机系统。

ESPHome Device Builder 提供了一个简单的 Web 用户界面（UI），允许您创建、编辑配置并将设备配置安装到设备上。

安装 ESPHome Device Builder

要在 Home Assistant 中安装 ESPHome Device Builder，请点击以下按钮：

这应该打开 ESPHome 插件页面；到达后，只需点击 INSTALL 按钮：

插件的安装可能需要一两分钟。完成后，点击 “Start”，然后点击 “Open Web UI”。

NOTE

如果您运行的 Home Assistant 方式不提供对插件的访问，您可以在 Docker 中独立运行 ESPHome Device Builder。

Web UI 将显示一个向导，引导您创建第一个配置：

向导首先询问您想如何创建配置。您有三个选择：

• 新建设备设置：向导引导您完成平台选择、开发板配置和 Wi-Fi 设置，以创建基本的工作配置。
• 从文件导入：上传现有的 ESPHome 配置文件（.yaml 或 .yml）。这对于恢复备份和迁移配置很有用。您可以浏览文件或直接将它们拖放到对话框中。
• 空配置：为喜欢从头开始编写自己的配置或从 devices.esphome.io 粘贴的高级用户创建最小配置文件。

创建第一个配置后，您需要将其安装到设备上。

NOTE

在新设备上初始安装 ESPHome 通常是最困难和/或最令人畏惧的部分 — 至少在您做过几次之前。

如果您以前没有做过，请参阅物理设备连接。

如果在创建第一个设备时没有按照提示操作，您需要在安装后立即输入您的 Wi-Fi 网络凭据，以便您的设备可以连接到 Wi-Fi 网络并随后与 Home Assistant 通信。

Device Builder 界面

让我们快速浏览一下 ESPHome Device Builder 界面。

主页显示您创建的所有节点配置文件列表。对于每个文件，您可以执行一些操作：

• UPDATE：当设备运行的 ESPHome 版本比 ESPHome Device Builder 插件中可用的版本旧时，此按钮会出现。

• EDIT：这将打开配置编辑器。

• LOGS：这允许您查看设备发出的日志。如果设备通过 USB 连接，您可以选择使用 USB/串行连接；否则，它将尝试连接到设备并（一旦连接）通过 Wi-Fi 连接显示日志。

• 溢出菜单：这是一个下拉菜单，允许您执行一些额外的操作。值得注意的是：

  • Validate：这将验证配置文件。

  • Install：打开安装对话框。

  • Clean Build Files：这将删除所有生成的构建文件；它可以帮助解决编译问题（如果发生）。这在任何时候执行都是安全的，您应该在报告错误或其他问题之前尝试此操作。

  • Delete：这将删除配置文件。

ESPHome 的配置文件存储在 <HOME_ASSISTANT_CONFIG>/esphome/ 目录中。例如，上图中 “Bedroom Light” 节点的配置可以在 /config/esphome/bedroom-light.yaml 中找到。

NOTE

Home Assistant 插件作为单独的容器运行；这可能使访问您的配置文件/日志有点挑战性。如果您希望这样做，您需要安装 Home Assistant 的 SSH 插件，使用用户名和密码配置它，并禁用 “Protection Mode”（请评估这样做的相关风险）。

最后，要通过 SSH 客户端从设备访问日志，您可以登录并使用类似 docker exec -it addon_15ef4d2f_esphome esphome logs /config/esphome/bedroom-light.yaml 的命令。

有关更多详情，请参阅命令行入门。

添加功能

完成向导后，您应该有一个设备配置（YAML）文件。在 ESPHome Device Builder 中，点击 “EDIT” 打开该文件，并在配置中添加一个 GPIO 开关：

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

在 Home Assistant 中，上面的示例代码将如下所示：

在上面的示例中，我们只是添加了一个名为 “Living Room Dehumidifier” 并连接到引脚 GPIO5 的开关。这个开关实际上可以控制任何东西 — 例如灯或台扇。它的名称和功能是任意的，应根据您的特定应用程序进行适当设置。

添加二进制传感器

接下来，让我们添加一个监控 GPIO 引脚的二进制传感器来确定并报告其状态。

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

在 Home Assistant 中，上面的示例代码将如下所示：

将此添加到您的设备配置文件后，请确保点击 “SAVE” 以保存您对配置所做的更改…然后继续阅读下一节！

更新您的设备

每次修改设备配置文件时，您都需要使用修改后的配置更新相关的物理设备。换句话说，仅仅保存配置文件本身不会将更改更新到 ESPHome 设备。

每次修改设备配置文件时，您需要通过点击 INSTALL 来重新编译并将更新的配置重新安装到设备上。

请注意，您不需要再次使用 USB 数据线将设备连接到系统，因为（一旦在设备上安装了 ESPHome）它可以通过空中更新设备。

将您的设备连接到 Home Assistant

一旦您的配置安装在设备上并连接到 Wi-Fi，Home Assistant 将自动发现它（假设您的网络允许），并提供配置：

或者，您可以在 Home Assistant 集成页面上手动添加设备。为此，点击 “Add Integration” 按钮（右下角），搜索 “ESPHome” 并输入 ESPHome 设备的主机名。主机名基于您给设备的名称；如果您将设备命名为 “living-room-lamp”，其主机名将是 living-room-lamp.local。如果出于某种原因您更喜欢使用 IP 地址，您也可以输入设备的 IP 地址。

您可以为每个 ESPHome 设备重复此过程。

下一步去哪里

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

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

另见

• ESPHome 文档
• ESPHome 命令行入门
• 安全最佳实践