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

esphome/components/web_server_idf/web_server_idf.h

@@ -4,12 +4,18 @@
 #include <esp_http_server.h>
 
 #include <functional>
+#include <list>
 #include <map>
 #include <set>
 #include <string>
+#include <utility>
 #include <vector>
 
 namespace esphome {
+namespace web_server {
+class WebServer;
+class ListEntitiesIterator;
+};  // namespace web_server
 namespace web_server_idf {
 
 #define F(string_literal) (string_literal)
@@ -215,19 +221,58 @@ class AsyncWebHandler {
 };
 
 class AsyncEventSource;
+class AsyncEventSourceResponse;
+
+using message_generator_t = std::string(esphome::web_server::WebServer *, void *);
+
+/*
+  This class holds a pointer to the source component that wants to publish a state event, and a pointer to a function
+  that will lazily generate that event.  The two pointers allow dedup in the deferred queue if multiple publishes for
+  the same component are backed up, and take up only 8 bytes of memory.  The entry in the deferred queue (a
+  std::vector) is the DeferredEvent instance itself (not a pointer to one elsewhere in heap) so still only 8 bytes per
+  entry (and no heap fragmentation).  Even 100 backed up events (you'd have to have at least 100 sensors publishing
+  because of dedup) would take up only 0.8 kB.
+*/
+struct DeferredEvent {
+  friend class AsyncEventSourceResponse;
+
+ protected:
+  void *source_;
+  message_generator_t *message_generator_;
+
+ public:
+  DeferredEvent(void *source, message_generator_t *message_generator)
+      : source_(source), message_generator_(message_generator) {}
+  bool operator==(const DeferredEvent &test) const {
+    return (source_ == test.source_ && message_generator_ == test.message_generator_);
+  }
+} __attribute__((packed));
 
 class AsyncEventSourceResponse {
   friend class AsyncEventSource;
 
  public:
-  void send(const char *message, const char *event = nullptr, uint32_t id = 0, uint32_t reconnect = 0);
+  bool try_send_nodefer(const char *message, const char *event = nullptr, uint32_t id = 0, uint32_t reconnect = 0);
+  void deferrable_send_state(void *source, const char *event_type, message_generator_t *message_generator);
+  void loop();
 
  protected:
-  AsyncEventSourceResponse(const AsyncWebServerRequest *request, AsyncEventSource *server);
+  AsyncEventSourceResponse(const AsyncWebServerRequest *request, esphome::web_server_idf::AsyncEventSource *server,
+                           esphome::web_server::WebServer *ws);
+
+  void deq_push_back_with_dedup_(void *source, message_generator_t *message_generator);
+  void process_deferred_queue_();
+  void process_buffer_();
+
   static void destroy(void *p);
   AsyncEventSource *server_;
   httpd_handle_t hd_{};
   int fd_{};
+  std::vector<DeferredEvent> deferred_queue_;
+  esphome::web_server::WebServer *web_server_;
+  std::unique_ptr<esphome::web_server::ListEntitiesIterator> entities_iterator_;
+  std::string event_buffer_{""};
+  size_t event_bytes_sent_;
 };
 
 using AsyncEventSourceClient = AsyncEventSourceResponse;
@@ -237,7 +282,7 @@ class AsyncEventSource : public AsyncWebHandler {
   using connect_handler_t = std::function<void(AsyncEventSourceClient *)>;
 
  public:
-  AsyncEventSource(std::string url) : url_(std::move(url)) {}
+  AsyncEventSource(std::string url, esphome::web_server::WebServer *ws) : url_(std::move(url)), web_server_(ws) {}
   ~AsyncEventSource() override;
 
   // NOLINTNEXTLINE(readability-identifier-naming)
@@ -249,7 +294,10 @@ class AsyncEventSource : public AsyncWebHandler {
   // NOLINTNEXTLINE(readability-identifier-naming)
   void onConnect(connect_handler_t cb) { this->on_connect_ = std::move(cb); }
 
-  void send(const char *message, const char *event = nullptr, uint32_t id = 0, uint32_t reconnect = 0);
+  void try_send_nodefer(const char *message, const char *event = nullptr, uint32_t id = 0, uint32_t reconnect = 0);
+  void deferrable_send_state(void *source, const char *event_type, message_generator_t *message_generator);
+  void loop();
+  bool empty() { return this->count() == 0; }
 
   size_t count() const { return this->sessions_.size(); }
 
@@ -257,6 +305,7 @@ class AsyncEventSource : public AsyncWebHandler {
   std::string url_;
   std::set<AsyncEventSourceResponse *> sessions_;
   connect_handler_t on_connect_{};
+  esphome::web_server::WebServer *web_server_;
 };
 
 class DefaultHeaders {

esphome/config_validation.py

@@ -1223,8 +1223,7 @@ def subscribe_topic(value):
         if index != len(value) - 1:
             # If there are multiple wildcards, this will also trigger
             raise Invalid(
-                "Multi-level wildcard must be the last "
-                "character in the topic filter."
+                "Multi-level wildcard must be the last character in the topic filter."
             )
         if len(value) > 1 and value[index - 1] != "/":
             raise Invalid("Multi-level wildcard must be after a topic level separator.")
@@ -1642,140 +1641,39 @@ class GenerateID(Optional):
         super().__init__(key, default=lambda: None)
 
 
-def _get_priority_default(*args):
-    for arg in args:
-        if arg is not vol.UNDEFINED:
-            return arg
-    return vol.UNDEFINED
+def _get_default_key(*args):
+    return ["_".join([CORE.target_platform] + list(args))]
 
 
 class SplitDefault(Optional):
     """Mark this key to have a split default for ESP8266/ESP32."""
 
-    def __init__(
-        self,
-        key,
-        esp8266=vol.UNDEFINED,
-        esp32=vol.UNDEFINED,
-        esp32_arduino=vol.UNDEFINED,
-        esp32_idf=vol.UNDEFINED,
-        esp32_s2=vol.UNDEFINED,
-        esp32_s2_arduino=vol.UNDEFINED,
-        esp32_s2_idf=vol.UNDEFINED,
-        esp32_s3=vol.UNDEFINED,
-        esp32_s3_arduino=vol.UNDEFINED,
-        esp32_s3_idf=vol.UNDEFINED,
-        esp32_c3=vol.UNDEFINED,
-        esp32_c3_arduino=vol.UNDEFINED,
-        esp32_c3_idf=vol.UNDEFINED,
-        esp32_c6=vol.UNDEFINED,
-        esp32_c6_arduino=vol.UNDEFINED,
-        esp32_c6_idf=vol.UNDEFINED,
-        esp32_h2=vol.UNDEFINED,
-        esp32_h2_arduino=vol.UNDEFINED,
-        esp32_h2_idf=vol.UNDEFINED,
-        rp2040=vol.UNDEFINED,
-        bk72xx=vol.UNDEFINED,
-        rtl87xx=vol.UNDEFINED,
-        host=vol.UNDEFINED,
-    ):
+    def __init__(self, key, **kwargs):
         super().__init__(key)
-        self._esp8266_default = vol.default_factory(esp8266)
-        self._esp32_arduino_default = vol.default_factory(
-            _get_priority_default(esp32_arduino, esp32)
-        )
-        self._esp32_idf_default = vol.default_factory(
-            _get_priority_default(esp32_idf, esp32)
-        )
-        self._esp32_s2_arduino_default = vol.default_factory(
-            _get_priority_default(esp32_s2_arduino, esp32_s2, esp32_arduino, esp32)
-        )
-        self._esp32_s2_idf_default = vol.default_factory(
-            _get_priority_default(esp32_s2_idf, esp32_s2, esp32_idf, esp32)
-        )
-        self._esp32_s3_arduino_default = vol.default_factory(
-            _get_priority_default(esp32_s3_arduino, esp32_s3, esp32_arduino, esp32)
-        )
-        self._esp32_s3_idf_default = vol.default_factory(
-            _get_priority_default(esp32_s3_idf, esp32_s3, esp32_idf, esp32)
-        )
-        self._esp32_c3_arduino_default = vol.default_factory(
-            _get_priority_default(esp32_c3_arduino, esp32_c3, esp32_arduino, esp32)
-        )
-        self._esp32_c3_idf_default = vol.default_factory(
-            _get_priority_default(esp32_c3_idf, esp32_c3, esp32_idf, esp32)
-        )
-        self._esp32_c6_arduino_default = vol.default_factory(
-            _get_priority_default(esp32_c6_arduino, esp32_c6, esp32_arduino, esp32)
-        )
-        self._esp32_c6_idf_default = vol.default_factory(
-            _get_priority_default(esp32_c6_idf, esp32_c6, esp32_idf, esp32)
-        )
-        self._esp32_h2_arduino_default = vol.default_factory(
-            _get_priority_default(esp32_h2_arduino, esp32_h2, esp32_arduino, esp32)
-        )
-        self._esp32_h2_idf_default = vol.default_factory(
-            _get_priority_default(esp32_h2_idf, esp32_h2, esp32_idf, esp32)
-        )
-        self._rp2040_default = vol.default_factory(rp2040)
-        self._bk72xx_default = vol.default_factory(bk72xx)
-        self._rtl87xx_default = vol.default_factory(rtl87xx)
-        self._host_default = vol.default_factory(host)
+
+        self._defaults = {}
+
+        for platform_key, value in kwargs.items():
+            self._defaults[platform_key] = vol.default_factory(value)
 
     @property
     def default(self):
-        if CORE.is_esp8266:
-            return self._esp8266_default
+        keys = []
         if CORE.is_esp32:
             from esphome.components.esp32 import get_esp32_variant
-            from esphome.components.esp32.const import (
-                VARIANT_ESP32C3,
-                VARIANT_ESP32C6,
-                VARIANT_ESP32H2,
-                VARIANT_ESP32S2,
-                VARIANT_ESP32S3,
-            )
-
-            variant = get_esp32_variant()
-            if variant == VARIANT_ESP32S2:
-                if CORE.using_arduino:
-                    return self._esp32_s2_arduino_default
-                if CORE.using_esp_idf:
-                    return self._esp32_s2_idf_default
-            elif variant == VARIANT_ESP32S3:
-                if CORE.using_arduino:
-                    return self._esp32_s3_arduino_default
-                if CORE.using_esp_idf:
-                    return self._esp32_s3_idf_default
-            elif variant == VARIANT_ESP32C3:
-                if CORE.using_arduino:
-                    return self._esp32_c3_arduino_default
-                if CORE.using_esp_idf:
-                    return self._esp32_c3_idf_default
-            elif variant == VARIANT_ESP32C6:
-                if CORE.using_arduino:
-                    return self._esp32_c6_arduino_default
-                if CORE.using_esp_idf:
-                    return self._esp32_c6_idf_default
-            elif variant == VARIANT_ESP32H2:
-                if CORE.using_arduino:
-                    return self._esp32_h2_arduino_default
-                if CORE.using_esp_idf:
-                    return self._esp32_h2_idf_default
-            else:
-                if CORE.using_arduino:
-                    return self._esp32_arduino_default
-                if CORE.using_esp_idf:
-                    return self._esp32_idf_default
-        if CORE.is_rp2040:
-            return self._rp2040_default
-        if CORE.is_bk72xx:
-            return self._bk72xx_default
-        if CORE.is_rtl87xx:
-            return self._rtl87xx_default
-        if CORE.is_host:
-            return self._host_default
-        raise NotImplementedError
+            from esphome.components.esp32.const import VARIANT_ESP32
+
+            variant = get_esp32_variant().replace(VARIANT_ESP32, "").lower()
+            framework = CORE.target_framework.replace("esp-", "")
+            if variant:
+                keys += _get_default_key(variant, framework)
+                keys += _get_default_key(variant)
+            keys += _get_default_key(framework)
+        keys += _get_default_key()
+        for key in keys:
+            if self._defaults.get(key) is not None:
+                return self._defaults[key]
+        return vol.default_factory(vol.UNDEFINED)
 
     @default.setter
     def default(self, value):

esphome/const.py

@@ -1,6 +1,6 @@
 """Constants used by esphome."""
 
-__version__ = "2025.2.2"
+__version__ = "2025.3.0b1"
 
 ALLOWED_NAME_CHARS = "abcdefghijklmnopqrstuvwxyz0123456789-_"
 VALID_SUBSTITUTIONS_CHARACTERS = (
@@ -546,6 +546,9 @@ CONF_OFF_SPEED_CYCLE = "off_speed_cycle"
 CONF_OFFSET = "offset"
 CONF_OFFSET_HEIGHT = "offset_height"
 CONF_OFFSET_WIDTH = "offset_width"
+CONF_OFFSET_X = "offset_x"
+CONF_OFFSET_Y = "offset_y"
+CONF_OFFSET_Z = "offset_z"
 CONF_ON = "on"
 CONF_ON_BLE_ADVERTISE = "on_ble_advertise"
 CONF_ON_BLE_MANUFACTURER_DATA_ADVERTISE = "on_ble_manufacturer_data_advertise"
@@ -927,6 +930,7 @@ CONF_VALUE = "value"
 CONF_VALUE_FONT = "value_font"
 CONF_VARIABLES = "variables"
 CONF_VARIANT = "variant"
+CONF_VARS = "vars"
 CONF_VERSION = "version"
 CONF_VIBRATIONS = "vibrations"
 CONF_VISIBLE = "visible"

esphome/core/config.py

@@ -1,5 +1,4 @@
 import logging
-import multiprocessing
 import os
 from pathlib import Path
 
@@ -94,10 +93,19 @@ def valid_project_name(value: str):
     return value
 
 
+def get_usable_cpu_count() -> int:
+    """Return the number of CPUs that can be used for processes.
+    On Python 3.13+ this is the number of CPUs that can be used for processes.
+    On older Python versions this is the number of CPUs.
+    """
+    return (
+        os.process_cpu_count() if hasattr(os, "process_cpu_count") else os.cpu_count()
+    )
+
+
 if "ESPHOME_DEFAULT_COMPILE_PROCESS_LIMIT" in os.environ:
     _compile_process_limit_default = min(
-        int(os.environ["ESPHOME_DEFAULT_COMPILE_PROCESS_LIMIT"]),
-        multiprocessing.cpu_count(),
+        int(os.environ["ESPHOME_DEFAULT_COMPILE_PROCESS_LIMIT"]), get_usable_cpu_count()
     )
 else:
     _compile_process_limit_default = cv.UNDEFINED
@@ -156,7 +164,7 @@ CONFIG_SCHEMA = cv.All(
             ),
             cv.Optional(
                 CONF_COMPILE_PROCESS_LIMIT, default=_compile_process_limit_default
-            ): cv.int_range(min=1, max=multiprocessing.cpu_count()),
+            ): cv.int_range(min=1, max=get_usable_cpu_count()),
         }
     ),
     validate_hostname,

esphome/core/defines.h

@@ -71,7 +71,7 @@
 #define USE_OTA
 #define USE_OTA_PASSWORD
 #define USE_OTA_STATE_CALLBACK
-#define USE_OTA_VERSION 1
+#define USE_OTA_VERSION 2
 #define USE_OUTPUT
 #define USE_POWER_SUPPLY
 #define USE_QR_CODE

esphome/core/helpers.h

@@ -3,11 +3,11 @@
 #include <cmath>
 #include <cstring>
 #include <functional>
+#include <limits>
 #include <memory>
 #include <string>
 #include <type_traits>
 #include <vector>
-#include <limits>
 
 #include "esphome/core/optional.h"
 
@@ -700,8 +700,10 @@ template<class T> class RAMAllocator {
   }
   template<class U> constexpr RAMAllocator(const RAMAllocator<U> &other) : flags_{other.flags_} {}
 
-  T *allocate(size_t n) {
-    size_t size = n * sizeof(T);
+  T *allocate(size_t n) { return this->allocate(n, sizeof(T)); }
+
+  T *allocate(size_t n, size_t manual_size) {
+    size_t size = n * manual_size;
     T *ptr = nullptr;
 #ifdef USE_ESP32
     if (this->flags_ & Flags::ALLOC_EXTERNAL) {

esphome/core/time.cpp

@@ -197,6 +197,7 @@ void ESPTime::recalc_timestamp_local() {
   tm.tm_hour = this->hour;
   tm.tm_min = this->minute;
   tm.tm_sec = this->second;
+  tm.tm_isdst = -1;
 
   this->timestamp = mktime(&tm);
 }

esphome/cpp_generator.py

@@ -506,9 +506,9 @@ def with_local_variable(id_: ID, rhs: SafeExpType, callback: Callable, *args) ->
     """
 
     # throw if the callback is async:
-    assert not inspect.iscoroutinefunction(
-        callback
-    ), "with_local_variable() callback cannot be async!"
+    assert not inspect.iscoroutinefunction(callback), (
+        "with_local_variable() callback cannot be async!"
+    )
 
     CORE.add(RawStatement("{"))  # output opening curly brace
     obj = variable(id_, rhs, None, True)

esphome/dashboard/core.py

@@ -9,7 +9,7 @@ import json
 import logging
 from pathlib import Path
 import threading
-from typing import TYPE_CHECKING, Any, Callable
+from typing import Any, Callable
 
 from esphome.storage_json import ignored_devices_storage_path
 
@@ -17,15 +17,15 @@ from ..zeroconf import DiscoveredImport
 from .dns import DNSCache
 from .entries import DashboardEntries
 from .settings import DashboardSettings
-
-if TYPE_CHECKING:
-    from .status.mdns import MDNSStatus
-
+from .status.mdns import MDNSStatus
+from .status.ping import PingStatus
 
 _LOGGER = logging.getLogger(__name__)
 
 IGNORED_DEVICES_STORAGE_PATH = "ignored-devices.json"
 
+MDNS_BOOTSTRAP_TIME = 7.5
+
 
 @dataclass
 class Event:
@@ -81,6 +81,7 @@ class ESPHomeDashboard:
         "dns_cache",
         "_background_tasks",
         "ignored_devices",
+        "_ping_status_task",
     )
 
     def __init__(self) -> None:
@@ -97,6 +98,7 @@ class ESPHomeDashboard:
         self.dns_cache = DNSCache()
         self._background_tasks: set[asyncio.Task] = set()
         self.ignored_devices: set[str] = set()
+        self._ping_status_task: asyncio.Task | None = None
 
     async def async_setup(self) -> None:
         """Setup the dashboard."""
@@ -121,41 +123,48 @@ class ESPHomeDashboard:
                 {"ignored_devices": sorted(self.ignored_devices)}, indent=2, fp=f_handle
             )
 
+    def _async_start_ping_status(self, ping_status: PingStatus) -> None:
+        self._ping_status_task = asyncio.create_task(ping_status.async_run())
+
     async def async_run(self) -> None:
         """Run the dashboard."""
         settings = self.settings
         mdns_task: asyncio.Task | None = None
-        ping_status_task: asyncio.Task | None = None
         await self.entries.async_update_entries()
 
-        if settings.status_use_ping:
-            from .status.ping import PingStatus
+        mdns_status = MDNSStatus(self)
+        ping_status = PingStatus(self)
+        start_ping_timer: asyncio.TimerHandle | None = None
 
-            ping_status = PingStatus()
-            ping_status_task = asyncio.create_task(ping_status.async_run())
-        else:
-            from .status.mdns import MDNSStatus
-
-            mdns_status = MDNSStatus()
-            await mdns_status.async_refresh_hosts()
-            self.mdns_status = mdns_status
+        self.mdns_status = mdns_status
+        if mdns_status.async_setup():
             mdns_task = asyncio.create_task(mdns_status.async_run())
+            # Start ping MDNS_BOOTSTRAP_TIME seconds after startup to ensure
+            # MDNS has had a chance to resolve the devices
+            start_ping_timer = self.loop.call_later(
+                MDNS_BOOTSTRAP_TIME, self._async_start_ping_status, ping_status
+            )
+        else:
+            # If mDNS is not available, start the ping status immediately
+            self._async_start_ping_status(ping_status)
 
         if settings.status_use_mqtt:
             from .status.mqtt import MqttStatusThread
 
-            status_thread_mqtt = MqttStatusThread()
+            status_thread_mqtt = MqttStatusThread(self)
             status_thread_mqtt.start()
 
-        shutdown_event = asyncio.Event()
         try:
-            await shutdown_event.wait()
+            await asyncio.Event().wait()
         finally:
             _LOGGER.info("Shutting down...")
             self.stop_event.set()
             self.ping_request.set()
-            if ping_status_task:
-                ping_status_task.cancel()
+            if start_ping_timer:
+                start_ping_timer.cancel()
+            if self._ping_status_task:
+                self._ping_status_task.cancel()
+                self._ping_status_task = None
             if mdns_task:
                 mdns_task.cancel()
             if settings.status_use_mqtt:

esphome/dashboard/dns.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import asyncio
+from contextlib import suppress
+from ipaddress import ip_address
 import sys
 
 from icmplib import NameLookupError, async_resolve
@@ -10,11 +12,15 @@ if sys.version_info >= (3, 11):
 else:
     from async_timeout import timeout as async_timeout
 
+RESOLVE_TIMEOUT = 3.0
+
 
 async def _async_resolve_wrapper(hostname: str) -> list[str] | Exception:
     """Wrap the icmplib async_resolve function."""
+    with suppress(ValueError):
+        return [str(ip_address(hostname))]
     try:
-        async with async_timeout(2):
+        async with async_timeout(RESOLVE_TIMEOUT):
             return await async_resolve(hostname)
     except (asyncio.TimeoutError, NameLookupError, UnicodeError) as ex:
         return ex

esphome/dashboard/entries.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 import asyncio
 from collections import defaultdict
+from dataclasses import dataclass
+from functools import lru_cache
 import logging
 import os
 from typing import TYPE_CHECKING, Any
@@ -27,37 +29,53 @@ _LOGGER = logging.getLogger(__name__)
 
 DashboardCacheKeyType = tuple[int, int, float, int]
 
-# Currently EntryState is a simple
-# online/offline/unknown enum, but in the future
-# it may be expanded to include more states
 
+@dataclass(frozen=True)
+class EntryState:
+    """Represents the state of an entry."""
 
-class EntryState(StrEnum):
+    reachable: ReachableState
+    source: EntryStateSource
+
+
+class EntryStateSource(StrEnum):
+    MDNS = "mdns"
+    PING = "ping"
+    MQTT = "mqtt"
+    UNKNOWN = "unknown"
+
+
+class ReachableState(StrEnum):
     ONLINE = "online"
     OFFLINE = "offline"
+    DNS_FAILURE = "dns_failure"
     UNKNOWN = "unknown"
 
 
-_BOOL_TO_ENTRY_STATE = {
-    True: EntryState.ONLINE,
-    False: EntryState.OFFLINE,
-    None: EntryState.UNKNOWN,
+_BOOL_TO_REACHABLE_STATE = {
+    True: ReachableState.ONLINE,
+    False: ReachableState.OFFLINE,
+    None: ReachableState.UNKNOWN,
 }
-_ENTRY_STATE_TO_BOOL = {
-    EntryState.ONLINE: True,
-    EntryState.OFFLINE: False,
-    EntryState.UNKNOWN: None,
+_REACHABLE_STATE_TO_BOOL = {
+    ReachableState.ONLINE: True,
+    ReachableState.OFFLINE: False,
+    ReachableState.DNS_FAILURE: False,
+    ReachableState.UNKNOWN: None,
 }
 
+UNKNOWN_STATE = EntryState(ReachableState.UNKNOWN, EntryStateSource.UNKNOWN)
 
-def bool_to_entry_state(value: bool) -> EntryState:
+
+@lru_cache  # creating frozen dataclass instances is expensive, so we cache them
+def bool_to_entry_state(value: bool | None, source: EntryStateSource) -> EntryState:
     """Convert a bool to an entry state."""
-    return _BOOL_TO_ENTRY_STATE[value]
+    return EntryState(_BOOL_TO_REACHABLE_STATE[value], source)
 
 
 def entry_state_to_bool(value: EntryState) -> bool | None:
     """Convert an entry state to a bool."""
-    return _ENTRY_STATE_TO_BOOL[value]
+    return _REACHABLE_STATE_TO_BOOL[value.reachable]
 
 
 class DashboardEntries:
@@ -119,6 +137,55 @@ class DashboardEntries:
         """Set the state for an entry."""
         self.async_set_state(entry, state)
 
+    def set_state_if_online_or_source(
+        self, entry: DashboardEntry, state: EntryState
+    ) -> None:
+        """Set the state for an entry if its online or provided by the source or unknown."""
+        asyncio.run_coroutine_threadsafe(
+            self._async_set_state_if_online_or_source(entry, state), self._loop
+        ).result()
+
+    async def _async_set_state_if_online_or_source(
+        self, entry: DashboardEntry, state: EntryState
+    ) -> None:
+        """Set the state for an entry if its online or provided by the source or unknown."""
+        self.async_set_state_if_online_or_source(entry, state)
+
+    def async_set_state_if_online_or_source(
+        self, entry: DashboardEntry, state: EntryState
+    ) -> None:
+        """Set the state for an entry if its online or provided by the source or unknown."""
+        if (
+            state.reachable is ReachableState.ONLINE
+            and entry.state.reachable is not ReachableState.ONLINE
+        ) or entry.state.source in (
+            EntryStateSource.UNKNOWN,
+            state.source,
+        ):
+            self.async_set_state(entry, state)
+
+    def set_state_if_source(self, entry: DashboardEntry, state: EntryState) -> None:
+        """Set the state for an entry if provided by the source or unknown."""
+        asyncio.run_coroutine_threadsafe(
+            self._async_set_state_if_source(entry, state), self._loop
+        ).result()
+
+    async def _async_set_state_if_source(
+        self, entry: DashboardEntry, state: EntryState
+    ) -> None:
+        """Set the state for an entry if rovided by the source or unknown."""
+        self.async_set_state_if_source(entry, state)
+
+    def async_set_state_if_source(
+        self, entry: DashboardEntry, state: EntryState
+    ) -> None:
+        """Set the state for an entry if provided by the source or unknown."""
+        if entry.state.source in (
+            EntryStateSource.UNKNOWN,
+            state.source,
+        ):
+            self.async_set_state(entry, state)
+
     def async_set_state(self, entry: DashboardEntry, state: EntryState) -> None:
         """Set the state for an entry."""
         if entry.state == state:
@@ -269,7 +336,7 @@ class DashboardEntry:
         self._storage_path = ext_storage_path(self.filename)
         self.cache_key = cache_key
         self.storage: StorageJSON | None = None
-        self.state = EntryState.UNKNOWN
+        self.state = UNKNOWN_STATE
         self._to_dict: dict[str, Any] | None = None
 
     def __repr__(self) -> str: