esphome

项目地址： https://github.com/esphome/esphome

官方文档： https://esphome.io/

PyPI： esphome 2026.10.0（GitHub Releases 同日发布，截至 2026-10）

许可证： 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.0

esphome version

esphome version 应打印 Version: 2026.10.0。CLI 会自行下载 PlatformIO 与工具链（首次编译较慢）。

方式二：Docker

docker run --rm -it \
  -v "$PWD":/config \
  -v esphome-cache:/cache \
  --network host \
  ghcr.io/esphome/esphome:2026.10.0 version

把 /config 指向存放 YAML 的目录；串口烧写需要额外 --device /dev/ttyUSB0 直通。

方式三：ESPHome Device Builder（图形界面）

官方容器也能以 dashboard 形态运行（暴露 6052 端口），在浏览器里点选配置。命令行仍是理解配置与做自动化的主路径，本技能以 CLI 为准。

验证

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