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}

Using IDs to Connect Components

Components reference each other through IDs. Define an output with an ID, then reference it in a light or switch.

output:
  - platform: pwm
    id: kitchen_light_output
    pin: GPIO5
    frequency: 1000 Hz

light:
  - platform: monochromatic
    id: kitchen_light
    name: "Kitchen Light"
    output: kitchen_light_output
    # Now the light controls the PWM output

IDs must follow C++ naming rules: start with a letter, use underscores, no spaces or special characters, not C++ keywords.

Protecting Sensitive Values with Secrets

Store passwords, API keys, and Wi-Fi credentials in secrets.yaml, separate from version control.

# config.yaml
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
  encryption:
    key: !secret api_encryption_key

# secrets.yaml (keep out of git)
wifi_ssid: "My WiFi"
wifi_password: "super_secret_password"
api_encryption_key: "ABABAB..."

Syntax and Structure

Indentation and Lists

Proper indentation is critical in YAML. Use spaces (not tabs). When a sequence item ends with a colon, its value must be indented further:

# Correct: list of mappings
sensors:
  - platform: gpio
    name: "Sensor 1"
    pin: GPIO32
  - platform: gpio
    name: "Sensor 2"
    pin: GPIO33

# Correct: nested mapping after key
binary_sensor:
  - label:
      text: "Button"

Reusing Configuration with Anchors

Use YAML anchors (&name) and aliases (*name) to avoid duplication, especially for repeated metadata:

sensor:
  - &adc_common
    platform: adc
    device_class: temperature
    unit_of_measurement: "°C"
    accuracy_decimals: 1
  -  20) {
        return true;
      } else {
        return false;
      }

Common Configuration Reference

For detailed syntax reference, see:

• YAML Features and Extensions: See [yaml-syntax.md](references/yaml-syntax.md) for comments, scalars, sequences, mappings, anchors, multi-line strings, secrets, substitutions, !include, hidden items, and lambdas

• Packages and Modularization: See [packages.md](references/packages.md) for local packages, remote git packages, templating with variables, extending, and removing configurations

• Configuration Types: See [configuration-types.md](references/configuration-types.md) for ID naming rules, pin specifications, and time period formats

Debugging Common Issues

Indentation errors - Ensure consistent space indentation (no tabs). Sequence items starting with - should be at the same indentation as their parent key.

ID conflicts - IDs must be unique across the configuration. ESPHome warns if you use the same ID twice.

Invalid ID names - IDs must start with a letter and contain only alphanumerics and underscores, not C++ keywords.

Pin already in use - By default, ESPHome flags if a pin is used by multiple components. Use allow_other_uses: true in the pin schema only if truly necessary.

Merge conflicts in packages - Remember that values in the main configuration override package values. Use !extend to modify included configuration rather than replacing it.

Secrets not found - Ensure the secrets file is in the same directory as the config file and uses simple key: value mappings only.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: narrowstacks
• Source: narrowstacks/claude-homeassistant-plugins
• License: MIT

Install and usage instructions live in the source repository linked above.