esphome-config-helper

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ESPHome Configuration Helper

ESPHome配置助手

Rapid ESPHome configuration generation and troubleshooting skill with ready-to-use templates, GPIO reference guides, and validation utilities.

本技能可提供快速的ESPHome配置生成与故障排除服务，包含即用型模板、GPIO参考指南和验证工具。

Purpose

用途

This skill accelerates ESPHome device configuration by providing:

Quick-start templates for common device types
GPIO pinout references to prevent conflicts
Common sensor configurations with wiring diagrams
Error message lookup and solutions
Configuration validation workflow

Use this skill for general ESPHome configuration tasks. For ESP32-S3-BOX-3 specific implementations, use the esphome-box3-builder skill instead.

本技能通过以下功能加速ESPHome设备配置：

常见设备类型的快速启动模板
GPIO引脚参考，避免引脚冲突
带接线图的常见传感器配置
错误信息查询与解决方案
配置验证流程

本技能适用于常规ESPHome配置任务。针对ESP32-S3-BOX-3的特定实现，请使用esphome-box3-builder技能。

When to Use This Skill

何时使用本技能

Use this skill when:

Starting a new ESPHome device configuration
Adding sensors, switches, or displays to existing configs
Troubleshooting compilation or runtime errors
Determining safe GPIO pins for components
Validating configuration before flashing

Delegate to specialized ESPHome agents for:

Deep technical questions (esphome-core, esphome-components, etc.)
Complex automation logic (esphome-automations agent)
Network troubleshooting (esphome-networking agent)
ESP32-S3-BOX-3 projects (esphome-box3 agent)

在以下场景使用本技能：

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

将以下场景委托给专业ESPHome代理：

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

Configuration Templates

配置模板

Available Templates

可用模板

Located in

templates/

directory:

basic-device.yaml
- Minimal ESP32 starter
- ESP32 platform with WiFi and API
- OTA updates enabled
- Logger and web server
- Use as foundation for custom projects
sensor-node.yaml
- Temperature/humidity sensor node
- DHT22 sensor on GPIO4
- WiFi with fallback AP
- Home Assistant integration
- Use for environmental monitoring
relay-switch.yaml
- 4-channel relay controller
- GPIO control for 4 relays (GPIO23, GPIO22, GPIO21, GPIO19)
- Physical button inputs with interlocks
- Switch entities for Home Assistant
- Use for home automation switching
display-node.yaml
- Display with sensors
- SSD1306 OLED display (128x64, I²C)
- DHT22 temperature/humidity
- Display lambda showing sensor readings
- Use for visual sensor displays

位于

templates/

目录下：

basic-device.yaml
- 极简ESP32启动模板
- 带WiFi和API的ESP32平台
- 启用OTA更新
- 日志器和Web服务器
- 用作自定义项目的基础
sensor-node.yaml
- 温湿度传感器节点
- GPIO4上的DHT22传感器
- 带 fallback AP的WiFi
- Home Assistant集成
- 用于环境监测
relay-switch.yaml
- 4通道继电器控制器
- 4个继电器的GPIO控制（GPIO23、GPIO22、GPIO21、GPIO19）
- 带互锁的物理按钮输入
- 适用于Home Assistant的开关实体
- 用于家庭自动化开关控制
display-node.yaml
- 带传感器的显示屏
- SSD1306 OLED显示屏（128x64，I²C）
- DHT22温湿度传感器
- 显示传感器读数的lambda表达式
- 用于传感器数据可视化显示

Using Templates

使用模板

To use a template:

Read the appropriate template file
Customize device name, WiFi credentials, GPIO pins
Add or remove components as needed
Validate configuration (see Validation Workflow below)

Template Workflow:

yaml

undefined

使用模板的步骤：

读取对应的模板文件
自定义设备名称、WiFi凭据、GPIO引脚
根据需要添加或移除组件
验证配置（见下文的验证流程）

模板使用流程：

yaml

undefined

1. Read template

1. 读取模板

cat .claude/skills/esphome-config-helper/templates/sensor-node.yaml

2. Copy to project

2. 复制到项目目录

cp .claude/skills/esphome-config-helper/templates/sensor-node.yaml my-device.yaml

3. Edit with device-specific values

3. 编辑设备专属参数

- Update device name

- 更新设备名称

- Set WiFi credentials (use secrets.yaml)

设置WiFi凭据（使用secrets.yaml）

- Adjust GPIO pins if needed

- 必要时调整GPIO引脚

- Customize sensor names

- 自定义传感器名称

4. Validate (see Validation Workflow)

4. 验证配置（见验证流程）

undefined

undefined

GPIO Pin Reference

GPIO引脚参考

Quick GPIO Lookup

快速GPIO查询

For detailed GPIO pinouts and safe pin selection, consult:

references/gpio-pinouts.md
- Complete ESP32 and ESP8266 GPIO reference
- Safe pins for each platform
- Strapping pins to avoid
- I²C/SPI/UART default pins
- Input-only vs output-capable pins
- Boot failure pins (GPIO0, GPIO2, GPIO15)

Quick Safe Pins:

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)

Avoid (strapping/boot pins):

ESP32: GPIO0, GPIO2, GPIO5, GPIO12, GPIO15 (use with caution)
ESP8266: GPIO0, GPIO2, GPIO15

如需详细的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

Common Sensor Configurations

常见传感器配置

Sensor Selection Guide

传感器选择指南

For detailed sensor configurations with wiring diagrams, consult:

references/common-sensors.md
- Top 20 sensor configurations
- Temperature/humidity sensors (DHT22, BME280, SHT3x)
- Motion sensors (PIR, mmWave)
- Light sensors (BH1750, TSL2561)
- Distance sensors (HC-SR04, VL53L0X)
- Gas sensors (MQ-series, SGP30)
- Complete wiring diagrams and platform selection

Quick Sensor Recommendations:

Temperature/Humidity: BME280 (I²C, more reliable than DHT22)
Motion: HC-SR501 PIR (GPIO binary sensor)
Light: BH1750 (I²C, accurate lux measurements)
Distance: HC-SR04 (ultrasonic, 2-400cm range)
Air Quality: BME680 (I²C, temp/humidity/pressure/gas)

如需带接线图的详细传感器配置，请参考：

references/common-sensors.md
- 20种常见传感器配置
- 温湿度传感器（DHT22、BME280、SHT3x）
- 运动传感器（PIR、毫米波）
- 光线传感器（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，温湿度/气压/气体检测）

Basic Sensor Patterns

基础传感器配置示例

I²C Sensor (BME280 example):

yaml

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 Sensor (DHT22 example):

yaml

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

Binary Sensor (PIR motion):

yaml

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

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

yaml

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示例）：

yaml

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

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

yaml

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

Troubleshooting Guide

故障排除指南

Error Lookup

错误查询

For complete error message lookup table and solutions, consult:

references/troubleshooting.md
- Comprehensive error message reference
- Compilation errors (unknown platform, GPIO conflicts, dependency issues)
- Runtime errors (WiFi failures, sensor timeouts, OTA problems)
- Configuration errors (YAML syntax, invalid pins, missing components)
- Hardware issues (sensor not detected, relay not switching)

Common Error Quick Reference:

Error Message	Quick Fix
"Unknown platform"	Check component name spelling, ensure platform supported
"GPIO already in use"	Check GPIO pin assignments, avoid duplicates
"Could not compile"	Check YAML syntax, verify indentation (2 spaces)
"WiFi connection failed"	Verify SSID/password, check signal strength, use static IP
"Sensor not found"	Check I²C address (use scan: true), verify wiring
"OTA upload failed"	Check device reachable, verify OTA password, restart device

如需完整的错误信息查询表和解决方案，请参考：

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密码，重启设备

Troubleshooting Workflow

故障排除流程

When encountering errors:

Check YAML syntax: Verify indentation (2 spaces, no tabs)
Validate GPIO pins: Ensure no conflicts, use safe pins
Check component platform: Verify platform name and configuration
Review logs: Use
```
esphome logs device.yaml
```
to see runtime errors
Consult references: Check
```
references/troubleshooting.md
```
for specific error
Validate config: Run validation workflow (see below)

遇到错误时：

检查YAML语法：验证缩进（2个空格，不要用制表符）
验证GPIO引脚：确保无冲突，使用安全引脚
检查组件平台：验证平台名称和配置
查看日志：使用
```
esphome logs device.yaml
```
查看运行时错误
参考文档：查看
```
references/troubleshooting.md
```
获取特定错误的解决方案
验证配置：运行下文的验证流程

Validation Workflow

验证流程

Using the Validation Script

使用验证脚本

The validation utility provides quick configuration checks:

Script:

scripts/validate-config.sh

Usage:

bash

undefined

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

脚本:

scripts/validate-config.sh

使用方法:

bash

undefined

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)

1. esphome config my-device.yaml (语法检查)

2. esphome compile my-device.yaml (compilation test)

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


**Validation Steps:**

1. **Syntax validation**: `esphome config my-device.yaml`
   - Checks YAML syntax
   - Validates component configuration
   - Reports missing requirements
   - Shows final configuration

2. **Compilation test**: `esphome compile my-device.yaml`
   - Downloads required libraries
   - Compiles firmware
   - Reports errors and warnings
   - Confirms configuration works

3. **Fix errors**: If validation fails:
   - Review error messages
   - Check GPIO conflicts
   - Verify component platforms
   - Consult `references/troubleshooting.md`
   - Re-validate after fixes


**验证步骤:**

1. **语法验证**: `esphome config my-device.yaml`
   - 检查YAML语法
   - 验证组件配置
   - 报告缺失的依赖
   - 显示最终配置

2. **编译测试**: `esphome compile my-device.yaml`
   - 下载所需库
   - 编译固件
   - 报告错误和警告
   - 确认配置可用

3. **修复错误**: 如果验证失败：
   - 查看错误信息
   - 检查GPIO冲突
   - 验证组件平台
   - 参考`references/troubleshooting.md`
   - 修复后重新验证

Pre-Flash Checklist

烧录前检查清单

Configuration Best Practices

配置最佳实践

YAML Structure

YAML结构

Organize configuration in logical sections:

yaml

undefined

按逻辑组织配置：

yaml

undefined

1. Core platform

1. 核心平台

esphome: name: device-name friendly_name: Device Name

esp32: board: esp32dev framework: type: arduino

esphome: name: device-name friendly_name: Device Name

esp32: board: esp32dev framework: type: arduino

2. Network

2. 网络配置

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

api: encryption: key: !secret api_encryption_key

ota:

platform: esphome password: !secret ota_password

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

3. 日志与Web服务

logger: web_server:

4. Components (sensors, switches, etc.)

4. 组件（传感器、开关等）

sensor:

...

binary_sensor:

...

undefined

sensor:

...

binary_sensor:

...

undefined

Secrets Management

凭据管理

Use

secrets.yaml

for sensitive data:

secrets.yaml:

yaml

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

Reference in config:

yaml

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

使用

secrets.yaml

存储敏感数据：

secrets.yaml:

yaml

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

在配置中引用:

yaml

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

Naming Conventions

命名规范

Follow consistent naming:

Device names: lowercase-with-hyphens (e.g.,
```
bedroom-sensor
```
)
Entity names: Title Case with Spaces (e.g.,
```
"Bedroom Temperature"
```
)
IDs: lowercase_with_underscores (e.g.,
```
temp_sensor
```
)

Example:

yaml

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

遵循一致的命名规则：

设备名称: 小写连字符格式（如：
```
bedroom-sensor
```
）
实体名称: 标题大小写加空格（如：
```
"Bedroom Temperature"
```
）
ID: 小写下划线格式（如：
```
temp_sensor
```
）

示例:

yaml

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

Integration with Other Skills and Agents

与其他技能和代理的集成

When to Use Other Resources

何时使用其他资源

ESP32-S3-BOX-3 projects: Use esphome-box3-builder skill
- Audio pipeline (I²S, ES7210, ES8311)
- Display lambda rendering (ILI9xxx)
- Touch interaction (GT911)
- Voice assistant integration
Deep technical questions: Delegate to ESPHome agents
- Core concepts → esphome-core agent
- Component selection → esphome-components agent
- Automation logic → esphome-automations agent
- Network issues → esphome-networking agent
- HA integration → esphome-homeassistant agent
Complex projects: Combine resources
- Start with template (this skill)
- Customize with agent guidance
- Validate with scripts (this skill)
- Deploy and troubleshoot (this skill + agents)

ESP32-S3-BOX-3项目: 使用esphome-box3-builder技能
- 音频流水线（I²S、ES7210、ES8311）
- 显示屏lambda渲染（ILI9xxx）
- 触摸交互（GT911）
- 语音助手集成
深度技术问题: 委托给ESPHome专业代理
- 核心概念 → esphome-core代理
- 组件选择 → esphome-components代理
- 自动化逻辑 → esphome-automations代理
- 网络问题 → esphome-networking代理
- Home Assistant集成 → esphome-homeassistant代理
复杂项目: 组合使用多种资源
- 从模板开始（本技能）
- 在代理指导下自定义
- 使用脚本验证（本技能）
- 部署与故障排除（本技能+代理）

Additional Resources

额外资源

Reference Files

参考文档

For detailed information, consult:

references/gpio-pinouts.md
- Complete ESP32/ESP8266 GPIO reference with safe pins, strapping pins, and pin capabilities
references/common-sensors.md
- Top 20 sensor configurations with wiring diagrams, platform selection, and usage examples
references/troubleshooting.md
- Comprehensive error message lookup table with solutions for compilation, runtime, and hardware issues

如需详细信息，请参考：

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

Template Files

模板文件

Working configuration examples in

templates/

basic-device.yaml
- Minimal ESP32 foundation
sensor-node.yaml
- DHT22 temperature/humidity node
relay-switch.yaml
- 4-channel relay controller
display-node.yaml
- OLED display with sensors

templates/

目录下的可用配置示例：

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

Utility Scripts

实用脚本

Validation and testing tools in

scripts/

validate-config.sh
- ESPHome configuration validation wrapper

scripts/

目录下的验证和测试工具：

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

Quick Start Workflow

快速入门流程

For new ESPHome device:

Select template based on device type (sensor, switch, display, or basic)
Copy template to project directory
Customize configuration:
- Update device name
- Set WiFi credentials in secrets.yaml
- Adjust GPIO pins using
```
references/gpio-pinouts.md
```
- Add/remove components as needed
Validate configuration using
```
scripts/validate-config.sh
```
Fix any errors using
```
references/troubleshooting.md
```
Flash device with validated configuration
Monitor logs and troubleshoot if needed

For adding to existing config:

Consult references for component configuration
Check GPIO availability in
```
references/gpio-pinouts.md
```
Add component to configuration
Validate before flashing
Update and monitor

This skill provides rapid configuration generation for common ESPHome use cases. For specialized hardware (ESP32-S3-BOX-3) or deep technical questions, use the appropriate specialist skills and agents.

针对新的ESPHome设备：

选择模板 根据设备类型（传感器、开关、显示屏或基础设备）选择对应模板
复制模板 到项目目录
自定义配置:
- 更新设备名称
- 在secrets.yaml中设置WiFi凭据
- 使用
```
references/gpio-pinouts.md
```
  调整GPIO引脚
- 根据需要添加/移除组件
验证配置 使用
```
scripts/validate-config.sh
```
修复错误 参考
```
references/troubleshooting.md
```
解决问题
烧录设备 使用验证通过的配置
监控日志 并在需要时进行故障排除

针对现有配置的扩展：

参考文档 获取组件配置信息
检查GPIO可用性 查看
```
references/gpio-pinouts.md
```
添加组件 到配置中
烧录前验证 配置
更新设备并监控

本技能为常见ESPHome使用场景提供快速配置生成服务。针对特殊硬件（如ESP32-S3-BOX-3）或深度技术问题，请使用对应的专业技能和代理。