This is an old version of the documentation. View the latest version here.
Control Surface  1.0.0
MIDI Control Surface library for Arduino
Public Member Functions | Static Public Member Functions | Private Attributes | List of all members
FilteredAnalog< Precision, FilterShiftFactor, FilterType, Upsample > Class Template Reference

A class that reads and filters an analog input. More...

#include <FilteredAnalog.hpp>

Collaboration diagram for FilteredAnalog< Precision, FilterShiftFactor, FilterType, Upsample >:

Public Member Functions

 FilteredAnalog (pin_t analogPin)
 Construct a new FilteredAnalog object. More...
 
void map (MappingFunction fn)
 Specify a mapping function that is applied to the raw analog value before filtering. More...
 
void invert ()
 Invert the analog value. More...
 
bool update ()
 Read the analog input value, apply the mapping function, and update the average. More...
 
analog_t getValue () const
 Get the filtered value of the analog input with the mapping function applied. More...
 
float getFloatValue () const
 Get the filtered value of the analog input with the mapping function applied as a floating point number from 0.0 to 1.0. More...
 
analog_t getRawValue () const
 Read the raw value of the analog input any filtering or mapping applied, but with its bit depth increased by Upsample. More...
 

Static Public Member Functions

static void setupADC ()
 

Private Attributes

const pin_t analogPin
 
MappingFunction mapFn = nullptr
 
EMA< FilterShiftFactor, FilterType > filter
 
Hysteresis< ADC_BITS+Upsample - Precision, analog_t, analog_thysteresis
 

Detailed Description

template<uint8_t Precision = 10, uint8_t FilterShiftFactor = ANALOG_FILTER_SHIFT_FACTOR, class FilterType = ANALOG_FILTER_TYPE, uint8_t Upsample = min(sizeof(FilterType) * CHAR_BIT - ADC_BITS - FilterShiftFactor, sizeof(analog_t) * CHAR_BIT - ADC_BITS)>
class FilteredAnalog< Precision, FilterShiftFactor, FilterType, Upsample >

A class that reads and filters an analog input.

A map function can be applied to the analog value (e.g. to compensate for logarithmic taper potentiometers or to calibrate the range). The analog input value is filtered using an exponential moving average filter. The default settings for this filter can be changed in Settings.hpp.
After filtering, hysteresis is applied to prevent flipping back and forth between two values when the input is not changing.

Template Parameters
PrecisionThe number of bits of precision the output should have.
FilterShiftFactorThe number of bits used for the EMA filter. The pole location is \( 1 - \left(\frac{1}{2}\right)^{\mathrm{FilterShiftFactor}} \).
A lower shift factor means less filtering ( \(0\) is no filtering), and a higher shift factor means more filtering (and more latency).
FilterTypeThe type to use for the intermediate types of the filter.
Should be at least \( 10 + \mathrm{Upsample} + \mathrm{FilterShiftFactor} \) bits ( \(10\) is the number of bits of the ADC).
UpsampleThe number of bits to upsample the analog reading by.
Examples
2.VU-Meter-OLED-USB-DAC.ino, and FilteredAnalog.ino.

Definition at line 47 of file FilteredAnalog.hpp.

Constructor & Destructor Documentation

◆ FilteredAnalog()

template<uint8_t Precision = 10, uint8_t FilterShiftFactor = ANALOG_FILTER_SHIFT_FACTOR, class FilterType = ANALOG_FILTER_TYPE, uint8_t Upsample = min(sizeof(FilterType) * CHAR_BIT - ADC_BITS - FilterShiftFactor, sizeof(analog_t) * CHAR_BIT - ADC_BITS)>
FilteredAnalog< Precision, FilterShiftFactor, FilterType, Upsample >::FilteredAnalog ( pin_t  analogPin)
inline

Construct a new FilteredAnalog object.

Parameters
analogPinThe analog pin to read from.

Definition at line 55 of file FilteredAnalog.hpp.

Member Function Documentation

◆ map()

template<uint8_t Precision = 10, uint8_t FilterShiftFactor = ANALOG_FILTER_SHIFT_FACTOR, class FilterType = ANALOG_FILTER_TYPE, uint8_t Upsample = min(sizeof(FilterType) * CHAR_BIT - ADC_BITS - FilterShiftFactor, sizeof(analog_t) * CHAR_BIT - ADC_BITS)>
void FilteredAnalog< Precision, FilterShiftFactor, FilterType, Upsample >::map ( MappingFunction  fn)
inline

Specify a mapping function that is applied to the raw analog value before filtering.

Parameters
fnA function pointer to the mapping function. This function should take the filtered value (of ADC_BITS + Upsample bits wide) as a parameter, and should return a value of ADC_BITS + Upsample bits wide.
Note
Applying the mapping function before filtering could result in the noise being amplified to such an extent that filtering it afterwards would be ineffective.
Applying it after hysteresis would result in a lower resolution.
That's why the mapping function is applied after filtering and before hysteresis.

Definition at line 74 of file FilteredAnalog.hpp.

◆ invert()

template<uint8_t Precision = 10, uint8_t FilterShiftFactor = ANALOG_FILTER_SHIFT_FACTOR, class FilterType = ANALOG_FILTER_TYPE, uint8_t Upsample = min(sizeof(FilterType) * CHAR_BIT - ADC_BITS - FilterShiftFactor, sizeof(analog_t) * CHAR_BIT - ADC_BITS)>
void FilteredAnalog< Precision, FilterShiftFactor, FilterType, Upsample >::invert ( )
inline

Invert the analog value.

For example, if the precision is 10 bits, when the analog input measures 1023, the output will be 0, and when the analog input measures 0, the output will be 1023.

Note
This overrides the mapping function set by the map method.

Definition at line 83 of file FilteredAnalog.hpp.

◆ update()

template<uint8_t Precision = 10, uint8_t FilterShiftFactor = ANALOG_FILTER_SHIFT_FACTOR, class FilterType = ANALOG_FILTER_TYPE, uint8_t Upsample = min(sizeof(FilterType) * CHAR_BIT - ADC_BITS - FilterShiftFactor, sizeof(analog_t) * CHAR_BIT - ADC_BITS)>
bool FilteredAnalog< Precision, FilterShiftFactor, FilterType, Upsample >::update ( )
inline

Read the analog input value, apply the mapping function, and update the average.

Return values
trueThe value changed since last time it was updated.
falseThe value is still the same.

Definition at line 97 of file FilteredAnalog.hpp.

◆ getValue()

template<uint8_t Precision = 10, uint8_t FilterShiftFactor = ANALOG_FILTER_SHIFT_FACTOR, class FilterType = ANALOG_FILTER_TYPE, uint8_t Upsample = min(sizeof(FilterType) * CHAR_BIT - ADC_BITS - FilterShiftFactor, sizeof(analog_t) * CHAR_BIT - ADC_BITS)>
analog_t FilteredAnalog< Precision, FilterShiftFactor, FilterType, Upsample >::getValue ( ) const
inline

Get the filtered value of the analog input with the mapping function applied.

Returns
The filtered value of the analog input, as a number of Precision bits wide.

Definition at line 113 of file FilteredAnalog.hpp.

◆ getFloatValue()

template<uint8_t Precision = 10, uint8_t FilterShiftFactor = ANALOG_FILTER_SHIFT_FACTOR, class FilterType = ANALOG_FILTER_TYPE, uint8_t Upsample = min(sizeof(FilterType) * CHAR_BIT - ADC_BITS - FilterShiftFactor, sizeof(analog_t) * CHAR_BIT - ADC_BITS)>
float FilteredAnalog< Precision, FilterShiftFactor, FilterType, Upsample >::getFloatValue ( ) const
inline

Get the filtered value of the analog input with the mapping function applied as a floating point number from 0.0 to 1.0.

Returns
The filtered value of the analog input, as a number from 0.0 to 1.0.

Definition at line 122 of file FilteredAnalog.hpp.

◆ getRawValue()

template<uint8_t Precision = 10, uint8_t FilterShiftFactor = ANALOG_FILTER_SHIFT_FACTOR, class FilterType = ANALOG_FILTER_TYPE, uint8_t Upsample = min(sizeof(FilterType) * CHAR_BIT - ADC_BITS - FilterShiftFactor, sizeof(analog_t) * CHAR_BIT - ADC_BITS)>
analog_t FilteredAnalog< Precision, FilterShiftFactor, FilterType, Upsample >::getRawValue ( ) const
inline

Read the raw value of the analog input any filtering or mapping applied, but with its bit depth increased by Upsample.

Definition at line 130 of file FilteredAnalog.hpp.

◆ setupADC()

template<uint8_t Precision = 10, uint8_t FilterShiftFactor = ANALOG_FILTER_SHIFT_FACTOR, class FilterType = ANALOG_FILTER_TYPE, uint8_t Upsample = min(sizeof(FilterType) * CHAR_BIT - ADC_BITS - FilterShiftFactor, sizeof(analog_t) * CHAR_BIT - ADC_BITS)>
static void FilteredAnalog< Precision, FilterShiftFactor, FilterType, Upsample >::setupADC ( )
inlinestatic
Examples
2.VU-Meter-OLED-USB-DAC.ino, and FilteredAnalog.ino.

Definition at line 135 of file FilteredAnalog.hpp.

Member Data Documentation

◆ analogPin

template<uint8_t Precision = 10, uint8_t FilterShiftFactor = ANALOG_FILTER_SHIFT_FACTOR, class FilterType = ANALOG_FILTER_TYPE, uint8_t Upsample = min(sizeof(FilterType) * CHAR_BIT - ADC_BITS - FilterShiftFactor, sizeof(analog_t) * CHAR_BIT - ADC_BITS)>
const pin_t FilteredAnalog< Precision, FilterShiftFactor, FilterType, Upsample >::analogPin
private

Definition at line 142 of file FilteredAnalog.hpp.

◆ mapFn

template<uint8_t Precision = 10, uint8_t FilterShiftFactor = ANALOG_FILTER_SHIFT_FACTOR, class FilterType = ANALOG_FILTER_TYPE, uint8_t Upsample = min(sizeof(FilterType) * CHAR_BIT - ADC_BITS - FilterShiftFactor, sizeof(analog_t) * CHAR_BIT - ADC_BITS)>
MappingFunction FilteredAnalog< Precision, FilterShiftFactor, FilterType, Upsample >::mapFn = nullptr
private

Definition at line 144 of file FilteredAnalog.hpp.

◆ filter

template<uint8_t Precision = 10, uint8_t FilterShiftFactor = ANALOG_FILTER_SHIFT_FACTOR, class FilterType = ANALOG_FILTER_TYPE, uint8_t Upsample = min(sizeof(FilterType) * CHAR_BIT - ADC_BITS - FilterShiftFactor, sizeof(analog_t) * CHAR_BIT - ADC_BITS)>
EMA<FilterShiftFactor, FilterType> FilteredAnalog< Precision, FilterShiftFactor, FilterType, Upsample >::filter
private

Definition at line 149 of file FilteredAnalog.hpp.

◆ hysteresis

template<uint8_t Precision = 10, uint8_t FilterShiftFactor = ANALOG_FILTER_SHIFT_FACTOR, class FilterType = ANALOG_FILTER_TYPE, uint8_t Upsample = min(sizeof(FilterType) * CHAR_BIT - ADC_BITS - FilterShiftFactor, sizeof(analog_t) * CHAR_BIT - ADC_BITS)>
Hysteresis<ADC_BITS + Upsample - Precision, analog_t, analog_t> FilteredAnalog< Precision, FilterShiftFactor, FilterType, Upsample >::hysteresis
private

Definition at line 158 of file FilteredAnalog.hpp.


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