filter.h

Go to the documentation of this file.

#pragma once
 
#include "esphome/core/defines.h"
#ifdef USE_SENSOR_FILTER
 
#include <array>
#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(uint16_t window_size, uint16_t send_every, uint16_t send_first_at);
 
  optional<float> new_value(float value) final;
 
 protected:
  virtual float compute_result() = 0;
 
  FixedRingBuffer<float> window_;
  uint16_t send_every_;  
  uint16_t send_at_;     
};
 
class MinMaxFilter : public SlidingWindowFilter {
 public:
  using SlidingWindowFilter::SlidingWindowFilter;
 
 protected:
  template<typename Compare> float find_extremum_() {
    float result = NAN;
    Compare comp;
    for (float v : this->window_) {
      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, uint16_t send_every, uint16_t send_first_at);
 
  optional<float> new_value(float value) override;
 
  void set_send_every(uint16_t send_every);
  void set_alpha(float alpha);
 
 protected:
  float accumulator_{NAN};
  float alpha_;
  uint16_t send_every_;
  uint16_t send_at_;
  bool first_value_{true};
};
 
class ThrottleAverageFilter : public Filter {
 public:
  explicit ThrottleAverageFilter(uint32_t time_period);
 
  void initialize(Sensor *parent, Filter *next) override;
 
  optional<float> new_value(float value) override;
 
 protected:
  float sum_{0.0f};
  uint32_t time_period_;
  // Sample count packed with NaN-seen flag in a single 32-bit word.
  // n_ is bounded by YAML cap on time_period_ (24 h) × max plausible source
  // rate (1 kHz) = 86.4M ≪ 2^31, so 31 bits has 25x headroom.
  uint32_t n_ : 31 {0};
  uint32_t have_nan_ : 1 {0};
};
 
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(TemplatableFn<float> offset);
 
  optional<float> new_value(float value) override;
 
 protected:
  TemplatableFn<float> offset_;
};
 
class MultiplyFilter : public Filter {
 public:
  explicit MultiplyFilter(TemplatableFn<float> multiplier);
  optional<float> new_value(float value) override;
 
 protected:
  TemplatableFn<float> multiplier_;
};
 
bool value_list_matches_any(Sensor *parent, float sensor_value, const TemplatableFn<float> *values, size_t count);
 
template<size_t N> class ValueListFilter : public Filter {
 protected:
  explicit ValueListFilter(std::initializer_list<TemplatableFn<float>> values) {
    init_array_from(this->values_, values);
  }
 
  bool value_matches_any_(float sensor_value) {
    return value_list_matches_any(this->parent_, sensor_value, this->values_.data(), N);
  }
 
  std::array<TemplatableFn<float>, N> values_{};
};
 
template<size_t N> class FilterOutValueFilter : public ValueListFilter<N> {
 public:
  explicit FilterOutValueFilter(std::initializer_list<TemplatableFn<float>> values_to_filter_out)
      : ValueListFilter<N>(values_to_filter_out) {}
 
  optional<float> new_value(float value) override {
    if (this->value_matches_any_(value))
      return {};   // Filter out
    return value;  // Pass through
  }
};
 
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_;
};
 
optional<float> throttle_with_priority_new_value(Sensor *parent, float value, const TemplatableFn<float> *values,
                                                 size_t count, uint32_t &last_input, uint32_t min_time_between_inputs);
 
template<size_t N> class ThrottleWithPriorityFilter : public ValueListFilter<N> {
 public:
  explicit ThrottleWithPriorityFilter(uint32_t min_time_between_inputs,
                                      std::initializer_list<TemplatableFn<float>> prioritized_values)
      : ValueListFilter<N>(prioritized_values), min_time_between_inputs_(min_time_between_inputs) {}
 
  optional<float> new_value(float value) override {
    return throttle_with_priority_new_value(this->parent_, value, this->values_.data(), N, this->last_input_,
                                            this->min_time_between_inputs_);
  }
 
 protected:
  uint32_t last_input_{0};
  uint32_t min_time_between_inputs_;
};
 
class ThrottleWithPriorityNanFilter : public Filter {
 public:
  explicit ThrottleWithPriorityNanFilter(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_;
};
 
// Base class for timeout filters - contains common loop logic.
//
// Why this intentionally inherits Component (and does NOT use the self-keyed
// `App.scheduler.set_timeout(this, ...)` pattern that the other Filter classes
// migrated to):
//
// Timeout filters re-arm on every input, so on devices with many sensors
// using timeout filters (e.g. multi-LD2450 boards) every armed filter would
// require a live SchedulerItem in RAM at the same time. A SchedulerItem is
// substantially larger than the Component bookkeeping bytes carried by this
// class, so paying the Component cost per filter (one-time, BSS) is cheaper
// than paying for a SchedulerItem per filter (live, while armed). #11922
// is the original symptom and switchover to the loop-based design; #16173
// attempted to migrate this onto the scheduler and was closed for exactly
// this reason — even if the scheduler pool were unbounded, RAM per armed
// filter would still be dominated by the SchedulerItem itself, not by
// anything we can shrink in the scheduler.
//
// The loop-based design has additional advantages on top of the RAM win:
// `enable_loop()` / `disable_loop()` partitions the cost away when no
// timeout is armed; while armed, work is a single timestamp compare per
// active filter, with no per-input scheduler cancel/insert path.
//
// Don't try to migrate this class onto the self-keyed scheduler. The math
// doesn't work — at scale, this design is the smaller one.
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 TemplatableFn<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(); }
  TemplatableFn<float> value_;  // 4 bytes (configured output value, can be lambda)
  // Total: 8 (base) + 4 = 12 bytes + vtable ptr + Component overhead
};
 
class DebounceFilter : public Filter {
 public:
  explicit DebounceFilter(uint32_t time_period);
 
  optional<float> new_value(float value) override;
 
 protected:
  uint32_t time_period_;
};
 
class HeartbeatFilter : public Filter {
 public:
  explicit HeartbeatFilter(uint32_t time_period);
 
  void initialize(Sensor *parent, Filter *next) override;
  optional<float> new_value(float value) 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};
};
 
void or_filter_initialize(Filter **filters, size_t count, Sensor *parent, Filter *phi);
optional<float> or_filter_new_value(Filter **filters, size_t count, float value, bool &has_value);
 
template<size_t N> class OrFilter : public Filter {
 public:
  explicit OrFilter(std::initializer_list<Filter *> filters) { init_array_from(this->filters_, filters); }
 
  void initialize(Sensor *parent, Filter *next) override {
    Filter::initialize(parent, next);
    or_filter_initialize(this->filters_.data(), N, parent, &this->phi_);
  }
 
  optional<float> new_value(float value) override {
    return or_filter_new_value(this->filters_.data(), N, value, this->has_value_);
  }
 
 protected:
  class PhiNode : public Filter {
   public:
    PhiNode(OrFilter *or_parent) : or_parent_(or_parent) {}
    optional<float> new_value(float value) override {
      if (!this->or_parent_->has_value_) {
        this->or_parent_->output(value);
        this->or_parent_->has_value_ = true;
      }
      return {};
    }
 
   protected:
    OrFilter *or_parent_;
  };
 
  std::array<Filter *, N> filters_{};
  PhiNode phi_{this};
  bool has_value_{false};
};
 
optional<float> calibrate_linear_compute(const std::array<float, 3> *functions, size_t count, float value);
 
template<size_t N> class CalibrateLinearFilter : public Filter {
 public:
  explicit CalibrateLinearFilter(std::initializer_list<std::array<float, 3>> linear_functions) {
    init_array_from(this->linear_functions_, linear_functions);
  }
  optional<float> new_value(float value) override {
    return calibrate_linear_compute(this->linear_functions_.data(), N, value);
  }
 
 protected:
  std::array<std::array<float, 3>, N> linear_functions_{};
};
 
optional<float> calibrate_polynomial_compute(const float *coefficients, size_t count, float value);
 
template<size_t N> class CalibratePolynomialFilter : public Filter {
 public:
  explicit CalibratePolynomialFilter(std::initializer_list<float> coefficients) {
    init_array_from(this->coefficients_, coefficients);
  }
  optional<float> new_value(float value) override {
    return calibrate_polynomial_compute(this->coefficients_.data(), N, value);
  }
 
 protected:
  std::array<float, N> 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_;
};
 
template<uint8_t Digits> class RoundSignificantDigitsFilter : public Filter {
 public:
  optional<float> new_value(float value) override {
    if (std::isfinite(value)) {
      if (value == 0.0f)
        return 0.0f;
      float factor = pow10_int(Digits - 1 - ilog10(value));
      return roundf(value * factor) / factor;
    }
    return value;
  }
};
 
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(uint16_t window_size, uint16_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;
 
  uint16_t window_size_;
  uint16_t count_{0};
  uint16_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