Arduino Helpers master
Utility library for Arduino
Public Types | Public Member Functions | Static Public Member Functions | Private Types | Private Member Functions | Private Attributes | List of all members
FilteredAnalog< Precision, FilterShiftFactor, FilterType, AnalogType, IncRes > Class Template Reference

#include <AH/Hardware/FilteredAnalog.hpp>

Detailed Description

template<uint8_t Precision = 10, uint8_t FilterShiftFactor = ANALOG_FILTER_SHIFT_FACTOR, class FilterType = ANALOG_FILTER_TYPE, class AnalogType = analog_t, uint8_t IncRes = MaximumFilteredAnalogIncRes< FilterShiftFactor, FilterType, AnalogType>::value>
class FilteredAnalog< Precision, FilterShiftFactor, FilterType, AnalogType, IncRes >

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)^{\text{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 \( \text{ADC_BITS} + \text{IncRes} + \text{FilterShiftFactor} \) bits wide.
AnalogTypeThe type to use for the analog values.
Should be at least \( \text{ADC_BITS} + \text{IncRes} \) bits wide.
IncResThe number of bits to increase the resolution of the analog reading by.
Examples
1.FilteredAnalog-Advanced.ino, and 1.FilteredAnalog.ino.

Definition at line 265 of file FilteredAnalog.hpp.

+ Inheritance diagram for FilteredAnalog< Precision, FilterShiftFactor, FilterType, AnalogType, IncRes >:
+ Collaboration diagram for FilteredAnalog< Precision, FilterShiftFactor, FilterType, AnalogType, IncRes >:

Public Types

using MappingFunction = AnalogType(*)(AnalogType)
 A function pointer to a mapping function to map analog values. More...
 

Public Member Functions

 FilteredAnalog (pin_t analogPin, AnalogType initial=0)
 Construct a new FilteredAnalog object. More...
 
 FilteredAnalog ()
 Construct a new FilteredAnalog object. More...
 
void invert ()
 Invert the analog value. More...
 
void reset (analog_t value=0)
 Reset the filter to the given value. More...
 
void resetToCurrentValue ()
 Reset the filtered value to the value that's currently being measured at the analog input. More...
 
void map (analog_t(*)(analog_t) fn)
 Specify a mapping function/functor that is applied to the analog value after filtering and before applying hysteresis. More...
 
analog_t(*)(analog_t) & getMappingFunction ()
 Get a reference to the mapping function. More...
 
const analog_t(*)(analog_t) & getMappingFunction () const
 Get a reference to the mapping function. 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 without any filtering or mapping applied, but with its bit depth increased by IncRes. More...
 

Static Public Member Functions

static constexpr analog_t getMaxRawValue ()
 Get the maximum value that can be returned from getRawValue. More...
 
static void setupADC ()
 Select the configured ADC resolution. More...
 

Private Types

using EMA_t = EMA< FilterShiftFactor, analog_t, ANALOG_FILTER_TYPE >
 

Private Member Functions

std::enable_if< std::is_constructible< bool, M >::value, analog_t >::type mapFnHelper (analog_t input)
 Helper function that applies the mapping function if it's enabled. More...
 
std::enable_if<!std::is_constructible< bool, M >::value, analog_t >::type mapFnHelper (analog_t input)
 Helper function that applies the mapping function without checking if it's enabled. More...
 

Private Attributes

pin_t analogPin
 
analog_t(*)(analog_tmapFn
 
EMA_t filter
 
Hysteresis< ADC_BITS+IncRes - Precision, analog_t, analog_thysteresis
 

Member Typedef Documentation

◆ MappingFunction

using MappingFunction = AnalogType (*)(AnalogType)

A function pointer to a mapping function to map analog values.

See also
map()

Definition at line 295 of file FilteredAnalog.hpp.

◆ EMA_t

using EMA_t = EMA<FilterShiftFactor, analog_t , ANALOG_FILTER_TYPE >
privateinherited

Definition at line 208 of file FilteredAnalog.hpp.

Constructor & Destructor Documentation

◆ FilteredAnalog() [1/2]

FilteredAnalog ( pin_t  analogPin,
AnalogType  initial = 0 
)
inline

Construct a new FilteredAnalog object.

Parameters
analogPinThe analog pin to read from.
initialThe initial value of the filter.

Definition at line 278 of file FilteredAnalog.hpp.

◆ FilteredAnalog() [2/2]

FilteredAnalog ( )
inline

Construct a new FilteredAnalog object.

This constructor should not be used.
It is just a way to easily create arrays of FilteredAnalog objects, and initializing them later. Trying to update a default-constructed or uninitialized FilteredAnalog object will result in a fatal runtime error.

Definition at line 291 of file FilteredAnalog.hpp.

Member Function Documentation

◆ invert()

void 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 304 of file FilteredAnalog.hpp.

◆ reset()

void reset ( analog_t  value = 0)
inlineinherited

Reset the filter to the given value.

Parameters
valueThe value to reset the filter state to.

Definition at line 63 of file FilteredAnalog.hpp.

◆ resetToCurrentValue()

void resetToCurrentValue ( )
inlineinherited

Reset the filtered value to the value that's currently being measured at the analog input.

This is useful to avoid transient effects upon initialization.

Examples
1.FilteredAnalog.ino.

Definition at line 76 of file FilteredAnalog.hpp.

◆ map()

void map ( analog_t(*)(analog_t fn)
inlineinherited

Specify a mapping function/functor that is applied to the analog value after filtering and before applying hysteresis.

Parameters
fnThis functor should have a call operator that takes the filtered value (of ADC_BITS + IncRes bits wide) as a parameter, and returns a value of ADC_BITS + IncRes 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 98 of file FilteredAnalog.hpp.

◆ getMappingFunction() [1/2]

analog_t(*)(analog_t) & getMappingFunction ( )
inlineinherited

Get a reference to the mapping function.

Definition at line 103 of file FilteredAnalog.hpp.

◆ getMappingFunction() [2/2]

const analog_t(*)(analog_t) & getMappingFunction ( ) const
inlineinherited

Get a reference to the mapping function.

Definition at line 107 of file FilteredAnalog.hpp.

◆ update()

bool update ( )
inlineinherited

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.
Examples
1.FilteredAnalog.ino.

Definition at line 118 of file FilteredAnalog.hpp.

◆ getValue()

analog_t getValue ( ) const
inlineinherited

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

Note
This function just returns the value from the last call to update, it doesn't read the analog input again.
Returns
The filtered value of the analog input, as a number of Precision bits wide.
Examples
1.FilteredAnalog.ino.

Definition at line 136 of file FilteredAnalog.hpp.

◆ getFloatValue()

float getFloatValue ( ) const
inlineinherited

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 145 of file FilteredAnalog.hpp.

◆ getRawValue()

analog_t getRawValue ( ) const
inlineinherited

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

Definition at line 153 of file FilteredAnalog.hpp.

◆ getMaxRawValue()

static constexpr analog_t getMaxRawValue ( )
inlinestaticconstexprinherited

Get the maximum value that can be returned from getRawValue.

Definition at line 165 of file FilteredAnalog.hpp.

◆ setupADC()

static void setupADC ( )
inlinestaticinherited

Select the configured ADC resolution.

By default, it is set to the maximum resolution supported by the hardware.

See also
ADC_BITS
ADCConfig.hpp
Examples
1.FilteredAnalog-Advanced.ino, and 1.FilteredAnalog.ino.

Definition at line 176 of file FilteredAnalog.hpp.

◆ mapFnHelper() [1/2]

std::enable_if< std::is_constructible< bool, M >::value, analog_t >::type mapFnHelper ( analog_t  input)
inlineprivateinherited

Helper function that applies the mapping function if it's enabled.

This function is only enabled if MappingFunction is explicitly convertible to bool.

Definition at line 189 of file FilteredAnalog.hpp.

◆ mapFnHelper() [2/2]

std::enable_if<!std::is_constructible< bool, M >::value, analog_t >::type mapFnHelper ( analog_t  input)
inlineprivateinherited

Helper function that applies the mapping function without checking if it's enabled.

This function is only enabled if MappingFunction is not convertible to bool.

Definition at line 200 of file FilteredAnalog.hpp.

Member Data Documentation

◆ analogPin

pin_t analogPin
privateinherited

Definition at line 205 of file FilteredAnalog.hpp.

◆ mapFn

analog_t(*)(analog_t) mapFn
privateinherited

Definition at line 206 of file FilteredAnalog.hpp.

◆ filter

EMA_t filter
privateinherited

Definition at line 222 of file FilteredAnalog.hpp.

◆ hysteresis

Hysteresis<ADC_BITS + IncRes - Precision, analog_t , analog_t > hysteresis
privateinherited

Definition at line 224 of file FilteredAnalog.hpp.


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