SwitchInput.h

Go to the documentation of this file.

/*
 * Copyright (c) 2018 https://www.thecoderscorner.com (Dave Cherry).
 * This product is licensed under an Apache license, see the LICENSE file in the top-level directory.
 */

 
#ifndef _SWITCHINPUT_H
#define _SWITCHINPUT_H
 
#include "IoAbstraction.h"
#include "TaskManager.h"
#include <BTreeList.h>
 
// START user adjustable section
 
// The threshold for an item becoming held down or for it to repeat, this is about half a second by default
#ifndef HOLD_THRESHOLD
#define HOLD_THRESHOLD 20
#endif //HOLD_THRESHOLD
 
// The rate a which switches will speed up under acceleration, 0 = extremely fast (untested!), 1 = fast, 2 = regular, 3 = slower
#ifndef SWITCHES_ACCELERATION_DIVISOR
#define SWITCHES_ACCELERATION_DIVISOR 2
#endif //SWITCHES_ACCELERATION_DIVISOR
 
/*
 * If you want more buttons, the library will reallocate as needed, however this is not efficient and in production
 * probably better to set this value to about the number of switches needed.  Each button adds about 10 bytes of RAM,
 * so on a tiny you could adjust downwards for example.
 */
#ifndef MAX_KEYS
#define MAX_KEYS DEFAULT_LIST_SIZE
#endif // MAX_KEYS defined

#ifndef MAX_ROTARY_ENCODERS
#define MAX_ROTARY_ENCODERS 4
#endif // MAX_ROTARY_ENCODERS
 
/*
 * This parameter defines the interval between polling on switches. It defaults to 20 millis per poll.
 */
#ifndef SWITCH_POLL_INTERVAL
#define SWITCH_POLL_INTERVAL 20
#endif // SWITCH_POLL_INTERVAL
 
/*
 * This parameter defines the time threshold for which the rotary encoder should reject a direction change as
 * part of the debouncing. IE if there is a spike that would represent a "valid" direction change this would prevent
 * that direction change if within 100 milliseconds of a turn in the other direction. A user would have to be pretty
 * quick to change direction in 1/10th of a second, but it is configurable in case.
 */
#ifndef REJECT_DIRECTION_CHANGE_THRESHOLD
#define REJECT_DIRECTION_CHANGE_THRESHOLD 10000
#endif //REJECT_DIRECTION_CHANGE_THRESHOLD
 
// END user adjustable section

#define NO_REPEAT 0xff
 
enum KeyPressState : uint8_t {
    NOT_PRESSED,
    DEBOUNCING1,
    DEBOUNCING2,
    PRESSED,
    BUTTON_HELD
};
 
#define KEY_PRESS_STATE_MASK 0x0f
#define KEY_LISTENER_MODE_BIT 7
#define KEY_LOGIC_IS_INVERTED 6

void switchesEnableLegacyStateEncoder();

class SwitchListener {
public:
    virtual void onPressed(pinid_t pin, bool held) = 0;
    virtual void onReleased(pinid_t pin, bool held) = 0;
};

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

typedef void(*EncoderCallbackFn)(int newValue);

class KeyboardItem {
private:
    uint8_t stateFlags;
    KeyPressState previousState;
    pinid_t pin;
    uint8_t counter;
    uint8_t acceleration;
    uint8_t repeatInterval;
    union {
        KeyCallbackFn callback;
        SwitchListener* listener;
    } notify;
    KeyCallbackFn callbackOnRelease;
public:
    KeyboardItem();
    KeyboardItem(pinid_t pin, KeyCallbackFn callback, uint8_t repeatInterval = NO_REPEAT, bool keyLogicIsInverted = false);
    KeyboardItem(pinid_t pin, SwitchListener* switchListener, uint8_t repeatInterval = NO_REPEAT, bool keyLogicIsInverted = false);
    KeyboardItem(const KeyboardItem& other);
    KeyboardItem& operator=(const KeyboardItem& other);
    void checkAndTrigger(uint8_t pin);
    void onRelease(KeyCallbackFn callbackOnRelease);
 
    bool isDebouncing() const { return getState() == DEBOUNCING1 || getState() == DEBOUNCING2; }
    bool isPressed() const { return getState() == PRESSED || getState() == BUTTON_HELD; }
    bool isHeld() const { return getState() == BUTTON_HELD; }
    pinid_t getPin() const { return pin;  }
    pinid_t getKey() const { return pin; }
    
    void trigger(bool held);
    void triggerRelease(bool held);
 
    KeyPressState getState() const { return (KeyPressState)(stateFlags & KEY_PRESS_STATE_MASK); }
    void setState(KeyPressState state) { 
        stateFlags &= ~KEY_PRESS_STATE_MASK; 
        stateFlags |= (state & KEY_PRESS_STATE_MASK);
    }
    bool isUsingListener() { return bitRead(stateFlags, KEY_LISTENER_MODE_BIT); }
    bool isLogicInverted() { return bitRead(stateFlags, KEY_LOGIC_IS_INVERTED); }
 
    void changeOnPressed(KeyCallbackFn pFunction);
    void changeListener(SwitchListener* listener);
 
    void setRepeatInterval(uint8_t newInterval) { repeatInterval = newInterval;}
};

enum EncoderUserIntention: uint8_t {
    CHANGE_VALUE = 0,
    SCROLL_THROUGH_ITEMS,
    SCROLL_THROUGH_SIDEWAYS,
    DIRECTION_ONLY
};

class EncoderListener {
public:
    virtual void encoderHasChanged(int newValue)=0;
};

class RotaryEncoder {
protected:
    enum EncoderFlagBits { LAST_SYNC_STATUS=0, WRAP_AROUND_MODE, OO_LISTENER_CALLBACK, LAST_ENCODER_DIRECTION_UP };
    uint16_t maximumValue;
    uint16_t currentReading;
    uint8_t stepSize;
    union {
        EncoderCallbackFn callback;
        EncoderListener* encoderListener;
    } notify;
    uint8_t flags;
    EncoderUserIntention intent;
public:
    explicit RotaryEncoder(EncoderCallbackFn callback);
    explicit RotaryEncoder(EncoderListener* listener);
    virtual ~RotaryEncoder() {;}

    void changePrecision(uint16_t maxValue, int currentValue, bool rolloverOnMax = false, int step = 1);

    void replaceCallback(EncoderCallbackFn callbackFn);

    void replaceCallbackListener(EncoderListener* callbackFn);

    int getCurrentReading() const { return currentReading; }

    void setCurrentReading(int reading) { currentReading = reading; }

    void increment(int8_t incVal);

    virtual void encoderChanged() {;}

    bool didLastSyncSucceed() { return bitRead(flags, LAST_SYNC_STATUS); }

    void setUserIntention(EncoderUserIntention intention);
 
    EncoderUserIntention getUserIntention() { return intent; }
 
    void runCallback(int newVal) {
        if(bitRead(flags, OO_LISTENER_CALLBACK)) {
            notify.encoderListener->encoderHasChanged(newVal);
        } else {
            notify.callback(newVal);
        }
    }

    bsize_t getMaximumValue() { return maximumValue; }
};

enum HWAccelerationMode : uint8_t {
    HWACCEL_NONE,
    HWACCEL_REGULAR, 
    HWACCEL_SLOWER
};

enum EncoderType : uint8_t {
    QUARTER_CYCLE,
    HALF_CYCLE, 
    FULL_CYCLE
};
 
class AbstractHwRotaryEncoder : public RotaryEncoder {
protected:
    unsigned long lastChange;
    pinid_t pinA;
    pinid_t pinB;
    HWAccelerationMode accelerationMode;
    EncoderType encoderType;
 
public:
    explicit AbstractHwRotaryEncoder(EncoderCallbackFn callback) : RotaryEncoder(callback) {}
    explicit AbstractHwRotaryEncoder(EncoderListener* listener) : RotaryEncoder(listener) {}

    void setAccelerationMode(HWAccelerationMode mode) { accelerationMode =  mode; }

    void setEncoderType(EncoderType et) { encoderType =  et; }
 
protected:
    void initialiseBase(pinid_t pinA, pinid_t pinB, HWAccelerationMode accelerationMode, EncoderType);
    int amountFromChange(unsigned long change);
    void handleChangeRaw(bool increase);
};
  
class HardwareRotaryEncoder : public AbstractHwRotaryEncoder {
private:
    uint8_t state = 0;        // Current state of the encoder
    uint8_t pulseCounter = 0; // Pulse counter for FULL_CYCLE and HALF_CYCLE modes
public:
    HardwareRotaryEncoder(pinid_t pinA, pinid_t pinB, EncoderCallbackFn callback, HWAccelerationMode accelerationMode = HWACCEL_REGULAR, EncoderType = FULL_CYCLE);

    HardwareRotaryEncoder(pinid_t pinA, pinid_t pinB, EncoderListener* listener, HWAccelerationMode accelerationMode = HWACCEL_REGULAR, EncoderType = FULL_CYCLE);
    void encoderChanged() override;
private:
    void initialise(pinid_t pinA, pinid_t pinB, HWAccelerationMode accelerationMode, EncoderType et);
};

class HwStateRotaryEncoder : public AbstractHwRotaryEncoder {
private:
    int8_t currentEncoderState = 0;
public:
    HwStateRotaryEncoder(pinid_t pinA, pinid_t pinB, EncoderCallbackFn callback, HWAccelerationMode accelerationMode = HWACCEL_REGULAR, EncoderType = FULL_CYCLE);

    HwStateRotaryEncoder(pinid_t pinA, pinid_t pinB, EncoderListener* listener, HWAccelerationMode accelerationMode = HWACCEL_REGULAR, EncoderType = FULL_CYCLE);
 
    void encoderChanged() override;
private:
    int8_t stateFor(uint8_t bits);
};
 

class EncoderUpDownButtons : public RotaryEncoder, public SwitchListener {
private:
    const pinid_t upPin, downPin, backPin, nextPin;
    SwitchListener* passThroughListener;
    const bool canRotate;
public:
    EncoderUpDownButtons(pinid_t pinUp, pinid_t pinDown, EncoderCallbackFn callback, uint8_t speed = 20);

    EncoderUpDownButtons(pinid_t pinUp, pinid_t pinDown, EncoderListener* listener, uint8_t speed = 20);

    EncoderUpDownButtons(pinid_t pinUp, pinid_t pinDown, pinid_t pinBack, pinid_t pinNext, SwitchListener* passThrough, EncoderCallbackFn callback, uint8_t speed = 20);

    EncoderUpDownButtons(pinid_t pinUp, pinid_t pinDown, pinid_t pinBack, pinid_t pinNext, SwitchListener* passThrough, EncoderListener* listener, uint8_t speed = 20);
 
    void onPressed(pinid_t pin, bool held) override;
    void onReleased(pinid_t pin, bool held) override;
 
protected:
    pinid_t getIncrementPin() { return intent == SCROLL_THROUGH_SIDEWAYS && canRotate ? nextPin : upPin; }
    pinid_t getDecrementPin() { return intent == SCROLL_THROUGH_SIDEWAYS && canRotate ? backPin : downPin; }
    pinid_t getBackPin() { return intent == SCROLL_THROUGH_SIDEWAYS && canRotate ? upPin : backPin; }
    pinid_t getNextPin() { return intent == SCROLL_THROUGH_SIDEWAYS && canRotate ? downPin : nextPin; }
};
 
#define SW_FLAG_PULLUP_LOGIC 0
#define SW_FLAG_INTERRUPT_DRIVEN 1
#define SW_FLAG_INTERRUPT_DEBOUNCE 2
#define SW_FLAG_ENCODER_IS_POLLING 3

enum SwitchInterruptMode {
    SWITCHES_NO_POLLING,
    SWITCHES_POLL_KEYS_ONLY,
    SWITCHES_POLL_EVERYTHING
};
 
 
class SwitchInput {
private:
    RotaryEncoder* encoder[MAX_ROTARY_ENCODERS];
    IoAbstractionRef ioDevice;
    BtreeList<pinid_t, KeyboardItem> keys;
    volatile uint8_t swFlags;
    bool lastSyncStatus;
public:
    explicit 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) { this->encoder[0] = encoder; };

    void setEncoder(uint8_t slot, RotaryEncoder* encoder);

    RotaryEncoder* getEncoder() {return encoder[0]; }

    void changeEncoderPrecision(uint16_t precision, uint16_t currentValue) { changeEncoderPrecision(0, precision, currentValue, false, 1); }

    void changeEncoderPrecision(uint8_t slot, uint16_t precision, uint16_t currentValue) { changeEncoderPrecision(slot, precision, currentValue, false, 1); }

    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() { return ioDevice; }

    bool isPullupLogic(bool invertedLogic) {
        bool pullUp = bitRead(swFlags, SW_FLAG_PULLUP_LOGIC);
        // check if we need to invert the state, basically when the two states don't match.
        return (pullUp && !invertedLogic) || (!pullUp && invertedLogic);
    }
    
    bool isEncoderPollingEnabled() {return bitRead(swFlags, SW_FLAG_ENCODER_IS_POLLING);}
 
    bool isInterruptDriven() {return bitRead(swFlags, SW_FLAG_INTERRUPT_DRIVEN);}

    bool isInterruptDebouncing() {return bitRead(swFlags, SW_FLAG_INTERRUPT_DEBOUNCE);}

    bool isSwitchPressed(pinid_t pin);

    void setInterruptDebouncing(bool debounce) { bitWrite(swFlags, SW_FLAG_INTERRUPT_DEBOUNCE, debounce);}

    bool didLastSyncSucceed() { return lastSyncStatus; }

    void resetAllSwitches();

    bool removeSwitch(pinid_t pin) {
        return keys.removeByKey(pin);
    }

    void setRepeatInterval(pinid_t pin, uint8_t interval);
    void ensureInitialized();
 
private:
    bool internalAddSwitch(pinid_t pin, bool invertLogic);
 
    friend void onSwitchesInterrupt(pinid_t);
};

extern SwitchInput switches;

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);
 
#endif