esphome 2025.8.3__py3-none-any.whl → 2025.9.0b1__py3-none-any.whl

esphome/core/scheduler.h

@@ -88,19 +88,22 @@ class Scheduler {
   struct SchedulerItem {
     // Ordered by size to minimize padding
     Component *component;
-    uint32_t interval;
-    // 64-bit time to handle millis() rollover. The scheduler combines the 32-bit millis()
-    // with a 16-bit rollover counter to create a 64-bit time that won't roll over for
-    // billions of years. This ensures correct scheduling even when devices run for months.
-    uint64_t next_execution_;
-
     // Optimized name storage using tagged union
     union {
       const char *static_name;  // For string literals (no allocation)
       char *dynamic_name;       // For allocated strings
     } name_;
-
+    uint32_t interval;
+    // Split time to handle millis() rollover. The scheduler combines the 32-bit millis()
+    // with a 16-bit rollover counter to create a 48-bit time space (using 32+16 bits).
+    // This is intentionally limited to 48 bits, not stored as a full 64-bit value.
+    // With 49.7 days per 32-bit rollover, the 16-bit counter supports
+    // 49.7 days × 65536 = ~8900 years. This ensures correct scheduling
+    // even when devices run for months. Split into two fields for better memory
+    // alignment on 32-bit systems.
+    uint32_t next_execution_low_;  // Lower 32 bits of execution time (millis value)
     std::function<void()> callback;
+    uint16_t next_execution_high_;  // Upper 16 bits (millis_major counter)
 
 #ifdef ESPHOME_THREAD_MULTI_ATOMICS
     // Multi-threaded with atomics: use atomic for lock-free access
@@ -126,7 +129,8 @@ class Scheduler {
     SchedulerItem()
         : component(nullptr),
           interval(0),
-          next_execution_(0),
+          next_execution_low_(0),
+          next_execution_high_(0),
 #ifdef ESPHOME_THREAD_MULTI_ATOMICS
           // remove is initialized in the member declaration as std::atomic<bool>{false}
           type(TIMEOUT),
@@ -142,11 +146,7 @@ class Scheduler {
     }
 
     // Destructor to clean up dynamic names
-    ~SchedulerItem() {
-      if (name_is_dynamic) {
-        delete[] name_.dynamic_name;
-      }
-    }
+    ~SchedulerItem() { clear_dynamic_name(); }
 
     // Delete copy operations to prevent accidental copies
     SchedulerItem(const SchedulerItem &) = delete;
@@ -159,13 +159,19 @@ class Scheduler {
     // Helper to get the name regardless of storage type
     const char *get_name() const { return name_is_dynamic ? name_.dynamic_name : name_.static_name; }
 
-    // Helper to set name with proper ownership
-    void set_name(const char *name, bool make_copy = false) {
-      // Clean up old dynamic name if any
+    // Helper to clear dynamic name if allocated
+    void clear_dynamic_name() {
       if (name_is_dynamic && name_.dynamic_name) {
         delete[] name_.dynamic_name;
+        name_.dynamic_name = nullptr;
         name_is_dynamic = false;
       }
+    }
+
+    // Helper to set name with proper ownership
+    void set_name(const char *name, bool make_copy = false) {
+      // Clean up old dynamic name if any
+      clear_dynamic_name();
 
       if (!name) {
         // nullptr case - no name provided
@@ -183,8 +189,22 @@ class Scheduler {
     }
 
     static bool cmp(const std::unique_ptr<SchedulerItem> &a, const std::unique_ptr<SchedulerItem> &b);
-    const char *get_type_str() const { return (type == TIMEOUT) ? "timeout" : "interval"; }
-    const char *get_source() const { return component ? component->get_component_source() : "unknown"; }
+
+    // Note: We use 48 bits total (32 + 16), stored in a 64-bit value for API compatibility.
+    // The upper 16 bits of the 64-bit value are always zero, which is fine since
+    // millis_major_ is also 16 bits and they must match.
+    constexpr uint64_t get_next_execution() const {
+      return (static_cast<uint64_t>(next_execution_high_) << 32) | next_execution_low_;
+    }
+
+    constexpr void set_next_execution(uint64_t value) {
+      next_execution_low_ = static_cast<uint32_t>(value);
+      // Cast to uint16_t intentionally truncates to lower 16 bits of the upper 32 bits.
+      // This is correct because millis_major_ that creates these values is also 16 bits.
+      next_execution_high_ = static_cast<uint16_t>(value >> 32);
+    }
+    constexpr const char *get_type_str() const { return (type == TIMEOUT) ? "timeout" : "interval"; }
+    const LogString *get_source() const { return component ? component->get_component_log_str() : LOG_STR("unknown"); }
   };
 
   // Common implementation for both timeout and interval
@@ -214,6 +234,15 @@ class Scheduler {
   // Common implementation for cancel operations
   bool cancel_item_(Component *component, bool is_static_string, const void *name_ptr, SchedulerItem::Type type);
 
+  // Helper to check if two scheduler item names match
+  inline bool HOT names_match_(const char *name1, const char *name2) const {
+    // Check pointer equality first (common for static strings), then string contents
+    // The core ESPHome codebase uses static strings (const char*) for component names,
+    // making pointer comparison effective. The std::string overloads exist only for
+    // compatibility with external components but are rarely used in practice.
+    return (name1 != nullptr && name2 != nullptr) && ((name1 == name2) || (strcmp(name1, name2) == 0));
+  }
+
   // Helper function to check if item matches criteria for cancellation
   inline bool HOT matches_item_(const std::unique_ptr<SchedulerItem> &item, Component *component, const char *name_cstr,
                                 SchedulerItem::Type type, bool match_retry, bool skip_removed = true) const {
@@ -221,29 +250,20 @@ class Scheduler {
         (match_retry && !item->is_retry)) {
       return false;
     }
-    const char *item_name = item->get_name();
-    if (item_name == nullptr) {
-      return false;
-    }
-    // Fast path: if pointers are equal
-    // This is effective because the core ESPHome codebase uses static strings (const char*)
-    // for component names. The std::string overloads exist only for compatibility with
-    // external components, but are rarely used in practice.
-    if (item_name == name_cstr) {
-      return true;
-    }
-    // Slow path: compare string contents
-    return strcmp(name_cstr, item_name) == 0;
+    return this->names_match_(item->get_name(), name_cstr);
   }
 
   // Helper to execute a scheduler item
   void execute_item_(SchedulerItem *item, uint32_t now);
 
   // Helper to check if item should be skipped
-  bool should_skip_item_(const SchedulerItem *item) const {
-    return item->remove || (item->component != nullptr && item->component->is_failed());
+  bool should_skip_item_(SchedulerItem *item) const {
+    return is_item_removed_(item) || (item->component != nullptr && item->component->is_failed());
   }
 
+  // Helper to recycle a SchedulerItem
+  void recycle_item_(std::unique_ptr<SchedulerItem> item);
+
   // Helper to check if item is marked for removal (platform-specific)
   // Returns true if item should be skipped, handles platform-specific synchronization
   // For ESPHOME_THREAD_MULTI_NO_ATOMICS platforms, the caller must hold the scheduler lock before calling this
@@ -280,8 +300,9 @@ class Scheduler {
   bool has_cancelled_timeout_in_container_(const Container &container, Component *component, const char *name_cstr,
                                            bool match_retry) const {
     for (const auto &item : container) {
-      if (item->remove && this->matches_item_(item, component, name_cstr, SchedulerItem::TIMEOUT, match_retry,
-                                              /* skip_removed= */ false)) {
+      if (is_item_removed_(item.get()) &&
+          this->matches_item_(item, component, name_cstr, SchedulerItem::TIMEOUT, match_retry,
+                              /* skip_removed= */ false)) {
         return true;
       }
     }
@@ -297,6 +318,16 @@ class Scheduler {
 #endif                                                      /* ESPHOME_THREAD_SINGLE */
   uint32_t to_remove_{0};
 
+  // Memory pool for recycling SchedulerItem objects to reduce heap churn.
+  // Design decisions:
+  // - std::vector is used instead of a fixed array because many systems only need 1-2 scheduler items
+  // - The vector grows dynamically up to MAX_POOL_SIZE (5) only when needed, saving memory on simple setups
+  // - Pool size of 5 matches typical usage (2-4 timers) while keeping memory overhead low (~250 bytes on ESP32)
+  // - The pool significantly reduces heap fragmentation which is critical because heap allocation/deallocation
+  //   can stall the entire system, causing timing issues and dropped events for any components that need
+  //   to synchronize between tasks (see https://github.com/esphome/backlog/issues/52)
+  std::vector<std::unique_ptr<SchedulerItem>> scheduler_item_pool_;
+
 #ifdef ESPHOME_THREAD_MULTI_ATOMICS
   /*
    * Multi-threaded platforms with atomic support: last_millis_ needs atomic for lock-free updates

esphome/core/time.cpp

@@ -203,27 +203,13 @@ void ESPTime::recalc_timestamp_local() {
 }
 
 int32_t ESPTime::timezone_offset() {
-  int32_t offset = 0;
   time_t now = ::time(nullptr);
-  auto local = ESPTime::from_epoch_local(now);
-  auto utc = ESPTime::from_epoch_utc(now);
-  bool negative = utc.hour > local.hour && local.day_of_year <= utc.day_of_year;
-
-  if (utc.minute > local.minute) {
-    local.minute += 60;
-    local.hour -= 1;
-  }
-  offset += (local.minute - utc.minute) * 60;
-
-  if (negative) {
-    offset -= (utc.hour - local.hour) * 3600;
-  } else {
-    if (utc.hour > local.hour) {
-      local.hour += 24;
-    }
-    offset += (local.hour - utc.hour) * 3600;
-  }
-  return offset;
+  struct tm local_tm = *::localtime(&now);
+  local_tm.tm_isdst = 0;  // Cause mktime to ignore daylight saving time because we want to include it in the offset.
+  time_t local_time = mktime(&local_tm);
+  struct tm utc_tm = *::gmtime(&now);
+  time_t utc_time = mktime(&utc_tm);
+  return static_cast<int32_t>(local_time - utc_time);
 }
 
 bool ESPTime::operator<(const ESPTime &other) const { return this->timestamp < other.timestamp; }

esphome/coroutine.py

@@ -42,7 +42,10 @@ Here everything is combined in `yield` expressions. You await other coroutines u
 the last `yield` expression defines what is returned.
 """
 
+from __future__ import annotations
+
 from collections.abc import Awaitable, Callable, Generator, Iterator
+import enum
 import functools
 import heapq
 import inspect
@@ -53,6 +56,79 @@ from typing import Any
 _LOGGER = logging.getLogger(__name__)
 
 
+class CoroPriority(enum.IntEnum):
+    """Execution priority stages for ESPHome code generation.
+
+    Higher values run first. These stages ensure proper dependency
+    resolution during code generation.
+    """
+
+    # Platform initialization - must run first
+    # Examples: esp32, esp8266, rp2040
+    PLATFORM = 1000
+
+    # Network infrastructure setup
+    # Examples: network (201)
+    NETWORK = 201
+
+    # Network transport layer
+    # Examples: async_tcp (200)
+    NETWORK_TRANSPORT = 200
+
+    # Core system components
+    # Examples: esphome core, most entity base components (cover, update, datetime,
+    # valve, alarm_control_panel, lock, event, binary_sensor, button, climate, fan,
+    # light, media_player, number, select, sensor, switch, text_sensor, text),
+    # microphone, speaker, audio_dac, touchscreen, stepper
+    CORE = 100
+
+    # Diagnostic and debugging systems
+    # Examples: logger (90)
+    DIAGNOSTICS = 90
+
+    # Status and monitoring systems
+    # Examples: status_led (80)
+    STATUS = 80
+
+    # Communication protocols and services
+    # Examples: web_server_base (65), captive_portal (64), wifi (60), ethernet (60),
+    # mdns (55), ota_updates (54), web_server_ota (52)
+    COMMUNICATION = 60
+
+    # Application-level services
+    # Examples: safe_mode (50)
+    APPLICATION = 50
+
+    # Web and UI services
+    # Examples: web_server (40)
+    WEB = 40
+
+    # Automations and user logic
+    # Examples: esphome core automations (30)
+    AUTOMATION = 30
+
+    # Bus and peripheral setup
+    # Examples: i2c (1)
+    BUS = 1
+
+    # Standard component priority (default)
+    # Components without explicit priority run at 0
+    COMPONENT = 0
+
+    # Components that need others to be registered first
+    # Examples: globals (-100)
+    LATE = -100
+
+    # Platform-specific workarounds and fixes
+    # Examples: add_arduino_global_workaround (-999), esp8266 pin states (-999)
+    WORKAROUNDS = -999
+
+    # Final setup that requires all components to be registered
+    # Examples: add_includes, _add_platformio_options, _add_platform_defines (all -1000),
+    # esp32_ble_tracker feature defines (-1000)
+    FINAL = -1000
+
+
 def coroutine(func: Callable[..., Any]) -> Callable[..., Awaitable[Any]]:
     """Decorator to apply to methods to convert them to ESPHome coroutines."""
     if getattr(func, "_esphome_coroutine", False):
@@ -95,15 +171,16 @@ def coroutine(func: Callable[..., Any]) -> Callable[..., Awaitable[Any]]:
     return coro
 
 
-def coroutine_with_priority(priority: float):
+def coroutine_with_priority(priority: float | CoroPriority):
     """Decorator to apply to functions to convert them to ESPHome coroutines.
 
     :param priority: priority with which to schedule the coroutine, higher priorities run first.
+                     Can be a float or a CoroPriority enum value.
     """
 
     def decorator(func):
         coro = coroutine(func)
-        coro.priority = priority
+        coro.priority = float(priority)
         return coro
 
     return decorator
@@ -173,7 +250,7 @@ class _Task:
         self.iterator = iterator
         self.original_function = original_function
 
-    def with_priority(self, priority: float) -> "_Task":
+    def with_priority(self, priority: float) -> _Task:
         return _Task(priority, self.id_number, self.iterator, self.original_function)
 
     @property

esphome/cpp_generator.py

@@ -253,6 +253,19 @@ class StringLiteral(Literal):
         return cpp_string_escape(self.string)
 
 
+class LogStringLiteral(Literal):
+    """A string literal that uses LOG_STR() macro for flash storage on ESP8266."""
+
+    __slots__ = ("string",)
+
+    def __init__(self, string: str) -> None:
+        super().__init__()
+        self.string = string
+
+    def __str__(self) -> str:
+        return f"LOG_STR({cpp_string_escape(self.string)})"
+
+
 class IntLiteral(Literal):
     __slots__ = ("i",)
 

esphome/cpp_helpers.py

@@ -9,7 +9,7 @@ from esphome.const import (
 )
 from esphome.core import CORE, ID, coroutine
 from esphome.coroutine import FakeAwaitable
-from esphome.cpp_generator import add, get_variable
+from esphome.cpp_generator import LogStringLiteral, add, get_variable
 from esphome.cpp_types import App
 from esphome.types import ConfigFragmentType, ConfigType
 from esphome.util import Registry, RegistryEntry
@@ -76,7 +76,7 @@ async def register_component(var, config):
             "Error while finding name of component, please report this", exc_info=e
         )
     if name is not None:
-        add(var.set_component_source(name))
+        add(var.set_component_source(LogStringLiteral(name)))
 
     add(App.register_component(var))
     return var

esphome/dashboard/web_server.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import base64
+import binascii
 from collections.abc import Callable, Iterable
 import datetime
 import functools
@@ -490,7 +491,17 @@ class WizardRequestHandler(BaseHandler):
         kwargs = {
             k: v
             for k, v in json.loads(self.request.body.decode()).items()
-            if k in ("name", "platform", "board", "ssid", "psk", "password")
+            if k
+            in (
+                "type",
+                "name",
+                "platform",
+                "board",
+                "ssid",
+                "psk",
+                "password",
+                "file_content",
+            )
         }
         if not kwargs["name"]:
             self.set_status(422)
@@ -498,19 +509,65 @@ class WizardRequestHandler(BaseHandler):
             self.write(json.dumps({"error": "Name is required"}))
             return
 
+        if "type" not in kwargs:
+            # Default to basic wizard type for backwards compatibility
+            kwargs["type"] = "basic"
+
         kwargs["friendly_name"] = kwargs["name"]
         kwargs["name"] = friendly_name_slugify(kwargs["friendly_name"])
-
-        kwargs["ota_password"] = secrets.token_hex(16)
-        noise_psk = secrets.token_bytes(32)
-        kwargs["api_encryption_key"] = base64.b64encode(noise_psk).decode()
+        if kwargs["type"] == "basic":
+            kwargs["ota_password"] = secrets.token_hex(16)
+            noise_psk = secrets.token_bytes(32)
+            kwargs["api_encryption_key"] = base64.b64encode(noise_psk).decode()
+        elif kwargs["type"] == "upload":
+            try:
+                kwargs["file_text"] = base64.b64decode(kwargs["file_content"]).decode(
+                    "utf-8"
+                )
+            except (binascii.Error, UnicodeDecodeError):
+                self.set_status(422)
+                self.set_header("content-type", "application/json")
+                self.write(
+                    json.dumps({"error": "The uploaded file is not correctly encoded."})
+                )
+                return
+        elif kwargs["type"] != "empty":
+            self.set_status(422)
+            self.set_header("content-type", "application/json")
+            self.write(
+                json.dumps(
+                    {"error": f"Invalid wizard type specified: {kwargs['type']}"}
+                )
+            )
+            return
         filename = f"{kwargs['name']}.yaml"
         destination = settings.rel_path(filename)
-        wizard.wizard_write(path=destination, **kwargs)
-        self.set_status(200)
-        self.set_header("content-type", "application/json")
-        self.write(json.dumps({"configuration": filename}))
-        self.finish()
+
+        # Check if destination file already exists
+        if os.path.exists(destination):
+            self.set_status(409)  # Conflict status code
+            self.set_header("content-type", "application/json")
+            self.write(
+                json.dumps({"error": f"Configuration file '{filename}' already exists"})
+            )
+            self.finish()
+            return
+
+        success = wizard.wizard_write(path=destination, **kwargs)
+        if success:
+            self.set_status(200)
+            self.set_header("content-type", "application/json")
+            self.write(json.dumps({"configuration": filename}))
+            self.finish()
+        else:
+            self.set_status(500)
+            self.set_header("content-type", "application/json")
+            self.write(
+                json.dumps(
+                    {"error": "Failed to write configuration, see logs for details"}
+                )
+            )
+            self.finish()
 
 
 class ImportRequestHandler(BaseHandler):

esphome/espota2.py

@@ -308,8 +308,12 @@ def perform_ota(
     time.sleep(1)
 
 
-def run_ota_impl_(remote_host, remote_port, password, filename):
+def run_ota_impl_(
+    remote_host: str | list[str], remote_port: int, password: str, filename: str
+) -> tuple[int, str | None]:
+    # Handle both single host and list of hosts
     try:
+        # Resolve all hosts at once for parallel DNS resolution
         res = resolve_ip_address(remote_host, remote_port)
     except EsphomeError as err:
         _LOGGER.error(
@@ -340,19 +344,22 @@ def run_ota_impl_(remote_host, remote_port, password, filename):
                 perform_ota(sock, password, file_handle, filename)
             except OTAError as err:
                 _LOGGER.error(str(err))
-                return 1
+                return 1, None
             finally:
                 sock.close()
 
-        return 0
+        # Successfully uploaded to sa[0]
+        return 0, sa[0]
 
     _LOGGER.error("Connection failed.")
-    return 1
+    return 1, None
 
 
-def run_ota(remote_host, remote_port, password, filename):
+def run_ota(
+    remote_host: str | list[str], remote_port: int, password: str, filename: str
+) -> tuple[int, str | None]:
     try:
         return run_ota_impl_(remote_host, remote_port, password, filename)
     except OTAError as err:
         _LOGGER.error(err)
-        return 1
+        return 1, None