使用 ESPHome 和 Home Assistant 入门

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

这是开始使用 ESPHome 的一般最简单方法。

ESPHome 简介

ESPHome 允许您创建“配置”，这些配置可以让您将常见的微控制器变成智能家居设备。

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

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

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

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

安装 ESPHome Device Builder

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

这将打开 ESPHome 插件页面；您到达那里后，只需点击 INSTALL 按钮：

插件的安装可能需要一秒钟或两秒钟。完成后，点击“开始”，然后点击“打开网页界面”。

ℹ️ Note

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

创建第一个配置后，您需要在您的设备上安装它。

ℹ️ Note

将 ESPHome 安装到新设备上的初始安装通常是最困难和/或最令人望而生畏的部分——至少直到您多次完成它。

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

Device Builder 界面

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

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

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

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

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

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

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

  • 安装：打开安装对话框。

  • 清理构建文件：这将删除所有生成的构建文件；如果出现问题，这有助于解决编译问题。您可以随时执行此操作，在报告错误或其他问题时，请尝试执行此操作。

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

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

ℹ️ Note

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

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

请参阅 使用 ESPHome 命令行入门 获取更多详细信息。

添加功能

完成向导后，您应该有一个设备配置（YAML）文件。在 ESPHome Device Builder 中，点击“编辑”以打开该文件，并像这样向配置添加一个 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 中，上面的示例代码将如下所示：

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

更新您的设备

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

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

请注意，您将不再需要使用 USB 数据线将设备连接到您的系统，因为（一旦 ESPHome 安装在您的设备上）它可以 Over-the-Air Updates。

将您的设备连接到 Home Assistant

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

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

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

下一步做什么

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

现在是查看 组件索引 的好时机。希望您能在那里找到所有您需要的硬件组件。如果您有任何问题或想要请求新功能，请要么在 GitHub 问题跟踪器 上创建一个新问题，要么在 Discord 聊天 上找到我们。请务必阅读 常见问题解答！

参考资料链接

• ESPHome 索引
• 使用 ESPHome 命令行入门