Description

The EventAnalog class is for analog inputs - slice an analog range into configurable number of increments.

For many uses of an analog input, the 1024 'slices' in the standard 10 bit analog range are more than is necessary. For 12 bit (4096), 14 bit (16384) and 16 bit (65536!)), even more so and with those higher numbers comes greater issues with noise, often resulting in a continuous fluctuation of values.

This library allows you to reduce those 1024 (or up to 65536!) slices to a more managable number, calling a handler function or method each time a defined slice increments up or down.

This approach also provides very effective noise reduction.

The following InputEventTypes are fired by EventAnalog:

InputEventType::ENABLED - fired when the input is enabled.
InputEventType::DISABLED - fired when the input is disabled.
InputEventType::IDLE - fired after no other event (except ENABLED & DISABLED) has been fired for a specified time. Each input can define its own idle timeout. Default is 10 seconds.
InputEventType::CHANGED - fired on each change of increment

#include <EventAnalog.h>

Inheritance diagram for EventAnalog:

[legend]

Public Member Functions
Constructor
	EventAnalog (byte analogPin, uint8_t adcBits=10)
	Construct an EventAnalog input. More...

Common Methods
These methods are common to all InputEvent classes. Additional methods for input enable, timeout, event blocking and user ID/value are also inherited from the EventInputBase class.
void	begin ()
	Initialise the EventAnalog. Must be called from within `setup()` More...

void	setCallback (CallbackFunction f)
	Set the Callback function. More...

template<typename T >
void	setCallback (T instance, void(T::method)(InputEventType, EventAnalog &))
	Set the Callback function to a class method. More...

void	unsetCallback () override
	Unset a previously set callback function or method. More...

void	update ()
	Update the state from the analog input. Must be called from within `loop()` in order to update state from the pin.

Getting the State
These methods return the current state of the input (as set during the last update() )
int16_t	position ()
	Returns the current position - this is not the analog value but the mapped position of the increments you have defined. More...

int16_t	previousPosition ()
	Returns the previous position - this is not the analog value but the mapped position of the increments you have defined. More...

bool	hasChanged ()
	Returns true if the position has changed since previous update() More...

Setting Required Increments
These methods are used to set the the number of increments to be 'sliced'.
void	setNumIncrements (uint8_t numIncr=10)
	Split the analog range into this number of slices. The default is 25. More...

void	setNumNegativeIncrements (uint8_t numIncr=10)
	Normally increments are set with setNumIncrements() but you can also set the negative and positive sides of 'centre normal' individually. More...

void	setNumPositiveIncrements (uint8_t numIncr=10)
	Normally increments are set with setNumIncrements() but you can also set the negative and positive sides of 'centre normal' individually. More...

Setting Analog Min, Max and Start values
These methods are used to set the min, max and start analog values of the input.
void	setStartValue (uint16_t val)
	Set the analog value that represents the 'starting' position. More...

void	setStartValue ()
	Will set the start value as the current position. More...

void	setMinValue (uint16_t val)
	The minimum ADC value that can be read by the analog pin. More...

void	setMaxValue (uint16_t val)
	The maximmum ADC value that can be read by the analog pin. More...

Setting Analog Start and End Boundaries
Boundaries set an area at the start or end of travel that is ignored. Some potentiometers are very inconsistent at either end and for joysticks it is impossible to reach min/max 'on the diagonal'.
void	setStartBoundary (uint16_t width=200)
	Used primarily for joysticks. More...

void	setEndBoundary (uint16_t width=100)
	Used primarily for joysticks. More...

Other Configuration Settings
void	setRateLimit (uint16_t ms)
	Limit the rate at which events are fired. More...

void	enableAutoCalibrate (bool enable=true)
	If enableAutoCalibrate is set to true (the default), will do auto calibration, setting the minValue and maxValue. More...

void	reversePosition (bool rev=true)
	Reverse the increments. More...

bool	isPositionReversed ()
	Returns true if position is reversed. More...

Public Member Functions inherited from EventInputBase
bool	isCallbackSet ()
	Returns true if the callback is set.

void	update ()
	Update the state of the input. More...

bool	isEnabled ()
	Returns true if input is enabled. More...

void	enable (bool e=true)
	Enable or disable an input. More...

void	setIdleTimeout (unsigned int timeoutMs=10000)
	Set the idle timeout in milliseconds (default 10000, 10 seconds) More...

unsigned long	msSinceLastEvent ()
	Returns the number of ms since any event was fired for this input.

bool	isIdle ()
	Return true if no activity for longer than setIdleTimeout - irrespective of whether the idle (or changed) callback has been fired. More...

void	resetIdleTimer ()
	Reset the idle timer. The IDLE event will fire setIdleTimeout ms after this is called. More...

void	blockEvent (InputEventType et)
	Stop an event from firing. More...

void	allowEvent (InputEventType et)
	Allow a a previously blocked event tto fire. More...

void	blockAllEvents ()
	Stop all events from firing - usually used in conjunction with allowEvent()

void	allowAllEvents ()
	Clear all blocked events.

bool	isEventAllowed (InputEventType et)
	Returns true if the event is not blocked.

void	setInputId (uint8_t id)
	Set the input ID (for use by user, not used internally). Not unique, default is 0.

uint8_t	getInputId ()
	Get the input ID (for use by user, not used internally). Not unique, default is 0.

void	setInputValue (uint8_t val)
	Set the input value (for use by user, not used internally). Not unique, default is 0.

uint8_t	getInputValue ()
	Get the input value (for use by user, not used internally). Not unique, default is 0.

Protected Types
typedef std::function< void(InputEventType et, EventAnalog &ie)>	CallbackFunction
	If `std::function` is supported, this creates the callback type.

typedef void(*	CallbackFunction) (InputEventType et, EventAnalog &)
	Used to create the callback type as pointer if `std::function` is not supported.

Protected Member Functions
void	invoke (InputEventType et) override
	Override of the `EventInputBase::invoke()` virtual method. More...

void	setSliceNeg ()
	Set the size of each negative slice/increment.

void	setSlicePos ()
	Set the size of each positive slice/increment.

Protected Member Functions inherited from EventInputBase
bool	isInvokable (InputEventType et)

virtual void	invoke (InputEventType et)=0
	To be overriden by derived classes. More...

virtual void	onEnabled ()
	Can be ovrriden by derived classes but base method must be called. More...

virtual void	onDisabled ()
	Can be ovrriden by derived classes but base method must be called. More...

virtual void	onIdle ()
	Can be ovrriden by derived classes but base method must be called. More...

Protected Attributes
CallbackFunction	callbackFunction = nullptr
	The callback function member.

Protected Attributes inherited from EventInputBase
uint8_t	input_id = 0
	Input ID, not used internally.

uint8_t	input_value = 0
	Input value, not used internally.

bool	_enabled = true
	Input enabled flag.

bool	idleFlagged = true
	True if input is idle.

unsigned long	lastEventMs = millis()
	number of milliseconds since the last event

unsigned long	idleTimeout = 10000
	The idle timeout in milliseconds.

bool	callbackIsSet = false
	Required because in C/C++ callback has to be defined in derived classes... :-/.

Constructor & Destructor Documentation

◆ EventAnalog()

EventAnalog::EventAnalog	(	byte	pin,
		uint8_t	adcBits = `10`
	)

Construct an EventAnalog input.

Parameters

analogPin	Must be an analog pin. For ESP32 avoid using pins attached to ADC2 (GPIO 0, 2, 4, 12-15, 25-27) as these are shared by the WiFi module.
adcBits	For most boards the default 10 (bits) will work fine but if your board has an ADC (analog to digital converter) resolution that is higher, pass the resolution (in bits) of your board. For most ESP32s this is 12.

GPLv2 Licence https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt

Member Function Documentation

◆ begin()

void EventAnalog::begin ( )

virtual

Initialise the EventAnalog. Must be called from within setup()

Implements EventInputBase.

◆ enableAutoCalibrate()

void EventAnalog::enableAutoCalibrate ( bool enable = true )

inline

If enableAutoCalibrate is set to true (the default), will do auto calibration, setting the minValue and maxValue.

This will be done even when input is disabled (ie no callbacks fired)

◆ hasChanged()

bool EventAnalog::hasChanged ( )

inline

Returns true if the position has changed since previous update()

Returns: true Changed since previous update(); false No change since previous update()

◆ invoke()

void EventAnalog::invoke ( InputEventType et )

overrideprotectedvirtual

Override of the EventInputBase::invoke() virtual method.

Parameters

et	Enum of type `InputEventType`

Implements EventInputBase.

◆ isPositionReversed()

bool EventAnalog::isPositionReversed ( )

inline

Returns true if position is reversed.

Returns: true Position is reverse.; false Position is not reversed (default behaviours)

◆ position()

int16_t EventAnalog::position ( )

inline

Returns the current position - this is not the analog value but the mapped position of the increments you have defined.

Can be negative if setStartValue() is greater than the minimum position (eg for joysticks).

Returns: int16_t

◆ previousPosition()

int16_t EventAnalog::previousPosition ( )

inline

Returns the previous position - this is not the analog value but the mapped position of the increments you have defined.

Returns: int16_t

◆ reversePosition()

void EventAnalog::reversePosition ( bool rev = true )

inline

Reverse the increments.

If your position is coming out backawards (negative), you can set this rather that rewire your input.

Parameters

rev	Default true to reverse, pass false to restore default behaviour.

◆ setCallback() [1/2]

void EventAnalog::setCallback ( CallbackFunction f )

inline

Set the Callback function.

Parameters

f	A function of type `EventAnalog::CallbackFunction` type.

◆ setCallback() [2/2]

template<typename T >

void EventAnalog::setCallback	(	T *	instance,
		void(T::*)(InputEventType, EventAnalog &)	method
	)

inline

Set the Callback function to a class method.

Note: This method is only available if std:function is supported.

Parameters

instance	The instance of a class implementing a CallbackFunction method.
method	The class method of type `EventAnalog::CallbackFunction` type.

◆ setEndBoundary()

void EventAnalog::setEndBoundary ( uint16_t width = 100 )

Used primarily for joysticks.

Again, used primarily for joysticks to create an outer 'deadzone' where joysticks are notoriously inconsistent or cannot be reach on a diagonal.

Parameters

width - the analog value

◆ setMaxValue()

void EventAnalog::setMaxValue ( uint16_t val )

The maximmum ADC value that can be read by the analog pin.

By default the maxValue is set to 95% of the ADC range and auto calibrated as the input is used. You can manually set it here if you have confidence in your potentiometer range.

Parameters

val	This is the maximum readable analog (ADC) value

◆ setMinValue()

void EventAnalog::setMinValue ( uint16_t val )

The minimum ADC value that can be read by the analog pin.

By default the minValue is set to 5% of the ADC range and auto calibrated as the input is used. You can manually set it here if you have confidence in your potentiometer range.

Parameters

val	This is the minimum readable analog (ADC) value

◆ setNumIncrements()

void EventAnalog::setNumIncrements ( uint8_t numIncr = 10 )

Split the analog range into this number of slices. The default is 25.

Note: This library is intended to reduce the usual 0-1024 range of analogRead() to a much smaller, more manageable number of 'slices'. Much higher numbers may produce variable results as a slice width is the ADC resolution (1024) divided by the number of increments.

An InputEventType::CHANGED event will be fired each time the increment changes.

Parameters

numIncr The number of desired increments. Should not be more than 20% of the ADC max value.

◆ setNumNegativeIncrements()

void EventAnalog::setNumNegativeIncrements ( uint8_t numIncr = 10 )

Normally increments are set with setNumIncrements() but you can also set the negative and positive sides of 'centre normal' individually.

Parameters

numIncr The number of increments required on the negative side.

◆ setNumPositiveIncrements()

void EventAnalog::setNumPositiveIncrements ( uint8_t numIncr = 10 )

Normally increments are set with setNumIncrements() but you can also set the negative and positive sides of 'centre normal' individually.

Parameters

numIncr The number of increments required on the positive side.

◆ setRateLimit()

void EventAnalog::setRateLimit ( uint16_t ms )

inline

Limit the rate at which events are fired.

When moving an analog fast it can generate a lot of events, so you can rate limit.

Parameters

ms	Number of milliseconds between events

◆ setStartBoundary()

void EventAnalog::setStartBoundary ( uint16_t width = 200 )

Used primarily for joysticks.

It is very difficult to press the joystick button without moving the joystick so with this we can create a central 'deadzone'.

Parameters

width - the analog value

◆ setStartValue() [1/2]

void EventAnalog::setStartValue ( )

Will set the start value as the current position.

Useful for joysticks that 'rest' in the centre but can also be called from a button push to change the behaviour of an analog input.

◆ setStartValue() [2/2]

void EventAnalog::setStartValue ( uint16_t val )

Set the analog value that represents the 'starting' position.

For normal potentiometers this would be 0 (the default) but for joysticks it would be the centre position of the joystick's potentionmeter (normally 512).

Parameters

val	This is the analog (ADC) value

◆ unsetCallback()

void EventAnalog::unsetCallback ( )

overridevirtual

Unset a previously set callback function or method.

Must be called before the set function or method is destoyed.

Reimplemented from EventInputBase.

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

src/EventAnalog.h
src/EventAnalog.cpp

Description

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ EventAnalog()

Member Function Documentation

◆ begin()

◆ enableAutoCalibrate()

◆ hasChanged()

◆ invoke()

◆ isPositionReversed()

◆ position()

◆ previousPosition()

◆ reversePosition()

◆ setCallback() [1/2]

◆ setCallback() [2/2]

◆ setEndBoundary()

◆ setMaxValue()

◆ setMinValue()

◆ setNumIncrements()

◆ setNumNegativeIncrements()

◆ setNumPositiveIncrements()

◆ setRateLimit()

◆ setStartBoundary()

◆ setStartValue() [1/2]

◆ setStartValue() [2/2]

◆ unsetCallback()