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:

# 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

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:

# 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

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.

Common Sensor Configurations for ESPHome

Top 20 sensor configurations with wiring diagrams, platform selection guidance, and complete working examples.

Temperature & Humidity Sensors

1. DHT22 (Temperature & Humidity)

Platform: dht Connection: Single GPIO pin with pull-up resistor Accuracy: ±0.5°C, ±2% RH Cost: Low Reliability: Moderate (prone to reading failures)

Wiring:

DHT22    ESP32/ESP8266
VCC  --> 3.3V
DATA --> GPIO4 (with 4.7kΩ pull-up to 3.3V)
GND  --> GND

Configuration:

sensor:
  - platform: dht
    pin: GPIO4
    model: DHT22  # or DHT11, DHT21, AM2302
    temperature:
      name: "Temperature"
      filters:
        - sliding_window_moving_average:
            window_size: 5
            send_every: 5
    humidity:
      name: "Humidity"
      filters:
        - sliding_window_moving_average:
            window_size: 5
            send_every: 5
    update_interval: 60s

Notes:

• Use 4.7kΩ pull-up resistor on DATA line
• Update interval should be >2s (avoid too frequent readings)
• Use filters to smooth noisy readings
• Consider BME280 for more reliable operation

---

2. BME280 (Temperature, Humidity, Pressure)

Platform: bme280 Connection: I²C or SPI Accuracy: ±1°C, ±3% RH, ±1 hPa Cost: Moderate Reliability: High (recommended over DHT22)

Wiring (I²C):

BME280   ESP32       ESP8266
VCC  --> 3.3V        3.3V
GND  --> GND         GND
SDA  --> GPIO21      GPIO4 (D2)
SCL  --> GPIO22      GPIO5 (D1)

Configuration:

i2c:
  sda: GPIO21  # ESP32, use GPIO4 for ESP8266
  scl: GPIO22  # ESP32, use GPIO5 for ESP8266
  scan: true

sensor:
  - platform: bme280
    temperature:
      name: "Temperature"
      oversampling: 16x
    humidity:
      name: "Humidity"
      oversampling: 16x
    pressure:
      name: "Pressure"
      oversampling: 16x
    address: 0x76  # or 0x77
    update_interval: 60s

Notes:

• I²C address is usually 0x76 or 0x77 (check with scan: true)
• Update interval >30s to prevent self-heating
• More reliable than DHT22, worth the extra cost
• Use oversampling to improve accuracy

---

3. DS18B20 (Waterproof Temperature)

Platform: dallas Connection: 1-Wire protocol, single GPIO Accuracy: ±0.5°C Cost: Low Reliability: High Special: Waterproof versions available

Wiring:

DS18B20  ESP32/ESP8266
VCC  --> 3.3V
DATA --> GPIO4 (with 4.7kΩ pull-up to 3.3V)
GND  --> GND

Configuration:

dallas:
  - pin: GPIO4

sensor:
  - platform: dallas
    address: 0x1c0000031edd2a28  # Use actual address from logs
    name: "Temperature"
    resolution: 12  # 9, 10, 11, or 12 bits
    update_interval: 60s

Notes:

• Requires 4.7kΩ pull-up resistor on DATA line
• Address auto-discovered on first boot (check logs)
• Multiple DS18B20 sensors can share same pin (1-Wire bus)
• Waterproof versions ideal for outdoor/pool/aquarium

---

4. SHT3x (High Accuracy Temperature & Humidity)

Platform: sht3xd Connection: I²C Accuracy: ±0.2°C, ±2% RH Cost: Moderate Reliability: Very High

Wiring (I²C):

SHT3x    ESP32       ESP8266
VCC  --> 3.3V        3.3V
GND  --> GND         GND
SDA  --> GPIO21      GPIO4 (D2)
SCL  --> GPIO22      GPIO5 (D1)

Configuration:

i2c:
  sda: GPIO21
  scl: GPIO22
  scan: true

sensor:
  - platform: sht3xd
    temperature:
      name: "Temperature"
    humidity:
      name: "Humidity"
    address: 0x44  # or 0x45
    update_interval: 60s

Notes:

• Superior accuracy compared to DHT22 and BME280
• I²C address is 0x44 or 0x45
• Very stable readings over time
• Higher cost but worth it for precision applications

---

Motion & Presence Sensors

5. HC-SR501 PIR (Motion Sensor)

Platform: gpio (binary_sensor) Connection: Single GPIO pin Range: Up to 7 meters Cost: Very Low Reliability: High

Wiring:

HC-SR501  ESP32/ESP8266
VCC   --> 5V (or 3.3V depending on module)
OUT   --> GPIO14
GND   --> GND

Configuration:

binary_sensor:
  - platform: gpio
    pin: GPIO14
    name: "Motion Sensor"
    device_class: motion
    filters:
      - delayed_off: 100ms  # Debounce

Notes:

• Some modules support 5V, others 3.3V (check datasheet)
• Adjustable sensitivity and time delay (potentiometers on module)
• Output HIGH when motion detected
• Use delayed_off filter to prevent flickering

---

6. RCWL-0516 (Microwave Motion Sensor)

Platform: gpio (binary_sensor) Connection: Single GPIO pin Range: Up to 7 meters through walls Cost: Low Reliability: High

Wiring:

RCWL-0516  ESP32/ESP8266
VIN   --> 5V
OUT   --> GPIO14
GND   --> GND

Configuration:

binary_sensor:
  - platform: gpio
    pin: GPIO14
    name: "Microwave Motion Sensor"
    device_class: motion
    filters:
      - delayed_off: 500ms

Notes:

• Detects motion through walls, glass, plastic
• More sensitive than PIR (can detect small movements)
• Requires 5V power
• May have false triggers (WiFi, microwave ovens)

---

Light Sensors

7. BH1750 (Ambient Light Sensor)

Platform: bh1750 Connection: I²C Range: 1-65535 lux Cost: Low Reliability: High

Wiring (I²C):

BH1750   ESP32       ESP8266
VCC  --> 3.3V        3.3V
GND  --> GND         GND
SDA  --> GPIO21      GPIO4 (D2)
SCL  --> GPIO22      GPIO5 (D1)
ADDR --> GND         GND (for 0x23)

Configuration:

i2c:
  sda: GPIO21
  scl: GPIO22

sensor:
  - platform: bh1750
    name: "Illuminance"
    address: 0x23  # 0x23 (ADDR=GND) or 0x5C (ADDR=VCC)
    update_interval: 60s

Notes:

• Accurate lux measurements (better than LDR)
• I²C address: 0x23 (ADDR=GND) or 0x5C (ADDR=VCC)
• Low power consumption
• Ideal for automatic lighting control

---

8. TSL2561 (Light Sensor with IR)

Platform: tsl2561 Connection: I²C Range: 0.1-40,000 lux Cost: Moderate Reliability: High

Wiring (I²C):

TSL2561  ESP32       ESP8266
VCC  --> 3.3V        3.3V
GND  --> GND         GND
SDA  --> GPIO21      GPIO4 (D2)
SCL  --> GPIO22      GPIO5 (D1)

Configuration:

i2c:
  sda: GPIO21
  scl: GPIO22

sensor:
  - platform: tsl2561
    name: "Illuminance"
    address: 0x39  # 0x29, 0x39, or 0x49
    update_interval: 60s

Notes:

• Dual spectrum (visible + IR)
• Better for outdoor use (compensates for IR)
• I²C address: 0x29, 0x39, or 0x49
• More expensive than BH1750

---

Distance Sensors

9. HC-SR04 (Ultrasonic Distance Sensor)

Platform: ultrasonic Connection: 2 GPIO pins (trigger + echo) Range: 2-400 cm Cost: Very Low Reliability: Moderate

Wiring:

HC-SR04  ESP32/ESP8266
VCC   --> 5V
TRIG  --> GPIO12
ECHO  --> GPIO14 (with voltage divider if using 5V module)
GND   --> GND

Configuration:

sensor:
  - platform: ultrasonic
    trigger_pin: GPIO12
    echo_pin: GPIO14
    name: "Distance"
    update_interval: 60s
    timeout: 3m  # Maximum measurement timeout
    filters:
      - filter_out: nan
      - median:
          window_size: 7
          send_every: 4

Notes:

• 5V modules require voltage divider on ECHO (5V → 3.3V)
• Affected by temperature and humidity
• Use filters to smooth readings
• Not suitable for very short distances (<2cm)

---

10. VL53L0X (ToF Laser Distance Sensor)

Platform: vl53l0x Connection: I²C Range: 3-200 cm Cost: Moderate Reliability: High

Wiring (I²C):

VL53L0X  ESP32       ESP8266
VCC  --> 3.3V        3.3V
GND  --> GND         GND
SDA  --> GPIO21      GPIO4 (D2)
SCL  --> GPIO22      GPIO5 (D1)

Configuration:

i2c:
  sda: GPIO21
  scl: GPIO22

sensor:
  - platform: vl53l0x
    name: "Distance"
    address: 0x29
    update_interval: 1s
    long_range: true  # Up to 2m (less accurate)

Notes:

• Time-of-Flight laser (very accurate)
• Not affected by ambient light or object color
• I²C address: 0x29
• long_range mode extends to 2m but reduces accuracy

---

Air Quality Sensors

11. BME680 (Air Quality, Temp, Humidity, Pressure)

Platform: bme680 Connection: I²C or SPI Accuracy: ±1°C, ±3% RH, ±1 hPa Cost: Moderate-High Reliability: High

Wiring (I²C):

BME680   ESP32       ESP8266
VCC  --> 3.3V        3.3V
GND  --> GND         GND
SDA  --> GPIO21      GPIO4 (D2)
SCL  --> GPIO22      GPIO5 (D1)

Configuration:

i2c:
  sda: GPIO21
  scl: GPIO22

sensor:
  - platform: bme680
    temperature:
      name: "Temperature"
    humidity:
      name: "Humidity"
    pressure:
      name: "Pressure"
    gas_resistance:
      name: "Gas Resistance"
    address: 0x76  # or 0x77
    update_interval: 60s

Notes:

• Gas resistance indicates air quality (VOC)
• Requires burn-in period (48 hours for stable readings)
• I²C address: 0x76 or 0x77
• Superior to BME280 for air quality monitoring

---

12. SGP30 (eCO2 and TVOC Sensor)

Platform: sgp30 Connection: I²C Measurements: eCO2 (400-60,000 ppm), TVOC (0-60,000 ppb) Cost: Moderate Reliability: High

Wiring (I²C):

SGP30    ESP32       ESP8266
VCC  --> 3.3V        3.3V
GND  --> GND         GND
SDA  --> GPIO21      GPIO4 (D2)
SCL  --> GPIO22      GPIO5 (D1)

Configuration:

i2c:
  sda: GPIO21
  scl: GPIO22

sensor:
  - platform: sgp30
    eco2:
      name: "eCO2"
      accuracy_decimals: 1
    tvoc:
      name: "TVOC"
      accuracy_decimals: 1
    address: 0x58
    update_interval: 1s
    compensation:
      temperature_source: temp_sensor_id  # Optional
      humidity_source: humidity_sensor_id  # Optional

Notes:

• Requires 12-hour burn-in for accurate readings
• Baseline calibration improves over time
• Compensation with temp/humidity improves accuracy
• Fixed I²C address: 0x58

---

Energy Monitoring

13. INA219 (Current/Voltage/Power Sensor)

Platform: ina219 Connection: I²C Range: 0-26V, ±3.2A (with 0.1Ω shunt) Cost: Low Reliability: High

Wiring (I²C):

INA219   ESP32       ESP8266
VCC  --> 3.3V        3.3V
GND  --> GND         GND
SDA  --> GPIO21      GPIO4 (D2)
SCL  --> GPIO22      GPIO5 (D1)

Configuration:

i2c:
  sda: GPIO21
  scl: GPIO22

sensor:
  - platform: ina219
    address: 0x40
    shunt_resistance: 0.1 ohm
    current:
      name: "Current"
    power:
      name: "Power"
    bus_voltage:
      name: "Bus Voltage"
    shunt_voltage:
      name: "Shunt Voltage"
    max_voltage: 26V
    max_current: 3.2A
    update_interval: 60s

Notes:

• Measures DC current, voltage, and power
• Shunt resistor value affects max current
• I²C address: 0x40-0x4F (configurable)
• Ideal for battery monitoring, solar panels

---

14. PZEM-004T (AC Power Monitor)

Platform: pzemac or pzemdc Connection: UART Range: 80-260V, 0-100A Cost: Moderate Reliability: High

Wiring (UART):

PZEM-004T  ESP32
5V     --> 5V
TX     --> GPIO16 (RX2)
RX     --> GPIO17 (TX2)
GND    --> GND

Configuration:

uart:
  id: uart_bus
  tx_pin: GPIO17
  rx_pin: GPIO16
  baud_rate: 9600

sensor:
  - platform: pzemac
    current:
      name: "Current"
    voltage:
      name: "Voltage"
    power:
      name: "Power"
    energy:
      name: "Energy"
    frequency:
      name: "Frequency"
    power_factor:
      name: "Power Factor"
    update_interval: 60s

Notes:

• AC power monitoring (mains voltage)
• Separate CT (current transformer) for current measurement
• PZEM-004T v3.0 uses UART (older versions use different protocol)
• Dangerous if not installed correctly (mains voltage)

---

Environmental Sensors

15. MH-Z19 (CO2 Sensor)

Platform: mhz19 Connection: UART Range: 0-5000 ppm CO2 Cost: Moderate Reliability: High

Wiring (UART):

MH-Z19   ESP32
VIN  --> 5V
TX   --> GPIO16 (RX2)
RX   --> GPIO17 (TX2)
GND  --> GND

Configuration:

uart:
  id: uart_bus
  tx_pin: GPIO17
  rx_pin: GPIO16
  baud_rate: 9600

sensor:
  - platform: mhz19
    co2:
      name: "CO2"
    temperature:
      name: "Temperature"
    update_interval: 60s
    automatic_baseline_calibration: false

Notes:

• Requires 24-hour warm-up for accurate readings
• Automatic baseline calibration should be disabled for accurate readings
• Manual calibration in fresh air (400 ppm) recommended
• Preheating time: 3 minutes

---

16. SDS011 (Particulate Matter Sensor)

Platform: sds011 Connection: UART Range: PM2.5 and PM10 (0-999.9 μg/m³) Cost: Moderate Reliability: High

Wiring (UART):

SDS011   ESP32
5V   --> 5V
TX   --> GPIO16 (RX2)
RX   --> GPIO17 (TX2)
GND  --> GND

Configuration:

uart:
  id: uart_bus
  tx_pin: GPIO17
  rx_pin: GPIO16
  baud_rate: 9600

sensor:
  - platform: sds011
    pm_2_5:
      name: "PM2.5"
    pm_10_0:
      name: "PM10"
    update_interval: 5min
    rx_only: false  # Set to true if you only connect RX

Notes:

• Measures fine dust particles (PM2.5 and PM10)
• Laser-based sensor (very accurate)
• Fan can be controlled (sleep mode to extend life)
• Use longer update_interval to extend fan life

---

Other Common Sensors

17. Pulse Counter (Water/Gas/Electricity Meter)

Platform: pulse_counter Connection: Single GPIO pin Cost: Free (uses existing meter) Reliability: High

Wiring:

Pulse Output  ESP32/ESP8266
Signal    --> GPIO14 (with pull-up if needed)
GND       --> GND

Configuration:

sensor:
  - platform: pulse_counter
    pin: GPIO14
    name: "Water Usage"
    unit_of_measurement: "L/min"
    filters:
      - multiply: 0.5  # Convert pulses to liters (depends on meter)
    total:
      name: "Total Water Usage"
      unit_of_measurement: "L"
      filters:
        - multiply: 0.5

Notes:

• Works with utility meters that have pulse output
• Calibration factor depends on meter (pulses per liter/kWh)
• Can monitor water, gas, electricity consumption
• Use internal_filter to debounce noisy signals

---

18. Rotary Encoder

Platform: rotary_encoder Connection: 2 GPIO pins (CLK + DT) Cost: Very Low Reliability: High

Wiring:

Encoder  ESP32/ESP8266
CLK  --> GPIO12
DT   --> GPIO14
SW   --> GPIO13 (optional button)
+    --> 3.3V
GND  --> GND

Configuration:

sensor:
  - platform: rotary_encoder
    name: "Rotary Encoder"
    pin_a: GPIO12
    pin_b: GPIO14
    resolution: 1  # 1, 2, or 4 (steps per detent)
    min_value: 0
    max_value: 100
    publish_initial_value: true

binary_sensor:
  - platform: gpio
    pin:
      number: GPIO13
      mode: INPUT_PULLUP
      inverted: true
    name: "Encoder Button"

Notes:

• Mechanical encoders may need debouncing
• resolution depends on encoder type (usually 1 or 2)
• Optional button (SW pin) for click detection
• Can be used for volume control, dimming, menu navigation

---

19. AHT10/AHT20 (Temperature & Humidity)

Platform: aht10 Connection: I²C Accuracy: ±0.3°C, ±2% RH Cost: Low Reliability: High

Wiring (I²C):

AHT10/20  ESP32       ESP8266
VCC   --> 3.3V        3.3V
GND   --> GND         GND
SDA   --> GPIO21      GPIO4 (D2)
SCL   --> GPIO22      GPIO5 (D1)

Configuration:

i2c:
  sda: GPIO21
  scl: GPIO22

sensor:
  - platform: aht10
    temperature:
      name: "Temperature"
    humidity:
      name: "Humidity"
    update_interval: 60s

Notes:

• Good alternative to DHT22 (more reliable)
• Fixed I²C address: 0x38
• Lower cost than BME280
• Newer AHT20 is drop-in replacement

---

20. Analog Input (Generic)

Platform: adc Connection: Single ADC pin Range: 0-3.3V (ESP32 with attenuation), 0-1V (ESP8266) Cost: Free Reliability: High

Wiring:

Sensor Output  ESP32           ESP8266
Signal     --> GPIO32 (ADC)    A0
GND        --> GND             GND

Configuration (ESP32):

sensor:
  - platform: adc
    pin: GPIO32  # Any ADC-capable pin
    name: "Analog Input"
    attenuation: 11db  # 0db (0-1V), 2.5db (0-1.5V), 6db (0-2V), 11db (0-3.3V)
    update_interval: 60s
    filters:
      - calibrate_linear:
          - 0.0 -> 0.0
          - 3.3 -> 100.0  # Map voltage to meaningful units

Configuration (ESP8266):

sensor:
  - platform: adc
    pin: A0  # Only ADC pin on ESP8266
    name: "Analog Input"
    update_interval: 60s
    filters:
      - multiply: 3.3  # Convert to voltage (0-1V range)

Notes:

• ESP32 has 18 ADC pins, ESP8266 has only 1 (A0)
• Use attenuation on ESP32 to adjust input range
• Use calibrate_linear filter to map voltage to sensor units
• Requires external voltage divider if sensor output >3.3V

---

Sensor Selection Guide

Temperature/Humidity

• Budget: DHT22 (GPIO, ±0.5°C)
• Recommended: BME280 (I²C, ±1°C, includes pressure)
• High Accuracy: SHT3x (I²C, ±0.2°C)
• Waterproof: DS18B20 (1-Wire, ±0.5°C)

Motion Detection

• Indoor: HC-SR501 PIR (GPIO, 7m range)
• Through Walls: RCWL-0516 Microwave (GPIO, 7m through obstacles)

Light Level

• Budget/Accurate: BH1750 (I²C, 1-65535 lux)
• Outdoor/IR Compensation: TSL2561 (I²C, dual spectrum)

Distance Measurement

• Budget: HC-SR04 Ultrasonic (GPIO, 2-400cm)
• Accurate: VL53L0X ToF Laser (I²C, 3-200cm)

Air Quality

• Budget: MQ-series Gas Sensors (analog, specific gases)
• Recommended: BME680 (I²C, VOC/gas resistance)
• CO2 Specific: MH-Z19 (UART, 0-5000 ppm)
• Particulate Matter: SDS011 (UART, PM2.5/PM10)

Energy Monitoring

• DC Power: INA219 (I²C, 0-26V, 0-3.2A)
• AC Power: PZEM-004T (UART, 80-260V, 0-100A)

Connection Type Comparison

• GPIO: Simplest, one pin, limited accuracy (PIR, DHT22)
• I²C: Multiple sensors on 2 pins, accurate (BME280, BH1750)
• 1-Wire: Multiple sensors on 1 pin (DS18B20)
• SPI: Fast, requires 4 pins (displays, high-speed sensors)
• UART: Serial communication, requires 2 pins (PZEM, MH-Z19)
• Analog (ADC): Voltage measurement, requires calibration (potentiometers, LDR)

---

Summary

Most Versatile: BME280 (temp/humidity/pressure, I²C, reliable)

Best Motion: HC-SR501 PIR (low cost, reliable, easy)

Best Light: BH1750 (accurate lux, I²C, low cost)

Best Air Quality: BME680 (comprehensive, I²C, includes VOC)

Best Distance: VL53L0X (accurate, I²C, not affected by ambient light)

Best for Beginners: DHT22, HC-SR501, BH1750 (simple GPIO/I²C, low cost)

Most Reliable: I²C sensors (BME280, BH1750, SHT3x, VL53L0X)

GPIO Pinout Reference for ESPHome

Complete GPIO reference for ESP32 and ESP8266 platforms with safe pin recommendations, strapping pin warnings, and pin capabilities.

ESP32 GPIO Pinout

Safe GPIO Pins (Recommended for General Use)

These pins are safe for most applications and won't interfere with boot:

Digital I/O (Input/Output):

• GPIO4, GPIO5, GPIO12, GPIO13, GPIO14, GPIO16, GPIO17, GPIO18, GPIO19, GPIO21, GPIO22, GPIO23, GPIO25, GPIO26, GPIO27, GPIO32, GPIO33

ADC Capable (Analog Input):

• GPIO32, GPIO33, GPIO34, GPIO35, GPIO36, GPIO39 (VP), GPIO38 (VN)

Touch Capable:

• GPIO0, GPIO2, GPIO4, GPIO12, GPIO13, GPIO14, GPIO15, GPIO27, GPIO32, GPIO33

PWM Capable:

• All GPIO pins can be used for PWM (16 channels available)

Strapping Pins (Use with Caution)

These pins affect boot behavior and should be used carefully:

GPIO0 (BOOT button)

• Pulled HIGH at boot
• LOW at boot = Flash mode
• Can be used after boot, but avoid pulling LOW on power-up
• Often connected to onboard button

GPIO2 (Built-in LED on many boards)

• Must be LOW for ESP32 to enter download mode
• Must be floating or HIGH at boot for normal operation
• Safe to use after boot
• Often connected to onboard LED

GPIO5

• Strapping pin
• Must be HIGH during boot for SDIO Slave mode
• Generally safe to use after boot

GPIO12 (MTDI)

• Flash voltage selector
• LOW = 3.3V Flash, HIGH = 1.8V Flash
• Use with caution if you have 3.3V flash (most boards)
• Can be used after boot

GPIO15 (MTDO)

• Outputs PWM signal at boot
• Strapping pin for debug output
• Must be HIGH at boot for normal operation
• Use with caution

Input-Only Pins

These pins can ONLY be used as inputs (no OUTPUT mode):

• GPIO34, GPIO35, GPIO36, GPIO39 (VP), GPIO38 (VN)
• Do not have internal pull-up or pull-down resistors
• Useful for analog sensors (ADC)

Pins to Avoid

Do NOT use for critical applications:

GPIO6-GPIO11 (SPI Flash)

• Connected to integrated SPI flash
• Using these will cause crashes
• Includes: GPIO6, GPIO7, GPIO8, GPIO9, GPIO10, GPIO11

GPIO1 (TX0)

• Serial TX pin
• Avoid if you need serial logging

GPIO3 (RX0)

• Serial RX pin
• Avoid if you need serial logging

Default I²C Pins

• SDA: GPIO21
• SCL: GPIO22

Can be changed in configuration:

i2c:
  sda: GPIO21
  scl: GPIO22

Default SPI Pins

• MOSI: GPIO23
• MISO: GPIO19
• CLK: GPIO18
• CS: User-defined (often GPIO5)

Default UART Pins

UART0 (USB Serial):

• TX: GPIO1
• RX: GPIO3

UART1 (Available):

• TX: GPIO10 (not recommended - SPI Flash)
• RX: GPIO9 (not recommended - SPI Flash)

UART2 (Recommended for external serial):

• TX: GPIO17
• RX: GPIO16

ESP32 DevKit Pin Mapping

Common pin labels on ESP32 DevKit boards:

---

ESP8266 GPIO Pinout

Safe GPIO Pins (Recommended)

Digital I/O (Input/Output):

• GPIO4 (D2), GPIO5 (D1), GPIO12 (D6), GPIO13 (D7), GPIO14 (D5)

PWM Capable:

• GPIO4 (D2), GPIO5 (D1), GPIO12 (D6), GPIO13 (D7), GPIO14 (D5)

ADC Capable:

• A0 (single ADC pin, 0-1V range)

Strapping Pins (Use with Caution)

GPIO0 (D3, FLASH button)

• Must be HIGH at boot for normal operation
• LOW at boot = Flash mode
• Can be used after boot (often as button input with pull-up)

GPIO2 (D4, Built-in LED)

• Must be HIGH at boot
• Often connected to onboard LED (inverted)
• Safe to use after boot

GPIO15 (D8)

• Must be LOW at boot
• Pulled LOW with resistor on most boards
• Can be used after boot

Pins to Avoid

GPIO6-GPIO11 (SPI Flash)

• Connected to integrated SPI flash
• Using these will cause crashes

GPIO1 (TX)

• Serial TX pin
• Avoid if you need serial logging

GPIO3 (RX)

• Serial RX pin
• Avoid if you need serial logging

GPIO16 (D0, Wake pin)

• Used for deep sleep wake
• No interrupt support
• No pull-up/pull-down resistors
• Use only for wake from deep sleep or simple output

Default I²C Pins

• SDA: GPIO4 (D2)
• SCL: GPIO5 (D1)

Can be changed in configuration:

i2c:
  sda: GPIO4
  scl: GPIO5

Default SPI Pins

Hardware SPI:

• MOSI: GPIO13 (D7)
• MISO: GPIO12 (D6)
• CLK: GPIO14 (D5)
• CS: User-defined (often GPIO15/D8)

ESP8266 NodeMCU Pin Mapping

Common pin labels on NodeMCU boards:

---

GPIO Configuration Examples

Basic Digital Output (LED)

switch:
  - platform: gpio
    pin: GPIO23  # ESP32 safe pin
    name: "LED"

Digital Input (Button with Pull-Up)

binary_sensor:
  - platform: gpio
    pin:
      number: GPIO4  # ESP32 safe pin
      mode: INPUT_PULLUP
      inverted: true
    name: "Button"

Digital Input (Button with Pull-Down)

binary_sensor:
  - platform: gpio
    pin:
      number: GPIO4
      mode: INPUT_PULLDOWN
    name: "Button"

PWM Output (Dimmable LED)

output:
  - platform: ledc  # ESP32
    pin: GPIO25
    id: pwm_output

light:
  - platform: monochromatic
    output: pwm_output
    name: "Dimmable Light"

Analog Input (ESP32)

sensor:
  - platform: adc
    pin: GPIO32  # ESP32 ADC pin
    name: "Analog Sensor"
    attenuation: 11db  # Allows 0-3.3V range
    update_interval: 60s

Analog Input (ESP8266)

sensor:
  - platform: adc
    pin: A0  # ESP8266 only has one ADC
    name: "Analog Sensor"
    update_interval: 60s

---

GPIO Conflict Prevention

Common GPIO Conflicts

I²C + Individual GPIO:

• Don't use GPIO21/GPIO22 (ESP32) or GPIO4/GPIO5 (ESP8266) for other purposes if using I²C

SPI + Individual GPIO:

• Don't use default SPI pins (GPIO18, GPIO19, GPIO23 on ESP32) for other purposes if using SPI

Serial Logging + GPIO1/GPIO3:

• If you need GPIO1 or GPIO3, disable serial logging

Strapping Pins at Boot:

• Avoid external pull-ups/pull-downs on GPIO0, GPIO2, GPIO12, GPIO15 (ESP32) during boot

How to Avoid Conflicts

1. List all GPIO usage in your configuration 2. Check for duplicates - same pin used twice 3. Check I²C/SPI defaults - ensure not conflicting 4. Avoid strapping pins for critical sensors 5. Test boot behavior - ensure device boots reliably

GPIO Conflict Example (Bad)

# BAD: GPIO21 used twice
i2c:
  sda: GPIO21  # Uses GPIO21
  scl: GPIO22

switch:
  - platform: gpio
    pin: GPIO21  # CONFLICT! Already used by I²C SDA
    name: "Relay"

GPIO Conflict Fixed (Good)

# GOOD: Use different pin for relay
i2c:
  sda: GPIO21
  scl: GPIO22

switch:
  - platform: gpio
    pin: GPIO23  # Safe pin, no conflict
    name: "Relay"

---

Quick Pin Selection Guide

Need Digital Output?

ESP32: GPIO4, GPIO5, GPIO13, GPIO14, GPIO16-19, GPIO21-23, GPIO25-27, GPIO32-33 ESP8266: GPIO4 (D2), GPIO5 (D1), GPIO12 (D6), GPIO13 (D7), GPIO14 (D5)

Need Digital Input?

ESP32: Same as digital output + GPIO34-36, GPIO39 ESP8266: Same as digital output + GPIO0 (D3) with pull-up

Need PWM?

ESP32: All output-capable pins ESP8266: GPIO4 (D2), GPIO5 (D1), GPIO12 (D6), GPIO13 (D7), GPIO14 (D5)

Need Analog Input?

ESP32: GPIO32-36, GPIO39 ESP8266: A0 only

Need I²C?

ESP32: Default GPIO21 (SDA), GPIO22 (SCL) ESP8266: Default GPIO4/D2 (SDA), GPIO5/D1 (SCL)

Need SPI?

ESP32: Default GPIO23 (MOSI), GPIO19 (MISO), GPIO18 (CLK) ESP8266: Default GPIO13/D7 (MOSI), GPIO12/D6 (MISO), GPIO14/D5 (CLK)

---

Platform-Specific Notes

ESP32 Advantages

• More GPIO pins (34+ vs 11)
• Multiple ADC channels (18 vs 1)
• Touch sensor support
• DAC support (GPIO25, GPIO26)
• More UART/I²C/SPI buses

ESP8266 Limitations

• Fewer GPIO pins (11 usable)
• Only 1 ADC pin (A0)
• No DAC
• No touch sensors
• Limited number of interrupts

When to Use ESP32 vs ESP8266

Use ESP32 when:

• Need more GPIO pins
• Need multiple ADC inputs
• Using touch sensors
• Complex projects with many peripherals

Use ESP8266 when:

• Budget constrained
• Simple projects (few sensors/switches)
• Lower power consumption needed
• Smaller physical size required

---

Summary

ESP32 Safe Pins: GPIO4, GPIO5, GPIO13, GPIO14, GPIO16-19, GPIO21-23, GPIO25-27, GPIO32-33

ESP8266 Safe Pins: GPIO4 (D2), GPIO5 (D1), GPIO12 (D6), GPIO13 (D7), GPIO14 (D5)

Avoid: GPIO0, GPIO2, GPIO6-11, GPIO15 for critical applications

Default I²C (ESP32): GPIO21 (SDA), GPIO22 (SCL)

Default I²C (ESP8266): GPIO4/D2 (SDA), GPIO5/D1 (SCL)

Always check: Boot behavior, strapping pins, and conflicts before finalizing design

ESPHome Troubleshooting Guide

Comprehensive error message lookup table with solutions for compilation errors, runtime issues, configuration problems, and hardware failures.

Quick Error Lookup

---

Compilation Errors

Error: "Unknown platform"

Full Error:

Platform 'xyz' doesn't exist
Unknown platform: xyz

Cause: Misspelled platform name or unsupported platform

Solutions: 1. Check platform spelling in ESPHome documentation 2. Ensure platform exists for component 3. Update ESPHome to latest version (platform may be new)

Example Fix:

# WRONG
sensor:
  - platform: dht11  # Wrong platform name

# CORRECT
sensor:
  - platform: dht
    model: DHT11  # Specify model instead

---

Error: "GPIO already in use"

Full Error:

Pin GPIO21 is already in use by component 'i2c'
GPIO21 already used

Cause: Same GPIO pin assigned to multiple components

Solutions: 1. List all GPIO usage in config 2. Find duplicate assignments 3. Reassign one component to different pin 4. Check I²C/SPI default pins not conflicting

Example Fix:

# WRONG - GPIO21 used twice
i2c:
  sda: GPIO21
  scl: GPIO22

switch:
  - platform: gpio
    pin: GPIO21  # CONFLICT!

# CORRECT - Use different pin
i2c:
  sda: GPIO21
  scl: GPIO22

switch:
  - platform: gpio
    pin: GPIO23  # Different pin

---

Error: "Could not compile"

Full Error:

Failed to compile firmware
Compilation failed

Causes:

• YAML syntax error (indentation, missing colon)
• Invalid configuration values
• Missing required fields
• Incompatible component versions

Solutions: 1. Run esphome config device.yaml to validate YAML 2. Check indentation (use 2 spaces, not tabs) 3. Verify all required fields present 4. Check ESPHome version compatibility 5. Review compilation error logs for specific issue

Common YAML Syntax Fixes:

# WRONG - Tab indentation
sensor:
→   - platform: dht  # Tab character

# CORRECT - 2 space indentation
sensor:
  - platform: dht  # 2 spaces

# WRONG - Missing colon
sensor
  - platform: dht

# CORRECT - Colon after key
sensor:
  - platform: dht

---

Error: "Invalid pin for platform"

Full Error:

GPIO34 cannot be used as output on ESP32
Pin GPIO1 is not available on ESP8266

Cause: Using input-only pin for output, or unavailable pin

Solutions: 1. Check GPIO pinout reference for platform 2. Use output-capable pins for switches/LEDs 3. Use input-only pins (GPIO34-39 ESP32) only for sensors 4. Avoid flash pins (GPIO6-11)

Example Fix:

# WRONG - GPIO34 is input-only on ESP32
switch:
  - platform: gpio
    pin: GPIO34  # Cannot be used as output

# CORRECT - Use output-capable pin
switch:
  - platform: gpio
    pin: GPIO23  # Output-capable

Refer to: references/gpio-pinouts.md for complete pin capabilities

---

Error: "YAML syntax error"

Full Error:

expected <block end>, but found '-'
mapping values are not allowed here

Cause: Invalid YAML syntax (indentation, structure)

Solutions: 1. Validate YAML with online validator 2. Check indentation (2 spaces per level) 3. Ensure no tabs (use spaces only) 4. Verify list items start with - 5. Check quotes around special characters

Common YAML Fixes:

# WRONG - Incorrect indentation
sensor:
- platform: dht
  pin: GPIO4

# CORRECT - Consistent 2-space indentation
sensor:
  - platform: dht
    pin: GPIO4

# WRONG - Missing dash for list item
sensor:
  platform: dht
  pin: GPIO4

# CORRECT - Dash for list item
sensor:
  - platform: dht
    pin: GPIO4

---

Error: "Flash size too small"

Full Error:

Firmware is too large (1234567 bytes), maximum is 1048576 bytes
Sketch too big

Cause: Firmware exceeds available flash memory

Solutions: 1. Reduce features (remove unused components) 2. Disable logger or reduce log level 3. Disable web_server if not needed 4. Use framework: arduino instead of esp-idf (smaller) 5. For ESP8266: Use larger flash size in board config

Example Fixes:

# Reduce logging
logger:
  level: WARN  # Instead of DEBUG or VERBOSE

# Disable web server
# web_server:  # Comment out if not needed

# Use minimal logger
logger:
  baud_rate: 0  # Disable serial logging

---

Runtime Errors

Error: "WiFi connection failed"

Full Error:

WiFi: Can't connect to network 'SSID'
Connection failed
WiFi: Not connected

Causes:

• Incorrect SSID or password
• Weak WiFi signal
• 5GHz network (ESP8266/ESP32 only support 2.4GHz)
• MAC filtering on router
• DHCP exhausted

Solutions: 1. Verify SSID and password in secrets.yaml 2. Check WiFi signal strength (move closer to AP) 3. Ensure using 2.4GHz network (not 5GHz) 4. Check router MAC filter allow list 5. Use static IP if DHCP issues 6. Verify WiFi credentials are in quotes if contain special characters

Example Fixes:

# Use static IP to avoid DHCP issues
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  manual_ip:
    static_ip: 192.168.1.100
    gateway: 192.168.1.1
    subnet: 255.255.255.0

# Quote special characters
# secrets.yaml
wifi_password: "P@ssw0rd!"  # Quote if contains special chars

---

Error: "API connection timeout"

Full Error:

Connection timeout
Can't connect to ESPHome API
API client connection timeout

Causes:

• Firewall blocking connection
• Incorrect API encryption key
• Device not reachable on network
• mDNS not working
• Port 6053 blocked

Solutions: 1. Verify device IP address (check router DHCP table) 2. Use IP address instead of .local hostname 3. Check API encryption key matches Home Assistant 4. Disable firewall temporarily to test 5. Verify port 6053 not blocked 6. Restart device and Home Assistant

Example Fixes:

# Ensure API encryption key matches Home Assistant
api:
  encryption:
    key: !secret api_encryption_key  # Must match HA integration

# Use static IP for reliability
wifi:
  manual_ip:
    static_ip: 192.168.1.100

Check connectivity:

# Ping device
ping 192.168.1.100

# Check logs
esphome logs device.yaml

# Connect via IP instead of hostname
# In Home Assistant: 192.168.1.100 instead of device.local

---

Error: "Sensor not found"

Full Error:

I2C: Device not found at address 0x76
Sensor 'xyz' not responding
No sensor detected

Causes:

• Incorrect I²C address
• Wiring issue (loose connection, wrong pins)
• Sensor not powered
• Pull-up resistors missing (for I²C)
• Incompatible voltage (3.3V vs 5V)

Solutions: 1. Use scan: true in i2c config to detect devices 2. Check wiring connections 3. Verify correct I²C address (common: 0x76, 0x77 for BME280) 4. Add pull-up resistors (4.7kΩ) on SDA/SCL if needed 5. Check sensor power supply voltage 6. Try different I²C pins

Example Debugging:

# Enable I2C scan to detect devices
i2c:
  sda: GPIO21
  scl: GPIO22
  scan: true  # Shows detected I2C addresses in logs

sensor:
  - platform: bme280
    address: 0x76  # Try 0x76 or 0x77
    # ...

Check logs:

I2C: Found device at address 0x76  # Sensor detected
I2C: Found device at address 0x77  # Sensor detected
I2C: No devices found  # Check wiring

---

Error: "OTA upload failed"

Full Error:

OTA update failed
Upload failed
Connection lost during upload

Causes:

• Device unreachable on network
• Incorrect OTA password
• Insufficient flash space
• Device rebooted during upload
• Weak WiFi signal
• Firewall blocking connection

Solutions: 1. Verify device reachable (ping IP address) 2. Check OTA password matches 3. Restart device before OTA update 4. Move device closer to WiFi AP 5. Use wired upload (USB) if OTA keeps failing 6. Clear flash and re-upload via USB

Example Fixes:

# Ensure OTA configured correctly
ota:
  - platform: esphome
    password: !secret ota_password  # Must match

# Increase safe_mode boot timeout
ota:
  - platform: esphome
    safe_mode: true
    reboot_timeout: 10min  # More time for unstable connections

Recovery steps:

# 1. Try OTA update with verbose logging
esphome upload device.yaml --device 192.168.1.100

# 2. If OTA fails, use USB upload
esphome upload device.yaml --device /dev/ttyUSB0

# 3. Last resort: factory reset
# Hold BOOT button, press RESET, release BOOT
# Then upload via USB

---

Configuration Errors

Error: "Missing required field"

Full Error:

Required option 'name' not specified
Missing required field: 'pin'

Cause: Required configuration field not provided

Solutions: 1. Check component documentation for required fields 2. Add missing field to configuration 3. Verify field name spelling

Example Fixes:

# WRONG - Missing name
sensor:
  - platform: dht
    pin: GPIO4

# CORRECT - Name required
sensor:
  - platform: dht
    pin: GPIO4
    temperature:
      name: "Temperature"  # Required
    humidity:
      name: "Humidity"  # Required

---

Error: "Invalid configuration value"

Full Error:

Invalid value for 'update_interval': '10'
Value must be a time period

Cause: Configuration value has wrong type or format

Solutions: 1. Check expected value type (string, number, boolean) 2. Use correct units for time periods (s, min, h) 3. Quote strings if needed 4. Use correct format for enums

Example Fixes:

# WRONG - Missing time unit
sensor:
  - platform: dht
    update_interval: 60  # Missing 's'

# CORRECT - Include time unit
sensor:
  - platform: dht
    update_interval: 60s  # Correct

# WRONG - Incorrect enum value
sensor:
  - platform: adc
    attenuation: 11  # Should be 11db

# CORRECT - Use correct enum
sensor:
  - platform: adc
    attenuation: 11db  # Correct

---

Error: "Conflicting ID"

Full Error:

ID 'sensor_id' is already in use
Duplicate ID: 'my_sensor'

Cause: Same ID used for multiple components

Solutions: 1. Ensure each component has unique ID 2. Search config for duplicate ID names 3. Use descriptive, unique ID names

Example Fixes:

# WRONG - Duplicate ID
sensor:
  - platform: dht
    id: temp_sensor  # Duplicate!
    temperature:
      name: "Room Temp"

  - platform: bme280
    id: temp_sensor  # Duplicate!
    temperature:
      name: "Outside Temp"

# CORRECT - Unique IDs
sensor:
  - platform: dht
    id: room_temp_sensor  # Unique
    temperature:
      name: "Room Temp"

  - platform: bme280
    id: outside_temp_sensor  # Unique
    temperature:
      name: "Outside Temp"

---

Hardware Issues

Issue: "Sensor readings are incorrect"

Symptoms:

• Temperature reads 0°C or -127°C
• Humidity reads 0%
• Distance sensor reads infinity
• Readings jump erratically

Causes:

• Sensor not connected properly
• Pull-up resistors missing (I²C, 1-Wire)
• Voltage mismatch (3.3V vs 5V)
• Sensor failure
• Interference from other devices
• Update interval too fast

Solutions: 1. Check all wiring connections 2. Add pull-up resistors (4.7kΩ) for I²C/1-Wire 3. Verify sensor voltage requirements 4. Increase update_interval (>2s for DHT, >30s for BME280) 5. Add filters to smooth readings 6. Move sensor away from interference sources 7. Test sensor with different ESP device

Example Fixes:

# Add filters to smooth noisy readings
sensor:
  - platform: dht
    pin: GPIO4
    temperature:
      name: "Temperature"
      filters:
        - sliding_window_moving_average:
            window_size: 5
            send_every: 5
        - filter_out: nan  # Filter out invalid readings
    humidity:
      name: "Humidity"
      filters:
        - sliding_window_moving_average:
            window_size: 5
            send_every: 5
        - filter_out: nan
    update_interval: 60s  # Slower = more reliable

# For 1-Wire sensors (DS18B20)
dallas:
  - pin: GPIO4
    update_interval: 60s

sensor:
  - platform: dallas
    filters:
      - filter_out: 85.0  # Filter out sensor error value
      - filter_out: nan

---

Issue: "Device keeps rebooting"

Symptoms:

• Device reboots every few seconds
• Boot loop
• Cannot connect to device

Causes:

• Power supply insufficient
• Brownout detector triggered
• Watchdog timeout (infinite loop in lambda)
• Memory overflow
• Bad flash
• Incorrect GPIO state at boot

Solutions: 1. Use adequate power supply (5V 1A minimum, 2A recommended) 2. Disable brownout detector (ESP32) 3. Check lambdas for infinite loops 4. Reduce memory usage (remove unused components) 5. Reflash firmware via USB 6. Check strapping pins not pulled wrong at boot

Example Fixes:

# Disable brownout detector (ESP32 only)
esp32:
  board: esp32dev
  framework:
    type: arduino
    version: recommended
  variant: esp32
  # Add this to disable brownout:
  # platformio_options:
  #   board_build.f_cpu: 240000000L
  #   board_build.f_flash: 40000000L
  #   board_build.flash_mode: dio
  #   board_build.partitions: default.csv

# Increase watchdog timeout if needed
ota:
  - platform: esphome
    safe_mode: true
    reboot_timeout: 10min  # More time before reboot

Power supply recommendations:

• ESP32: 5V 1A minimum (2A recommended with peripherals)
• ESP8266: 5V 500mA minimum (1A recommended)
• Use dedicated power supply (not USB from computer)
• Add decoupling capacitors (10μF, 100nF) near ESP module

---

Issue: "Relay not switching"

Symptoms:

• Relay clicks but load doesn't switch
• No relay click at all
• Relay switches opposite direction

Causes:

• Insufficient drive current
• Inverted logic
• Wrong GPIO pin configuration
• Relay powered from wrong voltage
• Relay coil voltage mismatch

Solutions: 1. Use transistor/MOSFET driver for relay coil 2. Check inverted configuration 3. Verify GPIO is output-capable 4. Power relay from external 5V (not ESP) 5. Check relay coil voltage rating 6. Use relay module (has built-in driver circuit)

Example Fixes:

# Check inverted setting
switch:
  - platform: gpio
    pin:
      number: GPIO23
      inverted: false  # Try true if relay switches opposite
    name: "Relay"

# For active-low relay modules
switch:
  - platform: gpio
    pin:
      number: GPIO23
      inverted: true  # Active-low relay module
    name: "Relay"
    restore_mode: RESTORE_DEFAULT_OFF  # Ensure off at boot

Wiring check:

ESP32      Relay Module
GPIO23 --> IN
GND    --> GND
VCC not connected (relay module powered externally from 5V)

---

Network Issues

Issue: "Device keeps disconnecting"

Symptoms:

• WiFi disconnects every few minutes
• API unavailable intermittently
• Logs show reconnection messages

Causes:

• Weak WiFi signal
• Power supply insufficient
• Router DHCP lease timeout
• WiFi power saving mode
• Network congestion
• ESP32 Bluetooth interference (if enabled)

Solutions: 1. Move device closer to WiFi AP 2. Use better power supply 3. Configure static IP 4. Disable WiFi power saving 5. Disable Bluetooth on ESP32 6. Use 2.4GHz-only WiFi network

Example Fixes:

# Disable WiFi power saving
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  power_save_mode: NONE  # Disable power saving (ESP32)
  # or
  output_power: 20db  # Increase TX power (ESP32)

# Use static IP for stability
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  manual_ip:
    static_ip: 192.168.1.100
    gateway: 192.168.1.1
    subnet: 255.255.255.0

# Increase reboot timeout
api:
  reboot_timeout: 15min  # More time before reboot on disconnect

---

Debugging Techniques

Enable Verbose Logging

logger:
  level: VERBOSE  # DEBUG, VERBOSE, or VERY_VERBOSE
  logs:
    component: VERBOSE  # Log specific component

Use Serial Logging

# Monitor serial output
esphome logs device.yaml

# Or use platformio
pio device monitor

Enable I²C Scan

i2c:
  sda: GPIO21
  scl: GPIO22
  scan: true  # Shows detected I2C devices

Check WiFi Signal

sensor:
  - platform: wifi_signal
    name: "WiFi Signal"
    update_interval: 60s

Monitor Uptime

sensor:
  - platform: uptime
    name: "Uptime"

Use Safe Mode

ota:
  - platform: esphome
    safe_mode: true  # Boots without sensors if errors occur

---

Recovery Procedures

Factory Reset

1. Hold BOOT button 2. Press RESET button briefly 3. Release BOOT button after 2 seconds 4. Device enters flash mode 5. Upload firmware via USB

Clear Flash

# Erase entire flash
esptool.py --port /dev/ttyUSB0 erase_flash

# Then upload firmware
esphome upload device.yaml --device /dev/ttyUSB0

Safe Mode Recovery

If device is stuck in boot loop with OTA enabled:

1. Device will boot into safe mode after failed boots 2. Connect via OTA (device will have .safe suffix) 3. Upload working firmware

---

Common Error Patterns

Pattern 1: Boot Loop After OTA

Symptoms: Device reboots continuously after OTA update

Solution: 1. Wait for safe mode (automatic after ~10 failed boots) 2. Upload previous working firmware 3. Fix issue in new firmware 4. Verify GPIO states at boot

Pattern 2: I²C Device Not Found

Symptoms: scan: true shows no devices

Solution: 1. Check SDA/SCL connections 2. Add 4.7kΩ pull-up resistors 3. Try different I²C pins 4. Verify sensor power supply 5. Test sensor with Arduino first

Pattern 3: GPIO Conflict

Symptoms: Device boots but feature doesn't work

Solution: 1. List all GPIO usage 2. Check I²C/SPI default pins 3. Avoid strapping pins (GPIO0, 2, 12, 15) 4. Use gpio-pinouts.md reference

Pattern 4: Memory Issues

Symptoms: Random crashes, heap warnings in logs

Solution: 1. Reduce features 2. Disable web_server 3. Lower logger level 4. Remove unused components 5. Use framework: arduino (smaller than esp-idf)

---

Summary of Quick Fixes

1. YAML errors → Check indentation (2 spaces, no tabs) 2. GPIO conflicts → List all pins, check for duplicates 3. WiFi issues → Verify credentials, use static IP 4. I²C not found → Enable scan, check wiring, add pull-ups 5. Sensor errors → Increase update_interval, add filters 6. OTA fails → Restart device, use USB upload 7. Boot loops → Check power supply, disable brownout 8. API timeout → Verify encryption key, use IP not .local

Always check:

• Logs with esphome logs device.yaml
• GPIO pinout reference
• ESPHome documentation for component

When stuck: Start with minimal config, add components one by one to isolate issue