Agent skill

esphome-devices

Create and configure ESPHome devices for DIY smart home sensors and actuators. Write YAML configurations for ESP8266/ESP32 boards, sensors, displays, and automations. Use when building custom IoT devices, flashing ESPHome firmware, or integrating with Home Assistant. (project)

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/esphome-devices

SKILL.md

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

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

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

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

Common Sensors

Temperature & Humidity (DHT22)

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

Temperature (Dallas DS18B20)

yaml
dallas:
  - pin: D4

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

BME280 (I2C)

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

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

Door/Window Sensor

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

Light Sensor (BH1750)

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

Analog Sensor

yaml
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

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

Button-Controlled Relay

yaml
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

yaml
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

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

yaml
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

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

yaml
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

yaml
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

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

yaml
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

yaml
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

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

Didn't find tool you were looking for?

Be as detailed as possible for better results