SwitchInput.h File Reference

Switch input provides the button and rotary encoder input capabilities provided by this library. There is a globally defined variable switches declared that you can use directly. To add a rotary encoder, see the helper functions further down. There's also a rotary encoder emulation based on Up and Down buttons. More...

Go to the source code of this file.

Classes
class	SwitchListener
class	KeyboardItem
class	EncoderListener
class	RotaryEncoder
class	AbstractHwRotaryEncoder
class	HardwareRotaryEncoder
class	HwStateRotaryEncoder
class	EncoderUpDownButtons
class	SwitchInput

Typedefs
typedef void(*	KeyCallbackFn) (pinid_t key, bool heldDown)
typedef void(*	EncoderCallbackFn) (int newValue)

Enumerations
enum	KeyPressState : uint8_t {   NOT_PRESSED , DEBOUNCING1 , DEBOUNCING2 , PRESSED ,   BUTTON_HELD }
enum	EncoderUserIntention : uint8_t { CHANGE_VALUE = 0 , SCROLL_THROUGH_ITEMS , SCROLL_THROUGH_SIDEWAYS , DIRECTION_ONLY }
enum	HWAccelerationMode : uint8_t { HWACCEL_NONE , HWACCEL_REGULAR , HWACCEL_SLOWER }
enum	EncoderType : uint8_t { QUARTER_CYCLE , HALF_CYCLE , FULL_CYCLE }
enum	SwitchInterruptMode { SWITCHES_NO_POLLING , SWITCHES_POLL_KEYS_ONLY , SWITCHES_POLL_EVERYTHING }

Functions
void	setupStateMachineRotaryEncoder (pinid_t pinA, pinid_t pinB, EncoderCallbackFn callback, HWAccelerationMode accelerationMode=HWACCEL_REGULAR, EncoderType encoderType=FULL_CYCLE)
void	setupStateMachineRotaryEncoder (pinid_t pinA, pinid_t pinB, EncoderListener *listener, HWAccelerationMode accelerationMode=HWACCEL_REGULAR, EncoderType encoderType=FULL_CYCLE)
void	setupRotaryEncoderWithInterrupt (pinid_t pinA, pinid_t pinB, EncoderCallbackFn callback, HWAccelerationMode accelerationMode=HWACCEL_REGULAR, EncoderType encoderType=FULL_CYCLE)
void	setupRotaryEncoderWithInterrupt (pinid_t pinA, pinid_t pinB, EncoderListener *listener, HWAccelerationMode accelerationMode=HWACCEL_REGULAR, EncoderType encoderType=FULL_CYCLE)
void	setupUpDownButtonEncoder (pinid_t pinUp, pinid_t pinDown, EncoderCallbackFn callback, int speed=20)
void	setupUpDownButtonEncoder (pinid_t pinUp, pinid_t pinDown, EncoderListener *listener, int speed=20)
void	setupUpDownButtonEncoder (pinid_t pinUp, pinid_t pinDown, pinid_t pinLeft, pinid_t pinRight, SwitchListener *passThroughListener, EncoderListener *listener, int speed=20)
void	setupUpDownButtonEncoder (pinid_t pinUp, pinid_t pinDown, pinid_t pinLeft, pinid_t pinRight, SwitchListener *passThroughListener, EncoderCallbackFn encoderCallbackFn, int speed=20)

Variables
SwitchInput	switches

Detailed Description

Switch input provides the button and rotary encoder input capabilities provided by this library. There is a globally defined variable switches declared that you can use directly. To add a rotary encoder, see the helper functions further down. There's also a rotary encoder emulation based on Up and Down buttons.

Typedef Documentation

KeyCallbackFn

typedef void(* KeyCallbackFn) (pinid_t key, bool heldDown)

The signature for a callback function that is registered with addSwitch, you can also implement the SwitchListener interface instead to receive updates.

Parameters

key	the pin associated with the pin
heldDown	if the button has been held down

EncoderCallbackFn

typedef void(* EncoderCallbackFn) (int newValue)

The signature for the encoder callback, in addition to this, you can also implement the EncoderListener interface instead to receive updates.

Parameters

newValue

the value of the rotary encoder

Enumeration Type Documentation

EncoderUserIntention

enum EncoderUserIntention : uint8_t

When working with rotary encoders there's three possible ways that the user will interact, and it is this intent that we need to capture, they are either using it for direction only, to scroll through items, or to change a value.

Enumerator
CHANGE_VALUE	User wishes to change or set a value
SCROLL_THROUGH_ITEMS	User wishes to scroll through a list of items
SCROLL_THROUGH_SIDEWAYS	User wishes to scrool through items sideways, such as card layout.
DIRECTION_ONLY	User is just using the encoder for direction only

HWAccelerationMode

enum HWAccelerationMode : uint8_t

This enumeration is used to control how acceleration is handled within a particular instance of a HardwareRotaryEncoder.

Enumerator
HWACCEL_NONE	No acceleration, no matter how fast the encoder is turned
HWACCEL_REGULAR	The default, accelerates based on how fast the encoder is turned
HWACCEL_SLOWER	Slower acceleration than above is applied

EncoderType

enum EncoderType : uint8_t

This enumeration is used to define how an encoder's detents relate to its output states

Enumerator
QUARTER_CYCLE	Detent after every signal change, A or B
HALF_CYCLE	Detent on every position where A == B
FULL_CYCLE	Detent after every full cycle of both signals, A and B

SwitchInterruptMode

enum SwitchInterruptMode

An enumeration of values, one of which is used when calling switches.init to tell switches what to poll for, or not to poll at all.

Enumerator
SWITCHES_NO_POLLING	Do no polling, everything is interrupt driven, it doesn't matter if the interrupt is shared over many keys
SWITCHES_POLL_KEYS_ONLY	Poll for keys but the rotary encoder is managed by interrupt
SWITCHES_POLL_EVERYTHING	Poll for everything, there are no interrupts defined in this mode. Halves the switch poll interval.

Function Documentation

setupStateMachineRotaryEncoder() [1/2]

void setupStateMachineRotaryEncoder	(	pinid_t	pinA,
		pinid_t	pinB,
		EncoderCallbackFn	callback,
		HWAccelerationMode	accelerationMode = HWACCEL_REGULAR,
		EncoderType	encoderType = FULL_CYCLE
	)

Initialise a hardware rotary encoder on the pins passed in, when the value changes the callback function will be called. This library will set pinA and pinB to INPUT_PULLUP, and debounces internally. In most cases no additional components are needed. This function automatically adds the encoder to the global switches instance. This uses the state machine encoder, which is presently in BETA at best.

Parameters

pinA	the first pin of the encoder, this pin must handle interrupts.
pinB	the third pin of the encoder, the middle pin goes to ground.
callback	the function that will receive the new state of the encoder on changes.
accelerationMode	the mode of acceleration to use
encoderType	the type of encoder being used

setupStateMachineRotaryEncoder() [2/2]

void setupStateMachineRotaryEncoder	(	pinid_t	pinA,
		pinid_t	pinB,
		EncoderListener *	listener,
		HWAccelerationMode	accelerationMode = HWACCEL_REGULAR,
		EncoderType	encoderType = FULL_CYCLE
	)

Initialise a hardware rotary encoder on the pins passed in, when the value changes the OO listener will be invoked. This library will set pinA and pinB to INPUT_PULLUP, and debounces internally. In most cases no additional components are needed. This function automatically adds the encoder to the global switches instance. This uses the state machine encoder, which is presently in BETA at best.

Essentially this does:

    auto* enc = new EncoderUpDownButtons(pinUp, pinDown, callback);
 switches.setEncoder(0, enc);

Parameters

pinA	the first pin of the encoder, this pin must handle interrupts.
pinB	the third pin of the encoder, the middle pin goes to ground.
listener	the function that will receive the new state of the encoder on changes.
accelerationMode	the mode of acceleration to use
encoderType	the type of encoder being used

setupRotaryEncoderWithInterrupt() [1/2]

void setupRotaryEncoderWithInterrupt	(	pinid_t	pinA,
		pinid_t	pinB,
		EncoderCallbackFn	callback,
		HWAccelerationMode	accelerationMode = HWACCEL_REGULAR,
		EncoderType	encoderType = FULL_CYCLE
	)

Initialise a hardware rotary encoder on the pins passed in, when the value changes the callback function will be called. This library will set pinA and pinB to INPUT_PULLUP, and debounces internally. In most cases no additional components are needed. This function automatically adds the encoder to the global switches instance.

Essentially this does:

    auto* enc = new EncoderUpDownButtons(pinUp, pinDown, callback);
 switches.setEncoder(0, enc);

Parameters

pinA	the first pin of the encoder, this pin must handle interrupts.
pinB	the third pin of the encoder, the middle pin goes to ground.
callback	the function that will receive the new state of the encoder on changes.
accelerationMode	the mode of acceleration to use
encoderType	the type of encoder being used

setupRotaryEncoderWithInterrupt() [2/2]

void setupRotaryEncoderWithInterrupt	(	pinid_t	pinA,
		pinid_t	pinB,
		EncoderListener *	listener,
		HWAccelerationMode	accelerationMode = HWACCEL_REGULAR,
		EncoderType	encoderType = FULL_CYCLE
	)

Initialise a hardware rotary encoder on the pins passed in, when the value changes the OO listener will be invoked. This library will set pinA and pinB to INPUT_PULLUP, and debounces internally. In most cases no additional components are needed. This function automatically adds the encoder to the global switches instance.

Essentially this does:

    auto* enc = new EncoderUpDownButtons(pinUp, pinDown, callback);
 switches.setEncoder(0, enc);

Parameters

pinA	the first pin of the encoder, this pin must handle interrupts.
pinB	the third pin of the encoder, the middle pin goes to ground.
listener	the function that will receive the new state of the encoder on changes.
accelerationMode	the mode of acceleration to use
encoderType	the type of encoder being used

setupUpDownButtonEncoder() [1/4]

void setupUpDownButtonEncoder	(	pinid_t	pinUp,
		pinid_t	pinDown,
		EncoderCallbackFn	callback,
		int	speed = 20
	)

Initialise an encoder that uses up and down buttons to handle the same functions as a hardware encoder. This function automatically adds the encoder to the global switches instance.

Essentially this does:

    auto* enc = new EncoderUpDownButtons(pinUp, pinDown, callback);
 switches.setEncoder(0, enc);

Parameters

pinUp	the up button
pinDown	the down button
callback	the function that will receive the new state on change.

setupUpDownButtonEncoder() [2/4]

void setupUpDownButtonEncoder	(	pinid_t	pinUp,
		pinid_t	pinDown,
		EncoderListener *	listener,
		int	speed = 20
	)

Initialise an encoder that uses up and down buttons to handle the same functions as a hardware encoder. This function automatically adds the encoder to the global switches instance. This version takes an OO listener implementing EncoderListener.

Essentially this does:

    auto* enc = new EncoderUpDownButtons(pinUp, pinDown, listener);
 switches.setEncoder(0, enc);

Parameters

pinUp	the up button
pinDown	the down button
listener	the OO listener that will receive the new state on change.

setupUpDownButtonEncoder() [3/4]

void setupUpDownButtonEncoder	(	pinid_t	pinUp,
		pinid_t	pinDown,
		pinid_t	pinLeft,
		pinid_t	pinRight,
		SwitchListener *	passThroughListener,
		EncoderListener *	listener,
		int	speed = 20
	)

Initialise an encoder that uses up and down buttons to handle the same functions as a hardware encoder. This function automatically adds the encoder to the global switches instance. This version takes an OO listener implementing EncoderListener. This version supports the idea of rotating the cursor key operation if needed by changing the intent to be sideways.

Parameters

pinUp	the up button
pinDown	the down button
pinLeft	the left button
pinRight	the right button
passThroughListener	a listener that will receive notifications for left and right presses.
listener	the OO listener that will receive the new state on change.

setupUpDownButtonEncoder() [4/4]

void setupUpDownButtonEncoder	(	pinid_t	pinUp,
		pinid_t	pinDown,
		pinid_t	pinLeft,
		pinid_t	pinRight,
		SwitchListener *	passThroughListener,
		EncoderCallbackFn	encoderCallbackFn,
		int	speed = 20
	)

Initialise an encoder that uses up and down buttons to handle the same functions as a hardware encoder. This function automatically adds the encoder to the global switches instance. This version takes an OO listener implementing EncoderListener. This version supports the idea of rotating the cursor key operation if needed by changing the intent to be sideways.

Parameters

pinUp	the up button
pinDown	the down button
pinLeft	the left button
pinRight	the right button
passThroughListener	a listener that will receive notifications for left and right presses.
encoderCallbackFn	will receive the new value on change.

Variable Documentation

switches

SwitchInput switches

extern

This is the global switch input variable. Do not create other instances of this class.