IoAbstraction
Public Member Functions | Friends | List of all members
SwitchInput Class Reference

#include <SwitchInput.h>

Public Member Functions

 SwitchInput ()
 
void initialise (IoAbstractionRef ioDevice, bool usePullUpSwitching=false)
 
void init (IoAbstractionRef ioDevice, SwitchInterruptMode mode, bool defaultIsPullUp)
 
void initialiseInterrupt (IoAbstractionRef ioDevice, bool usePullUpSwitching=false)
 
bool addSwitch (pinid_t pin, KeyCallbackFn callback, uint8_t repeat=NO_REPEAT, bool invertLogic=false)
 
bool addSwitchListener (pinid_t pin, SwitchListener *listener, uint8_t repeat=NO_REPEAT, bool invertLogic=false)
 
void onRelease (pinid_t pin, KeyCallbackFn callbackOnRelease)
 
void replaceOnPressed (pinid_t pin, KeyCallbackFn callbackOnPressed)
 
void replaceSwitchListener (pinid_t pin, SwitchListener *newListener)
 
void setEncoder (RotaryEncoder *encoder)
 
void setEncoder (uint8_t slot, RotaryEncoder *encoder)
 
RotaryEncodergetEncoder ()
 
void changeEncoderPrecision (uint16_t precision, uint16_t currentValue)
 
void changeEncoderPrecision (uint8_t slot, uint16_t precision, uint16_t currentValue)
 
void changeEncoderPrecision (uint8_t slot, uint16_t precision, uint16_t currentValue, bool rollover, int step=1)
 
void pushSwitch (pinid_t pin, bool held)
 
bool runLoop ()
 
IoAbstractionRef getIoAbstraction ()
 
bool isPullupLogic (bool invertedLogic)
 
bool isEncoderPollingEnabled ()
 
bool isInterruptDriven ()
 
bool isInterruptDebouncing ()
 
bool isSwitchPressed (pinid_t pin)
 
void setInterruptDebouncing (bool debounce)
 
bool didLastSyncSucceed ()
 
void resetAllSwitches ()
 
bool removeSwitch (pinid_t pin)
 

Friends

void onSwitchesInterrupt (pinid_t)
 

Detailed Description

Provides event based switches that are automatically debounced with repeatkey or hold notification. This library integrates with TaskManager and taskManager.runLoop() must therefore be called in the loop method. This class can handle pull up or pull down switches, either interrupt driven or polling.

Further, this library can work with ANY of the IO abstractions, so the switches can be on either arduino pins or an i2c expander.

See also
BasicIoAbstraction
TaskManager

Constructor & Destructor Documentation

◆ SwitchInput()

SwitchInput::SwitchInput ( )
explicit

always use the global switches instance.

See also
switches

Member Function Documentation

◆ initialise()

void SwitchInput::initialise ( IoAbstractionRef  ioDevice,
bool  usePullUpSwitching = false 
)

initialise switch input so that it can start managing switches using polling via task manager every 1/20 of a second. If the switches are pull the library automatically uses INPUT_PULLUP. For most usages this will mean no external resistors are needed.

Parameters
ioDevicethe ioDevice where the switches are connected
usePullUpSwitchingtrue if the switches are pull, false for pull down.
Deprecated:
please use init(IoAbstractionRef, SwitchInterruptMode) instead in new code

◆ init()

void SwitchInput::init ( IoAbstractionRef  ioDevice,
SwitchInterruptMode  mode,
bool  defaultIsPullUp 
)

initialise switch input so that it can start managing switches either using polling via task manager or via an interrupt callback if so configured. Note that the configuration of mode defines the polling, and when set to NO_POLLING it means that switches completely relies on interrupts.

You can define the default for pull up / pull down, and if the code is interrupt driven. If the switches are in pull-up mode the library automatically uses INPUT_PULLUP. At least for testing, this will mean no external resistors are needed. Prefer this in newer code to initialise which is kept around for backward compatibility.

Switches and the encoder will use the same ioDevice that will be used to register any needed interrupts, set up pin direction

Parameters
ioDevicethe ioDevice where the switches are connected
interruptModemode the interrupt mode to operate in
defaultIsPullUpif true the default is pull up, otherwise the default is pull down

◆ initialiseInterrupt()

void SwitchInput::initialiseInterrupt ( IoAbstractionRef  ioDevice,
bool  usePullUpSwitching = false 
)

initialise switch input so that it can start managing switches using an interrupt to determine switch changes. Polling is only used for debounce or repeat key actions. If the switches are pull the library automatically uses INPUT_PULLUP. For most usages this will mean no external resistors are needed.

Parameters
ioDevicethe ioDevice where the switches are connected
usePullUpSwitchingtrue if the switches are pull, false for pull down.
Deprecated:
please use init(IoAbstractionRef, SwitchInterruptMode) instead in new code

◆ addSwitch()

bool SwitchInput::addSwitch ( pinid_t  pin,
KeyCallbackFn  callback,
uint8_t  repeat = NO_REPEAT,
bool  invertLogic = false 
)

Add a switch to be managed by switches, it can optionally be a repeat key

Parameters
pinthe pin on which the switch is attached
callbackthe function to be called back upon change
invertLogicoptional - inverts the logic between active high and active low for one switch
repeatoptional - the frequency in intervals of 1/20th second to repeat.
Returns
true if successful, false if the pin could not be registered.

◆ addSwitchListener()

bool SwitchInput::addSwitchListener ( pinid_t  pin,
SwitchListener listener,
uint8_t  repeat = NO_REPEAT,
bool  invertLogic = false 
)

Add a switch to be managed by switches using an implementation of the SwitchListener interface to receive events instead of function callbacks.

Parameters
pinthe pin on which the switch is attached
listenerreference to a listener that will be notified of press and release.
invertLogicoptional - inverts the logic between active high and active low for one switch
repeatoptional - the frequency in intervals of 1/20th second to repeat.
Returns
true if successful, false if the pin could not be registered.

◆ onRelease()

void SwitchInput::onRelease ( pinid_t  pin,
KeyCallbackFn  callbackOnRelease 
)

Set callback the function to be called back upon key release

Parameters
pinthe pin on which the switch is attached
callbackOnReleasethe function to be called back upon key release

◆ replaceOnPressed()

void SwitchInput::replaceOnPressed ( pinid_t  pin,
KeyCallbackFn  callbackOnPressed 
)

Allows for a change of the function to be called when a key is pressed for a given key

Parameters
pinthe pin on which the switch is attached
callbackOnPressedthe function to be called when a key is pressed

◆ replaceSwitchListener()

void SwitchInput::replaceSwitchListener ( pinid_t  pin,
SwitchListener newListener 
)

Allows for a change of the listener that reports when a key is pressed for a given key

Parameters
pinthe pin on which the switch is attached
newListenerthe new object to receive updates when a key is pressed

◆ setEncoder() [1/2]

void SwitchInput::setEncoder ( RotaryEncoder encoder)
inline

Sets the rotary encoder to use, unless you have a custom one, prefer to use the setup methods

See also
setupRotaryEncoderWithInterrupt
setupUpDownButtonEncoder

◆ setEncoder() [2/2]

void SwitchInput::setEncoder ( uint8_t  slot,
RotaryEncoder encoder 
)

Use this method if you want to work with serveral encoders. This lib defaults to 4 (value of MAX_ROTARY_ENCODERS) encoders, but the actual number of encoders depends on the hardware you are using and the value of that define. If your port expander is 8-bit it supports up to 4 rotary encoders. To use more than 4, you set MAX_ROTARY_ENCODERS to the value you need and use a 16-bit encoder.

Parameters
slotthe index of the encoder to set, zero based.
encoderthe encoder to be added.

◆ getEncoder()

RotaryEncoder* SwitchInput::getEncoder ( )
inline

Gets a pointer to the current encoder, or NULL if there is not one

◆ changeEncoderPrecision() [1/3]

void SwitchInput::changeEncoderPrecision ( uint16_t  precision,
uint16_t  currentValue 
)
inline

This is helper function that calls the rotary encoders change precision function. It changes the maximum value that can be represented and also the current value of the encoder. This always affects slot 0; which is normally the default rotary encoder.

Parameters
precisionthe maximum value to be set
currentValuethe current value to be set.

◆ changeEncoderPrecision() [2/3]

void SwitchInput::changeEncoderPrecision ( uint8_t  slot,
uint16_t  precision,
uint16_t  currentValue 
)
inline

This is helper function that calls the rotary encoders change precision function. It changes the maximum value that can be represented and also the current value of the encoder. The encoder to change is selected by the slot paramter.

Parameters
slotthe index of the desired encoder, zero based
precisionthe maximum value to be set
currentValuethe current value to be set.

◆ changeEncoderPrecision() [3/3]

void SwitchInput::changeEncoderPrecision ( uint8_t  slot,
uint16_t  precision,
uint16_t  currentValue,
bool  rollover,
int  step = 1 
)

Use this version of changeEncoderPrecision if you are working with more than one rotary encoder. This is helper function that calls the rotary encoders change precision function. It changes the maximum value that can be represented and also the current value of the encoder.

Parameters
slotthe index of the desired encoder, zero based
precisionthe maximum value to be set
currentValuethe current value to be set.
rolloverif the encoder should wrap around at min/max values or stop
stepthe size of each step of the encoder, default is 1

◆ pushSwitch()

void SwitchInput::pushSwitch ( pinid_t  pin,
bool  held 
)

Simulates a switch press by calling the callback directly without changing the internal state of the key. Useful to simulate a key press in some situations.

Parameters
pinthe pin associated with the switch
heldif the held state should be set on the callback

◆ runLoop()

bool SwitchInput::runLoop ( )

This will normally be called by task manager when not interrupt driven.

◆ getIoAbstraction()

IoAbstractionRef SwitchInput::getIoAbstraction ( )
inline

Gets the IoAbstraction that is being used

◆ isPullupLogic()

bool SwitchInput::isPullupLogic ( bool  invertedLogic)
inline

Returns true if the logic should be pull up, otherwise false.

Parameters
invertedLogicindicates if the key we are checking for is invertedLogic
Returns
true if pull up style switching, otherwise false.

◆ isEncoderPollingEnabled()

bool SwitchInput::isEncoderPollingEnabled ( )
inline
Returns
if encoders are configured as polling or interrupt only

◆ isInterruptDebouncing()

bool SwitchInput::isInterruptDebouncing ( )
inline
Returns
if interrupt debouncing is in progress

◆ isSwitchPressed()

bool SwitchInput::isSwitchPressed ( pinid_t  pin)

Returns true if the switch at the defined pin is pressed, otherwise false

Parameters
pinthe pin to check if pressed

◆ setInterruptDebouncing()

void SwitchInput::setInterruptDebouncing ( bool  debounce)
inline

Sets the debounce state - only really for internal use.

Parameters
debouncetrue if debouncing.

◆ didLastSyncSucceed()

bool SwitchInput::didLastSyncSucceed ( )
inline

Gets the last sync status of the IoAbstraction being used by switches.

Returns
the last sync status as an bool, true for success, otherwise false.

◆ resetAllSwitches()

void SwitchInput::resetAllSwitches ( )

Removes all switch definitions and resets switches as if it were just initialised. IMPORTANT: no attempt is made to deregister any resources or remove registered interrupts.

◆ removeSwitch()

bool SwitchInput::removeSwitch ( pinid_t  pin)
inline

Remove a switch by it's pin reference. Returns true if able to remove the pin IMPORTANT: no attempt is made to deregister any resources or remove registered interrupts.

Parameters
pinthe pin number to remove
Returns
true if removed, otherwise false.

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