深夜想给阳台加一个温湿度上报,手里只有一块 ESP32 开发板和一支 DHT22。写 C 固件要搭工具链、处理 WiFi 重连和上报协议,一晚上未必调得通。ESPHome 把这些全变成了几行配置:你只描述「我有什么传感器、想让它干什么」,剩下的固件编译、刷写、联网重连,它全包了。
项目名片
| 项目 | 内容 |
|---|---|
| 仓库 | esphome/esphome |
| star / fork | 12093 / 5801(2026-11-13 抓取) |
| 技术栈 | Python + C++(固件运行时) |
| 许可证 | MIT + GPLv3 双许可(Python 部分 MIT,C++ 运行时 GPLv3,已核对 LICENSE 原文) |
| 最新版本 | 2026.10.2(2026-11-02 发布) |
| 默认端口 | 6053(Web 控制台与设备 API 同用) |
它解决什么问题
自己给一块 ESP 板写联网固件,难的不是读传感器,而是 WiFi 断线重连、OTA 升级、状态上报、本地控制这一整套外围工作。每做一个新设备都要重新踩一遍。ESPHome 把这些写成了通用组件,你只维护一份 YAML:温度传感器用 dht 组件声明,按键用 binary_sensor 声明,编译出的固件自带这些能力。芯片支持面上,ESP32、ESP8266 之外,BK72xx、RP2040 也在官方支持列表里,家里二手便宜的智能插座模块不少能洗成自己的设备。某些场景下它可以替代手写 C 固件,替不掉的是极端省内存的场合和对时序要求苛刻的自定义协议——那些还是得回到底层代码。
核心机制
- 配置即固件:YAML 描述传感器、开关、显示,编译时才生成对应 C++ 代码。(推断:这正是它比通用固件省资源的原因,没配的组件不会进二进制。)
- 双通道更新:第一次用 USB 线刷,之后所有改动走 OTA 无线升级,设备不拆也能改逻辑。固件里还内置了版本回滚保护,升级失败会退回上一个能用的版本。
- 原生 API 直连:设备和 Home Assistant 用自定义 TCP 协议通信,不走云端,断网也能本地联动。协议基于 protobuf 定义,开源的 aioesphomeapi 库也能直接调用它。
- 回退热点:设备连不上 WiFi 时自动开一个配置热点,手机连上去改密码,不用重新接线。
- 编译走缓存:只有配置变动的部分会重新编译,改一行传感器阈值,十几秒就能出固件。(推断:缓存粒度是组件级,这也是 OTA 升级通常几十秒内完成的原因。)
跑起来
装 Docker 的机器上一条命令起控制台:
V=/opt/esphome
docker run -d --name esphome \
--net=host \
--restart unless-stopped \
-v $V:/config \
ghcr.io/esphome/esphome
然后浏览器打开 http://你的服务器IP:6053 就能看到控制台。没有 Docker 也可以用官方安装脚本装成系统服务,桌面用户则推荐官方的 ESPHome Device Builder。设备端不需要装任何东西,固件全部由控制台编译产出。
从零到能用
- 在控制台首页点 New device,按向导给设备起名,生成一份基础 YAML。
- 在 YAML 里加一段
dht传感器配置,声明接的是哪个 GPIO 引脚。 - 用 USB 线接上开发板,点 Install 选 Plug into this computer,等编译完成自动刷入。
- 设备启动后连上你的 WiFi,在 Home Assistant 的集成页里确认它出现在 discovered 列表,点添加即可。
- 之后每次改完 YAML 点 Install,选 wirelessly,设备几秒内完成 OTA 升级。
- 想加按键、屏幕、继电器,照官方组件文档在 YAML 里加几行,重复第 5 步。
适合谁用 / 别用
适合手里攒了一堆 ESP 开发板、想把它们变成正经智能家居传感器的人,也适合想给简历加一个「从固件到上位平台」完整项目的学生,YAML 本身就是一份可读的设备说明书。
别用它做电池要撑一年的低功耗采集终端虽然能做但深睡配置细节多,新手容易卡住;也别指望它接工业现场总线设备,那类需求请交给专门的协议网关。
三个真实的坑
- ESP8266 深度睡眠不醒。官方文档原文写明:ESP8266 要定时唤醒,GPIO16 必须接到 RST 引脚;而且 D1 mini 这类板子的板载 USB 芯片连着 RST,USB 供电时可能直接唤不醒,要改用独立 3.3V 供电。出处:esphome.io 的 deep_sleep 组件文档。
- 设备莫名其妙自己重启。api 组件默认 reboot_timeout 是 15 分钟:没有任何客户端完成认证连接,设备就主动重启,这是官方为了恢复假联网状态的设计。Home Assistant 长期停机的用户几乎都会撞上,设成 0s 可关闭。出处:esphome.io 的 api 组件文档。
- 日志里刷 Component took a long time for an operation。这是仓库 issue 区最热闹的帖子之一(issue 9517,384 条评论),多半是某个组件阻塞了主循环导致看门狗告警,常见诱因是网络慢或传感器轮询过重,官方后续版本做了调度优化。出处:github.com/esphome/esphome issue 9517。
小结
回到开头那个阳台:从通电到温湿度出现在 Home Assistant 里,一套 ESPHome 流程大概二十分钟,其中大部分时间在等编译。今晚拿一块板子试一次,你就会明白为什么社区把它当作智能家居 DIY 的事实标准。
参考资料
- 仓库:https://github.com/esphome/esphome
- 文档:https://esphome.io
- 深睡组件:https://esphome.io/components/deep_sleep/
- API 组件:https://esphome.io/components/api/
- issue 9517:https://github.com/esphome/esphome/issues/9517
默认评论
Halo系统提供的评论