esphome 2025.2.1__py3-none-any.whl → 2025.3.0b1__py3-none-any.whl

esphome/dashboard/settings.py

@@ -54,10 +54,6 @@ class DashboardSettings:
     def relative_url(self) -> str:
         return os.getenv("ESPHOME_DASHBOARD_RELATIVE_URL") or "/"
 
-    @property
-    def status_use_ping(self):
-        return get_bool_env("ESPHOME_DASHBOARD_USE_PING")
-
     @property
     def status_use_mqtt(self) -> bool:
         return get_bool_env("ESPHOME_DASHBOARD_USE_MQTT")

esphome/dashboard/status/mdns.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import asyncio
+import logging
+import typing
 
 from esphome.zeroconf import (
     ESPHOME_SERVICE_TYPE,
@@ -11,20 +13,36 @@ from esphome.zeroconf import (
 )
 
 from ..const import SENTINEL
-from ..core import DASHBOARD
-from ..entries import DashboardEntry, bool_to_entry_state
+from ..entries import DashboardEntry, EntryStateSource, bool_to_entry_state
+
+if typing.TYPE_CHECKING:
+    from ..core import ESPHomeDashboard
+
+_LOGGER = logging.getLogger(__name__)
 
 
 class MDNSStatus:
     """Class that updates the mdns status."""
 
-    def __init__(self) -> None:
+    def __init__(self, dashboard: ESPHomeDashboard) -> None:
         """Initialize the MDNSStatus class."""
         super().__init__()
         self.aiozc: AsyncEsphomeZeroconf | None = None
         # This is the current mdns state for each host (True, False, None)
         self.host_mdns_state: dict[str, bool | None] = {}
         self._loop = asyncio.get_running_loop()
+        self.dashboard = dashboard
+
+    def async_setup(self) -> bool:
+        """Set up the MDNSStatus class."""
+        try:
+            self.aiozc = AsyncEsphomeZeroconf()
+        except OSError as e:
+            _LOGGER.warning(
+                "Failed to initialize zeroconf, will fallback to ping: %s", e
+            )
+            return False
+        return True
 
     async def async_resolve_host(self, host_name: str) -> list[str] | None:
         """Resolve a host name to an address in a thread-safe manner."""
@@ -32,9 +50,9 @@ class MDNSStatus:
             return await aiozc.async_resolve_host(host_name)
         return None
 
-    async def async_refresh_hosts(self):
+    async def async_refresh_hosts(self) -> None:
         """Refresh the hosts to track."""
-        dashboard = DASHBOARD
+        dashboard = self.dashboard
         host_mdns_state = self.host_mdns_state
         entries = dashboard.entries
         poll_names: dict[str, set[DashboardEntry]] = {}
@@ -49,7 +67,7 @@ class MDNSStatus:
                 # the device won't respond to a request to ._esphomelib._tcp.local.
                 poll_names.setdefault(entry.name, set()).add(entry)
             elif (online := host_mdns_state.get(entry.name, SENTINEL)) != SENTINEL:
-                entries.async_set_state(entry, bool_to_entry_state(online))
+                self._async_set_state(entry, online)
         if poll_names and self.aiozc:
             results = await asyncio.gather(
                 *(self.aiozc.async_resolve_host(name) for name in poll_names)
@@ -58,13 +76,25 @@ class MDNSStatus:
                 result = bool(address_list)
                 host_mdns_state[name] = result
                 for entry in poll_names[name]:
-                    entries.async_set_state(entry, bool_to_entry_state(result))
+                    self._async_set_state(entry, result)
+
+    def _async_set_state(self, entry: DashboardEntry, result: bool | None) -> None:
+        """Set the state of an entry."""
+        state = bool_to_entry_state(result, EntryStateSource.MDNS)
+        if result:
+            # If we can reach it via mDNS, we always set it online
+            # since its the fastest source if its working
+            self.dashboard.entries.async_set_state(entry, state)
+        else:
+            # However if we can't reach it via mDNS
+            # we only set it to offline if the state is unknown
+            # or from mDNS
+            self.dashboard.entries.async_set_state_if_source(entry, state)
 
     async def async_run(self) -> None:
-        dashboard = DASHBOARD
+        """Run the mdns status."""
+        dashboard = self.dashboard
         entries = dashboard.entries
-        aiozc = AsyncEsphomeZeroconf()
-        self.aiozc = aiozc
         host_mdns_state = self.host_mdns_state
 
         def on_update(dat: dict[str, bool | None]) -> None:
@@ -73,15 +103,14 @@ class MDNSStatus:
                 host_mdns_state[name] = result
                 if matching_entries := entries.get_by_name(name):
                     for entry in matching_entries:
-                        if not entry.no_mdns:
-                            entries.async_set_state(entry, bool_to_entry_state(result))
+                        self._async_set_state(entry, result)
 
         stat = DashboardStatus(on_update)
         imports = DashboardImportDiscovery()
         dashboard.import_result = imports.import_state
 
         browser = DashboardBrowser(
-            aiozc.zeroconf,
+            self.aiozc.zeroconf,
             ESPHOME_SERVICE_TYPE,
             [stat.browser_callback, imports.browser_callback],
         )
@@ -93,5 +122,5 @@ class MDNSStatus:
             ping_request.clear()
 
         await browser.async_cancel()
-        await aiozc.async_close()
+        await self.aiozc.async_close()
         self.aiozc = None

esphome/dashboard/status/mqtt.py

@@ -4,19 +4,27 @@ import binascii
 import json
 import os
 import threading
+import typing
 
 from esphome import mqtt
 
-from ..core import DASHBOARD
-from ..entries import EntryState
+from ..entries import EntryStateSource, bool_to_entry_state
+
+if typing.TYPE_CHECKING:
+    from ..core import ESPHomeDashboard
 
 
 class MqttStatusThread(threading.Thread):
     """Status thread to get the status of the devices via MQTT."""
 
+    def __init__(self, dashboard: ESPHomeDashboard) -> None:
+        """Initialize the status thread."""
+        super().__init__()
+        self.dashboard = dashboard
+
     def run(self) -> None:
         """Run the status thread."""
-        dashboard = DASHBOARD
+        dashboard = self.dashboard
         entries = dashboard.entries
         current_entries = entries.all()
 
@@ -31,10 +39,13 @@ class MqttStatusThread(threading.Thread):
                 data = json.loads(payload)
                 if "name" not in data:
                     return
-                for entry in current_entries:
-                    if entry.name == data["name"]:
-                        entries.set_state(entry, EntryState.ONLINE)
-                        return
+                if matching_entries := entries.get_by_name(data["name"]):
+                    for entry in matching_entries:
+                        # Only override state if we don't have a state from another source
+                        # or we have a state from MQTT and the device is reachable
+                        entries.set_state_if_online_or_source(
+                            entry, bool_to_entry_state(True, EntryStateSource.MQTT)
+                        )
 
         def on_connect(client, userdata, flags, return_code):
             client.publish("esphome/discover", None, retain=False)
@@ -56,8 +67,10 @@ class MqttStatusThread(threading.Thread):
             current_entries = entries.all()
             # will be set to true on on_message
             for entry in current_entries:
-                if entry.no_mdns:
-                    entries.set_state(entry, EntryState.OFFLINE)
+                # Only override state if we don't have a state from another source
+                entries.set_state_if_source(
+                    entry, bool_to_entry_state(False, EntryStateSource.MQTT)
+                )
 
             client.publish("esphome/discover", None, retain=False)
             dashboard.mqtt_ping_request.wait()

esphome/dashboard/status/ping.py

@@ -3,29 +3,44 @@ from __future__ import annotations
 import asyncio
 import logging
 import time
+import typing
 from typing import cast
 
 from icmplib import Host, SocketPermissionError, async_ping
 
 from ..const import MAX_EXECUTOR_WORKERS
-from ..core import DASHBOARD
-from ..entries import DashboardEntry, EntryState, bool_to_entry_state
+from ..entries import (
+    DashboardEntry,
+    EntryState,
+    EntryStateSource,
+    ReachableState,
+    bool_to_entry_state,
+)
 from ..util.itertools import chunked
 
+if typing.TYPE_CHECKING:
+    from ..core import ESPHomeDashboard
+
+
 _LOGGER = logging.getLogger(__name__)
 
 GROUP_SIZE = int(MAX_EXECUTOR_WORKERS / 2)
 
+DNS_FAILURE_STATE = EntryState(ReachableState.DNS_FAILURE, EntryStateSource.PING)
+
+MIN_PING_INTERVAL = 5  # ensure we don't ping too often
+
 
 class PingStatus:
-    def __init__(self) -> None:
+    def __init__(self, dashboard: ESPHomeDashboard) -> None:
         """Initialize the PingStatus class."""
         super().__init__()
         self._loop = asyncio.get_running_loop()
+        self.dashboard = dashboard
 
     async def async_run(self) -> None:
         """Run the ping status."""
-        dashboard = DASHBOARD
+        dashboard = self.dashboard
         entries = dashboard.entries
         privileged = await _can_use_icmp_lib_with_privilege()
         if privileged is None:
@@ -36,10 +51,24 @@ class PingStatus:
             # Only ping if the dashboard is open
             await dashboard.ping_request.wait()
             dashboard.ping_request.clear()
+            iteration_start = time.monotonic()
             current_entries = dashboard.entries.async_all()
-            to_ping: list[DashboardEntry] = [
-                entry for entry in current_entries if entry.address is not None
-            ]
+            to_ping: list[DashboardEntry] = []
+
+            for entry in current_entries:
+                if entry.address is None:
+                    # No address or we already have a state from another source
+                    # so no need to ping
+                    continue
+                if (
+                    entry.state.reachable is ReachableState.ONLINE
+                    and entry.state.source
+                    not in (EntryStateSource.PING, EntryStateSource.UNKNOWN)
+                ):
+                    # If we already have a state from another source and
+                    # it's online, we don't need to ping
+                    continue
+                to_ping.append(entry)
 
             # Resolve DNS for all entries
             entries_with_addresses: dict[DashboardEntry, list[str]] = {}
@@ -56,7 +85,10 @@ class PingStatus:
 
                 for entry, result in zip(ping_group, dns_results):
                     if isinstance(result, Exception):
-                        entries.async_set_state(entry, EntryState.UNKNOWN)
+                        # Only update state if its unknown or from ping
+                        # so we don't mark it as offline if we have a state
+                        # from mDNS or MQTT
+                        entries.async_set_state_if_source(entry, DNS_FAILURE_STATE)
                         continue
                     if isinstance(result, BaseException):
                         raise result
@@ -82,8 +114,20 @@ class PingStatus:
                     else:
                         host: Host = result
                         ping_result = host.is_alive
-                    entry, _ = entry_addresses
-                    entries.async_set_state(entry, bool_to_entry_state(ping_result))
+                    entry: DashboardEntry = entry_addresses[0]
+                    # If we can reach it via ping, we always set it
+                    # online, however if we can't reach it via ping
+                    # we only set it to offline if the state is unknown
+                    # or from ping
+                    entries.async_set_state_if_online_or_source(
+                        entry,
+                        bool_to_entry_state(ping_result, EntryStateSource.PING),
+                    )
+
+            if not dashboard.stop_event.is_set():
+                iteration_duration = time.monotonic() - iteration_start
+                if iteration_duration < MIN_PING_INTERVAL:
+                    await asyncio.sleep(MIN_PING_INTERVAL - iteration_duration)
 
 
 async def _can_use_icmp_lib_with_privilege() -> None | bool:

esphome/dashboard/web_server.py

@@ -33,18 +33,24 @@ import tornado.process
 import tornado.queues
 import tornado.web
 import tornado.websocket
+import voluptuous as vol
 import yaml
 from yaml.nodes import Node
 
 from esphome import const, platformio_api, yaml_util
 from esphome.helpers import get_bool_env, mkdir_p
-from esphome.storage_json import StorageJSON, ext_storage_path, trash_storage_path
+from esphome.storage_json import (
+    StorageJSON,
+    archive_storage_path,
+    ext_storage_path,
+    trash_storage_path,
+)
 from esphome.util import get_serial_ports, shlex_quote
 from esphome.yaml_util import FastestAvailableSafeLoader
 
 from .const import DASHBOARD_COMMAND
 from .core import DASHBOARD
-from .entries import EntryState, entry_state_to_bool
+from .entries import UNKNOWN_STATE, entry_state_to_bool
 from .util.file import write_file
 from .util.subprocess import async_run_system_command
 from .util.text import friendly_name_slugify
@@ -52,7 +58,6 @@ from .util.text import friendly_name_slugify
 if TYPE_CHECKING:
     from requests import Response
 
-
 _LOGGER = logging.getLogger(__name__)
 
 ENV_DEV = "ESPHOME_DASHBOARD_DEV"
@@ -381,7 +386,7 @@ class EsphomeRenameHandler(EsphomeCommandWebSocket):
         # Remove the old ping result from the cache
         entries = DASHBOARD.entries
         if entry := entries.get(self.old_name):
-            entries.async_set_state(entry, EntryState.UNKNOWN)
+            entries.async_set_state(entry, UNKNOWN_STATE)
 
 
 class EsphomeUploadHandler(EsphomePortCommandWebSocket):
@@ -592,16 +597,39 @@ class IgnoreDeviceRequestHandler(BaseHandler):
 class DownloadListRequestHandler(BaseHandler):
     @authenticated
     @bind_config
-    def get(self, configuration: str | None = None) -> None:
+    async def get(self, configuration: str | None = None) -> None:
+        loop = asyncio.get_running_loop()
+        try:
+            downloads_json = await loop.run_in_executor(None, self._get, configuration)
+        except vol.Invalid:
+            self.send_error(404)
+            return
+        if downloads_json is None:
+            self.send_error(404)
+            return
+        self.set_status(200)
+        self.set_header("content-type", "application/json")
+        self.write(downloads_json)
+        self.finish()
+
+    def _get(self, configuration: str | None = None) -> dict[str, Any] | None:
         storage_path = ext_storage_path(configuration)
         storage_json = StorageJSON.load(storage_path)
         if storage_json is None:
-            self.send_error(404)
-            return
+            return None
+
+        config = yaml_util.load_yaml(settings.rel_path(configuration))
+
+        if const.CONF_EXTERNAL_COMPONENTS in config:
+            from esphome.components.external_components import (
+                do_external_components_pass,
+            )
+
+            do_external_components_pass(config)
 
         from esphome.components.esp32 import VARIANTS as ESP32_VARIANTS
 
-        downloads = []
+        downloads: list[dict[str, Any]] = []
         platform: str = storage_json.target_platform.lower()
 
         if platform.upper() in ESP32_VARIANTS:
@@ -615,12 +643,7 @@ class DownloadListRequestHandler(BaseHandler):
         except AttributeError as exc:
             raise ValueError(f"Unknown platform {platform}") from exc
         downloads = get_download_types(storage_json)
-
-        self.set_status(200)
-        self.set_header("content-type", "application/json")
-        self.write(json.dumps(downloads))
-        self.finish()
-        return
+        return json.dumps(downloads)
 
 
 class DownloadBinaryRequestHandler(BaseHandler):
@@ -918,16 +941,16 @@ class EditRequestHandler(BaseHandler):
         self.set_status(200)
 
 
-class DeleteRequestHandler(BaseHandler):
+class ArchiveRequestHandler(BaseHandler):
     @authenticated
     @bind_config
     def post(self, configuration: str | None = None) -> None:
         config_file = settings.rel_path(configuration)
         storage_path = ext_storage_path(configuration)
 
-        trash_path = trash_storage_path()
-        mkdir_p(trash_path)
-        shutil.move(config_file, os.path.join(trash_path, configuration))
+        archive_path = archive_storage_path()
+        mkdir_p(archive_path)
+        shutil.move(config_file, os.path.join(archive_path, configuration))
 
         storage_json = StorageJSON.load(storage_path)
         if storage_json is not None:
@@ -935,16 +958,16 @@ class DeleteRequestHandler(BaseHandler):
             name = storage_json.name
             build_folder = os.path.join(settings.config_dir, name)
             if build_folder is not None:
-                shutil.rmtree(build_folder, os.path.join(trash_path, name))
+                shutil.rmtree(build_folder, os.path.join(archive_path, name))
 
 
-class UndoDeleteRequestHandler(BaseHandler):
+class UnArchiveRequestHandler(BaseHandler):
     @authenticated
     @bind_config
     def post(self, configuration: str | None = None) -> None:
         config_file = settings.rel_path(configuration)
-        trash_path = trash_storage_path()
-        shutil.move(os.path.join(trash_path, configuration), config_file)
+        archive_path = archive_storage_path()
+        shutil.move(os.path.join(archive_path, configuration), config_file)
 
 
 class LoginHandler(BaseHandler):
@@ -1185,8 +1208,10 @@ def make_app(debug=get_bool_env(ENV_DEV)) -> tornado.web.Application:
             (f"{rel}download.bin", DownloadBinaryRequestHandler),
             (f"{rel}serial-ports", SerialPortRequestHandler),
             (f"{rel}ping", PingRequestHandler),
-            (f"{rel}delete", DeleteRequestHandler),
-            (f"{rel}undo-delete", UndoDeleteRequestHandler),
+            (f"{rel}delete", ArchiveRequestHandler),
+            (f"{rel}undo-delete", UnArchiveRequestHandler),
+            (f"{rel}archive", ArchiveRequestHandler),
+            (f"{rel}unarchive", UnArchiveRequestHandler),
             (f"{rel}wizard", WizardRequestHandler),
             (f"{rel}static/(.*)", StaticFileHandler, {"path": get_static_path()}),
             (f"{rel}devices", ListDevicesHandler),
@@ -1211,6 +1236,13 @@ def start_web_server(
     config_dir: str,
 ) -> None:
     """Start the web server listener."""
+
+    trash_path = trash_storage_path()
+    if os.path.exists(trash_path):
+        _LOGGER.info("Renaming 'trash' folder to 'archive'")
+        archive_path = archive_storage_path()
+        shutil.move(trash_path, archive_path)
+
     if socket is None:
         _LOGGER.info(
             "Starting dashboard web server on http://%s:%s and configuration dir %s...",

esphome/storage_json.py

@@ -36,6 +36,10 @@ def trash_storage_path() -> str:
     return CORE.relative_config_path("trash")
 
 
+def archive_storage_path() -> str:
+    return CORE.relative_config_path("archive")
+
+
 class StorageJSON:
     def __init__(
         self,

esphome/wizard.py

@@ -144,17 +144,17 @@ def wizard_file(**kwargs):
 
     # Configure API
     if "password" in kwargs:
-        config += f"  password: \"{kwargs['password']}\"\n"
+        config += f'  password: "{kwargs["password"]}"\n'
     if "api_encryption_key" in kwargs:
-        config += f"  encryption:\n    key: \"{kwargs['api_encryption_key']}\"\n"
+        config += f'  encryption:\n    key: "{kwargs["api_encryption_key"]}"\n'
 
     # Configure OTA
     config += "\nota:\n"
     config += "  - platform: esphome\n"
     if "ota_password" in kwargs:
-        config += f"    password: \"{kwargs['ota_password']}\""
+        config += f'    password: "{kwargs["ota_password"]}"'
     elif "password" in kwargs:
-        config += f"    password: \"{kwargs['password']}\""
+        config += f'    password: "{kwargs["password"]}"'
 
     # Configuring wifi
     config += "\n\nwifi:\n"
@@ -181,18 +181,14 @@ def wizard_file(**kwargs):
     password: "{fallback_psk}"
 
 captive_portal:
-    """.format(
-            **kwargs
-        )
+    """.format(**kwargs)
     else:
         config += """
   # Enable fallback hotspot in case wifi connection fails
   ap:
     ssid: "{fallback_name}"
     password: "{fallback_psk}"
-    """.format(
-            **kwargs
-        )
+    """.format(**kwargs)
 
     return config
 
@@ -388,19 +384,19 @@ def wizard(path):
     safe_print()
     # Don't sleep because user needs to copy link
     if platform == "ESP32":
-        safe_print(f"For example \"{color(Fore.BOLD_WHITE, 'nodemcu-32s')}\".")
+        safe_print(f'For example "{color(Fore.BOLD_WHITE, "nodemcu-32s")}".')
         boards_list = esp32_boards.BOARDS.items()
     elif platform == "ESP8266":
-        safe_print(f"For example \"{color(Fore.BOLD_WHITE, 'nodemcuv2')}\".")
+        safe_print(f'For example "{color(Fore.BOLD_WHITE, "nodemcuv2")}".')
         boards_list = esp8266_boards.BOARDS.items()
     elif platform == "BK72XX":
-        safe_print(f"For example \"{color(Fore.BOLD_WHITE, 'cb2s')}\".")
+        safe_print(f'For example "{color(Fore.BOLD_WHITE, "cb2s")}".')
         boards_list = bk72xx_boards.BOARDS.items()
     elif platform == "RTL87XX":
-        safe_print(f"For example \"{color(Fore.BOLD_WHITE, 'wr3')}\".")
+        safe_print(f'For example "{color(Fore.BOLD_WHITE, "wr3")}".')
         boards_list = rtl87xx_boards.BOARDS.items()
     elif platform == "RP2040":
-        safe_print(f"For example \"{color(Fore.BOLD_WHITE, 'rpipicow')}\".")
+        safe_print(f'For example "{color(Fore.BOLD_WHITE, "rpipicow")}".')
         boards_list = rp2040_boards.BOARDS.items()
 
     else:
@@ -439,7 +435,7 @@ def wizard(path):
             f"First, what's the {color(Fore.GREEN, 'SSID')} (the name) of the WiFi network {name} should connect to?"
         )
         sleep(1.5)
-        safe_print(f"For example \"{color(Fore.BOLD_WHITE, 'Abraham Linksys')}\".")
+        safe_print(f'For example "{color(Fore.BOLD_WHITE, "Abraham Linksys")}".')
         while True:
             ssid = safe_input(color(Fore.BOLD_WHITE, "(ssid): "))
             try:
@@ -465,7 +461,7 @@ def wizard(path):
             f"Now please state the {color(Fore.GREEN, 'password')} of the WiFi network so that I can connect to it (Leave empty for no password)"
         )
         safe_print()
-        safe_print(f"For example \"{color(Fore.BOLD_WHITE, 'PASSWORD42')}\"")
+        safe_print(f'For example "{color(Fore.BOLD_WHITE, "PASSWORD42")}"')
         sleep(0.5)
         psk = safe_input(color(Fore.BOLD_WHITE, "(PSK): "))
         safe_print(

esphome/writer.py

@@ -212,9 +212,7 @@ def write_platformio_project():
     write_platformio_ini(content)
 
 
-DEFINES_H_FORMAT = (
-    ESPHOME_H_FORMAT
-) = """\
+DEFINES_H_FORMAT = ESPHOME_H_FORMAT = """\
 #pragma once
 #include "esphome/core/macros.h"
 {}

esphome/yaml_util.py

@@ -273,48 +273,18 @@ class ESPHomeLoaderMixin:
 
     @_add_data_ref
     def construct_include(self, node):
+        from esphome.const import CONF_VARS
+
         def extract_file_vars(node):
             fields = self.construct_yaml_map(node)
             file = fields.get("file")
             if file is None:
                 raise yaml.MarkedYAMLError("Must include 'file'", node.start_mark)
-            vars = fields.get("vars")
+            vars = fields.get(CONF_VARS)
             if vars:
                 vars = {k: str(v) for k, v in vars.items()}
             return file, vars
 
-        def substitute_vars(config, vars):
-            from esphome.components import substitutions
-            from esphome.const import CONF_DEFAULTS, CONF_SUBSTITUTIONS
-
-            org_subs = None
-            result = config
-            if not isinstance(config, dict):
-                # when the included yaml contains a list or a scalar
-                # wrap it into an OrderedDict because do_substitution_pass expects it
-                result = OrderedDict([("yaml", config)])
-            elif CONF_SUBSTITUTIONS in result:
-                org_subs = result.pop(CONF_SUBSTITUTIONS)
-
-            defaults = {}
-            if CONF_DEFAULTS in result:
-                defaults = result.pop(CONF_DEFAULTS)
-
-            result[CONF_SUBSTITUTIONS] = vars
-            for k, v in defaults.items():
-                if k not in result[CONF_SUBSTITUTIONS]:
-                    result[CONF_SUBSTITUTIONS][k] = v
-
-            # Ignore missing vars that refer to the top level substitutions
-            substitutions.do_substitution_pass(result, None, ignore_missing=True)
-            result.pop(CONF_SUBSTITUTIONS)
-
-            if not isinstance(config, dict):
-                result = result["yaml"]  # unwrap the result
-            elif org_subs:
-                result[CONF_SUBSTITUTIONS] = org_subs
-            return result
-
         if isinstance(node, yaml.nodes.MappingNode):
             file, vars = extract_file_vars(node)
         else:
@@ -432,6 +402,39 @@ def parse_yaml(file_name: str, file_handle: TextIOWrapper) -> Any:
         )
 
 
+def substitute_vars(config, vars):
+    from esphome.components import substitutions
+    from esphome.const import CONF_DEFAULTS, CONF_SUBSTITUTIONS
+
+    org_subs = None
+    result = config
+    if not isinstance(config, dict):
+        # when the included yaml contains a list or a scalar
+        # wrap it into an OrderedDict because do_substitution_pass expects it
+        result = OrderedDict([("yaml", config)])
+    elif CONF_SUBSTITUTIONS in result:
+        org_subs = result.pop(CONF_SUBSTITUTIONS)
+
+    defaults = {}
+    if CONF_DEFAULTS in result:
+        defaults = result.pop(CONF_DEFAULTS)
+
+    result[CONF_SUBSTITUTIONS] = vars
+    for k, v in defaults.items():
+        if k not in result[CONF_SUBSTITUTIONS]:
+            result[CONF_SUBSTITUTIONS][k] = v
+
+    # Ignore missing vars that refer to the top level substitutions
+    substitutions.do_substitution_pass(result, None, ignore_missing=True)
+    result.pop(CONF_SUBSTITUTIONS)
+
+    if not isinstance(config, dict):
+        result = result["yaml"]  # unwrap the result
+    elif org_subs:
+        result[CONF_SUBSTITUTIONS] = org_subs
+    return result
+
+
 def _load_yaml_internal(fname: str) -> Any:
     """Load a YAML file."""
     try: