esphome-config-helper

ESPHome 配置助手

快速生成和排查 ESPHome 配置的技能，提供可直接使用的模板、GPIO 参考指南和验证工具。

用途

此技能通过以下功能加快 ESPHome 设备配置：

• 常见设备类型的快速入门模板
• GPIO 引脚布局参考，避免冲突
• 带接线图的常见传感器配置
• 错误消息查询与解决方案
• 配置验证工作流

此技能适用于一般 ESPHome 配置任务。对于 ESP32-S3-BOX-3 专用实现，请改用 esphome-box3-builder 技能。

何时使用此技能

在以下情况下使用此技能：

• 开始配置新的 ESPHome 设备
• 向现有配置添加传感器、开关或显示屏
• 排查编译或运行时错误
• 确定组件可安全使用的 GPIO 引脚
• 刷写前验证配置

以下情况请委派给专用 ESPHome Agent：

• 深入的技术问题（esphome-core、esphome-components 等）
• 复杂的自动化逻辑（esphome-automations agent）
• 网络故障排查（esphome-networking agent）
• ESP32-S3-BOX-3 项目（esphome-box3 agent）

配置模板

可用模板

位于 templates/ 目录：

1. basic-device.yaml - 最简 ESP32 入门模板

   • 支持 WiFi 和 API 的 ESP32 平台
   • 已启用 OTA 更新
   • Logger 和 Web 服务器
   • 用作自定义项目的基础

2. sensor-node.yaml - 温湿度传感器节点

   • GPIO4 上的 DHT22 传感器
   • 带备用 AP 的 WiFi
   • Home Assistant 集成
   • 用于环境监测

3. relay-switch.yaml - 4 通道继电器控制器

   • 通过 GPIO 控制 4 个继电器（GPIO23、GPIO22、GPIO21、GPIO19）
   • 带互锁的实体按钮输入
   • Home Assistant 开关实体
   • 用于家庭自动化开关控制

4. display-node.yaml - 带传感器的显示屏

   • SSD1306 OLED 显示屏（128x64，I²C）
   • DHT22 温湿度传感器
   • 显示传感器读数的 lambda
   • 用于传感器读数可视化

使用模板

使用模板：

1. 阅读相应的模板文件
2. 自定义设备名称、WiFi 凭据和 GPIO 引脚
3. 按需添加或移除组件
4. 验证配置（见下文的验证工作流）

模板工作流：

# 1. Read template
cat .claude/skills/esphome-config-helper/templates/sensor-node.yaml

# 2. Copy to project
cp .claude/skills/esphome-config-helper/templates/sensor-node.yaml my-device.yaml

# 3. Edit with device-specific values
# - Update device name
# - Set WiFi credentials (use secrets.yaml)
# - Adjust GPIO pins if needed
# - Customize sensor names

# 4. Validate (see Validation Workflow)

GPIO 引脚参考

GPIO 快速查询

有关详细的 GPIO 引脚布局和安全引脚选择，请参阅：

• references/gpio-pinouts.md - ESP32 和 ESP8266 GPIO 完整参考
  • 各平台的安全引脚
  • 应避免使用的绑带引脚
  • I²C/SPI/UART 默认引脚
  • 仅输入与支持输出的引脚
  • 可能导致启动失败的引脚（GPIO0、GPIO2、GPIO15）

常用安全引脚：

• ESP32：GPIO4、GPIO5、GPIO12、GPIO13、GPIO14、GPIO16、GPIO17、GPIO18、GPIO19、GPIO21、GPIO22、GPIO23、GPIO25-27、GPIO32、GPIO33
• ESP8266：GPIO4（D2）、GPIO5（D1）、GPIO12（D6）、GPIO13（D7）、GPIO14（D5）

避免使用（绑带/启动引脚）：

• ESP32：GPIO0、GPIO2、GPIO5、GPIO12、GPIO15（谨慎使用）
• ESP8266：GPIO0、GPIO2、GPIO15

常见传感器配置

传感器选择指南

有关带接线图的详细传感器配置，请参阅：

• references/common-sensors.md - 20 种常用传感器配置
  • 温湿度传感器（DHT22、BME280、SHT3x）
  • 运动传感器（PIR、mmWave）
  • 光照传感器（BH1750、TSL2561）
  • 距离传感器（HC-SR04、VL53L0X）
  • 气体传感器（MQ 系列、SGP30）
  • 完整接线图和平台选择指南

传感器快速推荐：

• 温度/湿度：BME280（I²C，比 DHT22 更可靠）
• 运动：HC-SR501 PIR（GPIO 二进制传感器）
• 光照：BH1750（I²C，可准确测量照度）
• 距离：HC-SR04（超声波，测距范围为 2-400cm）
• 空气质量：BME680（I²C，可测温湿度、气压和气体）

基本传感器模式

I²C 传感器（BME280 示例）：

i2c:
  sda: GPIO21
  scl: GPIO22
  scan: true

sensor:
  - platform: bme280
    temperature:
      name: "Temperature"
    humidity:
      name: "Humidity"
    pressure:
      name: "Pressure"
    address: 0x76
    update_interval: 60s

GPIO 传感器（DHT22 示例）：

sensor:
  - platform: dht
    pin: GPIO4
    model: DHT22
    temperature:
      name: "Temperature"
    humidity:
      name: "Humidity"
    update_interval: 60s

二进制传感器（PIR 运动传感器）：

binary_sensor:
  - platform: gpio
    pin: GPIO14
    name: "Motion Sensor"
    device_class: motion

故障排查指南

错误查询

如需查询完整的错误消息表及解决方案，请参阅：

• references/troubleshooting.md - 全面的错误消息参考
  • 编译错误（未知平台、GPIO 冲突、依赖问题）
  • 运行时错误（WiFi 故障、传感器超时、OTA 问题）
  • 配置错误（YAML 语法、无效引脚、缺少组件）
  • 硬件问题（未检测到传感器、继电器未切换）

常见错误速查：

错误消息	快速修复
"Unknown platform"	检查组件名称拼写，确保平台受支持
"GPIO already in use"	检查 GPIO 引脚分配，避免重复
"Could not compile"	检查 YAML 语法，确认缩进（2 个空格）
"WiFi connection failed"	确认 SSID/密码，检查信号强度，使用静态 IP
"Sensor not found"	检查 I²C 地址（使用 scan: true），确认接线
"OTA upload failed"	检查设备是否可访问，确认 OTA 密码，重启设备

故障排查工作流

遇到错误时：

1. 检查 YAML 语法：确认缩进（2 个空格，不使用制表符）
2. 验证 GPIO 引脚：确保没有冲突，使用安全引脚
3. 检查组件平台：确认平台名称和配置
4. 查看日志：使用 esphome logs device.yaml 查看运行时错误
5. 查阅参考资料：在 references/troubleshooting.md 中查找具体错误
6. 验证配置：运行验证工作流（见下文）

验证工作流

使用验证脚本

验证工具可快速检查配置：

脚本：scripts/validate-config.sh

用法：

# Validate configuration
./.claude/skills/esphome-config-helper/scripts/validate-config.sh my-device.yaml

# The script runs:
# 1. esphome config my-device.yaml  (syntax check)
# 2. esphome compile my-device.yaml (compilation test)

验证步骤：

1. 语法验证：esphome config my-device.yaml

   • 检查 YAML 语法
   • 验证组件配置
   • 报告缺少的要求
   • 显示最终配置

2. 编译测试：esphome compile my-device.yaml

   • 下载所需库
   • 编译固件
   • 报告错误和警告
   • 确认配置可用

3. 修复错误：如果验证失败：

   • 查看错误消息
   • 检查 GPIO 冲突
   • 确认组件平台
   • 查阅 references/troubleshooting.md
   • 修复后重新验证

刷写前检查清单

刷写设备前：

• 配置验证通过，无错误
• WiFi 凭据正确（使用 secrets.yaml）
• 设备名称在网络中唯一
• 已确认 GPIO 引脚安全
• 已设置 OTA 密码（供后续更新使用）
• 已配置 API 加密密钥（2026.1.0+）

配置最佳实践

YAML 结构

将配置按逻辑分区组织：

# 1. Core platform
esphome:
  name: device-name
  friendly_name: Device Name

esp32:
  board: esp32dev
  framework:
    type: arduino

# 2. Network
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
  encryption:
    key: !secret api_encryption_key

ota:
  - platform: esphome
    password: !secret ota_password

# 3. Logging
logger:
web_server:

# 4. Components (sensors, switches, etc.)
sensor:
  # ...

binary_sensor:
  # ...

密钥管理

使用 secrets.yaml 存储敏感数据：

secrets.yaml：

wifi_ssid: "MyNetwork"
wifi_password: "MyPassword123"
api_encryption_key: "base64-generated-key"
ota_password: "SecureOTAPassword"

在配置中引用：

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

命名约定

遵循一致的命名规范：

• 设备名称：小写字母并用连字符分隔（例如，bedroom-sensor）
• 实体名称：单词首字母大写，单词间用空格分隔（例如，"Bedroom Temperature"）
• ID：小写字母并用下划线分隔（例如，temp_sensor）

示例：

sensor:
  - platform: dht
    pin: GPIO4
    temperature:
      name: "Living Room Temperature"
      id: living_room_temp
    humidity:
      name: "Living Room Humidity"
      id: living_room_humidity

与其他技能和 Agent 集成

何时使用其他资源

• ESP32-S3-BOX-3 项目：使用 esphome-box3-builder 技能

  • 音频管线（I²S、ES7210、ES8311）
  • 显示屏 lambda 渲染（ILI9xxx）
  • 触控交互（GT911）
  • 语音助手集成

• 深入的技术问题：委派给 ESPHome Agent

  • 核心概念 → esphome-core Agent
  • 组件选择 → esphome-components Agent
  • 自动化逻辑 → esphome-automations Agent
  • 网络问题 → esphome-networking Agent
  • HA 集成 → esphome-homeassistant Agent

• 复杂项目：组合使用资源

  • 从模板开始（此技能）
  • 根据 Agent 指导进行自定义
  • 使用脚本验证（此技能）
  • 部署并排查问题（此技能 + Agent）

更多资源

参考文件

如需详细信息，请参阅：

• references/gpio-pinouts.md - 完整的 ESP32/ESP8266 GPIO 参考，包含安全引脚、启动绑带引脚和引脚功能
• references/common-sensors.md - 20 种常见传感器配置，包含接线图、平台选择和使用示例
• references/troubleshooting.md - 全面的错误消息查询表，涵盖编译、运行时和硬件问题及其解决方案

模板文件

templates/ 中的可用配置示例：

• basic-device.yaml - 最简 ESP32 基础配置
• sensor-node.yaml - DHT22 温湿度节点
• relay-switch.yaml - 4 通道继电器控制器
• display-node.yaml - 配有传感器的 OLED 显示屏

实用脚本

scripts/ 中的验证和测试工具：

• validate-config.sh - ESPHome 配置验证封装脚本

快速入门工作流

创建新的 ESPHome 设备：

1. 选择模板，根据设备类型（传感器、开关、显示屏或基础设备）进行选择
2. 复制模板到项目目录
3. 自定义配置：
   • 更新设备名称
   • 在 secrets.yaml 中设置 WiFi 凭据
   • 使用 references/gpio-pinouts.md 调整 GPIO 引脚
   • 根据需要添加或移除组件
4. 使用 scripts/validate-config.sh 验证配置
5. 使用 references/troubleshooting.md 修复任何错误
6. 使用已验证的配置刷写设备
7. 监控日志，并在需要时排查问题

向现有配置中添加内容：

1. 查阅参考资料，了解组件配置
2. 在 references/gpio-pinouts.md 中检查 GPIO 是否可用
3. 向配置中添加组件
4. 刷写前进行验证
5. 更新并监控

此技能可快速生成适用于常见 ESPHome 使用场景的配置。对于专用硬件（ESP32-S3-BOX-3）或深入的技术问题，请使用相应的专业技能和 Agent。