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/helpers.h"
#include "esphome/core/log.h"
#include "esphome/core/optional.h"
 
namespace esphome {
 
// Forward declaration for LogString
struct LogString;
 
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;
 
// Remove before 2026.8.0
enum class RetryResult { DONE, RETRY };
 
inline constexpr uint16_t WARN_IF_BLOCKING_OVER_MS = 50U;
 
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);
 
#ifdef USE_LOOP_PRIORITY
  virtual float get_loop_priority() const;
#endif
 
  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();
 
  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(const char *message = nullptr);
  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; }
 
  void set_component_source(const LogString *source) { component_source_ = source; }
  const LogString *get_component_log_str() const;
 
  bool should_warn_of_blocking(uint32_t blocking_time);
 
 protected:
  friend class Application;
 
  void call_loop_();
  virtual void call_setup();
  void call_dump_config_();
 
  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
  const LogString *component_source_{nullptr};
  uint16_t warn_if_blocking_over_{WARN_IF_BLOCKING_OVER_MS};  
  uint8_t component_state_{0x00};
  volatile bool pending_enable_loop_{false};  
};
 
class PollingComponent : public Component {
 public:
  PollingComponent() : PollingComponent(0) {}
 
  explicit PollingComponent(uint32_t update_interval);
 
  virtual void set_update_interval(uint32_t 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_;
};
 
#ifdef USE_RUNTIME_STATS
uint32_t micros();  // Forward declare for inline constructor
#endif
 
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
  uint32_t finish();
 
  ~WarnIfComponentBlockingGuard() = default;
 
 protected:
  uint32_t started_;
  Component *component_;
#ifdef USE_RUNTIME_STATS
  uint32_t started_us_;
#endif
};
 
// 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