IoAbstraction
Classes | Typedefs | Enumerations | Functions | Variables
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
keythe pin associated with the pin
heldDownif 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
newValuethe 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

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
pinAthe first pin of the encoder, this pin must handle interrupts.
pinBthe third pin of the encoder, the middle pin goes to ground.
callbackthe function that will receive the new state of the encoder on changes.
accelerationModethe mode of acceleration to use
encoderTypethe 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
pinAthe first pin of the encoder, this pin must handle interrupts.
pinBthe third pin of the encoder, the middle pin goes to ground.
listenerthe function that will receive the new state of the encoder on changes.
accelerationModethe mode of acceleration to use
encoderTypethe 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
pinAthe first pin of the encoder, this pin must handle interrupts.
pinBthe third pin of the encoder, the middle pin goes to ground.
callbackthe function that will receive the new state of the encoder on changes.
accelerationModethe mode of acceleration to use
encoderTypethe 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
pinAthe first pin of the encoder, this pin must handle interrupts.
pinBthe third pin of the encoder, the middle pin goes to ground.
listenerthe function that will receive the new state of the encoder on changes.
accelerationModethe mode of acceleration to use
encoderTypethe 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
pinUpthe up button
pinDownthe down button
callbackthe 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
pinUpthe up button
pinDownthe down button
listenerthe 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
pinUpthe up button
pinDownthe down button
pinLeftthe left button
pinRightthe right button
passThroughListenera listener that will receive notifications for left and right presses.
listenerthe 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
pinUpthe up button
pinDownthe down button
pinLeftthe left button
pinRightthe right button
passThroughListenera listener that will receive notifications for left and right presses.
encoderCallbackFnwill 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.