Sensor

The sensor namespace contains all sensors.

See Application::register_sensor().

API Reference

Sensor

class sensor::Sensor

Base-class for all sensors.

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

Inherits from Nameable

Subclassed by sensor::EmptySensor< 3, ICON_FLASH, UNIT_V >, sensor::EmptySensor< default_accuracy_decimals, default_icon, default_unit_of_measurement >, sensor::PollingSensorComponent, sensor::RotaryEncoderSensor

Public Functions

sensor::SensorSensor(const std::string &name)
void sensor::Sensorset_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_measurement: The unit of measurement, “” to disable.

void sensor::Sensorset_icon(const std::string &icon)

Manually set the icon of this sensor.

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

Parameters
  • icon: The icon, for example “mdi:flash”. “” to disable.

void sensor::Sensorset_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_decimals: The accuracy decimal that should be used.

void sensor::Sensoradd_filter(Filter *filter)

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

void sensor::Sensoradd_filters(const std::list<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 });

void sensor::Sensorset_filters(const std::list<Filter *> &filters)

Clear the filters and replace them by filters.

void sensor::Sensoradd_lambda_filter(lambda_filter_t filter)

Add a lambda filter to the back of the filter chain.

For example: sensor->add_lambda_filter([](float value) -> optional<float> { return value * 42; });

If you return an unset Optional, the value will be discarded and no filters after this one will get the value.

void sensor::Sensoradd_offset_filter(float offset)

Helper to add a simple offset filter to the back of the filter chain.

This can be used to easily correct for sensors that have a small offset in their value reporting.

Parameters
  • offset: The offset that will be added to each value.

void sensor::Sensoradd_multiply_filter(float multiplier)

Helper to add a simple multiply filter to the back of the filter chain.

Each value will be multiplied by this multiplier. Can be used to convert units easily. For example converting “pulses/min” to a more reasonable unit like kW.

Parameters
  • multiplier: The multiplier each value will be multiplied with.

void sensor::Sensoradd_filter_out_value_filter(float values_to_filter_out)

Helper to add a simple filter that aborts the filter chain every time it receives a specific value.

Parameters
  • values_to_filter_out: The value that should be filtered out.

void sensor::Sensoradd_sliding_window_average_filter(size_t window_size, size_t send_every)

Helper to make adding sliding window moving average filters a bit easier.

void sensor::Sensoradd_exponential_moving_average_filter(float alpha, size_t send_every)

Helper to make adding exponential decay average filters a bit easier.

void sensor::Sensorclear_filters()

Clear the entire filter chain.

float sensor::Sensorget_value() const

Get the latest filtered value from this sensor.

float sensor::Sensorget_raw_value() const

Get the latest raw value from this sensor.

int8_t sensor::Sensorget_accuracy_decimals()

Get the accuracy in decimals used by this MQTT Sensor, first checks override, then sensor.

std::string sensor::Sensorget_unit_of_measurement()

Get the unit of measurements advertised to Home Assistant. First checks override, then sensor.

std::string sensor::Sensorget_icon()

Get the icon advertised to Home Assistant.

void sensor::Sensorpush_new_value(float value)

Push a new value to the MQTT front-end.

Note that you should publish the raw value here, i.e. without any rounding as the user can later override this accuracy.

Parameters
  • value: The floating point value.

std::string sensor::Sensorunit_of_measurement()

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

Return “” to disable this feature.

Return
The icon of this sensor, for example “°C”.

std::string sensor::Sensoricon()

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

Return “” to disable this feature.

Return
The icon of this sensor, for example “mdi:battery”.

uint32_t sensor::Sensorupdate_interval()

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

int8_t sensor::Sensoraccuracy_decimals()

Return the accuracy in decimals for this sensor.

void sensor::Sensoradd_on_value_callback(sensor_callback_t callback)

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

void sensor::Sensoradd_on_raw_value_callback(sensor_callback_t callback)

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

std::string sensor::Sensorunique_id()

A unique ID for this sensor, empty for no unique id.

See unique ID requirements: https://developers.home-assistant.io/docs/en/entity_registry_index.html#unique-id-requirements

Return
The unique id as a string.

SensorValueTrigger *sensor::Sensormake_value_trigger()
RawSensorValueTrigger *sensor::Sensormake_raw_value_trigger()
ValueRangeTrigger *sensor::Sensormake_value_range_trigger()

Public Members

float sensor::Sensorvalue = {NAN}

Stores the last filtered value. Public because of lambdas.

float sensor::Sensorraw_value = {NAN}

Stores the last raw value. Public because of lambdas.

Protected Functions

void sensor::Sensorsend_value_to_frontend(float value)

Protected Attributes

friend sensor::Sensor::Filter
friend sensor::Sensor::MQTTSensorComponent
CallbackManager<void(float)> sensor::Sensorraw_callback_

Storage for raw value callbacks.

CallbackManager<void(float)> sensor::Sensorcallback_

Storage for filtered value callbacks.

optional<std::string> sensor::Sensorunit_of_measurement_

Override the unit of measurement.

optional<std::string> sensor::Sensoricon_
optional<int8_t> sensor::Sensoraccuracy_decimals_

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

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

Filter *sensor::Sensorfilter_list_ = {nullptr}

Store all active filters.

using sensor::sensor_callback_t = typedef std::function<void(float)>
class sensor::PollingSensorComponent

Inherits from PollingComponent, sensor::Sensor

Subclassed by sensor::ADCSensorComponent, sensor::BH1750Sensor, sensor::DutyCycleSensor, sensor::ESP32HallSensor, sensor::MAX6675Sensor, sensor::PulseCounterSensorComponent, sensor::TemplateSensor, sensor::TSL2561Sensor, sensor::UltrasonicSensorComponent, sensor::WiFiSignalSensor

Public Functions

sensor::PollingSensorComponentPollingSensorComponent(const std::string &name, uint32_t update_interval)
uint32_t sensor::PollingSensorComponentupdate_interval()

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

template <int8_t default_accuracy_decimals, const char * default_icon, const char * default_unit_of_measurement>
class sensor::EmptySensor

Inherits from sensor::Sensor

Subclassed by sensor::EmptyPollingParentSensor< 1, ICON_EMPTY, UNIT_C, DallasComponent >, sensor::EmptyPollingParentSensor< 1, ICON_EMPTY, UNIT_C, SHT3XDComponent >, sensor::EmptyPollingParentSensor< 1, ICON_WATER_PERCENT, UNIT_PERCENT, SHT3XDComponent >, sensor::EmptyPollingParentSensor< default_accuracy_decimals, default_icon, default_unit_of_measurement, ParentType >

Public Functions

sensor::EmptySensorEmptySensor(const std::string &name)
std::string sensor::EmptySensorunit_of_measurement()

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

Return “” to disable this feature.

Return
The icon of this sensor, for example “°C”.

std::string sensor::EmptySensoricon()

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

Return “” to disable this feature.

Return
The icon of this sensor, for example “mdi:battery”.

int8_t sensor::EmptySensoraccuracy_decimals()

Return the accuracy in decimals for this sensor.

template <int8_t default_accuracy_decimals, const char * default_icon, const char * default_unit_of_measurement, class ParentType>
class sensor::EmptyPollingParentSensor

Inherits from sensor::EmptySensor< default_accuracy_decimals, default_icon, default_unit_of_measurement >

Public Functions

sensor::EmptyPollingParentSensorEmptyPollingParentSensor(const std::string &name, ParentType *parent)
uint32_t sensor::EmptyPollingParentSensorupdate_interval()

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

Protected Attributes

ParentType *sensor::EmptyPollingParentSensorparent_
const char sensor::ICON_EMPTY = ""
const char sensor::ICON_WATER_PERCENT = "mdi:water-percent"
const char sensor::ICON_GAUGE = "mdi:gauge"
const char sensor::ICON_FLASH = "mdi:flash"
const char sensor::ICON_SCREEN_ROTATION = "mdi:screen-rotation"
const char sensor::ICON_BRIEFCASE_DOWNLOAD = "mdi:briefcase-download"
const char sensor::UNIT_C = "°C"
const char sensor::UNIT_PERCENT = "%"
const char sensor::UNIT_HPA = "hPa"
const char sensor::UNIT_V = "V"
const char sensor::UNIT_DEGREES_PER_SECOND = "°/s"
const char sensor::UNIT_M_PER_S_SQUARED = "m/s²"

Filter

class sensor::Filter

Apply a filter to sensor values such as moving average.

This class is purposefully kept quite simple, since more complicated filters should really be done with the filter sensor in Home Assistant.

Subclassed by sensor::DebounceFilter, sensor::DeltaFilter, sensor::ExponentialMovingAverageFilter, sensor::FilterOutNANFilter, sensor::FilterOutValueFilter, sensor::HeartbeatFilter, sensor::LambdaFilter, sensor::MultiplyFilter, sensor::OffsetFilter, sensor::OrFilter, sensor::SlidingWindowMovingAverageFilter, sensor::ThrottleFilter, sensor::UniqueFilter

Public Functions

virtual optional<float> sensor::Filternew_value(float value) = 0

This will be called every time the filter receives a new value.

It can return an empty optional to indicate that the filter chain should stop, otherwise the value in the filter will be passed down the chain.

Return
An optional float, the new value that should be pushed out.
Parameters
  • value: The new value.

sensor::Filter~Filter()
void sensor::Filterinitialize(std::function<void(float)> &&output)
void sensor::Filterinput(float value)
uint32_t sensor::Filterexpected_interval(uint32_t input)

Return the amount of time that this filter is expected to take based on the input time interval.

Protected Attributes

friend sensor::Filter::Sensor
friend sensor::Filter::MQTTSensorComponent
std::function<void(float)> sensor::Filteroutput_
Filter *sensor::Filternext_ = {nullptr}
class sensor::SlidingWindowMovingAverageFilter

Simple sliding window moving average filter.

Essentially just takes takes the average of the last window_size values and pushes them out every send_every.

Inherits from sensor::Filter

Public Functions

sensor::SlidingWindowMovingAverageFilterSlidingWindowMovingAverageFilter(size_t window_size, size_t send_every)

Construct a SlidingWindowMovingAverageFilter.

Parameters
  • window_size: The number of values that should be averaged.
  • send_every: After how many sensor values should a new one be pushed out.

optional<float> sensor::SlidingWindowMovingAverageFilternew_value(float value)

This will be called every time the filter receives a new value.

It can return an empty optional to indicate that the filter chain should stop, otherwise the value in the filter will be passed down the chain.

Return
An optional float, the new value that should be pushed out.
Parameters
  • value: The new value.

size_t sensor::SlidingWindowMovingAverageFilterget_send_every() const
void sensor::SlidingWindowMovingAverageFilterset_send_every(size_t send_every)
size_t sensor::SlidingWindowMovingAverageFilterget_window_size() const
void sensor::SlidingWindowMovingAverageFilterset_window_size(size_t window_size)
uint32_t sensor::SlidingWindowMovingAverageFilterexpected_interval(uint32_t input)

Return the amount of time that this filter is expected to take based on the input time interval.

Protected Attributes

SlidingWindowMovingAverage sensor::SlidingWindowMovingAverageFiltervalue_average_
size_t sensor::SlidingWindowMovingAverageFiltersend_every_
size_t sensor::SlidingWindowMovingAverageFiltersend_at_
class sensor::ExponentialMovingAverageFilter

Simple exponential moving average filter.

Essentially just takes the average of the last few values using exponentially decaying weights. Use alpha to adjust decay rate.

Inherits from sensor::Filter

Public Functions

sensor::ExponentialMovingAverageFilterExponentialMovingAverageFilter(float alpha, size_t send_every)
optional<float> sensor::ExponentialMovingAverageFilternew_value(float value)

This will be called every time the filter receives a new value.

It can return an empty optional to indicate that the filter chain should stop, otherwise the value in the filter will be passed down the chain.

Return
An optional float, the new value that should be pushed out.
Parameters
  • value: The new value.

size_t sensor::ExponentialMovingAverageFilterget_send_every() const
void sensor::ExponentialMovingAverageFilterset_send_every(size_t send_every)
float sensor::ExponentialMovingAverageFilterget_alpha() const
void sensor::ExponentialMovingAverageFilterset_alpha(float alpha)
uint32_t sensor::ExponentialMovingAverageFilterexpected_interval(uint32_t input)

Return the amount of time that this filter is expected to take based on the input time interval.

Protected Attributes

ExponentialMovingAverage sensor::ExponentialMovingAverageFiltervalue_average_
ExponentialMovingAverage sensor::ExponentialMovingAverageFilteraccuracy_average_
size_t sensor::ExponentialMovingAverageFiltersend_every_
size_t sensor::ExponentialMovingAverageFiltersend_at_
using sensor::lambda_filter_t = typedef std::function<optional<float>(float)>
class sensor::LambdaFilter

This class allows for creation of simple template filters.

The constructor accepts a lambda of the form float -> optional<float>. It will be called with each new value in the filter chain and returns the modified value that shall be passed down the filter chain. Returning an empty Optional means that the value shall be discarded.

Inherits from sensor::Filter

Public Functions

sensor::LambdaFilterLambdaFilter(lambda_filter_t lambda_filter)
optional<float> sensor::LambdaFilternew_value(float value)

This will be called every time the filter receives a new value.

It can return an empty optional to indicate that the filter chain should stop, otherwise the value in the filter will be passed down the chain.

Return
An optional float, the new value that should be pushed out.
Parameters
  • value: The new value.

const lambda_filter_t &sensor::LambdaFilterget_lambda_filter() const
void sensor::LambdaFilterset_lambda_filter(const lambda_filter_t &lambda_filter)

Protected Attributes

lambda_filter_t sensor::LambdaFilterlambda_filter_
class sensor::OffsetFilter

A simple filter that adds offset to each value it receives.

Inherits from sensor::Filter

Public Functions

sensor::OffsetFilterOffsetFilter(float offset)
optional<float> sensor::OffsetFilternew_value(float value)

This will be called every time the filter receives a new value.

It can return an empty optional to indicate that the filter chain should stop, otherwise the value in the filter will be passed down the chain.

Return
An optional float, the new value that should be pushed out.
Parameters
  • value: The new value.

Protected Attributes

float sensor::OffsetFilteroffset_
class sensor::MultiplyFilter

A simple filter that multiplies to each value it receives by multiplier.

Inherits from sensor::Filter

Public Functions

sensor::MultiplyFilterMultiplyFilter(float multiplier)
optional<float> sensor::MultiplyFilternew_value(float value)

This will be called every time the filter receives a new value.

It can return an empty optional to indicate that the filter chain should stop, otherwise the value in the filter will be passed down the chain.

Return
An optional float, the new value that should be pushed out.
Parameters
  • value: The new value.

Protected Attributes

float sensor::MultiplyFiltermultiplier_
class sensor::FilterOutValueFilter

A simple filter that only forwards the filter chain if it doesn’t receive value_to_filter_out.

Inherits from sensor::Filter

Public Functions

sensor::FilterOutValueFilterFilterOutValueFilter(float values_to_filter_out)
optional<float> sensor::FilterOutValueFilternew_value(float value)

This will be called every time the filter receives a new value.

It can return an empty optional to indicate that the filter chain should stop, otherwise the value in the filter will be passed down the chain.

Return
An optional float, the new value that should be pushed out.
Parameters
  • value: The new value.

Protected Attributes

float sensor::FilterOutValueFiltervalue_to_filter_out_
class sensor::FilterOutNANFilter

A simple filter that only forwards the filter chain if it doesn’t receive nan.

Inherits from sensor::Filter

Public Functions

optional<float> sensor::FilterOutNANFilternew_value(float value)

This will be called every time the filter receives a new value.

It can return an empty optional to indicate that the filter chain should stop, otherwise the value in the filter will be passed down the chain.

Return
An optional float, the new value that should be pushed out.
Parameters
  • value: The new value.

class sensor::ThrottleFilter

Inherits from sensor::Filter

Public Functions

sensor::ThrottleFilterThrottleFilter(uint32_t min_time_between_inputs)
optional<float> sensor::ThrottleFilternew_value(float value)

This will be called every time the filter receives a new value.

It can return an empty optional to indicate that the filter chain should stop, otherwise the value in the filter will be passed down the chain.

Return
An optional float, the new value that should be pushed out.
Parameters
  • value: The new value.

Protected Attributes

uint32_t sensor::ThrottleFilterlast_input_ = {0}
uint32_t sensor::ThrottleFiltermin_time_between_inputs_
class sensor::HeartbeatFilter

Inherits from sensor::Filter, Component

Public Functions

sensor::HeartbeatFilterHeartbeatFilter(uint32_t time_period)
void sensor::HeartbeatFiltersetup()

Where the component’s initialization should happen.

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

optional<float> sensor::HeartbeatFilternew_value(float value)

This will be called every time the filter receives a new value.

It can return an empty optional to indicate that the filter chain should stop, otherwise the value in the filter will be passed down the chain.

Return
An optional float, the new value that should be pushed out.
Parameters
  • value: The new value.

uint32_t sensor::HeartbeatFilterexpected_interval(uint32_t input)

Return the amount of time that this filter is expected to take based on the input time interval.

Protected Attributes

uint32_t sensor::HeartbeatFiltertime_period_
float sensor::HeartbeatFilterlast_input_
class sensor::DebounceFilter

Inherits from sensor::Filter, Component

Public Functions

sensor::DebounceFilterDebounceFilter(uint32_t time_period)
optional<float> sensor::DebounceFilternew_value(float value)

This will be called every time the filter receives a new value.

It can return an empty optional to indicate that the filter chain should stop, otherwise the value in the filter will be passed down the chain.

Return
An optional float, the new value that should be pushed out.
Parameters
  • value: The new value.

Protected Attributes

uint32_t sensor::DebounceFiltertime_period_
class sensor::DeltaFilter

Inherits from sensor::Filter

Public Functions

sensor::DeltaFilterDeltaFilter(float min_delta)
optional<float> sensor::DeltaFilternew_value(float value)

This will be called every time the filter receives a new value.

It can return an empty optional to indicate that the filter chain should stop, otherwise the value in the filter will be passed down the chain.

Return
An optional float, the new value that should be pushed out.
Parameters
  • value: The new value.

Protected Attributes

float sensor::DeltaFiltermin_delta_
float sensor::DeltaFilterlast_value_ = {NAN}
class sensor::OrFilter

Inherits from sensor::Filter

Public Functions

sensor::OrFilterOrFilter(std::list<Filter *> filters)
sensor::OrFilter~OrFilter()
void sensor::OrFilterinitialize(std::function<void(float)> &&output)
uint32_t sensor::OrFilterexpected_interval(uint32_t input)

Return the amount of time that this filter is expected to take based on the input time interval.

optional<float> sensor::OrFilternew_value(float value)

This will be called every time the filter receives a new value.

It can return an empty optional to indicate that the filter chain should stop, otherwise the value in the filter will be passed down the chain.

Return
An optional float, the new value that should be pushed out.
Parameters
  • value: The new value.

Protected Attributes

std::list<Filter *> sensor::OrFilterfilters_
class sensor::UniqueFilter

Inherits from sensor::Filter

Public Functions

optional<float> sensor::UniqueFilternew_value(float value)

This will be called every time the filter receives a new value.

It can return an empty optional to indicate that the filter chain should stop, otherwise the value in the filter will be passed down the chain.

Return
An optional float, the new value that should be pushed out.
Parameters
  • value: The new value.

Protected Attributes

float sensor::UniqueFilterlast_value_ = {NAN}

MQTTSensorComponent

class sensor::MQTTSensorComponent

Class that exposes sensors to the MQTT frontend.

Inherits from mqtt::MQTTComponent

Public Functions

sensor::MQTTSensorComponentMQTTSensorComponent(Sensor *sensor)

Construct this MQTTSensorComponent instance with the provided friendly_name and sensor.

Note the sensor is never stored and is only used for initializing some values of this class. If sensor is nullptr, then automatic initialization of these fields is disabled.

Parameters
  • sensor: The sensor, this can be null to disable automatic setup.

void sensor::MQTTSensorComponentset_expire_after(uint32_t expire_after)

Setup an expiry, 0 disables it.

void sensor::MQTTSensorComponentdisable_expire_after()

Disable Home Assistant value exiry.

void sensor::MQTTSensorComponentsend_discovery(JsonBuffer &buffer, JsonObject &root, mqtt::SendDiscoveryConfig &config)

Send discovery info the Home Assistant, override this.

void sensor::MQTTSensorComponentsetup()

Override setup.

uint32_t sensor::MQTTSensorComponentget_expire_after() const

Get the expire_after in milliseconds used for Home Assistant discovery, first checks override.

void sensor::MQTTSensorComponentpublish_state(float value)
void sensor::MQTTSensorComponentsend_initial_state()
bool sensor::MQTTSensorComponentis_internal()

Protected Functions

std::string sensor::MQTTSensorComponentcomponent_type() const

Override for MQTTComponent, returns “sensor”.

std::string sensor::MQTTSensorComponentfriendly_name() const

Get the friendly name of this MQTT component.

Protected Attributes

Sensor *sensor::MQTTSensorComponentsensor_
optional<uint32_t> sensor::MQTTSensorComponentexpire_after_