esphome-config-helper

What this skill does

# 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

2. **`sensor-node.yaml`** - Temperature/humidity sensor node
   - DHT22 sensor on GPIO4
   - WiFi with fallback AP
   - Home Assistant integration
   - Use for environmental monitoring

3. **`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

4. **`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:**
```yaml
# 1. Read template
cat ${CLAUDE_PLUGIN_ROOT}/skills/esphome-config-helper/templates/sensor-node.yaml

# 2. Copy to project
cp ${CLAUDE_PLUGIN_ROOT}/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):
```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
```

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

### 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:**
```bash
# Validate configuration
${CLAUDE_PLUGIN_ROOT}/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

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

### 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:
```yaml
# 1. Core platform
esphome:
  name: device-name
  friendly_name: Device Name

esp32:
  board: esp32dev
  framework:
    type