ESPHome Devices

Expert guidance for ESPHome DIY smart home devices.

When to Use This Skill

• Creating custom ESP8266/ESP32 devices
• Configuring sensors (temperature, motion, etc.)
• Building smart switches and relays
• Creating LED controllers
• Setting up displays and notifications
• Integrating with Home Assistant

Installation & Setup

# docker-compose.yml
version: '3.8'
services:
  esphome:
    image: esphome/esphome
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    network_mode: host
    restart: unless-stopped

# CLI installation
pip install esphome

# Create new device
esphome wizard my_device.yaml

# Compile and upload
esphome run my_device.yaml

# Just compile
esphome compile my_device.yaml

# OTA upload
esphome upload my_device.yaml --device 192.168.1.100

# View logs
esphome logs my_device.yaml

Basic Configuration

# my_device.yaml
esphome:
  name: my-device
  friendly_name: My Device
  platform: ESP8266  # or ESP32
  board: nodemcuv2   # or esp32dev, d1_mini, etc.

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

  # Optional: Static IP
  manual_ip:
    static_ip: 192.168.1.100
    gateway: 192.168.1.1
    subnet: 255.255.255.0

  # Fallback AP
  ap:
    ssid: "My-Device Fallback"
    password: "fallback123"

captive_portal:

# Enable logging
logger:
  level: DEBUG

# Enable Home Assistant API
api:
  encryption:
    key: !secret api_encryption_key

# Enable OTA updates
ota:
  password: !secret ota_password

# Web server (optional)
web_server:
  port: 80

Secrets File

# secrets.yaml
wifi_ssid: "MyWiFi"
wifi_password: "password123"
api_encryption_key: "generated-key-here"
ota_password: "ota-password"

Common Sensors

Temperature & Humidity (DHT22)

sensor:
  - platform: dht
    pin: D2
    model: DHT22
    temperature:
      name: "Temperature"
      filters:
        - offset: -0.5  # Calibration
    humidity:
      name: "Humidity"
    update_interval: 60s

Temperature (Dallas DS18B20)

dallas:
  - pin: D4

sensor:
  - platform: dallas
    address: 0x1234567890ABCDEF
    name: "Temperature"
    resolution: 12

BME280 (I2C)

i2c:
  sda: D2
  scl: D1
  scan: true

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

Motion Sensor (PIR)

binary_sensor:
  - platform: gpio
    pin: D5
    name: "Motion"
    device_class: motion
    filters:
      - delayed_off: 30s

Door/Window Sensor

binary_sensor:
  - platform: gpio
    pin:
      number: D1
      mode: INPUT_PULLUP
      inverted: true
    name: "Door"
    device_class: door

Light Sensor (BH1750)

sensor:
  - platform: bh1750
    name: "Illuminance"
    address: 0x23
    update_interval: 60s

Analog Sensor

sensor:
  - platform: adc
    pin: A0
    name: "Soil Moisture"
    update_interval: 60s
    unit_of_measurement: "%"
    filters:
      - calibrate_linear:
          - 0.85 -> 0.0
          - 0.35 -> 100.0

Switches & Relays

Basic Relay

switch:
  - platform: gpio
    pin: D1
    name: "Relay"
    id: relay1
    restore_mode: RESTORE_DEFAULT_OFF

Button-Controlled Relay

binary_sensor:
  - platform: gpio
    pin:
      number: D2
      mode: INPUT_PULLUP
      inverted: true
    name: "Button"
    on_press:
      - switch.toggle: relay1

switch:
  - platform: gpio
    pin: D1
    name: "Relay"
    id: relay1

Sonoff Basic

esphome:
  name: sonoff-basic
  platform: ESP8266
  board: esp01_1m

binary_sensor:
  - platform: gpio
    pin:
      number: GPIO0
      mode: INPUT_PULLUP
      inverted: true
    name: "Button"
    on_press:
      - switch.toggle: relay

  - platform: status
    name: "Status"

switch:
  - platform: gpio
    pin: GPIO12
    name: "Relay"
    id: relay

status_led:
  pin:
    number: GPIO13
    inverted: true

Lights & LEDs

PWM LED

output:
  - platform: esp8266_pwm
    pin: D1
    id: led_output

light:
  - platform: monochromatic
    name: "LED"
    output: led_output
    gamma_correct: 2.8

RGB LED Strip (WS2812B)

light:
  - platform: fastled_clockless
    chipset: WS2812B
    pin: D4
    num_leds: 60
    rgb_order: GRB
    name: "LED Strip"
    effects:
      - random:
      - pulse:
      - strobe:
      - flicker:
      - addressable_rainbow:
      - addressable_color_wipe:
      - addressable_scan:
      - addressable_fireworks:

RGBW LED

output:
  - platform: esp8266_pwm
    pin: D1
    id: red
  - platform: esp8266_pwm
    pin: D2
    id: green
  - platform: esp8266_pwm
    pin: D3
    id: blue
  - platform: esp8266_pwm
    pin: D4
    id: white

light:
  - platform: rgbw
    name: "RGBW Light"
    red: red
    green: green
    blue: blue
    white: white

Displays

OLED Display (SSD1306)

i2c:
  sda: D2
  scl: D1

font:
  - file: "fonts/arial.ttf"
    id: font1
    size: 14

display:
  - platform: ssd1306_i2c
    model: "SSD1306 128x64"
    address: 0x3C
    lambda: |-
      it.printf(0, 0, id(font1), "Temp: %.1f°C", id(temperature).state);
      it.printf(0, 20, id(font1), "Humidity: %.1f%%", id(humidity).state);

E-Paper Display

spi:
  clk_pin: D5
  mosi_pin: D7

display:
  - platform: waveshare_epaper
    cs_pin: D8
    dc_pin: D1
    busy_pin: D2
    reset_pin: D0
    model: 2.90in
    lambda: |-
      it.print(0, 0, id(font1), "Hello World!");

Automations

# Time-based automation
time:
  - platform: homeassistant
    id: homeassistant_time
    on_time:
      - seconds: 0
        minutes: 0
        hours: 7
        then:
          - light.turn_on: led

# State-based automation
binary_sensor:
  - platform: gpio
    pin: D5
    name: "Motion"
    on_press:
      then:
        - light.turn_on:
            id: led
            brightness: 100%
            transition_length: 1s
    on_release:
      then:
        - delay: 5min
        - light.turn_off:
            id: led
            transition_length: 2s

# Template automation
interval:
  - interval: 1min
    then:
      - if:
          condition:
            sensor.in_range:
              id: temperature
              above: 25
          then:
            - switch.turn_on: fan
          else:
            - switch.turn_off: fan

ESP32 Bluetooth

BLE Presence Detection

esp32_ble_tracker:
  scan_parameters:
    interval: 1100ms
    window: 1100ms
    active: true

binary_sensor:
  - platform: ble_presence
    mac_address: AA:BB:CC:DD:EE:FF
    name: "Phone Present"

Xiaomi Sensors

esp32_ble_tracker:

sensor:
  - platform: xiaomi_lywsd03mmc
    mac_address: "A4:C1:38:XX:XX:XX"
    bindkey: "your-bind-key"
    temperature:
      name: "Temperature"
    humidity:
      name: "Humidity"
    battery_level:
      name: "Battery"

Best Practices

1. Use secrets.yaml for sensitive data
2. Set static IPs for reliability
3. Enable fallback AP for recovery
4. Use meaningful names for HA integration
5. Add filters for sensor smoothing
6. Enable OTA for remote updates
7. Test with logs before deploying
8. Use restore_mode for switches
9. Add status LED for debugging
10. Document pin assignments

Troubleshooting

# Enable verbose logging
logger:
  level: VERBOSE

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

# Restart button
button:
  - platform: restart
    name: "Restart"

# Safe mode
button:
  - platform: safe_mode
    name: "Safe Mode"