Trying to use package function to call a common.yaml from each ESPHome device

I did a wee search bit could not find too much on this (but apologies if I missed it). I have 5 ESP32-C3s, all running well for a while now, with an example yaml from one of them, as shown below.

The 5# yamls are identical, w.e.o. lines 2 and 3, which define names. That is it, the remaining 95% of the yamls are the same for each device (all BT Proxy Trackers, for now).

display_name: esp32c3btproxykat
friendly_name: ESP32C3BTProxyKat

As the 5# yamls are the same, I thought to streamline future edits so I only need to make changes in one file, say esp32common.yaml.

So what I have done, having read the esphome packages section is to split my example working yaml into:

1. The original first 3 lines (which includes the names) and package: section, which calls the esp32common.yaml file. I saved this as the original file name esp32c3btproxykat.yaml;

substitutions: # name substitutions ref Digiblur https://digiblur.com/wiki/ha/esphome-bluetooth-proxy-esp32c3/
  display_name: esp32c3btproxykat
  friendly_name: ESP32C3BTProxyKat
  
  packages:
    # wifi: !include common/wifi.yaml - example additional package for wifi
    esp32c3devices: !include common/esp32c3btproxy-common.yaml

2. A new yaml, esp32common.yaml, which contains the remaining 95% of the original yaml, without the above lines. I put this in /homeassistant/esphome/common.

However when I tried to verify it I got the following error:

INFO ESPHome 2025.4.0
INFO Reading configuration /config/esphome/esp32c3btproxykat.yaml...
Failed config

substitutions: None
  display_name: esp32c3btproxykat
  friendly_name: ESP32C3BTProxyKat
  
  Must be string, got <class 'esphome.helpers.OrderedDict'>. did you forget putting quotes around the value?.
  packages: 
    esp32c3devices: 
      esphome: 
        name: ${display_name}
        friendly_name: ${friendly_name}
        min_version: 2024.11.0
        name_add_mac_suffix: False
      wifi: 
        reboot_timeout: 3min
        ssid: !secret wifi_ssid

My understanding was that you could just call the common yaml from the main yaml for each device and that the display_name and friendly_name variables would be passed to the common_yaml. I will admit I am not 100% clear on this though!

I would really appreciate a heads up on why this is failing and how to achieve what it is I am looking to do. Thank you.

ORIGINAL WORKING YAML

substitutions: # name substitutions ref Digiblur https://digiblur.com/wiki/ha/esphome-bluetooth-proxy-esp32c3/
  display_name: esp32c3btproxykat
  friendly_name: ESP32C3BTProxyKat

esphome:
  name: ${display_name}
  friendly_name: ${friendly_name}
  min_version: 2024.11.0
  name_add_mac_suffix: false

wifi:
  # output_power: 8.5dB # enable if having issues with connectivity
  reboot_timeout: 3min
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  fast_connect: true # Optional. Required (true) if connecting to a hidden SSID; suggest disable if setting Manual IP

  ap: # Enable fallback hotspot (captive portal) in case wifi connection fails
    ssid: ${display_name}
    password: !secret wifi_ap_password

esp32: 
  variant: ESP32C3
  board: esp32-c3-devkitm-1
  framework:
    type: esp-idf # This is important: the default "arduino" framework does not perform well.
    sdkconfig_options:
      CONFIG_BT_BLE_42_FEATURES_SUPPORTED: y # BLE 4.2 is supported by ALL ESP32 boards that have bluetooth, the original and derivatives.
      CONFIG_BT_BLE_50_FEATURES_SUPPORTED: y # Also enable this on any derivative boards (S2, C3 etc) but not the original ESP32.
      CONFIG_ESP_TASK_WDT: y
      CONFIG_ESP_TASK_WDT_TIMEOUT_S: "10" # Extend the watchdog timeout, so the device reboots if the device appears locked up for over 10 seconds.

logger: # Enable logging
  level: DEBUG # Debug=Default; use Verbose if error checking
  # baud_rate: 0  # 0 Enables logging, but disables serial-port logging to free CPU and memory

ota: # Allow Over-The-Air updates
- platform: esphome
  password: !secret ota_password

api: # Enable Home Assistant API; MUST check option under ESPHome Configure!
  encryption:
    key: !secret encryption_key
  on_client_connected: # Only enable BLE tracking when wifi is up and api is connected;Gives single-core ESP32-C3 devices time to manage wifi and authenticate with api
     - esp32_ble_tracker.start_scan:
        continuous: true
  on_client_disconnected: # Disable BLE tracking when there are no api connections live
    if:
      condition:
        not:
          api.connected:
      then:
        - esp32_ble_tracker.stop_scan:
  
# Optional Manual IP
# manual_ip:
#   static_ip: 192.168.53.109
#   gateway: !secret gateway
#   subnet: !secret subnet

captive_portal:

esp32_ble_tracker:
  id: ble_tracker
  scan_parameters: # Bermuda suggests 280/320 or 920/1000 to allow offset BT/Wifi
    interval: 320ms # default 1100ms
    window: 280ms # default 1100ms
    continuous: true
    active: false #defaults to true - selecting false saves power but may not work

bluetooth_proxy:
  active: true # Optional, defaults to false

button:
  - platform: safe_mode
    id: button_safe_mode
    name: Safe Mode Boot

  - platform: factory_reset
    id: factory_reset_btn
    name: Factory Reset

# time:
#  - platform: homeassistant
#    id: homeassistant_time

sensor:
  - platform: uptime
    # The uptime sensor is extremely helpful to know if your device is rebooting
    # when it shouldn't be. This might indicate your interval-to-window timing is
    # too tight, and the window needs to be reduced.
    name: "Uptime Sensor"
    update_interval: 60s

1 post - 1 participant

Read full topic