Control Surface master MIDI Control Surface library for Arduino
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
 K The 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_t The integer type to use for the input and output of the filter. Can be signed or unsigned. state_t The 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 58 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 >
constexpr static 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

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

constexpr static state_t half_state = max_state / 2 + 1

constexpr static state_t zero = std::is_unsigned<input_t>::value ? state_t(0) : half_state

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

state_t state

## ◆ EMA()

 EMA ( input_t initial = input_t(0) )
inline

Constructor: initialize filter to zero or optional given value.

Definition at line 61 of file EMA.hpp.

## ◆ reset()

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

Reset the filter to the given value.

Parameters
 value The 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
 input The new raw input value.
Returns
The new filtered output value.

Definition at line 81 of file EMA.hpp.

## ◆ operator()()

 input_t operator() ( input_t input )
inline

Filter the input: Given $$x[n]$$, calculate $$y[n]$$.

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

Definition at line 90 of file EMA.hpp.

## ◆ supports_range()

 constexpr static bool supports_range ( T min, T 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:58
input_t filter(input_t input)
Filter the input: Given , calculate .
Definition: EMA.hpp:81
static_assert(filter.supports_range(0u, 2047u),
"use a wider state or input type, or a smaller shift factor");

Definition at line 121 of file EMA.hpp.

## ◆ max_state

 constexpr static state_t max_state = std::numeric_limits::max()
staticconstexpr

Definition at line 95 of file EMA.hpp.

## ◆ half_state

 constexpr static state_t half_state = max_state / 2 + 1
static

Definition at line 96 of file EMA.hpp.

## ◆ zero

 constexpr static state_t zero = std::is_unsigned::value ? state_t(0) : half_state
static

Definition at line 97 of file EMA.hpp.

## ◆ half

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

Definition at line 98 of file EMA.hpp.

## ◆ state

 state_t state
private

Definition at line 133 of file EMA.hpp.

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