Description

The EventEncoder class is for quadrature encoder inputs providing the position & encoder increment, event rate limiting without losing steps (eg for easy acceleration or to reduce events sent over Serial).

It is effectively an event wrapper around a low level encoder library. By default, Paul Stoffregen's Encoder library is used but adapters can easily be created for others (and more will be added).

The following InputEventTypes are fired by EventEncoder:

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 position

#include <EventEncoder.h>

Inheritance diagram for EventEncoder:

[legend]

Public Member Functions
Constructor and Destructor
	EventEncoder (EncoderAdapter *encoderAdapter)
	Construct an EventEncoder input from an EncoderAdapter More...

	~EventEncoder ()
	Destroy the EventEncoder input.

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 EventEncoder. More...

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

template<typename T >
void	setCallback (T instance, void(T::method)(InputEventType, EventEncoder &))
	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 underlying encoder library. More...

Getting the State
These methods return the current state of the input (as set during the last update() )
int16_t	increment ()
	Returns a positive (CW) or negative (CCW) integer. More...

long	position ()
	The current position of the encoder. Can be reset with resetPosition()

Other Configuration Settings
void	setRateLimit (long ms=0)
	Encoder callbacks are normally fired on every loop() but for MPG style encoders this can fire a huge number of events (that may swamp a serial connection). More...

void	setPositionDivider (uint8_t divider=4)
	Quadrature encoders usually have four states for each 'click' of the rotary control, although some have just 2. More...

uint8_t	getPositionDivider ()
	Get the currently set position divider value. More...

void	resetPosition (long pos=0)
	Reset the counted position of the encoder. 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, EventEncoder &ie)>	CallbackFunction
	If `std::function` is supported, this creates the callback type.

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

Protected Member Functions
void	readIncrement ()
	Read and set the increment during update()

void	invoke (InputEventType et) override
	To be overriden by derived classes. More...

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

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 = NULL
	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

◆ EventEncoder()

EventEncoder::EventEncoder ( EncoderAdapter * encoderAdapter )

Construct an EventEncoder input from an EncoderAdapter

Please see EncoderAdapter Notes

‍Note: The EncoderAdapter's begin() method will be called from the EventEncoder's begin() method.

Parameters

encoderAdapter Pass a previously created EncoderAdapter by reference.

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

Member Function Documentation

◆ begin()

void EventEncoder::begin ( )

virtual

Initialise the EventEncoder.

Must be called from within setup()

Implements EventInputBase.

◆ getPositionDivider()

uint8_t EventEncoder::getPositionDivider ( )

inline

Get the currently set position divider value.

Returns: uint8_t

◆ increment()

int16_t EventEncoder::increment ( )

inline

Returns a positive (CW) or negative (CCW) integer.

The returned value normally 1 or -1 but if your loop() has lots of processing, your Arduino is slow or you setRateLimit() this will report the actual number of increments made by the encoder since the update().

◆ invoke()

void EventEncoder::invoke ( InputEventType et )

overrideprotectedvirtual

To be overriden by derived classes.

Parameters

et	Enum of type `InputEventType`

Implements EventInputBase.

◆ onEnabled()

void EventEncoder::onEnabled ( )

overrideprotectedvirtual

Can be ovrriden by derived classes but base method must be called.

Reimplemented from EventInputBase.

◆ resetPosition()

void EventEncoder::resetPosition ( long pos = 0 )

inline

Reset the counted position of the encoder.

Note: Some underlying encoder libraries may only allow a 'reset' to 0, not the setting of a specific value.

◆ setCallback() [1/2]

void EventEncoder::setCallback ( CallbackFunction f )

inline

Set the Callback function.

Parameters

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

◆ setCallback() [2/2]

template<typename T >

void EventEncoder::setCallback	(	T *	instance,
		void(T::*)(InputEventType, EventEncoder &)	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 `EventButton::CallbackFunction` type.

◆ setPositionDivider()

void EventEncoder::setPositionDivider ( uint8_t divider = 4 )

inline

Quadrature encoders usually have four states for each 'click' of the rotary control, although some have just 2.

Normally we only want to fire an event once per click so the default positionDivider is 4. You can set this to any positive integer eg 8 would increment the position every 2 clicks. Affects pressed+turning for EventEncoderButton too.

◆ setRateLimit()

void EventEncoder::setRateLimit ( long ms = 0 )

inline

Encoder callbacks are normally fired on every loop() but for MPG style encoders this can fire a huge number of events (that may swamp a serial connection).

The encoder interupts will sitll be called but this will limit the call back firing to every set ms - read the EncoderButton.increment() for lossless counting of encoder. Set to zero (default) for no rate limit.

◆ unsetCallback()

void EventEncoder::unsetCallback ( )

overridevirtual

Unset a previously set callback function or method.

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

Reimplemented from EventInputBase.

◆ update()

void EventEncoder::update ( )

Update the state from the underlying encoder library.

Must be called from within loop()

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

src/EventEncoder.h
src/EventEncoder.cpp

Description

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ EventEncoder()

Member Function Documentation

◆ begin()

◆ getPositionDivider()

◆ increment()

◆ invoke()

◆ onEnabled()

◆ resetPosition()

◆ setCallback() [1/2]

◆ setCallback() [2/2]

◆ setPositionDivider()

◆ setRateLimit()

◆ unsetCallback()

◆ update()