ESPHome 入门指南

本指南将引导您将微控制器转变为智能家居设备：创建配置、添加硬件、将其安装到设备上，并将结果连接到 Home Assistant。

本指南假设您已经安装了 ESPHome。如果尚未安装，请从安装 ESPHome开始，安装后再回来继续。

ESPHome 简介

ESPHome 可将常见的微控制器转变为智能家居设备，而无需编写任何 C++ 代码。

您通过”配置”来描述设备应执行的操作：一个或多个 YAML 文件，列出连接到设备上的硬件。ESPHome 读取该描述并为您的设备构建自定义固件。您定义的任何内容——传感器、开关、灯光、显示屏——都会自动出现在 Home Assistant 的用户界面中。

ESPHome 设备构建器是一个 Web 界面，您可以在其中创建、编辑和安装这些配置。以下步骤是为设备构建器编写的，因为大多数安装方式都会提供它。如果您安装的是命令行工具，请参阅改用命令行了解等效命令——YAML 完全相同。

连接您的设备

首次安装必须通过 USB 线缆进行；之后的每次更新都可以通过无线方式完成。请按照物理设备连接中的步骤将设备插入电脑并使其被识别。

NOTE

首次安装通常是整个过程中最繁琐的部分，至少在您做过几次之前是这样。如果出现问题，故障排除指南涵盖了常见原因。

创建您的第一个配置

打开设备构建器。在没有任何设备的情况下，它会邀请您创建一个——点击创建设备启动向导。

向导会询问您希望如何创建配置。您有三个选项：

新设备设置：向导引导您完成平台选择、开发板配置和 Wi-Fi 设置，以创建基本可用的配置。如果您不确定，请选择此项。
从文件导入：上传现有的 ESPHome 配置文件（.yaml 或 .yml）。这对于恢复备份和迁移配置非常有用。您可以浏览文件或将其拖放到对话框中。
空配置：创建一个最小配置文件，适用于偏好从头开始编写或从 devices.esphome.io 粘贴配置的人。

向导结束时，您会得到一个配置文件。它目前功能不多——只是将设备连接到 Wi-Fi，仅此而已——但这足以进行安装。

如果您在向导期间没有输入 Wi-Fi 凭据，请立即输入：没有凭据，设备无法连接到您的网络，因此无法与 Home Assistant 通信或接受无线更新。

设备构建器界面

主页面默认以卡片形式列出您创建的每个设备。列表上方的控件允许您搜索、在卡片、表格和 YAML 视图之间切换，以及按平台、区域或标签筛选。选择多个可启用批量操作，而已经在您的网络上但设备构建器尚未管理的 ESPHome 设备会显示在已发现下。

每个设备卡片显示其配置文件名、在线或离线徽章，以及以下操作：

编辑：打开配置编辑器。
安装（上传图标）：编译配置并将其安装到设备上。
日志（文档图标）：显示来自设备的日志。如果设备通过 USB 连接，您可以使用串口连接；否则设备构建器通过网络连接。
溢出菜单（⋮）：其他操作，包括验证（在不构建的情况下检查配置）和清除构建文件（删除生成的构建输出）。清除通常可以解决编译错误，随时可以安全执行，在报告错误之前值得一试。

配置文件存储在设备构建器指定的目录下的 esphome/ 文件夹中。在 Home Assistant 中，该路径为 <HOME_ASSISTANT_CONFIG>/esphome/，因此上述”客厅”设备位于 /config/esphome/living-room.yaml。

NOTE

Home Assistant 应用作为独立容器运行，这使得从终端访问这些文件有些不便。如果需要，请安装 Home Assistant 的 SSH 应用，使用用户名和密码进行配置，并禁用”保护模式”（请先评估这样做带来的风险）。然后您可以对应用容器执行命令，例如 docker exec -it addon_5c53de3b_esphome esphome logs /config/esphome/living-room.yaml。

添加开关

点击设备上的编辑打开其配置，并添加一个 GPIO 开关：

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

将 GPIOXX 替换为您的硬件实际连接的引脚。该开关可以控制任何设备——除湿机、台灯、风扇——名称由您自行选择，仅影响其在 Home Assistant 中的标签。

如果您使用过 Home Assistant 的 configuration.yaml，这种配置格式应该很熟悉；ESPHome 有意保持与它相近的风格。ESPHome 还会为您翻译开发板特定的引脚名称，因此在 NodeMCU 开发板上，您可以写 D1 而非原始的 GPIO 编号。

在 Home Assistant 中，上述示例最终显示如下：

添加二进制传感器

接下来，添加一个二进制传感器，用于报告 GPIO 引脚是否被拉高或拉低：

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

请注意，这里的 pin: 是一个块而非单个值。ESPHome 中几乎所有引脚都接受这种更长的形式，它提供了反向和引脚模式的选项——请参阅引脚架构了解完整内容。

完成后点击保存，然后继续阅读。

更新您的设备

保存配置并不会改变物理设备。每次编辑配置后，您都需要点击安装以重新编译固件并推送到设备。

首次安装后，您就不再需要 USB 线缆了——ESPHome 通过无线方式更新设备。

将设备连接到 Home Assistant

一旦您的配置安装完成并且设备已加入您的 Wi-Fi 网络，Home Assistant 会自动发现它（假设您的网络支持 mDNS）并提供设置：

您也可以从 Home Assistant 的集成页面手动添加：点击添加集成，搜索”ESPHome”，然后输入设备的主机名。主机名来自您为设备指定的名称，因此名为 living-room-lamp 的设备可通过 living-room-lamp.local 访问。如果您愿意，也可以使用其 IP 地址。

为您创建的每个 ESPHome 设备重复此操作。

改用命令行

如果您安装了 esphome 命令行工具，上述每一步都有直接对应的命令。配置 YAML 完全相同。

设备构建器	命令行
创建配置（向导）	`esphome wizard livingroom.yaml`
验证	`esphome config livingroom.yaml`
安装	`esphome run livingroom.yaml`
日志	`esphome logs livingroom.yaml`
清除构建文件	`esphome clean livingroom.yaml`

esphome run 会验证配置、报告任何问题，然后编译并上传固件。它还会创建一个以设备命名的目录，其中包含生成的 PlatformIO 项目，您可以随意查看。

首次运行 esphome run 需要设备通过 USB 连接。之后上传会通过无线方式进行，使用相同的命令。

设备构建器是一个独立的包，而非 esphome 的子命令。安装 ESPHome 页面上的 pip 选项卡介绍了如何安装两者，以及如何针对配置目录运行设备构建器。

请参阅命令行界面了解所有 esphome 子命令，或参阅在 Docker 中运行 ESPHome（如果您使用容器镜像）。

下一步去哪里

太棒了！🎉 您已经完成了第一个 ESPHome 项目，在设备上安装了自定义固件，并通过配置文件启用了几个组件。

现在是浏览组件的好时机——您想要使用的硬件很可能已经得到支持。请务必也阅读常见问题。如果您遇到问题或想要请求功能，请在 GitHub 问题追踪器上提交问题，或在 Discord 聊天室上找到我们。