Skip to main content

ESPHome

  • esphome/esphome
    • ESPHome 使用 YAML 配置为 ESP32、ESP8266、BK72xx、RP2040、nRF52、RTL87xx 等芯片生成固件，并接入 Home Assistant / MQTT 等自动化系统。
  • 官网：https://esphome.io/
  • 特点
    • YAML 配置，不需要直接写 C++。
    • 支持 OTA 更新。
    • 支持传感器、开关、灯、显示屏、总线、媒体、蓝牙代理等组件。
    • 默认偏本地控制，常和 Home Assistant native API 配合使用。

CLI​

# 创建配置
esphome wizard livingroom.yaml

# 校验、编译、上传、看日志
esphome run livingroom.yaml

# 只编译
esphome compile livingroom.yaml

# 看日志
esphome logs livingroom.yaml

# 清理构建缓存
esphome clean livingroom.yaml

# 启动 Device Builder / dashboard
esphome dashboard config

Docker：

docker pull ghcr.io/esphome/esphome

# Linux USB 首刷
docker run --rm --privileged \
  -v "$PWD":/config \
  --device=/dev/ttyUSB0 \
  -it ghcr.io/esphome/esphome run livingroom.yaml

# Dashboard
docker run --rm --net=host \
  -v "$PWD":/config \
  -it ghcr.io/esphome/esphome
  • macOS Docker 不能直接透传 USB 设备，USB 首刷不适合在 Docker for Mac 内做；可用 ESPHome Web / esptool / 原生环境首刷。
  • 首次刷入通常需要 USB；之后可通过 OTA 更新。
  • Docker tag 建议固定到 YEAR.MONTH 或明确版本，不要无脑跟随 latest。

配置骨架​

substitutions:
  name: livingroom
  friendly_name: Living Room

esphome:
  name: ${name}
  friendly_name: ${friendly_name}
  project:
    name: wener.livingroom
    version: "1.0.0"

esp32:
  variant: esp32
  framework:
    type: esp-idf

logger:

api:
  encryption:
    key: !secret api_encryption_key

ota:
  - platform: esphome
    password: !secret ota_password

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: ${friendly_name} Fallback
    password: !secret fallback_ap_password

核心字段​

字段说明
esphome.name节点名，影响 mDNS、OTA、构建目录
esphome.friendly_name展示名称
esphome.project项目信息，会暴露到 device info / logger / mDNS
esp32.variantESP32 芯片族，推荐显式设置
esp32.boardPlatformIO board ID；新配置优先用 variant，board 主要影响 pin alias 和默认参数
esp32.framework.typeesp-idf 或 arduino；新 ESP32 变体多要求 ESP-IDF
logger串口/运行日志
apiHome Assistant native API
otaOTA 更新入口
wifiWi-Fi 和 fallback AP
secrets.yaml保存 Wi-Fi、API key、OTA password 等私密值
substitutions字符串替换，适合统一设备名、GPIO、尺寸等参数
packages拆分公共配置，适合多设备复用

ESP32​

  • 至少设置 esp32.variant 或 esp32.board 之一。
  • 官方推荐新配置优先用 variant；board 仍可用于兼容旧配置和 pin alias。
  • 常见 variant：esp32、esp32s2、esp32s3、esp32c3、esp32c6、esp32h2、esp32p4。
  • 经典 ESP32 没有原生 USB，刷机/串口依赖外部 USB-UART 或板载辅助 MCU。
  • 如果商业设备里的 ESP32 在默认最高频率下重启或启动失败，可尝试设置 cpu_frequency: 160MHz。
  • flash_size 不要写大于实际 flash 的值，否则可能无法启动。
esp32:
  variant: esp32
  flash_size: 4MB
  cpu_frequency: 160MHz
  framework:
    type: esp-idf

Packages​

packages:
  device: !include packages/device.yaml
  sensors: !include packages/sensors.yaml
  display: !include packages/display.yaml
  • 用 packages/ 拆分设备、传感器、显示、网络、通用行为。
  • 配合 substitutions 可以复用同一份配置到多个设备。
  • package 里使用新特性时，可以在 esphome.min_version 标注最低 ESPHome 版本。

常用组件​

组件用途
binary_sensorGPIO 按键、门磁、在线状态
sensorADC、温湿度、Wi-Fi signal、uptime
text_sensorWi-Fi info、版本、IP
switchGPIO 开关、模板开关
outputPWM、LED、蜂鸣器输出
light单色/RGB 灯
i2cI2C 总线和传感器
spiSPI 总线、显示屏、外设
displayTFT、OLED、电子纸等显示
timeHome Assistant / SNTP 时间源
web_server本地 Web 管理页面

小喵掌机方向​

spi:
  - id: lcd_spi
    clk_pin: GPIO18
    mosi_pin: GPIO23

display:
  - platform: mipi_spi
    id: tft_display
    model: ST7735
    spi_id: lcd_spi
    cs_pin: GPIO5
    dc_pin: GPIO4
    reset_pin: GPIO19
    rotation: 90
    dimensions:
      width: 128
      height: 160
  • 小喵/MeowBit 类硬件可把 ESPHome 当作硬件验证工具：先验证 Wi-Fi、ADC、按键、I2C、TFT 显示，再决定是否转 MicroPython/LVGL/原生固件。
  • GPIO34、GPIO35、GPIO36、GPIO39 是 input-only，适合按键/ADC，不适合作输出。
  • TFT 与 MicroSD 共享 SPI 时，要确认各自 CS 和驱动访问方式。

FAQ​

改名后 OTA 找不到设备怎么办？​

用旧地址上传一次：

wifi:
  use_address: old-name.local

上传成功后再移除 use_address。

什么时候用 ESP-IDF，什么时候用 Arduino？​

  • 新项目优先 ESP-IDF。
  • 需要 Arduino-only 组件或库时再考虑 Arduino framework。
  • ESP32-C2/C5/C6/C61/H2/P4 等新变体通常要求 ESP-IDF。

secrets.yaml 放什么？​

  • Wi-Fi SSID/password
  • API encryption key
  • OTA password
  • MQTT password
  • 外部服务 token

不要把 secrets.yaml 提交到公开仓库。

参考​