esphome-yaml

ESPHome YAML Configuration

Overview

ESPHome uses YAML for device configurations. This skill guides writing valid ESPHome configurations with proper syntax, component organization, modularization through packages, and correct usage of configuration types (IDs, pins, time values).

Core Workflows

Writing Basic Device Configuration

A typical ESPHome device configuration includes:

1. ESPHome metadata (name, platform, board)
2. Connectivity (Wi-Fi or Ethernet)
3. Common infrastructure (logger, API, web server)
4. Components (sensors, switches, lights, binaries)
5. Automations and actions

esphome:
  name: my_device
  friendly_name: "My Device"

esp32:
  board: wemos_d1_mini32

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

logger:

api:
  encryption:
    key: !secret api_encryption_key

web_server:
  port: 80

sensor:
  - platform: adc
    pin: GPIO32
    name: "Temperature"
    update_interval: 60s

Organizing Modular Configurations with Packages

When managing multiple devices, avoid repetition by extracting common configuration into packages. Packages are included files that merge with the main configuration.

# config.yaml
packages:
  base: !include common/base.yaml
  wifi: !include common/wifi.yaml
  sensors: !include common/sensors.yaml

# Device-specific overrides
substitutions:
  device_name: living_room_sensor

# common/base.yaml
esphome:
  name: ${device_name}
  friendly_name: "${device_name}"

esp32:
  board: wemos_d1_mini32

logger:

api:
  encryption:
    key: !secret api_encryption_key

Use templates with variables for configurations that repeat with variations:

# config.yaml with three garage doors
packages:
  left_door: !include garage-door.yaml
    vars:
      door_name: Left
  center_door: !include garage-door.yaml
    vars:
      door_name: Center
  right_door: !include garage-door.yaml
    vars:
      door_name: Right

# garage-door.yaml (template)
switch:
  - platform: gpio
    id: ${door_name}_switch
    name: "${door_name} Door"
    pin: GPIO${door_pin}