#154 interrupt support for keyboard manager with improved example.

davetcc · davetcc · commit c6ab48e6fce0 · 2022-05-28T09:12:36.000+01:00
diff --git a/examples/matrixKeyboard/matrixKeyboard.ino b/examples/matrixKeyboard/matrixKeyboard.ino
@@ -4,20 +4,23 @@
  * any matrix keyboard quite easily.
  * It just sends the characters that are typed on the keyboard to Serial. The keyboard in This
  * example is connected directly to Arduino pins, but could just as easily be connected over
- * a PCF8574, MCP23017 or other IoAbstraction.
+ * a PCF8574, MCP23017 or other IoAbstraction. For interrupt mode, you cannot use a PCF8574
+ * because the interrupt on the device would be triggered by the output changes when scanning.
+ * Only MCP23017 and device pins can be used in interrupt mode.
  */
 
 #include <Wire.h>
 #include <IoAbstraction.h>
+#include <IoAbstractionWire.h>
 #include<TaskManagerIO.h>
 #include <KeyboardManager.h>
 
 //
 // We need to make a keyboard layout that the manager can use. choose one of the below.
 // The parameter in brackets is the variable name.
 //
-MAKE_KEYBOARD_LAYOUT_3X4(keyLayout)
-//MAKE_KEYBOARD_LAYOUT_4X4(keyLayout)
+//MAKE_KEYBOARD_LAYOUT_3X4(keyLayout)
+MAKE_KEYBOARD_LAYOUT_4X4(keyLayout)
 
 //
 // We need a keyboard manager class too
@@ -47,10 +50,31 @@ public:
     }
 } myListener;
 
-void setup() {
-    while(!Serial);
-    Serial.begin(115200);
+/**
+ * In this method we initialise the keyboard for I2C operation, we assume a 4x4 keyboard was enabled at the top of
+ * the sketch, and as we are using an MCP23017, we can run in interrupt mode to avoid polling the I2C bus. Note that
+ * you cannot enable interrupt mode on PCF8574.
+ */
+void initialiseKeyboard4X4ForInterrupt23017() {
+    Wire.begin();
 
+    keyLayout.setRowPin(0, 11);
+    keyLayout.setRowPin(1, 10);
+    keyLayout.setRowPin(2, 9);
+    keyLayout.setRowPin(3, 8);
+    keyLayout.setColPin(0, 15);
+    keyLayout.setColPin(1, 14);
+    keyLayout.setColPin(2, 13);
+    keyLayout.setColPin(3, 12);
+
+    keyboard.initialise(ioFrom23017(0x20, ACTIVE_LOW_OPEN, 10), &keyLayout, &myListener, true);
+}
+
+/**
+ * In this method we initialise the keyboard to use the arduino pins directly. We assume a 4x3 keyboard was set at the
+ * top. We use the keyboard in polling mode in this case. Polling mode can be used on any device.
+ */
+void initialiseKeyboard3X4ForPollingDevicePins() {
     keyLayout.setRowPin(0, 22);
     keyLayout.setRowPin(1, 23);
     keyLayout.setRowPin(2, 24);
@@ -62,8 +86,22 @@ void setup() {
     // create the keyboard mapped to arduino pins and with the layout chosen above.
     // it will callback our listener
     keyboard.initialise(arduinoIo, &keyLayout, &myListener);
+}
+
+void setup() {
+    while(!Serial);
+    Serial.begin(115200);
+
+    tm_internal::setLoggingDelegate([](tm_internal::TmErrorCode errorCode, int task) {
+        serdebugF3("TMLog ", errorCode, task);
+    });
+
+    // here you can choose between two stock configurations or you could alter one of the
+    // methods to meet your hardware requirements.
+    initialiseKeyboard4X4ForInterrupt23017();
+    //initialiseKeyboard3X4ForPollingDevicePins();
 
-    // start repeating at 850 millis then repeat every 350ms
+    // now set up the repeat key start and interval
     keyboard.setRepeatKeyMillis(850, 350);
 
     Serial.println("Keyboard is initialised!");
diff --git a/src/IoAbstraction.h b/src/IoAbstraction.h
@@ -54,25 +54,25 @@ class ShiftRegisterIoAbstraction : public BasicIoAbstraction {
 	 */
 	ShiftRegisterIoAbstraction(pinid_t readClockPin, pinid_t readDataPin, pinid_t readLatchPin,
 	                           pinid_t writeClockPin, pinid_t writeDataPin, pinid_t writeLatchPin, uint8_t numRead, uint8_t numWrite);
-	virtual ~ShiftRegisterIoAbstraction() { }
-	virtual void pinDirection(pinid_t pin, uint8_t mode);
-	virtual void writeValue(pinid_t pin, uint8_t value);
-	virtual uint8_t readValue(uint8_t pin);
+	~ShiftRegisterIoAbstraction() override { }
+	void pinDirection(pinid_t pin, uint8_t mode) override;
+	void writeValue(pinid_t pin, uint8_t value) override;
+	uint8_t readValue(uint8_t pin) override;
 	/**
 	 * Interrupts are not supported on shift registers
 	 */
-	virtual void attachInterrupt(pinid_t, RawIntHandler, uint8_t) {;}
-	virtual bool runLoop();
+	void attachInterrupt(pinid_t, RawIntHandler, uint8_t) override {;}
+	bool runLoop() override;
 	
 	/**
 	 * writes to the output shift register - currently always port 0
 	 */
-	virtual void writePort(pinid_t port, uint8_t portVal);
+	void writePort(pinid_t port, uint8_t portVal) override;
 
 	/**
 	 * reads from the input shift register - currently always port 3
 	 */
-	virtual uint8_t readPort(pinid_t port);
+	uint8_t readPort(pinid_t port) override;
 };
 
 class ShiftRegisterIoAbstraction165In : public BasicIoAbstraction {
@@ -91,21 +91,21 @@ class ShiftRegisterIoAbstraction165In : public BasicIoAbstraction {
      * @see outputOnlyFromShiftRegister
      */
     ShiftRegisterIoAbstraction165In(pinid_t readClockPin, pinid_t readDataPin, pinid_t readLatchPin, pinid_t numRead);
-    ~ShiftRegisterIoAbstraction165In() override { }
+    ~ShiftRegisterIoAbstraction165In() override = default;
 
     /** Input only abstraction, does nothing because only input is supported */
-    virtual void pinDirection(pinid_t pin, uint8_t mode) { }
+    void pinDirection(pinid_t pin, uint8_t mode) override { }
 
-    virtual uint8_t readValue(pinid_t pin);
-    virtual bool runLoop();
-    virtual uint8_t readPort(pinid_t port);
+    uint8_t readValue(pinid_t pin) override;
+    bool runLoop() override;
+    uint8_t readPort(pinid_t port) override;
 
     //
     // Features not implemented on this abstaction
     //
-    virtual void writePort(pinid_t port, uint8_t portVal) { }
-    virtual void writeValue(pinid_t pin, uint8_t value) { }
-    virtual void attachInterrupt(pinid_t, RawIntHandler, uint8_t) { }
+    void writePort(pinid_t port, uint8_t portVal) override { }
+    void writeValue(pinid_t pin, uint8_t value) override { }
+    void attachInterrupt(pinid_t, RawIntHandler, uint8_t) override { }
 
     uint8_t shiftInFor165() const;
 };
@@ -208,8 +208,8 @@ class MultiIoAbstraction : public BasicIoAbstraction {
 	pinid_t limits[MAX_ALLOWABLE_DELEGATES];
 	uint8_t numDelegates;
 public:
-	MultiIoAbstraction(pinid_t arduinoPinsNeeded = 100);
-	virtual ~MultiIoAbstraction();
+	explicit MultiIoAbstraction(pinid_t arduinoPinsNeeded = 100);
+	~MultiIoAbstraction() override;
 	void addIoExpander(IoAbstractionRef expander, pinid_t numOfPinsNeeded);
 
 	/** 
diff --git a/src/KeyboardManager.cpp b/src/KeyboardManager.cpp
@@ -9,30 +9,51 @@
 #include "KeyboardManager.h"
 #include "IoLogging.h"
 
+MatrixKeyboardManager* MatrixKeyboardManager::INSTANCE = nullptr;
+
+ISR_ATTR void rawKeyboardInterrupt() {
+    auto kbMgr = MatrixKeyboardManager::INSTANCE;
+    if(kbMgr->keyMode == KEYMODE_NOT_PRESSED) {
+        // we only need to be notified when not pressed. As in other states we are polling
+        kbMgr->markTriggeredAndNotify();
+    }
+}
+
 MatrixKeyboardManager::MatrixKeyboardManager() {
-    this->ioRef = NULL;
-    this->layout = NULL;
-    this->listener = NULL;
+    this->ioRef = nullptr;
+    this->layout = nullptr;
+    this->listener = nullptr;
+    currentKey = 0;
+    keyMode = KEYMODE_NOT_PRESSED;
+    interruptMode = false;
+    counter = 0;
+    INSTANCE = this;
 }
 
-void MatrixKeyboardManager::initialise(IoAbstractionRef ref, KeyboardLayout* layout, KeyboardListener* listener) {
+void MatrixKeyboardManager::initialise(IoAbstractionRef ref, KeyboardLayout* layout_, KeyboardListener* listener_, bool interruptMode_) {
     this->ioRef = ref;
-    this->layout = layout;
-    this->listener = listener;
+    this->layout = layout_;
+    this->listener = listener_;
+    this->interruptMode = interruptMode_;
 
     for(int i=0; i<layout->numColumns(); i++) {
         ioDevicePinMode(ioRef, layout->getColPin(i), OUTPUT);
-        ioDeviceDigitalWrite(ioRef, layout->getColPin(i), HIGH);
+        ioDeviceDigitalWrite(ioRef, layout->getColPin(i), LOW);
+    }
+    for(int i=0; i<layout->numRows(); i++) {
+        ioDevicePinMode(ioRef, layout->getRowPin(i), INPUT_PULLUP);
+        if(interruptMode && INSTANCE) {
+            ioRef->attachInterrupt(layout->getRowPin(i), rawKeyboardInterrupt, CHANGE);
+        }
     }
-    for(int i=0; i<layout->numRows(); i++) ioDevicePinMode(ioRef, layout->getRowPin(i), INPUT_PULLUP);
 
     ioDeviceSync(ioRef);
 
     currentKey = 0;
-    taskManager.scheduleFixedRate(KEYBOARD_TASK_MILLIS, this);
+    taskManager.registerEvent(this);
 }
 
-void MatrixKeyboardManager::setToOuput(int col) {
+void MatrixKeyboardManager::setToOutput(int col) {
     for(int i=0; i<layout->numColumns(); i++) {
         ioDeviceDigitalWrite(ioRef, layout->getColPin(i), col != i);
     }
@@ -43,18 +64,26 @@ void MatrixKeyboardManager::setRepeatKeyMillis(int startAfterMillis, int repeatM
     repeatTicks = repeatMillis / KEYBOARD_TASK_MILLIS; 
 }
 
+inline bool isDebouncing(KeyMode keyMode) {
+    return keyMode == KEYMODE_DEBOUNCE || keyMode == KEYMODE_DEBOUNCE1 || keyMode == KEYMODE_DEBOUNCE2;
+}
+
 void MatrixKeyboardManager::exec() {
-    if(ioRef == NULL) return;
+    if(ioRef == nullptr) {
+        serdebugF("ioRef null");
+        return;
+    }
 
     char pressThisTime = 0;
 
+
     // then we read back the right state
     for(int c=0;c<layout->numColumns();c++) {
-        setToOuput(c);        
+        setToOutput(c);
         ioDeviceSync(ioRef); // first we set the right column low.
         taskManager.yieldForMicros(500); // let things settle while other tasks run.
         ioDeviceSync(ioRef); // then we read the latest row states back
-        
+
         for(int r=0; r<layout->numRows(); r++) {
             if(!ioDeviceDigitalRead(ioRef, layout->getRowPin(r))) {
                 pressThisTime = layout->keyFor(r, c);
@@ -63,11 +92,10 @@ void MatrixKeyboardManager::exec() {
         }
     }
 
-
     // if the key is the same as last time and not zero
     if(pressThisTime == currentKey && pressThisTime) {
         // then we either have finished debouncing or are repeating
-        if(keyMode == KEYMODE_DEBOUNCE) {
+        if(isDebouncing(keyMode)) {
             keyMode = KEYMODE_PRESSED;
             counter = repeatStartTicks;
             listener->keyPressed(currentKey, false);
@@ -79,16 +107,57 @@ void MatrixKeyboardManager::exec() {
             }
         }
         else keyMode = KEYMODE_DEBOUNCE;
-    }
-    else {
-        // otherwise the keys are not the same, we are either in released 
-        // state or debouncing.
+    } else {
+        // first clear any existing state
         if(keyMode == KEYMODE_PRESSED) {
             keyMode = KEYMODE_NOT_PRESSED;
             counter = 0;
             listener->keyReleased(currentKey);
+            currentKey = 0;
         }
-        if(pressThisTime != 0) keyMode = KEYMODE_DEBOUNCE;
-        currentKey = pressThisTime;
+        doDebounce(pressThisTime);
+    }
+
+    enableAllOutputsForInterrupt();
+}
+
+uint32_t MatrixKeyboardManager::timeOfNextCheck() {
+
+    if(interruptMode && (keyMode == KEYMODE_NOT_PRESSED)) {
+        return secondsToMicros(1);
+    } else {
+        setTriggered(true);
+        return millisToMicros(KEYBOARD_TASK_MILLIS);
+    }
+}
+
+void MatrixKeyboardManager::enableAllOutputsForInterrupt() {
+    if(interruptMode && keyMode == KEYMODE_NOT_PRESSED) {
+        // in interrupt mode we set all output pins low when nothing is pressed so that any change will be detected.
+        // this effectively means that each column pin is low and will pull down the input line. We don't need to
+        // know what is pressed, just that something was pressed.
+        for(int i=0; i < layout->numColumns(); i++) {
+            ioDeviceDigitalWrite(ioRef, layout->getColPin(i), 0);
+        }
+        ioDeviceSync(ioRef);
+    }
+}
+
+void MatrixKeyboardManager::doDebounce(char pressedNow) {
+    if(isDebouncing(keyMode) && currentKey == pressedNow) {
+        currentKey = pressedNow;
+        keyMode = KEYMODE_PRESSED;
+        return;
+    }
+
+    if(pressedNow && keyMode == KEYMODE_NOT_PRESSED) {
+        currentKey = pressedNow;
+        keyMode = KEYMODE_DEBOUNCE;
+    } else if(keyMode == KEYMODE_DEBOUNCE) {
+        keyMode = KEYMODE_DEBOUNCE1;
+    } else if(keyMode == KEYMODE_DEBOUNCE1) {
+        keyMode = KEYMODE_DEBOUNCE2;
+    } else if (keyMode == KEYMODE_DEBOUNCE2) {
+        keyMode = KEYMODE_NOT_PRESSED;
     }
 }
diff --git a/src/KeyboardManager.h b/src/KeyboardManager.h
@@ -96,35 +96,50 @@ class KeyboardLayout {
 enum KeyMode: uint8_t {
     KEYMODE_NOT_PRESSED,
     KEYMODE_DEBOUNCE,
+    KEYMODE_DEBOUNCE1,
+    KEYMODE_DEBOUNCE2,
     KEYMODE_PRESSED,
     KEYMODE_REPEATING
 };
 
 #define KEYBOARD_TASK_MILLIS 50
 
 /**
- * A keyboard manager that can determine if a key is pressed or released for a given
- * layout of keyboard. It is configured during initialisation with an IoAbstraction
- * that is used to access hardware, a specific keyboard layout and a listener that
- * will be called back when keys are pressed and released.
+ * A keyboard manager that can determine if a key is pressed or released for a given layout of keyboard. It is configured
+ * during initialisation with an IoAbstraction that is used to access hardware, a specific keyboard layout and a listener
+ * that will be called back when keys are pressed and released. The keyboard layout also sets what character is associated
+ * with each key.
+ *
+ * You can decide between polling operation and interrupt operation, if interrupt operation is chosen then all the row
+ * pins must be on interrupt capable pins, which on many boards is best achieved by using an MCP23017 for all the pins.
+ * Do not enable interrupt mode on a PCF8574 as the changing of the output pins will trigger the interrupt.
  */
-class MatrixKeyboardManager : public Executable {
+class MatrixKeyboardManager : public BaseEvent {
 private:
+    static MatrixKeyboardManager* INSTANCE;
     KeyboardListener* listener;
     KeyboardLayout* layout;
     IoAbstractionRef ioRef;
     uint8_t repeatTicks = 10;
     uint8_t repeatStartTicks = 30;
     char currentKey;
-    KeyMode keyMode;
+    volatile KeyMode keyMode;
     uint8_t counter;
+    bool interruptMode;
 public:
     MatrixKeyboardManager();
-    void initialise(IoAbstractionRef ref, KeyboardLayout* layout, KeyboardListener* listener);
+    void initialise(IoAbstractionRef ref, KeyboardLayout* layout, KeyboardListener* listener, bool interruptMode = false);
     void setRepeatKeyMillis(int startAfterMillis, int repeatMillis);
-    void exec();
+
+    uint32_t timeOfNextCheck() override;
+    void exec() override;
+
+    friend void rawKeyboardInterrupt();
 private:
-    void setToOuput(int i);
+    void setToOutput(int i);
+    void enableAllOutputsForInterrupt();
+
+    void doDebounce(char time);
 };
 
 #define MAKE_KEYBOARD_LAYOUT_3X4(varName) const char KEYBOARD_STD_3X4_KEYS[] PROGMEM = "123456789*0#"; KeyboardLayout varName(4, 3, KEYBOARD_STD_3X4_KEYS);
