Hotboards MX / Hotboards_keypad

driver to control n by m matrix keyboard with external pull-ups on columns

Dependents:   LoopCounter HelloKeypad MultiKey EventKeypad ... more

Hotboards_keypad.cpp@2:e870110f753b, 2016-03-04 (annotated)

Committer:
Hotboards
Date:
Fri Mar 04 02:37:55 2016 +0000
Revision:
2:e870110f753b
Parent:
1:975a5c527e8e 
first fucntional release

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Hotboards 0:4ca112f96484 1 /*
Hotboards 0:4ca112f96484 2 ||
Hotboards 0:4ca112f96484 3 || @file Hotboards_Keypad.h
Hotboards 0:4ca112f96484 4 || @version 3.2
Hotboards 0:4ca112f96484 5 || @ported by Diego (Hotboards)
Hotboards 0:4ca112f96484 6 || This Keypad fork library allow to work with keyboard that
Hotboards 0:4ca112f96484 7 || has physical pull-ups on columns (rather than rows)
Hotboards 0:4ca112f96484 8 ||
Hotboards 0:4ca112f96484 9 || Keypad library originaly develop by:
Hotboards 0:4ca112f96484 10 || @author Mark Stanley, Alexander Brevig
Hotboards 0:4ca112f96484 11 || @contact mstanley@technologist.com, alexanderbrevig@gmail.com
Hotboards 0:4ca112f96484 12 ||
Hotboards 0:4ca112f96484 13 || @description
Hotboards 0:4ca112f96484 14 || | This library provides a simple interface for using matrix
Hotboards 0:4ca112f96484 15 || | keypads. It supports multiple keypresses while maintaining
Hotboards 0:4ca112f96484 16 || | backwards compatibility with the old single key library.
Hotboards 0:4ca112f96484 17 || | It also supports user selectable pins and definable keymaps.
Hotboards 0:4ca112f96484 18 || #
Hotboards 0:4ca112f96484 19 ||
Hotboards 0:4ca112f96484 20 || @license
Hotboards 0:4ca112f96484 21 || | This library is free software; you can redistribute it and/or
Hotboards 0:4ca112f96484 22 || | modify it under the terms of the GNU Lesser General Public
Hotboards 0:4ca112f96484 23 || | License as published by the Free Software Foundation; version
Hotboards 0:4ca112f96484 24 || | 2.1 of the License.
Hotboards 0:4ca112f96484 25 || |
Hotboards 0:4ca112f96484 26 || | This library is distributed in the hope that it will be useful,
Hotboards 0:4ca112f96484 27 || | but WITHOUT ANY WARRANTY; without even the implied warranty of
Hotboards 0:4ca112f96484 28 || | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Hotboards 0:4ca112f96484 29 || | Lesser General Public License for more details.
Hotboards 0:4ca112f96484 30 || |
Hotboards 0:4ca112f96484 31 || | You should have received a copy of the GNU Lesser General Public
Hotboards 0:4ca112f96484 32 || | License along with this library; if not, write to the Free Software
Hotboards 0:4ca112f96484 33 || | Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Hotboards 0:4ca112f96484 34 || #
Hotboards 0:4ca112f96484 35 ||
Hotboards 0:4ca112f96484 36 */
Hotboards 0:4ca112f96484 37 #include "Hotboards_keypad.h"
Hotboards 0:4ca112f96484 38
Hotboards 2:e870110f753b 39 #define bitRead( var, bit ) (((var) >> (bit)) & 0x01)
Hotboards 2:e870110f753b 40 #define bitWrite( var, bit, val ) (val) ? (var) |= (1<<(bit)) : (var) &= ~(1<<(bit))
Hotboards 2:e870110f753b 41
Hotboards 0:4ca112f96484 42 // <<constructor>> Allows custom keymap, pin configuration, and keypad sizes.
Hotboards 0:4ca112f96484 43 Keypad::Keypad(char *userKeymap, DigitalInOut *row, DigitalInOut *col, uint8_t numRows, uint8_t numCols) {
Hotboards 0:4ca112f96484 44 rowPins = row;
Hotboards 0:4ca112f96484 45 columnPins = col;
Hotboards 0:4ca112f96484 46 sizeKpd.rows = numRows;
Hotboards 0:4ca112f96484 47 sizeKpd.columns = numCols;
Hotboards 0:4ca112f96484 48
Hotboards 0:4ca112f96484 49 begin(userKeymap);
Hotboards 0:4ca112f96484 50
Hotboards 0:4ca112f96484 51 setDebounceTime(10);
Hotboards 0:4ca112f96484 52 setHoldTime(500);
Hotboards 0:4ca112f96484 53 keypadEventListener = 0;
Hotboards 0:4ca112f96484 54
Hotboards 0:4ca112f96484 55 startTime = 0;
Hotboards 0:4ca112f96484 56 debounce.start();
Hotboards 0:4ca112f96484 57 single_key = false;
Hotboards 0:4ca112f96484 58 }
Hotboards 0:4ca112f96484 59
Hotboards 0:4ca112f96484 60 // Let the user define a keymap - assume the same row/column count as defined in constructor
Hotboards 0:4ca112f96484 61 void Keypad::begin(char *userKeymap) {
Hotboards 0:4ca112f96484 62 keymap = userKeymap;
Hotboards 0:4ca112f96484 63 }
Hotboards 0:4ca112f96484 64
Hotboards 0:4ca112f96484 65 // Returns a single key only. Retained for backwards compatibility.
Hotboards 0:4ca112f96484 66 char Keypad::getKey() {
Hotboards 0:4ca112f96484 67 single_key = true;
Hotboards 0:4ca112f96484 68
Hotboards 0:4ca112f96484 69 if (getKeys() && key[0].stateChanged && (key[0].kstate==PRESSED))
Hotboards 0:4ca112f96484 70 return key[0].kchar;
Hotboards 0:4ca112f96484 71
Hotboards 0:4ca112f96484 72 single_key = false;
Hotboards 0:4ca112f96484 73
Hotboards 0:4ca112f96484 74 return NO_KEY;
Hotboards 0:4ca112f96484 75 }
Hotboards 0:4ca112f96484 76
Hotboards 0:4ca112f96484 77 // Populate the key list.
Hotboards 0:4ca112f96484 78 bool Keypad::getKeys() {
Hotboards 0:4ca112f96484 79 bool keyActivity = false;
Hotboards 0:4ca112f96484 80
Hotboards 0:4ca112f96484 81 // Limit how often the keypad is scanned. This makes the loop() run 10 times as fast.
Hotboards 0:4ca112f96484 82 if ( (debounce.read_ms()-startTime)>debounceTime ) {
Hotboards 0:4ca112f96484 83 scanKeys();
Hotboards 0:4ca112f96484 84 keyActivity = updateList();
Hotboards 0:4ca112f96484 85 startTime = debounce.read_ms();
Hotboards 0:4ca112f96484 86 }
Hotboards 0:4ca112f96484 87
Hotboards 0:4ca112f96484 88 return keyActivity;
Hotboards 0:4ca112f96484 89 }
Hotboards 0:4ca112f96484 90
Hotboards 0:4ca112f96484 91 // Private : Hardware scan
Hotboards 0:4ca112f96484 92 void Keypad::scanKeys() {
Hotboards 0:4ca112f96484 93 // Re-intialize the row pins. Allows sharing these pins with other hardware.
Hotboards 2:e870110f753b 94 for (uint8_t c=0; c<sizeKpd.columns; c++) {
Hotboards 2:e870110f753b 95 columnPins[c].input();
Hotboards 0:4ca112f96484 96 }
Hotboards 0:4ca112f96484 97
Hotboards 0:4ca112f96484 98 // bitMap stores ALL the keys that are being pressed.
Hotboards 0:4ca112f96484 99 for (uint8_t r=0; r<sizeKpd.rows; r++) {
Hotboards 0:4ca112f96484 100 rowPins[r].output();
Hotboards 2:e870110f753b 101 rowPins[r].write( 0 ); // Begin column pulse output.
Hotboards 0:4ca112f96484 102 for (uint8_t c=0; c<sizeKpd.columns; c++) {
Hotboards 2:e870110f753b 103 bitWrite(bitMap[c], r, !columnPins[c].read()); // keypress is active low so invert to high.
Hotboards 0:4ca112f96484 104 }
Hotboards 0:4ca112f96484 105 // Set pin to high impedance input. Effectively ends column pulse.
Hotboards 2:e870110f753b 106 rowPins[r].write( 1 );
Hotboards 0:4ca112f96484 107 rowPins[r].input();
Hotboards 0:4ca112f96484 108 }
Hotboards 0:4ca112f96484 109 }
Hotboards 0:4ca112f96484 110
Hotboards 0:4ca112f96484 111 // Manage the list without rearranging the keys. Returns true if any keys on the list changed state.
Hotboards 0:4ca112f96484 112 bool Keypad::updateList() {
Hotboards 0:4ca112f96484 113
Hotboards 0:4ca112f96484 114 bool anyActivity = false;
Hotboards 0:4ca112f96484 115
Hotboards 0:4ca112f96484 116 // Delete any IDLE keys
Hotboards 0:4ca112f96484 117 for (uint8_t i=0; i<LIST_MAX; i++) {
Hotboards 0:4ca112f96484 118 if (key[i].kstate==IDLE) {
Hotboards 0:4ca112f96484 119 key[i].kchar = NO_KEY;
Hotboards 0:4ca112f96484 120 key[i].kcode = -1;
Hotboards 0:4ca112f96484 121 key[i].stateChanged = false;
Hotboards 0:4ca112f96484 122 }
Hotboards 0:4ca112f96484 123 }
Hotboards 0:4ca112f96484 124
Hotboards 0:4ca112f96484 125 // Add new keys to empty slots in the key list.
Hotboards 0:4ca112f96484 126 for (uint8_t c=0; c<sizeKpd.columns; c++) {
Hotboards 0:4ca112f96484 127 for (uint8_t r=0; r<sizeKpd.rows; r++) {
Hotboards 2:e870110f753b 128 bool button = bitRead(bitMap[r],c);
Hotboards 0:4ca112f96484 129 char keyChar = keymap[c * sizeKpd.rows + r];
Hotboards 0:4ca112f96484 130 int keyCode = r * sizeKpd.columns + c;
Hotboards 0:4ca112f96484 131 int idx = findInList (keyCode);
Hotboards 0:4ca112f96484 132 // Key is already on the list so set its next state.
Hotboards 0:4ca112f96484 133 if (idx > -1) {
Hotboards 0:4ca112f96484 134 nextKeyState(idx, button);
Hotboards 0:4ca112f96484 135 }
Hotboards 0:4ca112f96484 136 // Key is NOT on the list so add it.
Hotboards 0:4ca112f96484 137 if ((idx == -1) && button) {
Hotboards 0:4ca112f96484 138 for (uint8_t i=0; i<LIST_MAX; i++) {
Hotboards 0:4ca112f96484 139 if (key[i].kchar==NO_KEY) { // Find an empty slot or don't add key to list.
Hotboards 0:4ca112f96484 140 key[i].kchar = keyChar;
Hotboards 0:4ca112f96484 141 key[i].kcode = keyCode;
Hotboards 0:4ca112f96484 142 key[i].kstate = IDLE; // Keys NOT on the list have an initial state of IDLE.
Hotboards 0:4ca112f96484 143 nextKeyState (i, button);
Hotboards 0:4ca112f96484 144 break; // Don't fill all the empty slots with the same key.
Hotboards 0:4ca112f96484 145 }
Hotboards 0:4ca112f96484 146 }
Hotboards 0:4ca112f96484 147 }
Hotboards 0:4ca112f96484 148 }
Hotboards 0:4ca112f96484 149 }
Hotboards 0:4ca112f96484 150
Hotboards 0:4ca112f96484 151 // Report if the user changed the state of any key.
Hotboards 0:4ca112f96484 152 for (uint8_t i=0; i<LIST_MAX; i++) {
Hotboards 0:4ca112f96484 153 if (key[i].stateChanged) anyActivity = true;
Hotboards 0:4ca112f96484 154 }
Hotboards 0:4ca112f96484 155
Hotboards 0:4ca112f96484 156 return anyActivity;
Hotboards 0:4ca112f96484 157 }
Hotboards 0:4ca112f96484 158
Hotboards 0:4ca112f96484 159 // Private
Hotboards 0:4ca112f96484 160 // This function is a state machine but is also used for debouncing the keys.
Hotboards 0:4ca112f96484 161 void Keypad::nextKeyState(uint8_t idx, bool button) {
Hotboards 0:4ca112f96484 162 key[idx].stateChanged = false;
Hotboards 0:4ca112f96484 163
Hotboards 0:4ca112f96484 164 switch (key[idx].kstate) {
Hotboards 0:4ca112f96484 165 case IDLE:
Hotboards 0:4ca112f96484 166 if (button==CLOSED) {
Hotboards 0:4ca112f96484 167 transitionTo (idx, PRESSED);
Hotboards 0:4ca112f96484 168 holdTimer = debounce.read_ms(); } // Get ready for next HOLD state.
Hotboards 0:4ca112f96484 169 break;
Hotboards 0:4ca112f96484 170 case PRESSED:
Hotboards 0:4ca112f96484 171 if ((debounce.read_ms()-holdTimer)>holdTime) // Waiting for a key HOLD...
Hotboards 0:4ca112f96484 172 transitionTo (idx, HOLD);
Hotboards 0:4ca112f96484 173 else if (button==OPEN) // or for a key to be RELEASED.
Hotboards 0:4ca112f96484 174 transitionTo (idx, RELEASED);
Hotboards 0:4ca112f96484 175 break;
Hotboards 0:4ca112f96484 176 case HOLD:
Hotboards 0:4ca112f96484 177 if (button==OPEN)
Hotboards 0:4ca112f96484 178 transitionTo (idx, RELEASED);
Hotboards 0:4ca112f96484 179 break;
Hotboards 0:4ca112f96484 180 case RELEASED:
Hotboards 0:4ca112f96484 181 transitionTo (idx, IDLE);
Hotboards 0:4ca112f96484 182 break;
Hotboards 0:4ca112f96484 183 }
Hotboards 0:4ca112f96484 184 }
Hotboards 0:4ca112f96484 185
Hotboards 0:4ca112f96484 186 // New in 2.1
Hotboards 0:4ca112f96484 187 bool Keypad::isPressed(char keyChar) {
Hotboards 0:4ca112f96484 188 for (uint8_t i=0; i<LIST_MAX; i++) {
Hotboards 0:4ca112f96484 189 if ( key[i].kchar == keyChar ) {
Hotboards 0:4ca112f96484 190 if ( (key[i].kstate == PRESSED) && key[i].stateChanged )
Hotboards 0:4ca112f96484 191 return true;
Hotboards 0:4ca112f96484 192 }
Hotboards 0:4ca112f96484 193 }
Hotboards 0:4ca112f96484 194 return false; // Not pressed.
Hotboards 0:4ca112f96484 195 }
Hotboards 0:4ca112f96484 196
Hotboards 0:4ca112f96484 197 // Search by character for a key in the list of active keys.
Hotboards 0:4ca112f96484 198 // Returns -1 if not found or the index into the list of active keys.
Hotboards 0:4ca112f96484 199 int Keypad::findInList (char keyChar) {
Hotboards 0:4ca112f96484 200 for (uint8_t i=0; i<LIST_MAX; i++) {
Hotboards 0:4ca112f96484 201 if (key[i].kchar == keyChar) {
Hotboards 0:4ca112f96484 202 return i;
Hotboards 0:4ca112f96484 203 }
Hotboards 0:4ca112f96484 204 }
Hotboards 0:4ca112f96484 205 return -1;
Hotboards 0:4ca112f96484 206 }
Hotboards 0:4ca112f96484 207
Hotboards 0:4ca112f96484 208 // Search by code for a key in the list of active keys.
Hotboards 0:4ca112f96484 209 // Returns -1 if not found or the index into the list of active keys.
Hotboards 0:4ca112f96484 210 int Keypad::findInList (int keyCode) {
Hotboards 0:4ca112f96484 211 for (uint8_t i=0; i<LIST_MAX; i++) {
Hotboards 0:4ca112f96484 212 if (key[i].kcode == keyCode) {
Hotboards 0:4ca112f96484 213 return i;
Hotboards 0:4ca112f96484 214 }
Hotboards 0:4ca112f96484 215 }
Hotboards 0:4ca112f96484 216 return -1;
Hotboards 0:4ca112f96484 217 }
Hotboards 0:4ca112f96484 218
Hotboards 0:4ca112f96484 219 // New in 2.0
Hotboards 0:4ca112f96484 220 char Keypad::waitForKey() {
Hotboards 0:4ca112f96484 221 char waitKey = NO_KEY;
Hotboards 0:4ca112f96484 222 while( (waitKey = getKey()) == NO_KEY ); // Block everything while waiting for a keypress.
Hotboards 0:4ca112f96484 223 return waitKey;
Hotboards 0:4ca112f96484 224 }
Hotboards 0:4ca112f96484 225
Hotboards 0:4ca112f96484 226 // Backwards compatibility function.
Hotboards 0:4ca112f96484 227 KeyState Keypad::getState() {
Hotboards 0:4ca112f96484 228 return key[0].kstate;
Hotboards 0:4ca112f96484 229 }
Hotboards 0:4ca112f96484 230
Hotboards 0:4ca112f96484 231 // The end user can test for any changes in state before deciding
Hotboards 0:4ca112f96484 232 // if any variables, etc. needs to be updated in their code.
Hotboards 0:4ca112f96484 233 bool Keypad::keyStateChanged() {
Hotboards 0:4ca112f96484 234 return key[0].stateChanged;
Hotboards 0:4ca112f96484 235 }
Hotboards 0:4ca112f96484 236
Hotboards 0:4ca112f96484 237 // The number of keys on the key list, key[LIST_MAX], equals the number
Hotboards 0:4ca112f96484 238 // of bytes in the key list divided by the number of bytes in a Key object.
Hotboards 0:4ca112f96484 239 uint8_t Keypad::numKeys() {
Hotboards 0:4ca112f96484 240 return sizeof(key)/sizeof(Key);
Hotboards 0:4ca112f96484 241 }
Hotboards 0:4ca112f96484 242
Hotboards 0:4ca112f96484 243 // Minimum debounceTime is 1 mS. Any lower *will* slow down the loop().
Hotboards 0:4ca112f96484 244 void Keypad::setDebounceTime(uint debounce) {
Hotboards 0:4ca112f96484 245 debounce<1 ? debounceTime=1 : debounceTime=debounce;
Hotboards 0:4ca112f96484 246 }
Hotboards 0:4ca112f96484 247
Hotboards 0:4ca112f96484 248 void Keypad::setHoldTime(uint hold) {
Hotboards 0:4ca112f96484 249 holdTime = hold;
Hotboards 0:4ca112f96484 250 }
Hotboards 0:4ca112f96484 251
Hotboards 0:4ca112f96484 252 void Keypad::addEventListener(void (*listener)(char)){
Hotboards 0:4ca112f96484 253 keypadEventListener = listener;
Hotboards 0:4ca112f96484 254 }
Hotboards 0:4ca112f96484 255
Hotboards 0:4ca112f96484 256 void Keypad::transitionTo(uint8_t idx, KeyState nextState) {
Hotboards 0:4ca112f96484 257 key[idx].kstate = nextState;
Hotboards 0:4ca112f96484 258 key[idx].stateChanged = true;
Hotboards 0:4ca112f96484 259
Hotboards 0:4ca112f96484 260 // Sketch used the getKey() function.
Hotboards 0:4ca112f96484 261 // Calls keypadEventListener only when the first key in slot 0 changes state.
Hotboards 0:4ca112f96484 262 if (single_key) {
Hotboards 0:4ca112f96484 263 if ( (keypadEventListener!=NULL) && (idx==0) ) {
Hotboards 0:4ca112f96484 264 keypadEventListener(key[0].kchar);
Hotboards 0:4ca112f96484 265 }
Hotboards 0:4ca112f96484 266 }
Hotboards 0:4ca112f96484 267 // Sketch used the getKeys() function.
Hotboards 0:4ca112f96484 268 // Calls keypadEventListener on any key that changes state.
Hotboards 0:4ca112f96484 269 else {
Hotboards 0:4ca112f96484 270 if (keypadEventListener!=NULL) {
Hotboards 0:4ca112f96484 271 keypadEventListener(key[idx].kchar);
Hotboards 0:4ca112f96484 272 }
Hotboards 0:4ca112f96484 273 }
Hotboards 0:4ca112f96484 274 }
Hotboards 0:4ca112f96484 275
Hotboards 0:4ca112f96484 276 /*
Hotboards 0:4ca112f96484 277 || @changelog
Hotboards 0:4ca112f96484 278 || | 3.1 2013-01-15 - Mark Stanley : Fixed missing RELEASED & IDLE status when using a single key.
Hotboards 0:4ca112f96484 279 || | 3.0 2012-07-12 - Mark Stanley : Made library multi-keypress by default. (Backwards compatible)
Hotboards 0:4ca112f96484 280 || | 3.0 2012-07-12 - Mark Stanley : Modified pin functions to support Keypad_I2C
Hotboards 0:4ca112f96484 281 || | 3.0 2012-07-12 - Stanley & Young : Removed static variables. Fix for multiple keypad objects.
Hotboards 0:4ca112f96484 282 || | 3.0 2012-07-12 - Mark Stanley : Fixed bug that caused shorted pins when pressing multiple keys.
Hotboards 0:4ca112f96484 283 || | 2.0 2011-12-29 - Mark Stanley : Added waitForKey().
Hotboards 0:4ca112f96484 284 || | 2.0 2011-12-23 - Mark Stanley : Added the public function keyStateChanged().
Hotboards 0:4ca112f96484 285 || | 2.0 2011-12-23 - Mark Stanley : Added the private function scanKeys().
Hotboards 0:4ca112f96484 286 || | 2.0 2011-12-23 - Mark Stanley : Moved the Finite State Machine into the function getKeyState().
Hotboards 0:4ca112f96484 287 || | 2.0 2011-12-23 - Mark Stanley : Removed the member variable lastUdate. Not needed after rewrite.
Hotboards 0:4ca112f96484 288 || | 1.8 2011-11-21 - Mark Stanley : Added decision logic to compile WProgram.h or Arduino.h
Hotboards 0:4ca112f96484 289 || | 1.8 2009-07-08 - Alexander Brevig : No longer uses arrays
Hotboards 0:4ca112f96484 290 || | 1.7 2009-06-18 - Alexander Brevig : Every time a state changes the keypadEventListener will trigger, if set.
Hotboards 0:4ca112f96484 291 || | 1.7 2009-06-18 - Alexander Brevig : Added setDebounceTime. setHoldTime specifies the amount of
Hotboards 0:4ca112f96484 292 || | microseconds before a HOLD state triggers
Hotboards 0:4ca112f96484 293 || | 1.7 2009-06-18 - Alexander Brevig : Added transitionTo
Hotboards 0:4ca112f96484 294 || | 1.6 2009-06-15 - Alexander Brevig : Added getState() and state variable
Hotboards 0:4ca112f96484 295 || | 1.5 2009-05-19 - Alexander Brevig : Added setHoldTime()
Hotboards 0:4ca112f96484 296 || | 1.4 2009-05-15 - Alexander Brevig : Added addEventListener
Hotboards 0:4ca112f96484 297 || | 1.3 2009-05-12 - Alexander Brevig : Added lastUdate, in order to do simple debouncing
Hotboards 0:4ca112f96484 298 || | 1.2 2009-05-09 - Alexander Brevig : Changed getKey()
Hotboards 0:4ca112f96484 299 || | 1.1 2009-04-28 - Alexander Brevig : Modified API, and made variables private
Hotboards 0:4ca112f96484 300 || | 1.0 2007-XX-XX - Mark Stanley : Initial Release
Hotboards 0:4ca112f96484 301 || #
Hotboards 0:4ca112f96484 302 */