第3节第一个 ESPHome 设备

重要提示：关于开发板的兼容性

本教程的核心逻辑适用于所有 ESP32 开发板，但所有操作步骤均以 微雪 ESP32-S3-Zero 迷你开发板 为例进行讲解。若使用其他型号的开发板，请根据实际情况修改芯片类型、板型与引脚配置。

本节以微雪 ESP32-S3-Zero 为例，使用 ESPHome 向导生成最小配置、添加板载 RGB LED 组件、首次通过 USB 烧录，并在 Home Assistant 中控制 LED；最后演示后续如何通过 OTA 升级固件。

1. 准备工作

硬件：微雪 ESP32-S3-Zero 一块、USB-C 数据线一根。
网络：可用的 2.4 GHz Wi-Fi（ESP32-S3 不支持 5 GHz）。HA 主机与 ESP32-S3-Zero 必须在同一子网。
前置：已完成第 1、2 节，HA 与 ESPHome 应用已可访问。
浏览器：ESPHome Web 烧录工具需 Chrome 或 Edge（Firefox、Safari 不支持 Web Serial API）；虚拟机直通方式无此限制。

ESP32-S3-Zero 的板载资源中，唯一的可控元件是接在 GPIO21 上的一颗 WS2812 RGB LED。本节将以这颗 LED 作为示例，完整走一遍从空白配置到在 HA 中拖动色板控制板载 LED 的全过程。

2. 用向导创建配置

ESPHome 应用提供新设备向导，自动生成一份可直接烧录的最小 YAML。

打开 ESPHome 应用 Web 界面，点击右下角 NEW DEVICE。
在欢迎弹窗中点击 CONTINUE。
选择 New Device Setup。
为设备命名，再填写 Wi-Fi 名称（SSID）与密码。本教程示例设备名用 esp32-s3-zero——设备名只能包含小写字母、数字和连字符，同时也是设备的 mDNS 主机名（<name>.local）。
备注
- Wi-Fi 仅支持 2.4 GHz，ESP32-S3 不支持 5 GHz。
- 账号密码会自动写入 ESPHome 应用的 secrets.yaml，供本设备与后续设备共享，不会硬编码到设备 YAML 中（如何修改见 3.2 节）。
选择设备芯片类型。ESP32-S3-Zero 使用 ESP32-S3 芯片，选 ESP32-S3。
向导完成后会弹出 INSTALL 选项。点击 SKIP——我们要先添加板载 LED 配置再烧录。
返回设备列表，会看到一张名为 esp32-s3-zero 的设备卡片。点击卡片上的 EDIT 打开 YAML 编辑器，查看向导生成的初始配置：
```
esphome:
  name: esp32-s3-zero
  friendly_name: esp32-s3-zero

esp32:
  board: esp32-s3-devkitc-1
  framework:
    type: esp-idf

# Enable logging
logger:

# Enable Home Assistant API
api:
  encryption:
    key: "...."

ota:
  - platform: esphome
    password: "...."

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "Esp32-S3-Zero Fallback Hotspot"
    password: "...."

captive_portal:
```
各主要段落作用：
- esphome: — 设备元信息。name 是 mDNS 主机名，friendly_name 是在 HA 中显示的名字。
- esp32: — 芯片配置。board 指定开发板型号，framework.type: esp-idf 选择编译框架（另一选项是 arduino）。
- logger: — 启用日志输出。可在 ESPHome 的 LOGS 中查看。
- api: — 启用与 HA 通信的原生 API。加密密钥由向导自动生成，HA 接入时通过 mDNS 自动获取。
- ota: — 开启空中升级（Over-The-Air）支持，是后续无需 USB 烧录的关键。
- wifi: — Wi-Fi 配置。账号密码通过 !secret 从 secrets.yaml 读取。ap: 配置在 Wi-Fi 连接失败时启用 AP 备用热点，方便用手机连接重新配置。
- captive_portal: — 配合 wifi.ap 提供网页配网界面。
备注
ESPHome 向导输出的具体字段与默认值会随版本变化，显示内容与本教程可能略有差异。

3. 必备的最小 YAML 概念

在动手添加 LED 配置之前，先了解两个本节会用到的 YAML 基础概念。更进阶的组织手段（substitutions、!include、packages、external_components 等）在第 4 节扩展 ESPHome 配置介绍。

3.1 YAML 缩进与列表

YAML 用缩进表达层级，只能用空格，不能用 Tab，统一 2 空格一级。同一级的键对齐要严格，错一个空格就会导致解析失败。

esphome:
  name: esp32-s3-zero       # 2 空格缩进
  friendly_name: My First ESPHome     # 与上一行 name 对齐

短横线 - 开头表示列表项：

ota:
  - platform: esphome              # ota 是列表，包含一个映射元素
    password: "..."                # 该元素的 password 与 platform 对齐

编辑完成后，可以点击 Validate 按钮验证 YAML 格式是否正确。

3.2 `!secret` 与 `secrets.yaml`

!secret xxx 是 ESPHome 的特殊语法，表示“从 secrets.yaml 读取键 xxx 的值”。

ESPHome 向导第 4 步填写的 Wi-Fi 账号密码会自动写入 secrets.yaml：

# secrets.yaml
wifi_ssid: MyHomeWiFi
wifi_password: my-wifi-password

设备 YAML 中引用：

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

要修改 Wi-Fi 账号密码，可直接在 secrets.yaml 中修改：

把敏感信息集中放在 secrets.yaml 后，多个设备可以共用同一份凭据；导出或分享设备配置时也不会泄漏密码。

4. 添加板载 RGB LED

ESP32-S3-Zero 的板载 RGB LED 接在 GPIO21，类型为 WS2812（单颗 NeoPixel）。ESPHome 中通过 light 平台的 esp32_rmt_led_strip 驱动。

在向导生成的 YAML 末尾追加以下段落：

light:
  - platform: esp32_rmt_led_strip
    chipset: WS2812
    rgb_order: RGB
    pin: GPIO21
    num_leds: 1
    name: "RGB LED"

各字段含义：

platform: esp32_rmt_led_strip — 使用 ESP32 的 RMT 外设驱动 WS2812 兼容灯带（单颗灯也用同样的驱动）。
chipset: WS2812 — 灯珠协议类型。
rgb_order: RGB — ESP32-S3-Zero 板载 RGB LED 数据顺序固定为红、绿、蓝。
pin: GPIO21 — ESP32-S3-Zero 上 RGB LED 的数据引脚。
num_leds: 1 — 板载只有一颗。
name: "RGB LED" — 在 HA 中显示的实体名字。

完整字段说明请查阅 ESPHome esp32_rmt_led_strip 文档。

添加完成后，点击编辑器右上角 SAVE 保存，再点击右上角 INSTALL 进入烧录流程。

5. 编译与首次烧录

首次烧录必须通过 USB——Wirelessly（OTA）要等设备烧录过一次固件并连上 Wi-Fi 后才可用。

点击 INSTALL 后，弹窗会列出几种烧录方式：

Wirelessly — 通过 Wi-Fi 的 OTA 升级，要求设备已在线。首次烧录设备还没有固件，此项不可用。
Plug into this computer — 设备 USB 插在「正在操作浏览器的这台电脑」上，由浏览器通过 Web Serial 烧录。
Plug into the computer running ESPHome Device Builder — 设备 USB 插在「运行 ESPHome 的那台主机/服务器」上，由服务器端直接烧录。
Manual download — 下载固件二进制文件，自行用 ESPHome Web 工具或 esptool 烧录。

其中 Plug into this computer 依赖浏览器的 Web Serial API，而该 API 仅在 HTTPS（安全上下文）下可用；自建 Home Assistant 的页面通常通过 HTTP 访问，因此这种方式在多数自建环境下不可用。

无论用哪种方式，首次编译耗时较长（视网络与主机性能，约数分钟到十几分钟）。ESPHome 需要下载工具链、编译框架与依赖组件，之后重新编译速度明显加快；编译过程中进度可能暂时不动，属于正常现象，并非卡死。

下面给出两种可行方式，根据实际环境选择其一：

ESPHome Web 工具（推荐）
虚拟机烧录（Device Builder）

ESPHome Web 是官方提供的浏览器烧录工具，本身运行在 HTTPS 站点上，可直接通过 USB 给设备烧录。需 Chrome 或 Edge 浏览器。

在弹窗中选择 Manual download，窗口中会显示构建日志，耐心等待固件编译完成。

编译完成后，选择 Factory format 下载，得到一个 .bin 固件文件，然后关闭窗口。
打开 ESPHome Web，点击 Connect。
浏览器弹出“选择串口”对话框，找到 ESP32-S3-Zero 对应的端口（通常显示为 USB JTAG/serial debug unit 或带 ESP32-S3 字样），点击连接。

烧录失败或看不到端口时
大多数情况下插入 USB 即可直接烧录。如果失败或看不到端口，先拔掉 USB，然后按住 BOOT 键不放再插入 USB，识别到设备后松开 BOOT，重新烧录。
点击 Install，选择第 1 步下载的 .bin 文件，即开始烧录。
烧录成功。

让运行 ESPHome 的主机直接烧录。Home Assistant 跑在虚拟机里时，需先在 VMware 中将 USB 设备分配（直通）给虚拟机，否则虚拟机无法访问宿主机的 USB 端口。

把 ESP32-S3-Zero 插入宿主机的 USB 口。
在 VMware Workstation 顶部菜单 虚拟机 → 可移动设备 中找到 ESP32-S3 对应的条目，点击 连接（断开与主机的连接）。
在弹窗中选择 Plug into the computer running ESPHome Device Builder。
ESPHome 会列出服务器端识别到的串口，选择 ESP32-S3-Zero 对应的端口继续。

烧录失败或看不到端口时
大多数情况下插入 USB 即可直接烧录。如果失败或看不到端口，先拔掉 USB，然后按住 BOOT 键不放再插入 USB，识别到设备后松开 BOOT，重新烧录。
日志中出现 Successfully uploaded program. 即表示烧录成功，随后会开始打印设备运行日志。

看到 [I][safe_mode:142]: Boot seems successful; resetting boot loop counter 后，点击 STOP 关闭日志窗口。

6. 在 Home Assistant 中接入设备

设备烧录成功并连上 Wi-Fi 后，ESPHome 通过 mDNS 广播自身，HA 会自动发现该设备。

切换到 HA 主界面，点击 设置 → 设备与服务。在「已发现」一栏中，可以看到 “esp32-s3-zero ESPHome”。

点击添加，HA 会通过 mDNS 自动获取加密密钥，直接提交即可。
已发现中没有 ESPHome 设备？
- 确认设备与 HA 主机处于同一子网。
- 手动添加：设置 → 设备与服务 → 添加集成 → ESPHome，输入主机名 esp32-s3-zero.local 或设备 IP 地址。设备 IP 可在 ESPHome 应用的 LOGS 中查到。
提交后，HA 会要求为设备分配一个区域（如“客厅”），选择一个区域后点击完成。
接入成功后，HA 会自动跳转到设备页面。也可以进入 设置 → 设备与服务 → ESPHome，找到 esp32-s3-zero，其中有一个名为 RGB LED 的灯光实体。点击开关打开灯光，板载 LED 会亮起。
点击 RGB LED 实体打开控制面板，拖动颜色选择器或亮度滑条，板载 LED 会即时变化。
在 概览 → 客厅 → 灯光 中也能找到 RGB LED 实体，拖动色板同样可以控制 LED。

至此，这块 ESP32 已成为 HA 中的一个灯光设备。

至此，“YAML 编辑 → 烧录 → HA 接入 → 远程控制”的完整流程就完成了。

7. 后续修改：OTA 更新

设备已经联网且包含 OTA 模块，之后修改 YAML 无需再插 USB。

在 ESPHome 应用中编辑设备配置，例如把 LED 名字从 "RGB LED" 改为 "Status Light"，保存。
点击 INSTALL → 选择 Wirelessly。

OTA 后 1 分钟内的重启风险
ota: 组件会自动启用 safe mode，新固件启动后运行 1 分钟的 boot_is_good_after 计时器。计时到点前若发生任何形式的重启（手动按 RESET、断电、崩溃），下次启动会被 ESP-IDF bootloader 回滚到上一版固件；到点后固件会把自己标记为“已确认可用”，此后重启不再回滚。LOGS 中出现 Boot seems successful 即表示新固件已确认。
此回滚机制依赖 esp-idf 框架（本节 YAML 即为 framework: esp-idf），arduino 框架下行为不同。机制详见 ESPHome Safe Mode 文档。
ESPHome 会编译新固件，通过 Wi-Fi 推送到设备并自动重启。HA 中的实体名也会随之更新。

OTA 失败的常见原因：

设备离线：在 ESPHome 应用主界面查看设备状态，灰色表示离线。先解决 Wi-Fi 问题再 OTA。
OTA 密码不匹配：向导生成的密码写在 YAML 的 ota.password。若手动改过该字段但没烧录新固件，OTA 会被设备拒绝。

如果 OTA 失败导致设备无法启动或连不上 Wi-Fi，可以用 USB 重新烧录恢复。

8. 本节常见问题

编译报错 YAML syntax error：缩进出错。检查是否混用了 Tab 与空格、对齐是否一致。
编译报错 Unable to find component xxx：组件名拼写错，或当前 ESPHome 版本不包含该组件。在 ESPHome 组件目录查证准确名字。
烧录时看不到设备端口：未进入下载模式（见第 5 节“烧录失败或看不到端口时”），或主机识别不到 USB 设备（换数据线、换 USB 口）。用虚拟机烧录时还要确认 USB 设备已在 VMware 中分配给虚拟机。
烧录后 LED 不亮：检查 rgb_order 是否为 RGB；用 HA 拖动色板而不是仅亮度滑条（亮度 100% 但颜色为黑时 LED 仍不亮）。
HA 没有自动发现设备：见第 6 节第 1 步的提示。也可在 ESPHome 设备 LOGS 中确认是否成功连上 Wi-Fi 与 API。
OTA 失败 Connection refused：设备运行的固件 OTA 密码与当前 YAML 不一致，用 USB 重新烧录即可同步。
HA 显示实体“不再可用”，但 ESPHome 中设备 ONLINE：触发了 OTA 安全回滚——新固件 1 分钟内重启会被 bootloader 回滚到上一版。在 LOGS 中搜索 OTA rollback detected 确认，USB 重新烧录恢复。详见第 7 节的警告说明。

9. 参考链接

文档反馈

1. 准备工作​

2. 用向导创建配置​

3. 必备的最小 YAML 概念​

3.1 YAML 缩进与列表​

3.2 !secret 与 secrets.yaml​

4. 添加板载 RGB LED​

5. 编译与首次烧录​

6. 在 Home Assistant 中接入设备​

7. 后续修改：OTA 更新​

8. 本节常见问题​

9. 参考链接​