ESPHome  1.15.2
Public Member Functions | Data Fields | Protected Member Functions | Protected Attributes
esphome::sensor::Sensor Class Reference

Base-class for all sensors. More...

#include <sensor.h>

Inheritance diagram for esphome::sensor::Sensor:
esphome::Nameable esphome::adc::ADCSensor esphome::ads1115::ADS1115Sensor esphome::bh1750::BH1750Sensor esphome::binary_sensor_map::BinarySensorMap esphome::ble_rssi::BLERSSISensor esphome::ct_clamp::CTClampSensor esphome::dallas::DallasTemperatureSensor esphome::duty_cycle::DutyCycleSensor esphome::esp32_hall::ESP32HallSensor esphome::homeassistant::HomeassistantSensor esphome::hx711::HX711Sensor esphome::integration::IntegrationSensor esphome::max31855::MAX31855Sensor esphome::max31856::MAX31856Sensor esphome::max31865::MAX31865Sensor esphome::max6675::MAX6675Sensor esphome::mcp3008::MCP3008Sensor esphome::mqtt_subscribe::MQTTSubscribeSensor esphome::ntc::NTC esphome::pid::PIDClimateSensor esphome::pulse_counter::PulseCounterSensor esphome::pulse_width::PulseWidthSensor esphome::resistance::ResistanceSensor esphome::rotary_encoder::RotaryEncoderSensor esphome::sensor::PollingSensorComponent esphome::sts3x::STS3XComponent esphome::sun::SunSensor esphome::template_::TemplateSensor esphome::tmp117::TMP117Component esphome::total_daily_energy::TotalDailyEnergy esphome::tsl2561::TSL2561Sensor esphome::tuya::TuyaSensor esphome::ultrasonic::UltrasonicSensorComponent esphome::uptime::UptimeSensor esphome::vl53l0x::VL53L0XSensor esphome::wifi_signal::WiFiSignalSensor

Public Member Functions

 Sensor ()
 
 Sensor (const std::string &name)
 
void set_unit_of_measurement (const std::string &unit_of_measurement)
 Manually set the unit of measurement of this sensor. More...
 
void set_icon (const std::string &icon)
 Manually set the icon of this sensor. More...
 
void set_accuracy_decimals (int8_t accuracy_decimals)
 Manually set the accuracy in decimals for this sensor. More...
 
void add_filter (Filter *filter)
 Add a filter to the filter chain. Will be appended to the back. More...
 
void add_filters (const std::vector< Filter *> &filters)
 Add a list of vectors to the back of the filter chain. More...
 
void set_filters (const std::vector< Filter *> &filters)
 Clear the filters and replace them by filters. More...
 
void clear_filters ()
 Clear the entire filter chain. More...
 
float get_value () const ESPDEPRECATED(".value is deprecated
 Getter-syntax for .value. Please use .state instead. More...
 
float get_state () const
 Getter-syntax for .state. More...
 
float get_raw_value () const ESPDEPRECATED(".raw_value is deprecated
 Getter-syntax for .raw_value. Please use .raw_state instead. More...
 
float get_raw_state () const
 Getter-syntax for .raw_state. More...
 
int8_t get_accuracy_decimals ()
 Get the accuracy in decimals. Uses the manual override if specified or the default value instead. More...
 
std::string get_unit_of_measurement ()
 Get the unit of measurement. Uses the manual override if specified or the default value instead. More...
 
std::string get_icon ()
 Get the Home Assistant Icon. Uses the manual override if specified or the default value instead. More...
 
void publish_state (float state)
 Publish a new state to the front-end. More...
 
void push_new_value (float state) ESPDEPRECATED("push_new_value is deprecated. Please use .publish_state instead")
 Push a new value to the MQTT front-end. More...
 
void add_on_state_callback (std::function< void(float)> &&callback)
 Add a callback that will be called every time a filtered value arrives. More...
 
void add_on_raw_state_callback (std::function< void(float)> &&callback)
 Add a callback that will be called every time the sensor sends a raw value. More...
 
bool has_state () const
 Return whether this sensor has gotten a full state (that passed through all filters) yet. More...
 
virtual std::string unique_id ()
 A unique ID for this sensor, empty for no unique id. More...
 
virtual uint32_t update_interval ()
 Return with which interval the sensor is polled. Return 0 for non-polling mode. More...
 
uint32_t calculate_expected_filter_update_interval ()
 Calculate the expected update interval for values that pass through all filters. More...
 
void internal_send_state_to_frontend (float state)
 
bool get_force_update () const
 
void set_force_update (bool force_update)
 Set this sensor's force_update mode. More...
 
- Public Member Functions inherited from esphome::Nameable
 Nameable ()
 
 Nameable (const std::string &name)
 
const std::string & get_name () const
 
void set_name (const std::string &name)
 
const std::string & get_object_id ()
 Get the sanitized name of this nameable as an ID. Caching it internally. More...
 
uint32_t get_object_id_hash ()
 
bool is_internal () const
 
void set_internal (bool internal)
 

Data Fields

float please use state
 
float please use raw_state
 
float state
 This member variable stores the last state that has passed through all filters. More...
 
float raw_state
 This member variable stores the current raw state of the sensor. More...
 

Protected Member Functions

virtual std::string unit_of_measurement ()
 Override this to set the Home Assistant unit of measurement for this sensor. More...
 
virtual std::string icon ()
 Override this to set the Home Assistant icon for this sensor. More...
 
virtual int8_t accuracy_decimals ()
 Return the accuracy in decimals for this sensor. More...
 
uint32_t hash_base () override
 
- Protected Member Functions inherited from esphome::Nameable
void calc_object_id_ ()
 

Protected Attributes

CallbackManager< void(float)> raw_callback_
 Storage for raw state callbacks. More...
 
CallbackManager< void(float)> callback_
 Storage for filtered state callbacks. More...
 
optional< std::string > unit_of_measurement_
 Override the unit of measurement. More...
 
optional< std::string > icon_
 Override the icon advertised to Home Assistant, otherwise sensor's icon will be used. More...
 
optional< int8_t > accuracy_decimals_
 Override the accuracy in decimals, otherwise the sensor's values will be used. More...
 
Filterfilter_list_ {nullptr}
 Store all active filters. More...
 
bool has_state_ {false}
 
bool force_update_ {false}
 
- Protected Attributes inherited from esphome::Nameable
std::string name_
 
std::string object_id_
 
uint32_t object_id_hash_
 
bool internal_ {false}
 

Detailed Description

Base-class for all sensors.

A sensor has unit of measurement and can use publish_state to send out a new value with the specified accuracy.

Definition at line 30 of file sensor.h.

Constructor & Destructor Documentation

◆ Sensor() [1/2]

esphome::sensor::Sensor::Sensor ( )
explicit

Definition at line 27 of file sensor.cpp.

◆ Sensor() [2/2]

esphome::sensor::Sensor::Sensor ( const std::string &  name)
explicit

Definition at line 26 of file sensor.cpp.

Member Function Documentation

◆ accuracy_decimals()

int8_t esphome::sensor::Sensor::accuracy_decimals ( )
protectedvirtual

Return the accuracy in decimals for this sensor.

Reimplemented in esphome::integration::IntegrationSensor, and esphome::total_daily_energy::TotalDailyEnergy.

Definition at line 25 of file sensor.cpp.

◆ add_filter()

void esphome::sensor::Sensor::add_filter ( Filter filter)

Add a filter to the filter chain. Will be appended to the back.

Definition at line 53 of file sensor.cpp.

◆ add_filters()

void esphome::sensor::Sensor::add_filters ( const std::vector< Filter *> &  filters)

Add a list of vectors to the back of the filter chain.

This may look like:

sensor->add_filters({ LambdaFilter([&](float value) -> optional<float> { return 42/value; }), OffsetFilter(1), SlidingWindowMovingAverageFilter(15, 15), // average over last 15 values });

Definition at line 67 of file sensor.cpp.

◆ add_on_raw_state_callback()

void esphome::sensor::Sensor::add_on_raw_state_callback ( std::function< void(float)> &&  callback)

Add a callback that will be called every time the sensor sends a raw value.

Definition at line 35 of file sensor.cpp.

◆ add_on_state_callback()

void esphome::sensor::Sensor::add_on_state_callback ( std::function< void(float)> &&  callback)

Add a callback that will be called every time a filtered value arrives.

Definition at line 34 of file sensor.cpp.

◆ calculate_expected_filter_update_interval()

uint32_t esphome::sensor::Sensor::calculate_expected_filter_update_interval ( )

Calculate the expected update interval for values that pass through all filters.

Definition at line 96 of file sensor.cpp.

◆ clear_filters()

void esphome::sensor::Sensor::clear_filters ( )

Clear the entire filter chain.

Definition at line 76 of file sensor.cpp.

◆ get_accuracy_decimals()

int8_t esphome::sensor::Sensor::get_accuracy_decimals ( )

Get the accuracy in decimals. Uses the manual override if specified or the default value instead.

Definition at line 48 of file sensor.cpp.

◆ get_force_update()

bool esphome::sensor::Sensor::get_force_update ( ) const
inline

Definition at line 148 of file sensor.h.

◆ get_icon()

std::string esphome::sensor::Sensor::get_icon ( )

Get the Home Assistant Icon. Uses the manual override if specified or the default value instead.

Definition at line 38 of file sensor.cpp.

◆ get_raw_state()

float esphome::sensor::Sensor::get_raw_state ( ) const

Getter-syntax for .raw_state.

Definition at line 85 of file sensor.cpp.

◆ get_raw_value()

float esphome::sensor::Sensor::get_raw_value ( ) const

Getter-syntax for .raw_value. Please use .raw_state instead.

Definition at line 84 of file sensor.cpp.

◆ get_state()

float esphome::sensor::Sensor::get_state ( ) const

Getter-syntax for .state.

Definition at line 83 of file sensor.cpp.

◆ get_unit_of_measurement()

std::string esphome::sensor::Sensor::get_unit_of_measurement ( )

Get the unit of measurement. Uses the manual override if specified or the default value instead.

Definition at line 43 of file sensor.cpp.

◆ get_value()

float esphome::sensor::Sensor::get_value ( ) const

Getter-syntax for .value. Please use .state instead.

Definition at line 82 of file sensor.cpp.

◆ has_state()

bool esphome::sensor::Sensor::has_state ( ) const

Return whether this sensor has gotten a full state (that passed through all filters) yet.

Definition at line 95 of file sensor.cpp.

◆ hash_base()

uint32_t esphome::sensor::Sensor::hash_base ( )
overrideprotectedvirtual

Implements esphome::Nameable.

Definition at line 108 of file sensor.cpp.

◆ icon()

std::string esphome::sensor::Sensor::icon ( )
protectedvirtual

Override this to set the Home Assistant icon for this sensor.

Return "" to disable this feature.

Returns
The icon of this sensor, for example "mdi:battery".

Reimplemented in esphome::integration::IntegrationSensor, and esphome::total_daily_energy::TotalDailyEnergy.

Definition at line 23 of file sensor.cpp.

◆ internal_send_state_to_frontend()

void esphome::sensor::Sensor::internal_send_state_to_frontend ( float  state)

Definition at line 88 of file sensor.cpp.

◆ publish_state()

void esphome::sensor::Sensor::publish_state ( float  state)

Publish a new state to the front-end.

First, the new state will be assigned to the raw_value. Then it's passed through all filters until it finally lands in the .value member variable and a callback is issued.

Parameters
stateThe state as a floating point number.

Definition at line 9 of file sensor.cpp.

◆ push_new_value()

void esphome::sensor::Sensor::push_new_value ( float  state)

Push a new value to the MQTT front-end.

Note: deprecated, please use publish_state.

Definition at line 21 of file sensor.cpp.

◆ set_accuracy_decimals()

void esphome::sensor::Sensor::set_accuracy_decimals ( int8_t  accuracy_decimals)

Manually set the accuracy in decimals for this sensor.

By default, the sensor's default defined by accuracy_decimals() is used.

Parameters
accuracy_decimalsThe accuracy decimal that should be used.

Definition at line 33 of file sensor.cpp.

◆ set_filters()

void esphome::sensor::Sensor::set_filters ( const std::vector< Filter *> &  filters)

Clear the filters and replace them by filters.

Definition at line 72 of file sensor.cpp.

◆ set_force_update()

void esphome::sensor::Sensor::set_force_update ( bool  force_update)
inline

Set this sensor's force_update mode.

If the sensor is in force_update mode, the frontend is required to save all state changes to the database when they are published, even if the state is the same as before.

Definition at line 155 of file sensor.h.

◆ set_icon()

void esphome::sensor::Sensor::set_icon ( const std::string &  icon)

Manually set the icon of this sensor.

By default the sensor's default defined by icon() is used.

Parameters
iconThe icon, for example "mdi:flash". "" to disable.

Definition at line 32 of file sensor.cpp.

◆ set_unit_of_measurement()

void esphome::sensor::Sensor::set_unit_of_measurement ( const std::string &  unit_of_measurement)

Manually set the unit of measurement of this sensor.

By default the sensor's default defined by unit_of_measurement() is used.

Parameters
unit_of_measurementThe unit of measurement, "" to disable.

Definition at line 29 of file sensor.cpp.

◆ unique_id()

std::string esphome::sensor::Sensor::unique_id ( )
virtual

◆ unit_of_measurement()

std::string esphome::sensor::Sensor::unit_of_measurement ( )
protectedvirtual

Override this to set the Home Assistant unit of measurement for this sensor.

Return "" to disable this feature.

Returns
The icon of this sensor, for example "°C".

Reimplemented in esphome::integration::IntegrationSensor, and esphome::total_daily_energy::TotalDailyEnergy.

Definition at line 22 of file sensor.cpp.

◆ update_interval()

uint32_t esphome::sensor::Sensor::update_interval ( )
virtual

Return with which interval the sensor is polled. Return 0 for non-polling mode.

Reimplemented in esphome::sensor::PollingSensorComponent.

Definition at line 24 of file sensor.cpp.

Field Documentation

◆ accuracy_decimals_

optional<int8_t> esphome::sensor::Sensor::accuracy_decimals_
protected

Override the accuracy in decimals, otherwise the sensor's values will be used.

Definition at line 186 of file sensor.h.

◆ callback_

CallbackManager<void(float)> esphome::sensor::Sensor::callback_
protected

Storage for filtered state callbacks.

Definition at line 180 of file sensor.h.

◆ filter_list_

Filter* esphome::sensor::Sensor::filter_list_ {nullptr}
protected

Store all active filters.

Definition at line 187 of file sensor.h.

◆ force_update_

bool esphome::sensor::Sensor::force_update_ {false}
protected

Definition at line 189 of file sensor.h.

◆ has_state_

bool esphome::sensor::Sensor::has_state_ {false}
protected

Definition at line 188 of file sensor.h.

◆ icon_

optional<std::string> esphome::sensor::Sensor::icon_
protected

Override the icon advertised to Home Assistant, otherwise sensor's icon will be used.

Definition at line 184 of file sensor.h.

◆ raw_callback_

CallbackManager<void(float)> esphome::sensor::Sensor::raw_callback_
protected

Storage for raw state callbacks.

Definition at line 179 of file sensor.h.

◆ raw_state [1/2]

float please use esphome::sensor::Sensor::raw_state

Definition at line 81 of file sensor.h.

◆ raw_state [2/2]

float esphome::sensor::Sensor::raw_state

This member variable stores the current raw state of the sensor.

Unlike .state, this will be updated immediately when publish_state is called.

Definition at line 128 of file sensor.h.

◆ state [1/2]

float please use esphome::sensor::Sensor::state

Definition at line 77 of file sensor.h.

◆ state [2/2]

float esphome::sensor::Sensor::state

This member variable stores the last state that has passed through all filters.

On startup, when no state is available yet, this is NAN (not-a-number) and the validity can be checked using has_state().

This is exposed through a member variable for ease of use in esphome lambdas.

Definition at line 123 of file sensor.h.

◆ unit_of_measurement_

optional<std::string> esphome::sensor::Sensor::unit_of_measurement_
protected

Override the unit of measurement.

Definition at line 182 of file sensor.h.


The documentation for this class was generated from the following files: