esphome-config-helper

# 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/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):
```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/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: 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:**
```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
```

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

## 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
4. **Validate configuration** using `scripts/validate-config.sh`
5. **Fix any errors** using `references/troubleshooting.md`
6. **Flash device** with validated configuration
7. **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.