component.h

Go to the documentation of this file.

#pragma once
 
#include <cmath>
#include <cstdint>
#include <functional>
#include <string>
 
#include "esphome/core/defines.h"
#include "esphome/core/hal.h"
#include "esphome/core/helpers.h"
#include "esphome/core/log.h"
#include "esphome/core/optional.h"
 
// Forward declarations for friend access from codegen-generated setup()
void setup();           // NOLINT(readability-redundant-declaration) - may be declared in Arduino.h
void original_setup();  // NOLINT(readability-redundant-declaration)
 
namespace esphome {
 
// Forward declaration for LogString
struct LogString;
 
#ifdef USE_RUNTIME_STATS
namespace runtime_stats {
class RuntimeStatsCollector;
}  // namespace runtime_stats
#endif
 
namespace setup_priority {
 
inline constexpr float BUS = 1000.0f;
inline constexpr float IO = 900.0f;
inline constexpr float HARDWARE = 800.0f;
inline constexpr float DATA = 600.0f;
inline constexpr float PROCESSOR = 400.0f;
inline constexpr float BLUETOOTH = 350.0f;
inline constexpr float AFTER_BLUETOOTH = 300.0f;
inline constexpr float WIFI = 250.0f;
inline constexpr float ETHERNET = 250.0f;
inline constexpr float BEFORE_CONNECTION = 220.0f;
inline constexpr float AFTER_WIFI = 200.0f;
inline constexpr float AFTER_CONNECTION = 100.0f;
inline constexpr float LATE = -100.0f;
 
}  // namespace setup_priority
 
inline constexpr uint32_t SCHEDULER_DONT_RUN = 4294967295UL;
 
enum class InternalSchedulerID : uint32_t {
  POLLING_UPDATE = 0,  // PollingComponent interval
  DELAY_ACTION = 1,    // DelayAction timeout
};
 
// Forward declaration
class PollingComponent;
 
// Function declaration for LOG_UPDATE_INTERVAL
void log_update_interval(const char *tag, PollingComponent *component);
 
#define LOG_UPDATE_INTERVAL(this) log_update_interval(TAG, this)
 
// Component state uses bits 0-2 (8 states, 5 used)
inline constexpr uint8_t COMPONENT_STATE_MASK = 0x07;
inline constexpr uint8_t COMPONENT_STATE_CONSTRUCTION = 0x00;
inline constexpr uint8_t COMPONENT_STATE_SETUP = 0x01;
inline constexpr uint8_t COMPONENT_STATE_LOOP = 0x02;
inline constexpr uint8_t COMPONENT_STATE_FAILED = 0x03;
inline constexpr uint8_t COMPONENT_STATE_LOOP_DONE = 0x04;
// Status LED uses bits 3-4
inline constexpr uint8_t STATUS_LED_MASK = 0x18;
inline constexpr uint8_t STATUS_LED_OK = 0x00;
inline constexpr uint8_t STATUS_LED_WARNING = 0x08;
inline constexpr uint8_t STATUS_LED_ERROR = 0x10;
// Component loop override flag uses bit 5 (set at registration time)
inline constexpr uint8_t COMPONENT_HAS_LOOP = 0x20;
// Bit 6 on Application::app_state_ (ONLY) — set at the end of
// Application::setup(). Component::status_clear_*_slow_path_() uses this to
// decide whether to propagate clears to App.app_state_. Never set on a
// Component's component_state_.
inline constexpr uint8_t APP_STATE_SETUP_COMPLETE = 0x40;
// Remove before 2026.8.0
enum class RetryResult { DONE, RETRY };
 
inline constexpr uint8_t WARN_IF_BLOCKING_OVER_CS = 5U;  // 50ms in centiseconds (1cs = 10ms)
 
const LogString *component_source_lookup(uint8_t index);
 
#ifdef USE_RUNTIME_STATS
struct ComponentRuntimeStats {
  // Period stats (reset each logging interval)
  uint32_t period_count{0};
  uint32_t period_time_us{0};
  uint32_t period_max_time_us{0};
  // Total stats (persistent until reboot, uint64_t to avoid overflow)
  uint32_t total_count{0};
  uint64_t total_time_us{0};
  uint32_t total_max_time_us{0};
 
  // Cumulative sum of every record_time() duration since boot, across all
  // components. Used by Application::loop() to snapshot time spent inside
  // WarnIfComponentBlockingGuard (including guards constructed by the
  // scheduler at scheduler.cpp) so main-loop overhead accounting can
  // subtract scheduled-callback time from the before_loop_tasks_ wall time.
  static uint64_t global_recorded_us;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
 
  void record_time(uint32_t duration_us) {
    this->period_count++;
    this->period_time_us += duration_us;
    if (duration_us > this->period_max_time_us)
      this->period_max_time_us = duration_us;
    this->total_count++;
    this->total_time_us += duration_us;
    if (duration_us > this->total_max_time_us)
      this->total_max_time_us = duration_us;
    global_recorded_us += duration_us;
  }
  void reset_period() {
    this->period_count = 0;
    this->period_time_us = 0;
    this->period_max_time_us = 0;
  }
};
#endif
 
class Component {
 public:
  virtual void setup();
 
  virtual void loop();
 
  virtual void dump_config();
 
  virtual float get_setup_priority() const;
 
  float get_actual_setup_priority() const;
 
  void set_setup_priority(float priority);
 
  void call();
 
  virtual void on_shutdown() {}
  virtual void on_safe_shutdown() {}
 
  virtual bool teardown() { return true; }
 
  virtual void on_powerdown() {}
 
  uint8_t get_component_state() const { return this->component_state_; }
 
  void reset_to_construction_state();
 
  bool is_in_loop_state() const { return (this->component_state_ & COMPONENT_STATE_MASK) == COMPONENT_STATE_LOOP; }
 
  bool is_idle() const { return (this->component_state_ & COMPONENT_STATE_MASK) == COMPONENT_STATE_LOOP_DONE; }
 
  void mark_failed();
 
  // Remove before 2026.6.0
  ESPDEPRECATED("Use mark_failed(LOG_STR(\"static string literal\")) instead. Do NOT use .c_str() from temporary "
                "strings. Will stop working in 2026.6.0",
                "2025.12.0")
  void mark_failed(const char *message) {
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
    this->status_set_error(message);
#pragma GCC diagnostic pop
    this->mark_failed();
  }
 
  void mark_failed(const LogString *message) {
    this->status_set_error(message);
    this->mark_failed();
  }
 
  void disable_loop();
 
  void enable_loop() {
    if ((this->component_state_ & COMPONENT_STATE_MASK) == COMPONENT_STATE_LOOP_DONE)
      this->enable_loop_slow_path_();
  }
 
  void enable_loop_soon_any_context();
 
  bool is_failed() const { return (this->component_state_ & COMPONENT_STATE_MASK) == COMPONENT_STATE_FAILED; }
 
  bool is_ready() const;
 
  virtual bool can_proceed();
 
  bool status_has_warning() const { return this->component_state_ & STATUS_LED_WARNING; }
 
  bool status_has_error() const { return this->component_state_ & STATUS_LED_ERROR; }
 
  void status_set_warning();  // Set warning flag without message
  void status_set_warning(const char *message);
  void status_set_warning(const LogString *message);
 
  void status_set_error();  // Set error flag without message
  // Remove before 2026.6.0
  ESPDEPRECATED("Use status_set_error(LOG_STR(\"static string literal\")) instead. Do NOT use .c_str() from temporary "
                "strings. Will stop working in 2026.6.0",
                "2025.12.0")
  void status_set_error(const char *message);
  void status_set_error(const LogString *message);
 
  void status_clear_warning() {
    if ((this->component_state_ & STATUS_LED_WARNING) == 0)
      return;
    this->status_clear_warning_slow_path_();
  }
 
  void status_clear_error() {
    if ((this->component_state_ & STATUS_LED_ERROR) == 0)
      return;
    this->status_clear_error_slow_path_();
  }
 
  void status_momentary_warning(const char *name, uint32_t length = 5000);
 
  void status_momentary_error(const char *name, uint32_t length = 5000);
 
  bool has_overridden_loop() const { return (this->component_state_ & COMPONENT_HAS_LOOP) != 0; }
 
  inline const LogString *get_component_log_str() const ESPHOME_ALWAYS_INLINE {
    return component_source_lookup(this->component_source_index_);
  }
 
  bool should_warn_of_blocking(uint32_t blocking_time);
 
 protected:
  friend class Application;
  friend void ::setup();
  friend void ::original_setup();
 
  void set_component_source_(uint8_t index) { this->component_source_index_ = index; }
 
  virtual void call_setup();
  void call_dump_config_();
 
  void enable_loop_slow_path_();
 
  inline void set_component_state_(uint8_t state) {
    this->component_state_ &= ~COMPONENT_STATE_MASK;
    this->component_state_ |= state;
  }
 
  bool set_status_flag_(uint8_t flag);
 
  // Remove before 2026.7.0
  ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0")
  void set_interval(const std::string &name, uint32_t interval, std::function<void()> &&f);  // NOLINT
 
  void set_interval(const char *name, uint32_t interval, std::function<void()> &&f);  // NOLINT
 
  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
 
  // Remove before 2026.7.0
  ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0")
  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
 
  // Remove before 2026.8.0
  ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.",
                "2026.2.0")
  void set_retry(const std::string &name, uint32_t initial_wait_time, uint8_t max_attempts,       // NOLINT
                 std::function<RetryResult(uint8_t)> &&f, float backoff_increase_factor = 1.0f);  // NOLINT
 
  // Remove before 2026.8.0
  ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.",
                "2026.2.0")
  void set_retry(const char *name, uint32_t initial_wait_time, uint8_t max_attempts,              // NOLINT
                 std::function<RetryResult(uint8_t)> &&f, float backoff_increase_factor = 1.0f);  // NOLINT
 
  // Remove before 2026.8.0
  ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.",
                "2026.2.0")
  void set_retry(uint32_t id, uint32_t initial_wait_time, uint8_t max_attempts,                   // NOLINT
                 std::function<RetryResult(uint8_t)> &&f, float backoff_increase_factor = 1.0f);  // NOLINT
 
  // Remove before 2026.8.0
  ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.",
                "2026.2.0")
  void set_retry(uint32_t initial_wait_time, uint8_t max_attempts, std::function<RetryResult(uint8_t)> &&f,  // NOLINT
                 float backoff_increase_factor = 1.0f);                                                      // NOLINT
 
  // Remove before 2026.8.0
  ESPDEPRECATED("cancel_retry is deprecated and will be removed in 2026.8.0.", "2026.2.0")
  bool cancel_retry(const std::string &name);  // NOLINT
  // Remove before 2026.8.0
  ESPDEPRECATED("cancel_retry is deprecated and will be removed in 2026.8.0.", "2026.2.0")
  bool cancel_retry(const char *name);  // NOLINT
  // Remove before 2026.8.0
  ESPDEPRECATED("cancel_retry is deprecated and will be removed in 2026.8.0.", "2026.2.0")
  bool cancel_retry(uint32_t id);  // NOLINT
 
  // Remove before 2026.7.0
  ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0")
  void set_timeout(const std::string &name, uint32_t timeout, std::function<void()> &&f);  // NOLINT
 
  void set_timeout(const char *name, uint32_t timeout, std::function<void()> &&f);  // NOLINT
 
  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
 
  // Remove before 2026.7.0
  ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0")
  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
 
  // Remove before 2026.7.0
  ESPDEPRECATED("Use const char* overload instead. Removed in 2026.7.0", "2026.1.0")
  void defer(const std::string &name, std::function<void()> &&f);  // NOLINT
 
  void defer(const char *name, std::function<void()> &&f);  // NOLINT
 
  void defer(std::function<void()> &&f);  // NOLINT
 
  void defer(uint32_t id, std::function<void()> &&f);  // NOLINT
 
  // Remove before 2026.7.0
  ESPDEPRECATED("Use const char* overload instead. Removed in 2026.7.0", "2026.1.0")
  bool cancel_defer(const std::string &name);  // NOLINT
  bool cancel_defer(const char *name);         // NOLINT
  bool cancel_defer(uint32_t id);              // NOLINT
 
  void status_clear_warning_slow_path_();
  void status_clear_error_slow_path_();
 
  // Ordered for optimal packing on 32-bit systems (8 bytes total with vtable)
  uint8_t component_source_index_{0};  
  uint8_t warn_if_blocking_over_{WARN_IF_BLOCKING_OVER_CS};  
  uint8_t component_state_{0x00};
  volatile bool pending_enable_loop_{false};  
#ifdef USE_RUNTIME_STATS
  friend class runtime_stats::RuntimeStatsCollector;
  friend class WarnIfComponentBlockingGuard;
  ComponentRuntimeStats runtime_stats_;
#endif
};
 
class PollingComponent : public Component {
 public:
  PollingComponent() : PollingComponent(0) {}
 
  explicit PollingComponent(uint32_t update_interval);
 
  void set_update_interval(uint32_t update_interval) { this->update_interval_ = update_interval; }
 
  // ========== OVERRIDE METHODS ==========
  // (You'll only need this when creating your own custom sensor)
  virtual void update() = 0;
 
  // ========== INTERNAL METHODS ==========
  // (In most use cases you won't need these)
  void call_setup() override;
 
  virtual uint32_t get_update_interval() const;
 
  // Start the poller, used for component.suspend
  void start_poller();
 
  // Stop the poller, used for component.suspend
  void stop_poller();
 
 protected:
  uint32_t update_interval_;
};
 
// millis() and micros() are available via hal.h
 
class WarnIfComponentBlockingGuard {
 public:
  WarnIfComponentBlockingGuard(Component *component, uint32_t start_time)
      : started_(start_time),
        component_(component)
#ifdef USE_RUNTIME_STATS
        ,
        started_us_(micros())
#endif
  {
  }
 
  // Finish the timing operation and return the current time (millis)
  // Inlined: the fast path is just millis() + subtract + compare
  inline uint32_t HOT finish() {
#ifdef USE_RUNTIME_STATS
    this->component_->runtime_stats_.record_time(micros() - this->started_us_);
#endif
    uint32_t curr_time = millis();
#ifndef USE_BENCHMARK
    // Fast path: compare against constant threshold in ms (computed at compile time from centiseconds)
    static constexpr uint32_t WARN_IF_BLOCKING_OVER_MS = static_cast<uint32_t>(WARN_IF_BLOCKING_OVER_CS) * 10U;
    uint32_t blocking_time = curr_time - this->started_;
    if (blocking_time > WARN_IF_BLOCKING_OVER_MS) [[unlikely]] {
      warn_blocking(this->component_, blocking_time);
    }
#endif
    return curr_time;
  }
 
  ~WarnIfComponentBlockingGuard() = default;
 
 protected:
  uint32_t started_;
  Component *component_;
#ifdef USE_RUNTIME_STATS
  uint32_t started_us_;
#endif
 
 private:
  // Cold path for blocking warning - defined in component.cpp
  static void __attribute__((noinline, cold)) warn_blocking(Component *component, uint32_t blocking_time);
};
 
// Function to clear setup priority overrides after all components are set up
// Only has an implementation when USE_SETUP_PRIORITY_OVERRIDE is defined
void clear_setup_priority_overrides();
 
}  // namespace esphome