Every object that should be handled by the Application instance and receive setup() and loop() calls must be a subclass of Component.

API Reference


class Component

The base class for all esphomelib components.

esphomelib uses components to separate code for self-contained units such as peripheral devices in order to keep the library clean and simple. Each component should be registered in the Application instance via add_component. The application will then call the component’s setup() and loop() methods at the appropriate time. Each component should save all the information required for setup in the constructor, and only do the actual hardware initialization, such as pinMode, in setup().

Additionally, the get_setup_priority() and get_loop_priority() can be overwritten in order to force the setup() or loop() methods to be executed earlier than other components. For example, setting up a GPIO pin to be output-only should be done before WiFi and MQTT are initialized - so the component can assign itself a high priority via get_setup_priority().


Subclassed by api::APIServer, binary_sensor::CustomBinarySensorConstructor, binary_sensor::DelayedOffFilter, binary_sensor::DelayedOnFilter, binary_sensor::ESP32TouchComponent, binary_sensor::GPIOBinarySensorComponent, binary_sensor::HeartbeatFilter, binary_sensor::MultiClickTrigger, binary_sensor::RDM6300Component, binary_sensor::StatusBinarySensor, binary_sensor::TemplateBinarySensor, cover::TemplateCover, DebugComponent, DeepSleepComponent, DelayAction< T >, ESP32BLEBeacon, ESP32BLETracker, EthernetComponent, fan::BasicFanComponent, fan::FanState, GlobalVariableComponent< T >, I2CComponent, io::PCF8574Component, light::FastLEDLightOutputComponent, light::LightState, light::NeoPixelBusLightOutputBase< T_METHOD, T_COLOR_FEATURE >, LogComponent, LoopTrigger, mqtt::MQTTClientComponent, mqtt::MQTTComponent, mqtt::MQTTMessageTrigger, OTAComponent, output::ESP8266PWMOutput, output::GPIOBinaryOutputComponent, output::LEDCOutputComponent, output::MY9231OutputComponent, output::PCA9685OutputComponent, PollingComponent, PowerSupplyComponent, remote::RemoteReceiverComponent, remote::RemoteTransmitterComponent, sensor::ADS1115Component, sensor::CustomSensorConstructor, sensor::DebounceFilter, sensor::HeartbeatFilter, sensor::HomeassistantSensor, sensor::MQTTSubscribeSensor, sensor::PMSX003Component, sensor::RotaryEncoderSensor, sensor::TotalDailyEnergy, sensor::ValueRangeTrigger, SPIComponent, StartupTrigger, StatusLEDComponent, stepper::A4988, stepper::ULN2003, switch_::CustomSwitchConstructor, switch_::GPIOSwitch, switch_::OutputSwitch, switch_::RestartSwitch, switch_::ShutdownSwitch, switch_::TemplateSwitch, switch_::UARTSwitch, text_sensor::CustomTextSensorConstructor, text_sensor::HomeassistantTextSensor, text_sensor::MQTTSubscribeTextSensor, text_sensor::VersionTextSensor, time::CronTrigger, time::RealTimeClockComponent, UARTComponent, WebServer, WiFiComponent

Public Functions

void setup()

Where the component’s initialization should happen.

Analogous to Arduino’s setup(). This method is guaranteed to only be called once. Defaults to doing nothing.

void loop()

This method will be called repeatedly.

Analogous to Arduino’s loop(). setup() is guaranteed to be called before this. Defaults to doing nothing.

void dump_config()
float get_setup_priority() const

priority of setup().

higher -> executed earlier

Defaults to 0.

The setup priority of this component

float get_actual_setup_priority() const
void set_setup_priority(float priority)
float get_loop_priority() const

priority of loop().

higher -> executed earlier

Defaults to 0.

The loop priority of this component

void loop_()

Public loop() functions.

These will be called by the Application instance.

Note: This should normally not be overriden, unless you know what you’re doing. They’re basically to make creating custom components easier. For example the SensorComponent can override these methods to not have the user call some super methods within their custom sensors. These methods should ALWAYS call the loop_internal() and setup_internal() methods.

Basically, it handles stuff like interval/timeout functions and eventually calls loop().

void setup_()
uint32_t get_component_state() const
void mark_failed()

Mark this component as failed.

Any future timeouts/intervals/setup/loop will no longer be called.

This might be useful if a component wants to indicate that a connection to its peripheral failed. For example, i2c based components can check if the remote device is responding and otherwise mark the component as failed. Eventually this will also enable smart status LEDs.

bool is_failed()
bool can_proceed()
bool status_has_warning()
bool status_has_error()
void status_set_warning()
void status_set_error()
void status_clear_warning()
void status_clear_error()
void status_momentary_warning(const std::string &name, uint32_t length = 5000)
void status_momentary_error(const std::string &name, uint32_t length = 5000)

Protected Functions

void loop_internal()
void setup_internal()
void set_interval(uint32_t interval, std::function<void()> &&f)
void set_interval(const std::string &name, uint32_t interval, std::function<void()> &&f)

Set an interval function with a unique name.

Empty name means no cancelling possible.

This will call f every interval ms. Can be cancelled via CancelInterval(). Similar to javascript’s setInterval().

IMPORTANT: Do not rely on this having correct timing. This is only called from loop() and therefore can be significantly delay. If you need exact timing please use hardware timers.

  • name: The identifier for this interval function.
  • interval: The interval in ms.
  • f: The function (or lambda) that should be called

bool cancel_interval(const std::string &name)

Cancel an interval function.

Whether an interval functions was deleted.
  • name: The identifier for this interval function.

void set_timeout(uint32_t timeout, std::function<void()> &&f)
void set_timeout(const std::string &name, uint32_t timeout, std::function<void()> &&f)

Set a timeout function with a unique name.

Similar to javascript’s setTimeout(). Empty name means no cancelling possible.

IMPORTANT: Do not rely on this having correct timing. This is only called from loop() and therefore can be significantly delay. If you need exact timing please use hardware timers.

  • name: The identifier for this timeout function.
  • timeout: The timeout in ms.
  • f: The function (or lambda) that should be called

bool cancel_timeout(const std::string &name)

Cancel a timeout function.

Whether a timeout functions was deleted.
  • name: The identifier for this timeout function.

void defer(const std::string &name, std::function<void()> &&f)

Defer a callback to the next loop() call.

If name is specified and a defer() object with the same name exists, the old one is first removed.

  • name: The name of the defer function.
  • f: The callback.

void defer(std::function<void()> &&f)

Defer a callback to the next loop() call.

bool cancel_defer(const std::string &name)

Cancel a defer callback using the specified name, name must not be empty.

bool cancel_time_function(const std::string &name, TimeFunction::Type type)

Cancel an only time function. If name is empty, won’t do anything.

Protected Attributes

std::vector<TimeFunction> time_functions_

Storage for interval/timeout functions.

Intentionally a vector despite its map-like nature, because of the memory overhead.

uint32_t component_state_ = {0x0000}

State of this component.

optional<float> setup_priority_override_
struct TimeFunction

Internal struct for storing timeout/interval functions.

Public Types

enum Type



Public Functions

bool should_run(uint32_t now) const

Public Members

std::string name

The name/id of this TimeFunction.

Component::TimeFunction::Type type

The type of this TimeFunction. Either TIMEOUT, INTERVAL or DEFER.

uint32_t interval

The interval/timeout of this function.

uint32_t last_execution

The last execution for interval functions and the time, SetInterval was called, for timeout functions.

std::function<void()> f

The function (or callback) itself.

bool remove


class PollingComponent : public Component

This class simplifies creating components that periodically check a state.

You basically just need to implement the update() function, it will be called every update_interval ms after startup. Note that this class cannot guarantee a correct timing, as it’s not using timers, just a software polling feature with set_interval() from Component.

Subclassed by binary_sensor::PN532Component, display::LCDDisplay, display::MAX7219Component, display::Nextion, display::SSD1306, display::WaveshareEPaper, IntervalTrigger, sensor::APDS9960, sensor::BME280Component, sensor::BME680Component, sensor::BMP085Component, sensor::BMP280Component, sensor::CSE7766Component, sensor::DallasComponent, sensor::DHT12Component, sensor::DHTComponent, sensor::HDC1080Component, sensor::HLW8012Component, sensor::HMC5883LComponent, sensor::HTU21DComponent, sensor::INA219Component, sensor::INA3221Component, sensor::MHZ19Component, sensor::MPU6050Component, sensor::MS5611Component, sensor::PollingSensorComponent, sensor::SHT3XDComponent, sensor::TCS34725Component, text_sensor::TemplateTextSensor

Public Functions

PollingComponent(uint32_t update_interval)

Initialize this polling component with the given update interval in ms.

  • update_interval: The update interval in ms.

void set_update_interval(uint32_t update_interval)

Manually set the update interval in ms for this polling object.

Override this if you want to do some validation for the update interval.

  • update_interval: The update interval in ms.

virtual void update() = 0
void setup_()
uint32_t get_update_interval() const

Get the update interval in ms of this sensor.

Protected Attributes

uint32_t update_interval_

Setup Priorities

namespace setup_priority

default setup priorities for components of different types.


const float PRE_HARDWARE = 110.0f

only for internal components that are necessary for hardware component initialization (like i2c bus)

const float HARDWARE = 100.0f

for hardware initialization, but only where it’s really necessary (like outputs)

const float POST_HARDWARE = 90.0f
const float HARDWARE_LATE = 50.0f
const float WIFI = 10.0f

for WiFi initialization

const float MQTT_CLIENT = 7.5f

for the MQTT client initialization

const float MQTT_COMPONENT = -5.0f

for MQTT component initialization

const float LATE = -10.0f