项目地址: https://github.com/esphome/esphome
官方文档: https://esphome.io/
PyPI:
esphome2026.10.2(截至 2026-11,PyPI 与 GitHub Releases 一致;2026.11.0 仍处于 beta)许可证: MIT(部分组件依赖的第三方库另有许可)
概述
ESPHome 是一个「用 YAML 生成 ESP 固件」的框架。你描述设备有什么(板子型号、传感器接在哪个引脚、要暴露哪些实体),它负责生成 C++、编译、上传,并把设备自动接入 Home Assistant。
核心模型:
- 一份 YAML = 一台设备:
esphome:、esp32:、wifi:、api:、ota:是骨架,其余都是组件 - 组件(component):
sensor:、binary_sensor:、light:、display:等平台,每个下面按platform:选具体实现 - 实体(entity):组件里带
name:的条目会变成 Home Assistant 的实体;不带name的是内部件 - 原生 API:
api:段启用 protobuf over TCP(默认 6053),是 HA 集成的首选通道;MQTT 是另一条可选通道 - OTA:
ota: - platform: esphome让后续更新走网络,不必每次插 USB
相比手写 Arduino/ESP-IDF,它把构建系统、网络栈、HA 对接、OTA 都收敛到声明式配置里;代价是组件能力受框架支持范围限制。
环境准备
方式一:pip 安装 CLI(推荐,可脚本化)
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install esphome==2026.10.2
esphome version
esphome version 应打印 Version: 2026.10.2。CLI 会自行下载 PlatformIO 与工具链(首次编译较慢)。
方式二:Docker
docker run --rm -it \
-v "$PWD":/config \
-v esphome-cache:/cache \
--network host \
ghcr.io/esphome/esphome:2026.10.2 version
把 /config 指向存放 YAML 的目录;串口烧写需要额外 --device /dev/ttyUSB0 直通。
方式三:ESPHome Device Builder(图形界面)
ESPHome 2026.10(当前稳定版)已移除内置 dashboard(执行 esphome dashboard 会提示迁移),图形界面改用独立包:
pip install esphome-device-builder
esphome-device-builder
也可用官方 Device Builder 容器,在浏览器里点选配置。命令行仍是理解配置与做自动化的主路径,本技能以 CLI 为准;详见 https://github.com/esphome/device-builder。
验证
esphome version
esphome config my-device.yaml # 校验配置并打印最终生效内容
第二条命令不接硬件就能验证 YAML 是否正确,是改配置后的第一道检查。
核心 API / 配置
最小可用骨架
esphome:
name: livingroom
friendly_name: Living Room
area: "Living Room"
esp32:
variant: esp32s3 # 或 esp32 / esp32c3 / esp32c6 …;推荐用 variant 而非 board
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
manual_ip:
static_ip: 192.168.1.50
gateway: 192.168.1.1
subnet: 255.255.255.0
api:
encryption:
key: !secret livingroom__encryption_key
ota:
- platform: esphome
logger:
sensor:
- platform: dht
pin: GPIO4
temperature:
name: "Living room temperature"
humidity:
name: "Living room humidity"
update_interval: 60s
要点:
name只允许小写字母、数字与连字符,默认最长 24 字符(name_add_mac_suffix: false时可达 31);esp32段至少要给variant或board之一,两者须指向同一型号;新配置用variant;wifi必须存在(或 Ethernet 等其它网络段),否则校验阶段就失败;api.encryption.key建议与ota复用同一把密钥。
常用组件速览
| 组件 | 用途 | 关键字段 |
|---|---|---|
sensor |
数值型实体 | platform、name、update_interval |
binary_sensor |
开关量实体(门磁、人体感应) | platform、device_class |
switch / light |
可执行实体 | platform(gpio、esp32_rmt_led_strip 等) |
output |
底层 PWM/GPIO 输出 | platform、pin |
display |
OLED/LCD/墨水屏 | platform、lambda |
i2c / spi / uart |
总线定义 | sda/scl、mosi/clk、tx_pin/rx_pin |
mqtt |
接入 MQTT 而非原生 API | broker、topic_prefix |
web_server |
浏览器直接看状态 | port(默认 80) |
substitutions 与 packages
substitutions 用 bash 风格语法 ${key}(等价于 $key),适合一份文件跑多台设备:
substitutions:
device_name: livingroom
room: "Living Room"
esphome:
name: ${device_name}
friendly_name: ${room} Controller
sensor:
- platform: dht
pin: GPIO4
temperature:
name: "${room} temperature"
命令行也能覆盖(可多次给出):esphome run -s device_name kitchen my-device.yaml。
packages 用来复用公共片段:
packages:
base: !include common/base.yaml
wifi: !include common/wifi.yaml
关键配置项对照
| 段 | 字段 | 说明 |
|---|---|---|
api |
port |
默认 6053 |
api |
encryption.key |
加密密钥;写入后 HA 需填同一把 base64 密钥 |
api |
batch_delay |
默认 100ms;实时性要求高时降到 50ms |
ota |
platform: esphome + encryption: |
复用 api 加密密钥(推荐;password 与 encryption 互斥) |
ota |
platform: esphome + password |
旧式退路:只认证上传方、不保密镜像,官方已标注不推荐新设备使用 |
wifi |
manual_ip |
固定 IP,显著改善连接时间 |
esp32 |
flash_size |
2MB–32MB;写超过实际容量会导致无法启动 |
命令行
基本形式:esphome [OPTIONS] <COMMAND> <CONFIGURATION...>,部分命令支持一次给多个 YAML。
| 命令 | 作用 |
|---|---|
run <CONFIG> |
校验 → 编译 → 上传(OTA 或 USB)→ 打开日志,最常用 |
config <CONFIG> |
只校验并打印最终配置 |
config-hash <CONFIG> |
计算配置哈希,可与设备上的 Version 文本传感器比对 |
compile <CONFIG> |
只编译(--only-generate 仅生成 C++ 不编译) |
upload <CONFIG> |
上传最近一次构建的固件 |
logs <CONFIG> |
只看日志 |
clean / clean-all |
清理当前构建目录 / 清理全部构建目录 |
clean-mqtt |
清除 MQTT 保留的发现消息 |
bundle / analyze-memory |
打出可离线构建的配置包 / 分析内存占用 |
wizard <CONFIG> |
交互式生成配置骨架 |
dashboard(已移除) |
旧内置面板;现在会报错并提示改用 esphome-device-builder |
常用选项:
| 选项 | 作用 |
|---|---|
--device <port-or-ip> |
指定串口或 IP;可多次给出做兜底(如 --device 192.168.1.100 --device 2001:db8::1);写 OTA 表示自动解析地址 |
--upload_speed <baud> |
串口上传速率,默认 460800 |
--no-logs |
上传完不打开日志(CI 里必加) |
-s / --substitution KEY VALUE |
覆盖 substitution,可多次 |
--only-generate |
只生成 C++ 源码、不编译(compile 子命令) |
--toolchain <T> |
esp-idf(ESP32 默认)/ arduino(ESP8266 默认)/ sdk-nrf / host / platformio |
-v / --verbose / -q / --quiet |
打开 / 关闭 ESPHome 自身的日志 |
选项以本机
esphome <command> --help为准:ESPHome 2026.10 的 CLI 已没有--error-format,旧教程里的该参数会直接报错。
# 首次:USB 烧写并进日志
esphome run livingroom.yaml --device /dev/ttyUSB0
# 之后:走 OTA 更新
esphome run livingroom.yaml --device 192.168.1.50
# CI:只校验,不编译不上传(config 子命令本身即退出码化校验)
esphome config livingroom.yaml
典型工作流:新设备 → 配置 → USB 首刷 → OTA 更新 → HA 接入
目标:让一块 ESP32-S3 + DHT 温湿度传感器从零变成 Home Assistant 里的两个实体,并验证 OTA 通路。
步骤 1:生成骨架并填硬件参数
esphome wizard livingroom.yaml # 交互式填 name / 板型 / WiFi
esphome config livingroom.yaml # 先确认骨架校验通过
把 esp32.variant 改成实际型号(如 esp32s3),WiFi 与密钥移入 secrets.yaml。
步骤 2:加传感器与实体名
在 YAML 末尾追加上一节的 sensor: 段(DHT 接 GPIO4),name 用人能读懂的名字。
esphome config livingroom.yaml | grep -A 3 "Living room temperature"
步骤 3:USB 首次烧写
esphome run livingroom.yaml --device /dev/ttyUSB0
编译完成后开始上传,随后进入日志视图;看到 WiFi 连上、api 服务启动即可拔线。
步骤 4:OTA 更新(改配置后的常规路径)
esphome run livingroom.yaml --device 192.168.1.50
esphome run livingroom.yaml --device 192.168.1.50 --no-logs # 脚本/CI
步骤 5:Home Assistant 接入与验收
在 HA 的 设置 → 设备与服务 等待 ESPHome 集成自动发现(最多约 5 分钟),或手动添加并填 livingroom.local 或 IP;启用了加密则填同一把 base64 密钥。
# 1) 日志里能看到传感器读数变化
esphome logs livingroom.yaml
# 2) 配置哈希与设备上报一致(排错很有用)
esphome config-hash livingroom.yaml
# 3) HA 侧实体存在且状态在变(需要长期令牌)
curl -s -H "Authorization: Bearer $TOKEN" \
http://homeassistant.local:8123/api/states/sensor.living_room_temperature
最佳实践
- 配置进版本控制:YAML 是唯一事实来源;
secrets.yaml与.esphome/放进.gitignore。 - 优先
variant而非board:官方已把board标为不再推荐,variant会自动补标准 devkit 配置。 - 固定 IP:
wifi.manual_ip明显缩短连接时间,也让 OTA 目标稳定。 - 密钥复用:
api.encryption.key与ota.encryption共用一把,减少漏配。 - 改配置必跑
esphome config:比直接run快得多,且不碰硬件就能抓出拼写与缩进错误。 - 公共片段用
packages:WiFi、OTA、基础诊断抽到common/*.yaml,避免逐台复制。 - CI 用
--no-logs:否则会挂在日志视图上;校验是否通过看esphome config的退出码与报错行。 - OTA 翻车留后路:保留可插 USB 的物理通道,并开启 safe mode(OTA 平台默认启用),否则配置写错可能只能拆机重刷。
常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
校验报 Component not found / Platform not found |
组件名拼错,或该平台不支持当前芯片 | 核对官方组件页名称;ESP8266 上不存在的 ESP32 专属平台会直接报错 |
esphome run 卡在 "Looking for ESP" |
串口名不对,或用户不在 dialout/uucp 组 |
ls /dev/ttyUSB* 确认端口;把用户加入串口组后重新登录 |
| OTA 上传失败或连接被拒 | IP 变了、设备掉线,或旧固件没开 OTA | 先用 ping 与 esphome logs 确认在线;确认 YAML 有 ota: 段且至少刷入过一次 |
HA 里实体缺失或 unavailable |
组件没写 name,或 API 加密密钥不匹配 |
给组件条目补 name;在 HA 里重新配置 ESPHome 集成并填同一密钥 |
| 编译报工具链/依赖下载失败 | 首次构建需联网拉 PlatformIO 平台与库 | 换网络或配代理;Docker 形态把 /cache 挂成卷复用 |
| 刷完反复重启(boot loop) | flash_size / flash_mode 与实际芯片不符,或引脚冲突 |
改成实际值(如 8MB);检查是否把启动引脚复用成普通 GPIO |
${key} 没被替换 |
substitution 名大小写不匹配,或引用早于定义 | 名字小写且与 substitutions 键完全一致;必要时用 -s 覆盖调试 |
日志反复出现 WiFi: Connection lost |
信号弱或密码错误 | 用 manual_ip 并靠近 AP;先用手机确认密码;必要时调 reboot_timeout |
AI 使用建议
- 先探版本:
esphome version确认与文档一致(2026.10.2);CLI 选项随版本改名,旧教程里的参数可能已失效。 - 不碰硬件也能验证:改完先跑
esphome config <yaml>,过了校验再谈烧写,能省大量插拔。 - 写盘前确认设备目标:
run/upload会覆盖设备固件,--device指错可能刷到别的设备;执行前向用户确认端口或 IP。 - 验证产物:烧写后用
esphome logs看启动日志与读数,并用config-hash与设备上报值比对,确认刷进去的是这次构建。 - 密钥不入库:
secrets.yaml与示例里的!secret占位符不要换成真实值提交,报告里也不要粘贴加密密钥。
相关技能
- home-assistant — 设备最终接入的平台与 API:../home-assistant/SKILL.md
- node-red — 用低代码编排设备数据流:../node-red/SKILL.md
- ke3036-keyes-pico — MicroPython 路线的对照(RP2040 学习套件):../ke3036-keyes-pico/SKILL.md
- ollama — 本地大模型,可与 HA 语音助手组合:../../ai/ollama/SKILL.md
参考资源
- 官方文档:https://esphome.io/
- CLI 参考:https://esphome.io/guides/cli/
- 组件索引:https://esphome.io/components/
- 安全最佳实践(密钥与 WiFi):https://esphome.io/guides/security_best_practices/