#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

Precision	The number of bits of precision the output should have.
FilterShiftFactor	The 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).
FilterType	The type to use for the intermediate types of the filter. Should be at least \( \text{ADC_BITS} + \text{IncRes} + \text{FilterShiftFactor} \) bits wide.
AnalogType	The type to use for the analog values. Should be at least \( \text{ADC_BITS} + \text{IncRes} \) bits wide.
IncRes	The number of bits to increase the resolution of the analog reading by.

Definition at line 272 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.

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

Static Public Member Functions
static constexpr AnalogType	getMaxRawValue ()
	Get the maximum value that can be returned from getRawValue.
static void	setupADC ()
	Select the configured ADC resolution.

Private Types
using	EMA_t = EMA<FilterShiftFactor, AnalogType, FilterType>

Private Member Functions
template<typename M = MappingFunction>
std::enable_if< std::is_constructible< bool, M >::value, AnalogType >::type	mapFnHelper (AnalogType input)
	Helper function that applies the mapping function if it's enabled.
template<typename M = MappingFunction>
std::enable_if<!std::is_constructible< bool, M >::value, AnalogType >::type	mapFnHelper (AnalogType input)
	Helper function that applies the mapping function without checking if it's enabled.

Private Attributes
pin_t	analogPin
MappingFunction	mapFn
EMA_t	filter
Hysteresis< ADC_BITS+IncRes - Precision, AnalogType, AnalogType >	hysteresis

Member Typedef Documentation

◆ MappingFunction

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>

using MappingFunction = AnalogType (*)(AnalogType)

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

See also: map()

Definition at line 306 of file FilteredAnalog.hpp.

◆ EMA_t

template<class MappingFunction, 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>

using EMA_t = EMA<FilterShiftFactor, AnalogType, FilterType>

privateinherited

Definition at line 215 of file FilteredAnalog.hpp.

Constructor & Destructor Documentation

◆ FilteredAnalog() [1/3]

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>

FilteredAnalog	(	pin_t	analogPin,
		AnalogType	initial = 0 )

inline

Construct a new FilteredAnalog object.

Parameters

analogPin	The analog pin to read from.
initial	The initial value of the filter.

Definition at line 285 of file FilteredAnalog.hpp.

◆ FilteredAnalog() [2/3]

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>

FilteredAnalog	(	ArduinoPin_t	analogPin,
		AnalogType	initial = 0 )

inline

Definition at line 291 of file FilteredAnalog.hpp.

◆ FilteredAnalog() [3/3]

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>

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

Member Function Documentation

◆ invert()

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>

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

◆ reset()

template<class MappingFunction, 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>

void reset ( AnalogType value = 0 )

inlineinherited

Reset the filter to the given value.

Parameters

value The value to reset the filter state to.

Definition at line 70 of file FilteredAnalog.hpp.

◆ resetToCurrentValue()

template<class MappingFunction, 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>

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

◆ map()

template<class MappingFunction, 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>

void map ( MappingFunction fn )

inlineinherited

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

Parameters

fn	This 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 105 of file FilteredAnalog.hpp.

◆ getMappingFunction() [1/2]

template<class MappingFunction, 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>

MappingFunction & getMappingFunction ( )

inlineinherited

Get a reference to the mapping function.

Definition at line 110 of file FilteredAnalog.hpp.

◆ getMappingFunction() [2/2]

template<class MappingFunction, 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>

const MappingFunction & getMappingFunction ( ) const

inlineinherited

Get a reference to the mapping function.

Definition at line 114 of file FilteredAnalog.hpp.

◆ update()

template<class MappingFunction, 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>

bool update ( )

inlineinherited

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

Return values

true	The value changed since last time it was updated.
false	The value is still the same.

Examples: 1.FilteredAnalog.ino, and 2.VU-Meter-OLED-USB-DAC.ino.

Definition at line 125 of file FilteredAnalog.hpp.

◆ getValue()

template<class MappingFunction, 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>

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

◆ getFloatValue()

template<class MappingFunction, 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>

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.

Examples: 2.VU-Meter-OLED-USB-DAC.ino.

Definition at line 152 of file FilteredAnalog.hpp.

◆ getRawValue()

template<class MappingFunction, 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>

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

◆ getMaxRawValue()

template<class MappingFunction, 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>

constexpr AnalogType getMaxRawValue ( )

inlinestaticconstexprinherited

Get the maximum value that can be returned from getRawValue.

Definition at line 172 of file FilteredAnalog.hpp.

◆ setupADC()

template<class MappingFunction, 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>

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, 1.FilteredAnalog.ino, 2.VU-Meter-OLED-USB-DAC.ino, and FilteredAnalog.ino.

Definition at line 183 of file FilteredAnalog.hpp.

◆ mapFnHelper() [1/2]

template<class MappingFunction, 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>

template<typename M = MappingFunction>

std::enable_if< std::is_constructible< bool, M >::value, AnalogType >::type mapFnHelper ( AnalogType 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 196 of file FilteredAnalog.hpp.

◆ mapFnHelper() [2/2]

template<class MappingFunction, 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>

template<typename M = MappingFunction>

std::enable_if<!std::is_constructible< bool, M >::value, AnalogType >::type mapFnHelper ( AnalogType 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 207 of file FilteredAnalog.hpp.

Member Data Documentation

◆ analogPin

template<class MappingFunction, 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>

pin_t analogPin

privateinherited

Definition at line 212 of file FilteredAnalog.hpp.

◆ mapFn

template<class MappingFunction, 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>

MappingFunction mapFn

privateinherited

Definition at line 213 of file FilteredAnalog.hpp.

◆ filter

template<class MappingFunction, 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>

EMA_t filter

privateinherited

Definition at line 229 of file FilteredAnalog.hpp.

◆ hysteresis

template<class MappingFunction, 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>

Hysteresis<ADC_BITS + IncRes - Precision, AnalogType, AnalogType> hysteresis

privateinherited

Definition at line 231 of file FilteredAnalog.hpp.

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

FilteredAnalog.hpp

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Private Attributes

Member Typedef Documentation

◆ MappingFunction

◆ EMA_t

Constructor & Destructor Documentation

◆ FilteredAnalog() [1/3]

◆ FilteredAnalog() [2/3]

◆ FilteredAnalog() [3/3]

Member Function Documentation

◆ invert()

◆ reset()

◆ resetToCurrentValue()

◆ map()

◆ getMappingFunction() [1/2]

◆ getMappingFunction() [2/2]

◆ update()

◆ getValue()

◆ getFloatValue()

◆ getRawValue()

◆ getMaxRawValue()

◆ setupADC()

◆ mapFnHelper() [1/2]

◆ mapFnHelper() [2/2]

Member Data Documentation

◆ analogPin

◆ mapFn

◆ filter

◆ hysteresis