ESPHome 第一个设备：不写 C++，把一个按钮接进 Home Assistant · ESP32 专栏

01 / 家庭设备

先做本地闭环，再检查HA实体

本篇把物理按钮状态发布给Home Assistant，同时让按钮在ESP32本地切换一盏外接LED。HA还能通过同一个开关实体控制LED；断开HA时本地按钮仍有可观察的任务，不需要先建立自动化规则。

按钮在HA中是binary_sensor，表示按下/释放；External LED是switch，表示输出开关；Restart是可选的软件按钮实体。实体出现与物理动作正确是不同检查点，后面分别验证。本文的实板与HA流程尚未在本站执行，不把软件构建成功写成已接入。

GPIO5内部上拉按钮本地切GPIO4，GPIO4串330欧与WP7113ID到地，HA可独立控制同一个输出。 — 接线图按钮本地动作与HA API控制分别验收。本站原创概念示意，非实物照片或本站运行截图。本站原创 · CC BY 4.0

参考：[1] ESPHome2026.9.1固定发布与源码 [3] ESPHome2026.9.1：GPIO按钮与触发初态规则 [4] ESPHome2026.9.1：GPIO开关

02 / 家庭设备

断电接GPIO4和GPIO5，板载RGB留给另一任务

只用USB-to-UART接口给参考板供电。GPIO4（J1-4）串330Ω电阻接WP7113ID阳极，阴极接GND；GPIO5（J1-5）经常开按钮接GND，软件内部上拉。四脚按钮要先用断电通断档确认按下才导通的两组，不按外形猜。

外接LED与v1.1板载GPIO38可寻址RGB不是同一种器件，本例不控制板载RGB。330Ω为本例固定限流值；若沿用基础课的1kΩ，亮度可能较低，应在记录中说明，不能省掉电阻或把GPIO接5V。

主控端	器件端	检查
GPIO4/J1-4	330Ω→LED阳极	LED阴极到GND
GPIO5/J1-5	按钮一组	另一组到GND；不接5V
USB-to-UART	电脑USB数据线	本例唯一供电来源

参考：[2] DevKitC-1 v1.1固定文档提交927ed7e：排针、电源与USB [9] Kingbright WP7113ID V.14A

03 / 家庭设备

用Python3.12.13建立独立环境并锁2026.9.1

该ESPHome版本要求Python至少3.12，系统自带3.9不能直接运行。本轮实际使用macOS arm64的Python3.12.13；下载包含顶层requirements.txt与该环境完整pip锁。其他系统按上游安装，不能把含macOS专用包的锁文件直接装到Linux。

在本例目录创建虚拟环境，安装esphome==2026.9.1。第一次编译下载IDF5.5.5与工具，需要数GB空间；保留失败日志，优先解决版本、路径或网络原因。默认不需要安装Arduino core。

复制secrets.example.yaml为私有secrets.yaml，填真实2.4GHz Wi-Fi、随机恢复热点密码和新生成的32字节Base64 API密钥。公开包只保留REPLACE占位符；全零密钥会被该版拒绝。API与本例加密OTA使用同一个密钥，不能公开提交。

python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
cp secrets.example.yaml secrets.yaml
.venv/bin/python -c "import secrets,base64; print(base64.b64encode(secrets.token_bytes(32)).decode())"
.venv/bin/esphome version

参考：[1] ESPHome2026.9.1固定发布与源码 [5] ESPHome2026.9.1：加密OTA schema与密钥继承 [6] ESPHome官方安装与首个设备（页面核查2026.10.18）

04 / 家庭设备

完整YAML：本地切灯、加密API与恢复入口

下载中的同名YAML是完整设备配置。flash_size、QIO80MHz与Octal PSRAM对应N8R8；UART0日志固定115200，先插桥接口。开关ALWAYS_OFF让初始化从关开始，按钮不在初始状态触发自动动作，30ms双边滤波是可调整初值。

api.reboot_timeout=0s使HA客户端离线时不因API超时重启；Wi-Fi断线也不以超时重启作为默认恢复。恢复热点与USB是明确的维护入口。本例没有C++ lambda；动作由ESPHome已有组件生成。

esphome:
  name: esp32-h01
  friendly_name: ESP32 H01
  min_version: 2026.9.1
  on_boot:
    priority: -100
    then:
      - logger.log: "H01-A booted; inspect real device logs"

esp32:
  board: esp32-s3-devkitc-1
  variant: ESP32S3
  flash_size: 8MB
  flash_mode: qio
  flash_frequency: 80MHz
  toolchain: esp-idf
  framework:
    type: esp-idf
    version: 5.5.5

psram:
  mode: octal
  speed: 80MHz

logger:
  baud_rate: 115200
  hardware_uart: UART0
  level: DEBUG

api:
  encryption:
    key: !secret api_key
  reboot_timeout: 0s

ota:
  - platform: esphome
    encryption:
      key: !secret api_key

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  reboot_timeout: 0s
  ap:
    ssid: "esp32-h01 Recovery"
    password: !secret fallback_password
    ap_timeout: 90s

captive_portal:

switch:
  - platform: gpio
    id: external_led
    name: "External LED"
    pin: GPIO4
    restore_mode: ALWAYS_OFF

binary_sensor:
  - platform: gpio
    id: physical_button
    name: "Physical button"
    trigger_on_initial_state: false
    pin:
      number: GPIO5
      inverted: true
      mode:
        input: true
        pullup: true
    filters:
      - delayed_on_off: 30ms
    on_press:
      then:
        - switch.toggle: external_led

button:
  - platform: restart
    name: "Restart"

text_sensor:
  - platform: version
    name: "ESPHome version"

参考：[1] ESPHome2026.9.1固定发布与源码 [3] ESPHome2026.9.1：GPIO按钮与触发初态规则 [4] ESPHome2026.9.1：GPIO开关 [5] ESPHome2026.9.1：加密OTA schema与密钥继承

05 / 家庭设备

首次USB写入后，拿真实IP加入HA

先运行config，再compile；两者通过后才使用run并指定随插拔变化的实际串口。首次上传关闭其他串口工具；自动连接超时时按住BOOT、短按RESET、释放BOOT再试，完成后松开BOOT并RESET。

在UART日志确认H01-A、Wi-Fi与实际IP，再到HA设置→设备与服务→添加集成选择ESPHome。输入IP或主机名、默认端口6053及同一API密钥。mDNS跨网段不可达时手动输入IP；不为本教程开放公网端口。

到开发者工具→状态记录真实entity_id。做10次约0.2秒按下/释放，按钮状态应对应，LED每次切一次；长按2秒应只切一次。再从HA操作External LED，分别观察实体与实物；断开HA后检查本地按钮，再重连检查状态恢复。

.venv/bin/esphome config esp32-esphome-first-device.yaml
.venv/bin/esphome compile esp32-esphome-first-device.yaml
.venv/bin/esphome run esp32-esphome-first-device.yaml --device PORT
.venv/bin/esphome logs esp32-esphome-first-device.yaml --device PORT