Arduino Helpers master
Utility library for Arduino
Public Member Functions | Static Public Member Functions | Static Public Attributes | Private Attributes | List of all members
EMA< K, input_t, state_t > Class Template Reference

#include <AH/Filters/EMA.hpp>

Detailed Description

template<uint8_t K, class input_t = uint_fast16_t, class state_t = typename std::make_unsigned<input_t>::type>
class EMA< K, input_t, state_t >

Exponential moving average filter.

Fast integer EMA implementation where the weight factor is a power of two.

Difference equation: \( y[n] = \alpha·x[n]+(1-\alpha)·y[n-1] \) where \( \alpha = \left(\frac{1}{2}\right)^{K} \), \( x \) is the input sequence, and \( y \) is the output sequence.

An in-depth explanation of the EMA filter

Template Parameters
KThe amount of bits to shift by. This determines the location of the pole in the EMA transfer function, and therefore the cut-off frequency.
The higher this number, the more filtering takes place.
The pole location is \( 1 - 2^{-K} \).
input_tThe integer type to use for the input and output of the filter. Can be signed or unsigned.
state_tThe unsigned integer type to use for the internal state of the filter. A fixed-point representation with \( K \) fractional bits is used, so this type should be at least \( M + K \) bits wide, where \( M \) is the maximum number of bits of the input.

Some examples of different combinations of template parameters:

  1. Filtering the result of analogRead: analogRead returns an integer between 0 and 1023, which can be represented using 10 bits, so \( M = 10 \). If input_t and output_t are both uint16_t, the maximum shift factor K is \( 16 - M = 6 \). If state_t is increased to uint32_t, the maximum shift factor K is \( 32 - M = 22 \).
  2. Filtering a signed integer between -32768 and 32767: this can be represented using a 16-bit signed integer, so input_t is int16_t, and \( M = 16 \). (2¹⁵ = 32768) Let's say the shift factor K is 1, then the minimum width of state_t should be \( M + K = 17 \) bits, so uint32_t would be a sensible choice.

Definition at line 59 of file EMA.hpp.

+ Collaboration diagram for EMA< K, input_t, state_t >:

Public Member Functions

 EMA (input_t initial=input_t{0})
 Constructor: initialize filter to zero or optional given value. More...
 
void reset (input_t value=input_t(0))
 Reset the filter to the given value. More...
 
input_t filter (input_t input)
 Filter the input: Given \( x[n] \), calculate \( y[n] \). More...
 
input_t operator() (input_t input)
 Filter the input: Given \( x[n] \), calculate \( y[n] \). More...
 

Static Public Member Functions

template<class T >
static constexpr bool supports_range (T min, T max)
 Verify the input range to make sure it's compatible with the shift factor and the width of the state type. More...
 

Static Public Attributes

static constexpr state_t max_state = std::numeric_limits<state_t>::max()
 
static constexpr state_t half_state = max_state / 2 + 1
 
static constexpr state_t zero = std::is_unsigned<input_t>::value ? state_t{0} : half_state
 
static constexpr state_t half = K > 0 ? state_t{1} << (K - 1) : state_t{0}
 

Private Attributes

state_t state
 

Constructor & Destructor Documentation

◆ EMA()

EMA ( input_t  initial = input_t{0})
inline

Constructor: initialize filter to zero or optional given value.

Definition at line 62 of file EMA.hpp.

Member Function Documentation

◆ reset()

void reset ( input_t  value = input_t(0))
inline

Reset the filter to the given value.

Parameters
valueThe value to reset the filter state to.

Definition at line 70 of file EMA.hpp.

◆ filter()

input_t filter ( input_t  input)
inline

Filter the input: Given \( x[n] \), calculate \( y[n] \).

Parameters
inputThe new raw input value.
Returns
The new filtered output value.

Definition at line 82 of file EMA.hpp.

◆ operator()()

input_t operator() ( input_t  input)
inline

Filter the input: Given \( x[n] \), calculate \( y[n] \).

Parameters
inputThe new raw input value.
Returns
The new filtered output value.

Definition at line 91 of file EMA.hpp.

◆ supports_range()

static constexpr bool supports_range ( min,
max 
)
inlinestaticconstexpr

Verify the input range to make sure it's compatible with the shift factor and the width of the state type.

Examples:

static_assert(filter.supports_range(-1024, 1023),
"use a wider state or input type, or a smaller shift factor");
Exponential moving average filter.
Definition: EMA.hpp:59
input_t filter(input_t input)
Filter the input: Given , calculate .
Definition: EMA.hpp:82
static_assert(filter.supports_range(0u, 2047u),
"use a wider state or input type, or a smaller shift factor");

Definition at line 122 of file EMA.hpp.

Member Data Documentation

◆ max_state

constexpr state_t max_state = std::numeric_limits<state_t>::max()
staticconstexpr

Definition at line 96 of file EMA.hpp.

◆ half_state

constexpr state_t half_state = max_state / 2 + 1
static

Definition at line 97 of file EMA.hpp.

◆ zero

constexpr state_t zero = std::is_unsigned<input_t>::value ? state_t{0} : half_state
static

Definition at line 98 of file EMA.hpp.

◆ half

constexpr state_t half = K > 0 ? state_t{1} << (K - 1) : state_t{0}
static

Definition at line 99 of file EMA.hpp.

◆ state

state_t state
private

Definition at line 134 of file EMA.hpp.


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