Many similar ESPHome devices: !secret, substitutions and packages instead of copy-paste

With ten smart plugs or twenty room sensors, copy-pasted YAML drifts apart quickly. Three tools keep it maintainable.

secrets.yaml: credentials out of the device files

# secrets.yaml (flat key: value pairs only, never commit it)
wifi_ssid: MyNetwork
wifi_password: change-me
api_encryption_key: "generate-a-32-byte-base64-key"

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

Shared base as a package

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

api:
  encryption:
    key: !secret api_encryption_key

ota:
  - platform: esphome

logger:

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

captive_portal:

Each device file stays short

# kitchen-plug.yaml
substitutions:
  name: kitchen-plug

packages:
  base: !include common/base.yaml

esp8266:
  board: esp01_1m

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

Reusing one package several times

packages:
  left_door: !include
    file: garage-door.yaml
    vars:
      door_name: Left
  right_door: !include
    file: garage-door.yaml
    vars:
      door_name: Right

Rules worth knowing

• Substitutions are $key or ${key}, and case-sensitive. Override them for a one-off build with esphome -s name test-device run kitchen-plug.yaml.
• Values in the device file override the same keys from packages, so you can change one setting for one device.
• Packages can also come from a git repository (url:, files:, ref:), which is handy for sharing a base across sites. Pin a ref, so a change upstream doesn't silently alter every device on the next build.
• Keep secrets.yaml out of git. Commit an example file with dummy values instead.