ESPHome

ESPHome 让你用 YAML 文件描述「这块板子接了什么传感器、有哪些开关」，由它自动生成并编译固件，通过 Wi-Fi 无线更新，并和 Home Assistant 深度集成。它是 ESP32 做智能家居节点时最省事的选择，适合不想写 C++ 的人。

概览

ESPHome 由 Open Home Foundation 旗下的项目维护（原由 Nabu Casa 赞助，项目整体归入基金会），源码采用开源许可（核心为 MIT / GPL 混合，C++ 运行时为 LGPL，具体以仓库说明为准）。

它的工作流程：

在 YAML 里声明芯片、Wi-Fi、传感器、开关。
ESPHome 把 YAML 翻译成 C++ 工程，调用 PlatformIO / ESP-IDF 工具链编译。
第一次通过 USB 烧录，之后通过 OTA（无线更新）。
Home Assistant 通过「原生 API」自动发现设备，实体立刻可用。

最新版本：官网头部显示 2026.9.1，对应 2026.9 发布日志，博文日期为 2026-09-16。ESPHome 按「年.月」发版，大致每月一次，几乎每个版本都有破坏性变更，升级前一定要读更新日志。

关键信息

一个最小示例

以下 YAML 保存为 living-room.yaml，在 ESPHome（Home Assistant 加载项或本地命令行）里编译，烧录到 ESP32-S3 开发板运行：

yaml

esphome:
  name: living-room

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

logger:
api:
  encryption:
    key: !secret api_key
ota:
  - platform: esphome
    password: !secret ota_password

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

i2c:
  sda: GPIO8
  scl: GPIO9

sensor:
  - platform: bme280_i2c
    address: 0x76
    temperature:
      name: "Living Room Temperature"
    humidity:
      name: "Living Room Humidity"
    update_interval: 60s

switch:
  - platform: gpio
    pin: GPIO4
    name: "Desk Lamp"

!secret 对应同目录 secrets.yaml 中的变量。引脚、板型、OTA 写法不同版本可能有差异，请以当前文档为准。

命令行

在本地电脑执行：

bash

pip install esphome
esphome run living-room.yaml    # 编译、烧录并查看日志；首次用 USB，之后可选择 OTA
esphome logs living-room.yaml

Device Builder 与 Web 烧录

ESPHome 的网页管理界面通常以 Home Assistant 加载项或 Docker 容器形式运行。官方现在称其为 ESPHome Device Builder（早期叫 ESPHome Dashboard 或 ESPHome Builder，更名时间我没有逐一核对）。它提供：

浏览器里编辑 YAML、编译、查看日志。
通过 WebSerial 直接从浏览器烧录（需要 Chrome / Edge 等支持 Web Serial 的浏览器），原理见烧录工具。
设备「Adopt」（接管）功能，把别人已有的 ESPHome 固件纳入管理。

芯片与框架支持

ESPHome 的 esp32 平台可选框架 arduino 或 esp-idf，新项目官方文档一般推荐 esp-idf。2026.9 变更日志里能看到：

ESP32-S31 相关的显示功能（mipi_rgb 的 execute_from_psram）。
esp32_hosted 要求 ESP-IDF 5.3 及以上。
在 ESP32 上用自定义 eFuse MAC 作为所有接口的基础 MAC（破坏性变更）。
为 ESP8266 添加原生框架与工具链安装器。
OTA 支持 Noise 加密。

除乐鑫芯片外，它还支持 RP2040 / RP2350、部分 BK72xx 与 RTL87xx（LibreTiny）。具体到某颗乐鑫芯片的支持程度，请查官方 esp32 组件文档。

能力与局限

数百种传感器、显示屏、灯带、语音（voice_assistant、micro_wake_word）、LVGL、BLE 代理、蓝牙网关组件都以配置形式提供。
支持 lambda: 内嵌 C++ 与自定义组件，必要时可以突破配置的限制。
它不是通用编程框架：不适合写复杂状态机或非 Home Assistant 场景的产品。
固件依赖 Home Assistant 的 API 才能发挥全貌，也可以只用 MQTT 或 Web Server 组件。

暴露设备时的注意事项

web_server 组件默认可被局域网访问。如果需要外网访问，不要直接把设备端口映射到公网；开启 API 加密密钥与 OTA 密码，并通过 VPN 或 Home Assistant 的认证入口访问。

适合谁 / 不适合谁

适合 Home Assistant 用户、想批量部署传感器节点、不想维护 C++ 的人。不适合：需要自定义协议栈、严格时序驱动、或完全不使用 Home Assistant 且想要高度定制固件的场景。相关玩法见智能家居。

参考资料

ESPHome 官网：https://esphome.io/
ESPHome 更新日志：https://esphome.io/changelog/
ESPHome ESP32 组件文档：https://esphome.io/components/esp32/
Open Home Foundation：https://www.openhomefoundation.org/

ESPHome ​

概览 ​

关键信息 ​

一个最小示例 ​

命令行 ​

Device Builder 与 Web 烧录 ​

芯片与框架支持 ​

能力与局限 ​

适合谁 / 不适合谁 ​

参考资料 ​