[scheduler] Make core timer ID collisions impossible with type-safe internal IDs

Previously, PollingComponent used the string "update" and DelayAction used "delay" as scheduler names. If a component subclassing PollingComponent or using DelayAction also happened to use these same strings for its own timers, the core timer would be silently cancelled — a subtle bug that would be extremely hard to track down. This introduces InternalSchedulerID, a type-safe wrapper that routes through a new NUMERIC_ID_INTERNAL NameType. Since the scheduler matches by (component, name_type, id, type), internal IDs can never collide with component-level NUMERIC_ID or string-based names, even if the underlying uint32_t values overlap. Also migrates binary_sensor filters, MultiClickTrigger, and sensor filters from string-based to uint32_t scheduler IDs. Each filter is its own Component instance so IDs are scoped per-instance with no collision risk.
2026-02-19 07:55:35 -07:00 · 2026-02-09 05:50:41 -06:00
parent fb93283720
commit ed3acd582e
8 changed files with 132 additions and 40 deletions
--- a/esphome/components/binary_sensor/automation.cpp
+++ b/esphome/components/binary_sensor/automation.cpp
@@ -5,6 +5,14 @@ namespace esphome::binary_sensor {

 static const char *const TAG = "binary_sensor.automation";

+// MultiClickTrigger timeout IDs.
+// MultiClickTrigger is its own Component instance, so the scheduler scopes
+// IDs by component pointer — no risk of collisions between instances.
+constexpr uint32_t MULTICLICK_TRIGGER_ID = 0;
+constexpr uint32_t MULTICLICK_COOLDOWN_ID = 1;
+constexpr uint32_t MULTICLICK_IS_VALID_ID = 2;
+constexpr uint32_t MULTICLICK_IS_NOT_VALID_ID = 3;
+
 void MultiClickTrigger::on_state_(bool state) {
  // Handle duplicate events
  if (state == this->last_state_) {
@@ -27,7 +35,7 @@ void MultiClickTrigger::on_state_(bool state) {
               evt.min_length, evt.max_length);
      this->at_index_ = 1;
      if (this->timing_.size() == 1 && evt.max_length == 4294967294UL) {
-        this->set_timeout("trigger", evt.min_length, [this]() { this->trigger_(); });
+        this->set_timeout(MULTICLICK_TRIGGER_ID, evt.min_length, [this]() { this->trigger_(); });
      } else {
        this->schedule_is_valid_(evt.min_length);
        this->schedule_is_not_valid_(evt.max_length);
@@ -57,13 +65,13 @@ void MultiClickTrigger::on_state_(bool state) {
    this->schedule_is_not_valid_(evt.max_length);
  } else if (*this->at_index_ + 1 != this->timing_.size()) {
    ESP_LOGV(TAG, "B i=%zu min=%" PRIu32, *this->at_index_, evt.min_length);  // NOLINT
-    this->cancel_timeout("is_not_valid");
+    this->cancel_timeout(MULTICLICK_IS_NOT_VALID_ID);
    this->schedule_is_valid_(evt.min_length);
  } else {
    ESP_LOGV(TAG, "C i=%zu min=%" PRIu32, *this->at_index_, evt.min_length);  // NOLINT
    this->is_valid_ = false;
-    this->cancel_timeout("is_not_valid");
-    this->set_timeout("trigger", evt.min_length, [this]() { this->trigger_(); });
+    this->cancel_timeout(MULTICLICK_IS_NOT_VALID_ID);
+    this->set_timeout(MULTICLICK_TRIGGER_ID, evt.min_length, [this]() { this->trigger_(); });
  }

  *this->at_index_ = *this->at_index_ + 1;
@@ -71,14 +79,14 @@ void MultiClickTrigger::on_state_(bool state) {
 void MultiClickTrigger::schedule_cooldown_() {
  ESP_LOGV(TAG, "Multi Click: Invalid length of press, starting cooldown of %" PRIu32 " ms", this->invalid_cooldown_);
  this->is_in_cooldown_ = true;
-  this->set_timeout("cooldown", this->invalid_cooldown_, [this]() {
+  this->set_timeout(MULTICLICK_COOLDOWN_ID, this->invalid_cooldown_, [this]() {
    ESP_LOGV(TAG, "Multi Click: Cooldown ended, matching is now enabled again.");
    this->is_in_cooldown_ = false;
  });
  this->at_index_.reset();
-  this->cancel_timeout("trigger");
-  this->cancel_timeout("is_valid");
-  this->cancel_timeout("is_not_valid");
+  this->cancel_timeout(MULTICLICK_TRIGGER_ID);
+  this->cancel_timeout(MULTICLICK_IS_VALID_ID);
+  this->cancel_timeout(MULTICLICK_IS_NOT_VALID_ID);
 }
 void MultiClickTrigger::schedule_is_valid_(uint32_t min_length) {
  if (min_length == 0) {
@@ -86,13 +94,13 @@ void MultiClickTrigger::schedule_is_valid_(uint32_t min_length) {
    return;
  }
  this->is_valid_ = false;
-  this->set_timeout("is_valid", min_length, [this]() {
+  this->set_timeout(MULTICLICK_IS_VALID_ID, min_length, [this]() {
    ESP_LOGV(TAG, "Multi Click: You can now %s the button.", this->parent_->state ? "RELEASE" : "PRESS");
    this->is_valid_ = true;
  });
 }
 void MultiClickTrigger::schedule_is_not_valid_(uint32_t max_length) {
-  this->set_timeout("is_not_valid", max_length, [this]() {
+  this->set_timeout(MULTICLICK_IS_NOT_VALID_ID, max_length, [this]() {
    ESP_LOGV(TAG, "Multi Click: You waited too long to %s.", this->parent_->state ? "RELEASE" : "PRESS");
    this->is_valid_ = false;
    this->schedule_cooldown_();
@@ -106,9 +114,9 @@ void MultiClickTrigger::cancel() {
 void MultiClickTrigger::trigger_() {
  ESP_LOGV(TAG, "Multi Click: Hooray, multi click is valid. Triggering!");
  this->at_index_.reset();
-  this->cancel_timeout("trigger");
-  this->cancel_timeout("is_valid");
-  this->cancel_timeout("is_not_valid");
+  this->cancel_timeout(MULTICLICK_TRIGGER_ID);
+  this->cancel_timeout(MULTICLICK_IS_VALID_ID);
+  this->cancel_timeout(MULTICLICK_IS_NOT_VALID_ID);
  this->trigger();
 }

--- a/esphome/components/binary_sensor/filter.cpp
+++ b/esphome/components/binary_sensor/filter.cpp
@@ -6,6 +6,14 @@ namespace esphome::binary_sensor {

 static const char *const TAG = "sensor.filter";

+// Timeout IDs for filter classes.
+// Each filter is its own Component instance, so the scheduler scopes
+// IDs by component pointer — no risk of collisions between instances.
+constexpr uint32_t FILTER_TIMEOUT_ID = 0;
+// AutorepeatFilter needs two distinct IDs (both timeouts on the same component)
+constexpr uint32_t AUTOREPEAT_TIMING_ID = 0;
+constexpr uint32_t AUTOREPEAT_ON_OFF_ID = 1;
+
 void Filter::output(bool value) {
  if (this->next_ == nullptr) {
    this->parent_->send_state_internal(value);
@@ -23,16 +31,16 @@ void Filter::input(bool value) {
 }

 void TimeoutFilter::input(bool value) {
-  this->set_timeout("timeout", this->timeout_delay_.value(), [this]() { this->parent_->invalidate_state(); });
+  this->set_timeout(FILTER_TIMEOUT_ID, this->timeout_delay_.value(), [this]() { this->parent_->invalidate_state(); });
  // we do not de-dup here otherwise changes from invalid to valid state will not be output
  this->output(value);
 }

 optional<bool> DelayedOnOffFilter::new_value(bool value) {
  if (value) {
-    this->set_timeout("ON_OFF", this->on_delay_.value(), [this]() { this->output(true); });
+    this->set_timeout(FILTER_TIMEOUT_ID, this->on_delay_.value(), [this]() { this->output(true); });
  } else {
-    this->set_timeout("ON_OFF", this->off_delay_.value(), [this]() { this->output(false); });
+    this->set_timeout(FILTER_TIMEOUT_ID, this->off_delay_.value(), [this]() { this->output(false); });
  }
  return {};
 }
@@ -41,10 +49,10 @@ float DelayedOnOffFilter::get_setup_priority() const { return setup_priority::HA

 optional<bool> DelayedOnFilter::new_value(bool value) {
  if (value) {
-    this->set_timeout("ON", this->delay_.value(), [this]() { this->output(true); });
+    this->set_timeout(FILTER_TIMEOUT_ID, this->delay_.value(), [this]() { this->output(true); });
    return {};
  } else {
-    this->cancel_timeout("ON");
+    this->cancel_timeout(FILTER_TIMEOUT_ID);
    return false;
  }
 }
@@ -53,10 +61,10 @@ float DelayedOnFilter::get_setup_priority() const { return setup_priority::HARDW

 optional<bool> DelayedOffFilter::new_value(bool value) {
  if (!value) {
-    this->set_timeout("OFF", this->delay_.value(), [this]() { this->output(false); });
+    this->set_timeout(FILTER_TIMEOUT_ID, this->delay_.value(), [this]() { this->output(false); });
    return {};
  } else {
-    this->cancel_timeout("OFF");
+    this->cancel_timeout(FILTER_TIMEOUT_ID);
    return true;
  }
 }
@@ -76,8 +84,8 @@ optional<bool> AutorepeatFilter::new_value(bool value) {
    this->next_timing_();
    return true;
  } else {
-    this->cancel_timeout("TIMING");
-    this->cancel_timeout("ON_OFF");
+    this->cancel_timeout(AUTOREPEAT_TIMING_ID);
+    this->cancel_timeout(AUTOREPEAT_ON_OFF_ID);
    this->active_timing_ = 0;
    return false;
  }
@@ -89,7 +97,8 @@ void AutorepeatFilter::next_timing_() {
  // 2nd time: starts waiting the second delay and starts toggling with the first time_off / _on
  // last time: no delay to start but have to bump the index to reflect the last
  if (this->active_timing_ < this->timings_.size())
-    this->set_timeout("TIMING", this->timings_[this->active_timing_].delay, [this]() { this->next_timing_(); });
+    this->set_timeout(AUTOREPEAT_TIMING_ID, this->timings_[this->active_timing_].delay,
+                      [this]() { this->next_timing_(); });

  if (this->active_timing_ <= this->timings_.size()) {
    this->active_timing_++;
@@ -104,7 +113,8 @@ void AutorepeatFilter::next_timing_() {
 void AutorepeatFilter::next_value_(bool val) {
  const AutorepeatFilterTiming &timing = this->timings_[this->active_timing_ - 2];
  this->output(val);  // This is at least the second one so not initial
-  this->set_timeout("ON_OFF", val ? timing.time_on : timing.time_off, [this, val]() { this->next_value_(!val); });
+  this->set_timeout(AUTOREPEAT_ON_OFF_ID, val ? timing.time_on : timing.time_off,
+                    [this, val]() { this->next_value_(!val); });
 }

 float AutorepeatFilter::get_setup_priority() const { return setup_priority::HARDWARE; }
@@ -115,7 +125,7 @@ optional<bool> LambdaFilter::new_value(bool value) { return this->f_(value); }

 optional<bool> SettleFilter::new_value(bool value) {
  if (!this->steady_) {
-    this->set_timeout("SETTLE", this->delay_.value(), [this, value]() {
+    this->set_timeout(FILTER_TIMEOUT_ID, this->delay_.value(), [this, value]() {
      this->steady_ = true;
      this->output(value);
    });
@@ -123,7 +133,7 @@ optional<bool> SettleFilter::new_value(bool value) {
  } else {
    this->steady_ = false;
    this->output(value);
-    this->set_timeout("SETTLE", this->delay_.value(), [this]() { this->steady_ = true; });
+    this->set_timeout(FILTER_TIMEOUT_ID, this->delay_.value(), [this]() { this->steady_ = true; });
    return value;
  }
 }
--- a/esphome/components/sensor/filter.cpp
+++ b/esphome/components/sensor/filter.cpp
@@ -9,6 +9,11 @@ namespace esphome::sensor {

 static const char *const TAG = "sensor.filter";

+// Filter scheduler IDs.
+// Each filter is its own Component instance, so the scheduler scopes
+// IDs by component pointer — no risk of collisions between instances.
+constexpr uint32_t FILTER_ID = 0;
+
 // Filter
 void Filter::input(float value) {
  ESP_LOGVV(TAG, "Filter(%p)::input(%f)", this, value);
@@ -191,7 +196,7 @@ optional<float> ThrottleAverageFilter::new_value(float value) {
  return {};
 }
 void ThrottleAverageFilter::setup() {
-  this->set_interval("throttle_average", this->time_period_, [this]() {
+  this->set_interval(FILTER_ID, this->time_period_, [this]() {
    ESP_LOGVV(TAG, "ThrottleAverageFilter(%p)::interval(sum=%f, n=%i)", this, this->sum_, this->n_);
    if (this->n_ == 0) {
      if (this->have_nan_)
@@ -383,7 +388,7 @@ optional<float> TimeoutFilterConfigured::new_value(float value) {

 // DebounceFilter
 optional<float> DebounceFilter::new_value(float value) {
-  this->set_timeout("debounce", this->time_period_, [this, value]() { this->output(value); });
+  this->set_timeout(FILTER_ID, this->time_period_, [this, value]() { this->output(value); });

  return {};
 }
@@ -406,7 +411,7 @@ optional<float> HeartbeatFilter::new_value(float value) {
 }

 void HeartbeatFilter::setup() {
-  this->set_interval("heartbeat", this->time_period_, [this]() {
+  this->set_interval(FILTER_ID, this->time_period_, [this]() {
    ESP_LOGVV(TAG, "HeartbeatFilter(%p)::interval(has_value=%s, last_input=%f)", this, YESNO(this->has_value_),
              this->last_input_);
    if (!this->has_value_)
--- a/esphome/core/base_automation.h
+++ b/esphome/core/base_automation.h
@@ -191,15 +191,16 @@ template<typename... Ts> class DelayAction : public Action<Ts...>, public Compon
    // instead of std::bind to avoid bind overhead (~16 bytes heap + faster execution)
    if constexpr (sizeof...(Ts) == 0) {
      App.scheduler.set_timer_common_(
-          this, Scheduler::SchedulerItem::TIMEOUT, Scheduler::NameType::STATIC_STRING, "delay", 0, this->delay_.value(),
-          [this]() { this->play_next_(); },
+          this, Scheduler::SchedulerItem::TIMEOUT, Scheduler::NameType::NUMERIC_ID_INTERNAL, nullptr,
+          scheduler_internal_id::DELAY_ACTION.id, this->delay_.value(), [this]() { this->play_next_(); },
          /* is_retry= */ false, /* skip_cancel= */ this->num_running_ > 1);
    } else {
      // For delays with arguments, use std::bind to preserve argument values
      // Arguments must be copied because original references may be invalid after delay
      auto f = std::bind(&DelayAction<Ts...>::play_next_, this, x...);
-      App.scheduler.set_timer_common_(this, Scheduler::SchedulerItem::TIMEOUT, Scheduler::NameType::STATIC_STRING,
-                                      "delay", 0, this->delay_.value(x...), std::move(f),
+      App.scheduler.set_timer_common_(this, Scheduler::SchedulerItem::TIMEOUT, Scheduler::NameType::NUMERIC_ID_INTERNAL,
+                                      nullptr, scheduler_internal_id::DELAY_ACTION.id, this->delay_.value(x...),
+                                      std::move(f),
                                      /* is_retry= */ false, /* skip_cancel= */ this->num_running_ > 1);
    }
  }
@@ -208,7 +209,7 @@ template<typename... Ts> class DelayAction : public Action<Ts...>, public Compon
  void play(const Ts &...x) override { /* ignore - see play_complex */
  }

-  void stop() override { this->cancel_timeout("delay"); }
+  void stop() override { this->cancel_timeout(scheduler_internal_id::DELAY_ACTION); }
 };

 template<typename... Ts> class LambdaAction : public Action<Ts...> {
--- a/esphome/core/component.cpp
+++ b/esphome/core/component.cpp
@@ -195,12 +195,24 @@ void Component::set_timeout(uint32_t id, uint32_t timeout, std::function<void()>

 bool Component::cancel_timeout(uint32_t id) { return App.scheduler.cancel_timeout(this, id); }

+void Component::set_timeout(InternalSchedulerID id, uint32_t timeout, std::function<void()> &&f) {  // NOLINT
+  App.scheduler.set_timeout(this, id, timeout, std::move(f));
+}
+
+bool Component::cancel_timeout(InternalSchedulerID id) { return App.scheduler.cancel_timeout(this, id); }
+
 void Component::set_interval(uint32_t id, uint32_t interval, std::function<void()> &&f) {  // NOLINT
  App.scheduler.set_interval(this, id, interval, std::move(f));
 }

 bool Component::cancel_interval(uint32_t id) { return App.scheduler.cancel_interval(this, id); }

+void Component::set_interval(InternalSchedulerID id, uint32_t interval, std::function<void()> &&f) {  // NOLINT
+  App.scheduler.set_interval(this, id, interval, std::move(f));
+}
+
+bool Component::cancel_interval(InternalSchedulerID id) { return App.scheduler.cancel_interval(this, id); }
+
 void Component::set_retry(uint32_t id, uint32_t initial_wait_time, uint8_t max_attempts,
                          std::function<RetryResult(uint8_t)> &&f, float backoff_increase_factor) {  // NOLINT
  App.scheduler.set_retry(this, id, initial_wait_time, max_attempts, std::move(f), backoff_increase_factor);
@@ -516,12 +528,12 @@ void PollingComponent::call_setup() {

 void PollingComponent::start_poller() {
  // Register interval.
-  this->set_interval("update", this->get_update_interval(), [this]() { this->update(); });
+  this->set_interval(scheduler_internal_id::POLLING_UPDATE, this->get_update_interval(), [this]() { this->update(); });
 }

 void PollingComponent::stop_poller() {
  // Clear the interval to suspend component
-  this->cancel_interval("update");
+  this->cancel_interval(scheduler_internal_id::POLLING_UPDATE);
 }

 uint32_t PollingComponent::get_update_interval() const { return this->update_interval_; }
--- a/esphome/core/component.h
+++ b/esphome/core/component.h
@@ -49,6 +49,21 @@ extern const float LATE;

 static const uint32_t SCHEDULER_DONT_RUN = 4294967295UL;

+/// Type-safe wrapper for internal scheduler IDs used by core base classes.
+/// Uses a separate NameType (NUMERIC_ID_INTERNAL) so IDs can never collide
+/// with component-level NUMERIC_ID values, even if the uint32_t values overlap.
+struct InternalSchedulerID {
+  uint32_t id;
+};
+
+/// Reserved scheduler IDs for core base classes.
+/// These use InternalSchedulerID which routes through NUMERIC_ID_INTERNAL,
+/// a separate matching namespace from the NUMERIC_ID used by components.
+namespace scheduler_internal_id {
+constexpr InternalSchedulerID POLLING_UPDATE{0};  // PollingComponent interval
+constexpr InternalSchedulerID DELAY_ACTION{1};    // DelayAction timeout
+}  // namespace scheduler_internal_id
+
 // Forward declaration
 class PollingComponent;

@@ -334,6 +349,8 @@ class Component {
   */
  void set_interval(uint32_t id, uint32_t interval, std::function<void()> &&f);  // NOLINT

+  void set_interval(InternalSchedulerID id, uint32_t interval, std::function<void()> &&f);  // NOLINT
+
  void set_interval(uint32_t interval, std::function<void()> &&f);  // NOLINT

  /** Cancel an interval function.
@@ -346,6 +363,7 @@ class Component {
  bool cancel_interval(const std::string &name);  // NOLINT
  bool cancel_interval(const char *name);         // NOLINT
  bool cancel_interval(uint32_t id);              // NOLINT
+  bool cancel_interval(InternalSchedulerID id);   // NOLINT

  /** Set an retry function with a unique name. Empty name means no cancelling possible.
   *
@@ -452,6 +470,8 @@ class Component {
   */
  void set_timeout(uint32_t id, uint32_t timeout, std::function<void()> &&f);  // NOLINT

+  void set_timeout(InternalSchedulerID id, uint32_t timeout, std::function<void()> &&f);  // NOLINT
+
  void set_timeout(uint32_t timeout, std::function<void()> &&f);  // NOLINT

  /** Cancel a timeout function.
@@ -464,6 +484,7 @@ class Component {
  bool cancel_timeout(const std::string &name);  // NOLINT
  bool cancel_timeout(const char *name);         // NOLINT
  bool cancel_timeout(uint32_t id);              // NOLINT
+  bool cancel_timeout(InternalSchedulerID id);   // NOLINT

  /** Defer a callback to the next loop() call.
   *
--- a/esphome/core/scheduler.cpp
+++ b/esphome/core/scheduler.cpp
@@ -53,9 +53,12 @@ struct SchedulerNameLog {
    } else if (name_type == NameType::HASHED_STRING) {
      ESPHOME_snprintf_P(buffer, sizeof(buffer), ESPHOME_PSTR("hash:0x%08" PRIX32), hash_or_id);
      return buffer;
-    } else {  // NUMERIC_ID
+    } else if (name_type == NameType::NUMERIC_ID) {
      ESPHOME_snprintf_P(buffer, sizeof(buffer), ESPHOME_PSTR("id:%" PRIu32), hash_or_id);
      return buffer;
+    } else {  // NUMERIC_ID_INTERNAL
+      ESPHOME_snprintf_P(buffer, sizeof(buffer), ESPHOME_PSTR("iid:%" PRIu32), hash_or_id);
+      return buffer;
    }
  }
 };
@@ -137,6 +140,9 @@ void HOT Scheduler::set_timer_common_(Component *component, SchedulerItem::Type
    case NameType::NUMERIC_ID:
      item->set_numeric_id(hash_or_id);
      break;
+    case NameType::NUMERIC_ID_INTERNAL:
+      item->set_internal_id(hash_or_id);
+      break;
  }
  item->type = type;
  item->callback = std::move(func);
@@ -218,6 +224,11 @@ void HOT Scheduler::set_timeout(Component *component, uint32_t id, uint32_t time
  this->set_timer_common_(component, SchedulerItem::TIMEOUT, NameType::NUMERIC_ID, nullptr, id, timeout,
                          std::move(func));
 }
+void HOT Scheduler::set_timeout(Component *component, InternalSchedulerID id, uint32_t timeout,
+                                std::function<void()> func) {
+  this->set_timer_common_(component, SchedulerItem::TIMEOUT, NameType::NUMERIC_ID_INTERNAL, nullptr, id.id, timeout,
+                          std::move(func));
+}
 bool HOT Scheduler::cancel_timeout(Component *component, const std::string &name) {
  return this->cancel_item_(component, NameType::HASHED_STRING, nullptr, fnv1a_hash(name), SchedulerItem::TIMEOUT);
 }
@@ -227,6 +238,9 @@ bool HOT Scheduler::cancel_timeout(Component *component, const char *name) {
 bool HOT Scheduler::cancel_timeout(Component *component, uint32_t id) {
  return this->cancel_item_(component, NameType::NUMERIC_ID, nullptr, id, SchedulerItem::TIMEOUT);
 }
+bool HOT Scheduler::cancel_timeout(Component *component, InternalSchedulerID id) {
+  return this->cancel_item_(component, NameType::NUMERIC_ID_INTERNAL, nullptr, id.id, SchedulerItem::TIMEOUT);
+}
 void HOT Scheduler::set_interval(Component *component, const std::string &name, uint32_t interval,
                                 std::function<void()> func) {
  this->set_timer_common_(component, SchedulerItem::INTERVAL, NameType::HASHED_STRING, nullptr, fnv1a_hash(name),
@@ -242,6 +256,11 @@ void HOT Scheduler::set_interval(Component *component, uint32_t id, uint32_t int
  this->set_timer_common_(component, SchedulerItem::INTERVAL, NameType::NUMERIC_ID, nullptr, id, interval,
                          std::move(func));
 }
+void HOT Scheduler::set_interval(Component *component, InternalSchedulerID id, uint32_t interval,
+                                 std::function<void()> func) {
+  this->set_timer_common_(component, SchedulerItem::INTERVAL, NameType::NUMERIC_ID_INTERNAL, nullptr, id.id, interval,
+                          std::move(func));
+}
 bool HOT Scheduler::cancel_interval(Component *component, const std::string &name) {
  return this->cancel_item_(component, NameType::HASHED_STRING, nullptr, fnv1a_hash(name), SchedulerItem::INTERVAL);
 }
@@ -251,6 +270,9 @@ bool HOT Scheduler::cancel_interval(Component *component, const char *name) {
 bool HOT Scheduler::cancel_interval(Component *component, uint32_t id) {
  return this->cancel_item_(component, NameType::NUMERIC_ID, nullptr, id, SchedulerItem::INTERVAL);
 }
+bool HOT Scheduler::cancel_interval(Component *component, InternalSchedulerID id) {
+  return this->cancel_item_(component, NameType::NUMERIC_ID_INTERNAL, nullptr, id.id, SchedulerItem::INTERVAL);
+}

 struct RetryArgs {
  // Ordered to minimize padding on 32-bit systems
--- a/esphome/core/scheduler.h
+++ b/esphome/core/scheduler.h
@@ -46,11 +46,14 @@ class Scheduler {
  void set_timeout(Component *component, const char *name, uint32_t timeout, std::function<void()> func);
  /// Set a timeout with a numeric ID (zero heap allocation)
  void set_timeout(Component *component, uint32_t id, uint32_t timeout, std::function<void()> func);
+  /// Set a timeout with an internal scheduler ID (separate namespace from component NUMERIC_ID)
+  void set_timeout(Component *component, InternalSchedulerID id, uint32_t timeout, std::function<void()> func);

  ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0")
  bool cancel_timeout(Component *component, const std::string &name);
  bool cancel_timeout(Component *component, const char *name);
  bool cancel_timeout(Component *component, uint32_t id);
+  bool cancel_timeout(Component *component, InternalSchedulerID id);

  ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0")
  void set_interval(Component *component, const std::string &name, uint32_t interval, std::function<void()> func);
@@ -66,11 +69,14 @@ class Scheduler {
  void set_interval(Component *component, const char *name, uint32_t interval, std::function<void()> func);
  /// Set an interval with a numeric ID (zero heap allocation)
  void set_interval(Component *component, uint32_t id, uint32_t interval, std::function<void()> func);
+  /// Set an interval with an internal scheduler ID (separate namespace from component NUMERIC_ID)
+  void set_interval(Component *component, InternalSchedulerID id, uint32_t interval, std::function<void()> func);

  ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0")
  bool cancel_interval(Component *component, const std::string &name);
  bool cancel_interval(Component *component, const char *name);
  bool cancel_interval(Component *component, uint32_t id);
+  bool cancel_interval(Component *component, InternalSchedulerID id);

  ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0")
  void set_retry(Component *component, const std::string &name, uint32_t initial_wait_time, uint8_t max_attempts,
@@ -102,9 +108,10 @@ class Scheduler {
  // Name storage type discriminator for SchedulerItem
  // Used to distinguish between static strings, hashed strings, and numeric IDs
  enum class NameType : uint8_t {
-    STATIC_STRING = 0,  // const char* pointer to static/flash storage
-    HASHED_STRING = 1,  // uint32_t FNV-1a hash of a runtime string
-    NUMERIC_ID = 2      // uint32_t numeric identifier
+    STATIC_STRING = 0,       // const char* pointer to static/flash storage
+    HASHED_STRING = 1,       // uint32_t FNV-1a hash of a runtime string
+    NUMERIC_ID = 2,          // uint32_t numeric identifier (component-level)
+    NUMERIC_ID_INTERNAL = 3  // uint32_t numeric identifier (core/internal, separate namespace)
  };

 protected:
@@ -206,6 +213,12 @@ class Scheduler {
      name_type_ = NameType::NUMERIC_ID;
    }

+    // Helper to set an internal numeric ID (separate namespace from NUMERIC_ID)
+    void set_internal_id(uint32_t id) {
+      name_.hash_or_id = id;
+      name_type_ = NameType::NUMERIC_ID_INTERNAL;
+    }
+
    static bool cmp(const std::unique_ptr<SchedulerItem> &a, const std::unique_ptr<SchedulerItem> &b);

    // Note: We use 48 bits total (32 + 16), stored in a 64-bit value for API compatibility.