filter.h

Go to the documentation of this file.

#pragma once
 
#include "esphome/core/defines.h"
#ifdef USE_SENSOR_FILTER
 
#include <utility>
#include <vector>
#include "esphome/core/automation.h"
#include "esphome/core/component.h"
#include "esphome/core/helpers.h"
 
namespace esphome::sensor {
 
class Sensor;
 
class Filter {
 public:
  virtual optional<float> new_value(float value) = 0;
 
  virtual void initialize(Sensor *parent, Filter *next);
 
  void input(float value);
 
  void output(float value);
 
 protected:
  friend Sensor;
 
  Filter *next_{nullptr};
  Sensor *parent_{nullptr};
};
 
class SlidingWindowFilter : public Filter {
 public:
  SlidingWindowFilter(size_t window_size, size_t send_every, size_t send_first_at);
 
  optional<float> new_value(float value) final;
 
 protected:
  virtual float compute_result() = 0;
 
  FixedVector<float> window_;
  size_t window_head_{0};   
  size_t window_count_{0};  
  size_t window_size_;      
  size_t send_every_;       
  size_t send_at_;          
};
 
class MinMaxFilter : public SlidingWindowFilter {
 public:
  using SlidingWindowFilter::SlidingWindowFilter;
 
 protected:
  template<typename Compare> float find_extremum_() {
    float result = NAN;
    Compare comp;
    for (size_t i = 0; i < this->window_count_; i++) {
      float v = this->window_[i];
      if (!std::isnan(v)) {
        result = std::isnan(result) ? v : (comp(v, result) ? v : result);
      }
    }
    return result;
  }
};
 
class SortedWindowFilter : public SlidingWindowFilter {
 public:
  using SlidingWindowFilter::SlidingWindowFilter;
 
 protected:
  FixedVector<float> get_window_values_();
};
 
class QuantileFilter : public SortedWindowFilter {
 public:
  explicit QuantileFilter(size_t window_size, size_t send_every, size_t send_first_at, float quantile);
 
  void set_quantile(float quantile) { this->quantile_ = quantile; }
 
 protected:
  float compute_result() override;
  float quantile_;
};
 
class MedianFilter : public SortedWindowFilter {
 public:
  using SortedWindowFilter::SortedWindowFilter;
 
 protected:
  float compute_result() override;
};
 
class SkipInitialFilter : public Filter {
 public:
  explicit SkipInitialFilter(size_t num_to_ignore);
 
  optional<float> new_value(float value) override;
 
 protected:
  size_t num_to_ignore_;
};
 
class MinFilter : public MinMaxFilter {
 public:
  using MinMaxFilter::MinMaxFilter;
 
 protected:
  float compute_result() override;
};
 
class MaxFilter : public MinMaxFilter {
 public:
  using MinMaxFilter::MinMaxFilter;
 
 protected:
  float compute_result() override;
};
 
class SlidingWindowMovingAverageFilter : public SlidingWindowFilter {
 public:
  using SlidingWindowFilter::SlidingWindowFilter;
 
 protected:
  float compute_result() override;
};
 
class ExponentialMovingAverageFilter : public Filter {
 public:
  ExponentialMovingAverageFilter(float alpha, size_t send_every, size_t send_first_at);
 
  optional<float> new_value(float value) override;
 
  void set_send_every(size_t send_every);
  void set_alpha(float alpha);
 
 protected:
  float accumulator_{NAN};
  float alpha_;
  size_t send_every_;
  size_t send_at_;
  bool first_value_{true};
};
 
class ThrottleAverageFilter : public Filter, public Component {
 public:
  explicit ThrottleAverageFilter(uint32_t time_period);
 
  void setup() override;
 
  optional<float> new_value(float value) override;
 
  float get_setup_priority() const override;
 
 protected:
  float sum_{0.0f};
  unsigned int n_{0};
  uint32_t time_period_;
  bool have_nan_{false};
};
 
using lambda_filter_t = std::function<optional<float>(float)>;
 
class LambdaFilter : public Filter {
 public:
  explicit LambdaFilter(lambda_filter_t lambda_filter);
 
  optional<float> new_value(float value) override;
 
  const lambda_filter_t &get_lambda_filter() const;
  void set_lambda_filter(const lambda_filter_t &lambda_filter);
 
 protected:
  lambda_filter_t lambda_filter_;
};
 
class StatelessLambdaFilter : public Filter {
 public:
  explicit StatelessLambdaFilter(optional<float> (*lambda_filter)(float)) : lambda_filter_(lambda_filter) {}
 
  optional<float> new_value(float value) override { return this->lambda_filter_(value); }
 
 protected:
  optional<float> (*lambda_filter_)(float);
};
 
class OffsetFilter : public Filter {
 public:
  explicit OffsetFilter(TemplatableValue<float> offset);
 
  optional<float> new_value(float value) override;
 
 protected:
  TemplatableValue<float> offset_;
};
 
class MultiplyFilter : public Filter {
 public:
  explicit MultiplyFilter(TemplatableValue<float> multiplier);
  optional<float> new_value(float value) override;
 
 protected:
  TemplatableValue<float> multiplier_;
};
 
class ValueListFilter : public Filter {
 protected:
  explicit ValueListFilter(std::initializer_list<TemplatableValue<float>> values);
 
  bool value_matches_any_(float sensor_value);
 
  FixedVector<TemplatableValue<float>> values_;
};
 
class FilterOutValueFilter : public ValueListFilter {
 public:
  explicit FilterOutValueFilter(std::initializer_list<TemplatableValue<float>> values_to_filter_out);
 
  optional<float> new_value(float value) override;
};
 
class ThrottleFilter : public Filter {
 public:
  explicit ThrottleFilter(uint32_t min_time_between_inputs);
 
  optional<float> new_value(float value) override;
 
 protected:
  uint32_t last_input_{0};
  uint32_t min_time_between_inputs_;
};
 
class ThrottleWithPriorityFilter : public ValueListFilter {
 public:
  explicit ThrottleWithPriorityFilter(uint32_t min_time_between_inputs,
                                      std::initializer_list<TemplatableValue<float>> prioritized_values);
 
  optional<float> new_value(float value) override;
 
 protected:
  uint32_t last_input_{0};
  uint32_t min_time_between_inputs_;
};
 
// Base class for timeout filters - contains common loop logic
class TimeoutFilterBase : public Filter, public Component {
 public:
  void loop() override;
  float get_setup_priority() const override;
 
 protected:
  explicit TimeoutFilterBase(uint32_t time_period) : time_period_(time_period) { this->disable_loop(); }
  virtual float get_output_value() = 0;
 
  uint32_t time_period_;            // 4 bytes (timeout duration in ms)
  uint32_t timeout_start_time_{0};  // 4 bytes (when the timeout was started)
  // Total base: 8 bytes
};
 
// Timeout filter for "last" mode - outputs the last received value after timeout
class TimeoutFilterLast : public TimeoutFilterBase {
 public:
  explicit TimeoutFilterLast(uint32_t time_period) : TimeoutFilterBase(time_period) {}
 
  optional<float> new_value(float value) override;
 
 protected:
  float get_output_value() override { return this->pending_value_; }
  float pending_value_{0};  // 4 bytes (value to output when timeout fires)
  // Total: 8 (base) + 4 = 12 bytes + vtable ptr + Component overhead
};
 
// Timeout filter with configured value - evaluates TemplatableValue after timeout
class TimeoutFilterConfigured : public TimeoutFilterBase {
 public:
  explicit TimeoutFilterConfigured(uint32_t time_period, const TemplatableValue<float> &new_value)
      : TimeoutFilterBase(time_period), value_(new_value) {}
 
  optional<float> new_value(float value) override;
 
 protected:
  float get_output_value() override { return this->value_.value(); }
  TemplatableValue<float> value_;  // 16 bytes (configured output value, can be lambda)
  // Total: 8 (base) + 16 = 24 bytes + vtable ptr + Component overhead
};
 
class DebounceFilter : public Filter, public Component {
 public:
  explicit DebounceFilter(uint32_t time_period);
 
  optional<float> new_value(float value) override;
 
  float get_setup_priority() const override;
 
 protected:
  uint32_t time_period_;
};
 
class HeartbeatFilter : public Filter, public Component {
 public:
  explicit HeartbeatFilter(uint32_t time_period);
 
  void setup() override;
  optional<float> new_value(float value) override;
  float get_setup_priority() const override;
 
  void set_optimistic(bool optimistic) { this->optimistic_ = optimistic; }
 
 protected:
  uint32_t time_period_;
  float last_input_;
  bool has_value_{false};
  bool optimistic_{false};
};
 
class DeltaFilter : public Filter {
 public:
  explicit DeltaFilter(float min_a0, float min_a1, float max_a0, float max_a1);
 
  void set_baseline(float (*fn)(float));
 
  optional<float> new_value(float value) override;
 
 protected:
  // These values represent linear equations for the min and max values but in practice only one of a0 and a1 will be
  // non-zero Each limit is calculated as fabs(a0 + value * a1)
 
  float min_a0_, min_a1_, max_a0_, max_a1_;
  // default baseline is the previous value
  float (*baseline_)(float) = [](float last_value) { return last_value; };
 
  float last_value_{NAN};
};
 
class OrFilter : public Filter {
 public:
  explicit OrFilter(std::initializer_list<Filter *> filters);
 
  void initialize(Sensor *parent, Filter *next) override;
 
  optional<float> new_value(float value) override;
 
 protected:
  class PhiNode : public Filter {
   public:
    PhiNode(OrFilter *or_parent);
    optional<float> new_value(float value) override;
 
   protected:
    OrFilter *or_parent_;
  };
 
  FixedVector<Filter *> filters_;
  PhiNode phi_;
  bool has_value_{false};
};
 
class CalibrateLinearFilter : public Filter {
 public:
  explicit CalibrateLinearFilter(std::initializer_list<std::array<float, 3>> linear_functions);
  optional<float> new_value(float value) override;
 
 protected:
  FixedVector<std::array<float, 3>> linear_functions_;
};
 
class CalibratePolynomialFilter : public Filter {
 public:
  explicit CalibratePolynomialFilter(std::initializer_list<float> coefficients);
  optional<float> new_value(float value) override;
 
 protected:
  FixedVector<float> coefficients_;
};
 
class ClampFilter : public Filter {
 public:
  ClampFilter(float min, float max, bool ignore_out_of_range);
  optional<float> new_value(float value) override;
 
 protected:
  float min_{NAN};
  float max_{NAN};
  bool ignore_out_of_range_;
};
 
class RoundFilter : public Filter {
 public:
  explicit RoundFilter(uint8_t precision);
  optional<float> new_value(float value) override;
 
 protected:
  uint8_t precision_;
};
 
class RoundMultipleFilter : public Filter {
 public:
  explicit RoundMultipleFilter(float multiple);
  optional<float> new_value(float value) override;
 
 protected:
  float multiple_;
};
 
class ToNTCResistanceFilter : public Filter {
 public:
  ToNTCResistanceFilter(double a, double b, double c) : a_(a), b_(b), c_(c) {}
  optional<float> new_value(float value) override;
 
 protected:
  double a_;
  double b_;
  double c_;
};
 
class ToNTCTemperatureFilter : public Filter {
 public:
  ToNTCTemperatureFilter(double a, double b, double c) : a_(a), b_(b), c_(c) {}
  optional<float> new_value(float value) override;
 
 protected:
  double a_;
  double b_;
  double c_;
};
 
class StreamingFilter : public Filter {
 public:
  StreamingFilter(size_t window_size, size_t send_first_at);
 
  optional<float> new_value(float value) final;
 
 protected:
  virtual void process_value(float value) = 0;
 
  virtual float compute_batch_result() = 0;
 
  virtual void reset_batch() = 0;
 
  size_t window_size_;
  size_t count_{0};
  size_t send_first_at_;
  bool first_send_{true};
};
 
class StreamingMinFilter : public StreamingFilter {
 public:
  using StreamingFilter::StreamingFilter;
 
 protected:
  void process_value(float value) override;
  float compute_batch_result() override;
  void reset_batch() override;
 
  float current_min_{NAN};
};
 
class StreamingMaxFilter : public StreamingFilter {
 public:
  using StreamingFilter::StreamingFilter;
 
 protected:
  void process_value(float value) override;
  float compute_batch_result() override;
  void reset_batch() override;
 
  float current_max_{NAN};
};
 
class StreamingMovingAverageFilter : public StreamingFilter {
 public:
  using StreamingFilter::StreamingFilter;
 
 protected:
  void process_value(float value) override;
  float compute_batch_result() override;
  void reset_batch() override;
 
  float sum_{0.0f};
  size_t valid_count_{0};
};
 
}  // namespace esphome::sensor
 
#endif  // USE_SENSOR_FILTER