esphome-config-helper（esphome 配置助手）

ESPHome Configuration Helper

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

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.

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)

Configuration Templates

Available Templates

Located in templates/ directory:

1. 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

1. sensor-node.yaml - Temperature/humidity sensor node

- DHT22 sensor on GPIO4 - WiFi with fallback AP - Home Assistant integration - Use for environmental monitoring

1. 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

1. 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

Using Templates

To use a template:

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

Template Workflow:

# 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 Pin Reference

Quick GPIO Lookup

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

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)

Basic Sensor Patterns

I²C Sensor (BME280 example):

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):

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

Binary Sensor (PIR motion):

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:

Troubleshooting Workflow

When encountering errors:

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

Validation Workflow

Using the Validation Script

The validation utility provides quick configuration checks:

Script: scripts/validate-config.sh

Usage:

# 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)

Validation Steps:

1. Syntax validation: esphome config my-device.yaml

- Checks YAML syntax - Validates component configuration - Reports missing requirements - Shows final configuration

1. Compilation test: esphome compile my-device.yaml

- Downloads required libraries - Compiles firmware - Reports errors and warnings - Confirms configuration works

1. Fix errors: If validation fails:

- Review error messages - Check GPIO conflicts - Verify component platforms - Consult references/troubleshooting.md - Re-validate after fixes

Pre-Flash Checklist

Before flashing device:

• Configuration validates without errors
• WiFi credentials correct (use secrets.yaml)
• Device name unique on network
• GPIO pins verified safe
• OTA password set (for future updates)
• API encryption key configured (2026.1.0+)

Configuration Best Practices

YAML Structure

Organize configuration in logical sections:

# 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 Management

Use secrets.yaml for sensitive data:

secrets.yaml:

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

Reference in config:

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:

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)

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

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

Utility Scripts

Validation and testing tools in scripts/:

• validate-config.sh - ESPHome configuration validation wrapper

Quick Start Workflow

For new ESPHome device:

1. Select template based on device type (sensor, switch, display, or basic)
2. Copy template to project directory
3. Customize configuration:

- Update device name - Set WiFi credentials in secrets.yaml - Adjust GPIO pins using references/gpio-pinouts.md - Add/remove components as needed

1. Validate configuration using scripts/validate-config.sh
2. Fix any errors using references/troubleshooting.md
3. Flash device with validated configuration
4. Monitor logs and troubleshoot if needed

For adding to existing config:

1. Consult references for component configuration
2. Check GPIO availability in references/gpio-pinouts.md
3. Add component to configuration
4. Validate before flashing
5. 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.