ESPHome 使用教程

本教程介绍如何使用 ESPHome Device Builder 创建 ESPHome 配置、编译并烧录固件。

1. 准备工作

环境准备

1. 参考 Home Assistant 官方文档 安装并启动 Home Assistant。
2. 参考 ESPHome 官方文档 安装并启动 ESPHome Device Builder。

2. 固件编译 & 烧录

创建设备

1. 在 Home Assistant 侧边栏打开 ESPHome Builder。
2. 点击右下角的 + Create device。首次使用时，也可以点击页面中的 Add new device。

3. 在 Create configuration 窗口中选择 Create new project。

4. 在板型列表中搜索并选择实际使用的开发板。

• 如果列表中有准确型号，优先选择准确型号。
• 如果不确定板型，可点击 Connect your board 尝试识别。
• 只有在确认芯片型号和必要参数后，才使用 Generic ESP32 Board 等通用板型。

5. 输入设备名称，然后点击 Finish setup。

修改配置

项目创建完成后，ESPHome 会生成一份最小配置。右侧为 YAML 编辑器，左侧可以通过 Core configuration、Components 和 Automations 查看或添加配置项。

默认配置通常包含以下部分：

以 Unit TMOS PIR 为例，使用 M5Stack 外部组件时，先引入对应的 ESPHome 组件仓库：

external_components:
  - source: github://m5stack/esphome-yaml/components
    components: [sths34pf80]
    refresh: 0s

引入后，再在对应的 ESPHome 平台配置中使用该组件。不同产品的具体平台名称、参数和实体配置，请参考对应产品的 ESPHome 组件详情页。

编辑完成后点击右下角的 Save。如果编辑器提示语法或组件错误，请先修正错误再继续编译。

编译固件

1. 点击编辑器右下角的 Install。

选择安装方式前，可参考下表：

烧录固件

Plug into this computer

此方式推荐用于首次烧录。

1. 使用 USB 数据线将设备连接到当前电脑。部分设备需要先进入下载模式，请参考对应产品的下载模式说明。
2. 在安装方式窗口中选择 Plug into this computer。
3. 等待编译完成。日志中出现 Successfully compiled program 后，点击 Open USB flasher。

4. 浏览器会在新标签页打开 ESPHome Web。确认页面已收到 firmware.factory.bin，然后点击 Connect & install。

5. 在浏览器弹出的串口列表中选择目标设备，然后点击 连接。

串口名称因系统和 USB 芯片而异，常见名称包括：

• macOS：cu.usbmodem... 或 cu.usbserial...
• Linux：/dev/ttyUSB... 或 /dev/ttyACM...
• Windows：COM...

6. 按页面提示确认安装，等待擦除、写入和校验完成。烧录期间保持当前页面可见，不要拔出 USB 数据线。
7. 烧录完成后重启设备。设备将使用 YAML 中的 Wi-Fi 配置联网；如果连接失败，会启动备用热点。

Plug into your Home Assistant server

此方式适用于设备通过 USB 直接连接到 Home Assistant 主机，而不是连接到浏览器所在电脑。

1. 将设备连接到 Home Assistant 主机的 USB 接口。
2. 选择 Plug into your Home Assistant server。
3. 在串口列表中选择目标设备，例如 /dev/ttyUSB0 或 /dev/ttyACM0。
4. 等待编译和写入完成，然后重启设备。

如果列表中没有目标串口，请确认：

• USB 线支持数据传输，设备已正确供电。
• Home Assistant 主机已经识别 USB 设备。
• 虚拟机、Docker 或 NAS 环境已将 USB 设备映射给 Home Assistant/ESPHome。
• 串口未被其他插件或程序占用。

On the network（OTA）

此方式仅适用于已经运行 ESPHome 固件且当前在线的设备。

1. 确认设备和 Home Assistant 之间的网络可以互相访问。
2. 选择 On the network。
3. 选择目标设备，等待编译、上传和重启完成。
4. 在日志中确认设备重新上线且没有启动错误。

如果设备是首次烧录、离线、修改网络配置后无法连接，或 OTA 配置已被移除，请改用 USB 方式恢复。

下载固件后手动烧录

在编译结果页点击 Download 可以保存固件。首次完整烧录通常使用 firmware.factory.bin；firmware.ota.bin 用于 OTA 更新，不应直接替代首次完整烧录文件。

手动烧录前请核对文件类型、芯片型号、Flash 参数和写入地址。若没有明确的产品烧录说明，优先使用 ESPHome 提供的 USB flasher。

烧录完成后，ESPHome Web 会显示安装进度和重启状态。

3. 开始使用

添加到 Home Assistant

固件启动并成功连接网络后，Home Assistant 通常会自动发现 ESPHome 设备。

1. 打开 Settings -> Devices & services。

2. 在 Discovered 区域找到 ESPHome 设备，点击 Add。

3. 在确认窗口中检查设备信息，然后点击 Submit。

4. 输入设备名称，选择对应的 Area，然后点击 Finish。

5. 打开设备详情页，确认实体状态和传感器数据正常更新。

如果 Home Assistant 没有自动发现设备：

1. 点击 Add integration，搜索 ESPHome。
2. 输入设备的主机名（例如 living-room-sensor.local）或 IP 地址。
3. 如系统要求，输入 YAML 中 api.encryption.key 对应的密钥。