Serial Wombat Arduino Library
SerialWombatMatrixKeypad.h
Go to the documentation of this file.
1 #pragma once
2 
3 /*
4 Copyright 2021-2023 Broadwell Consulting Inc.
5 
6 "Serial Wombat" is a registered trademark of Broadwell Consulting Inc. in
7 the United States. See SerialWombat.com for usage guidance.
8 
9 Permission is hereby granted, free of charge, to any person obtaining a
10  * copy of this software and associated documentation files (the "Software"),
11  * to deal in the Software without restriction, including without limitation
12  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
13  * and/or sell copies of the Software, and to permit persons to whom the
14  * Software is furnished to do so, subject to the following conditions:
15 
16 The above copyright notice and this permission notice shall be included in
17  * all copies or substantial portions of the Software.
18 
19 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
22  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
23  * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
24  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
25  * OTHER DEALINGS IN THE SOFTWARE.
26 */
27 
28 #include "Stream.h"
29 #include "SerialWombat.h"
88  public Stream
89 {
90 public:
95  SerialWombatMatrixKeypad(SerialWombatChip& serialWombat):_sw(serialWombat)
96  {
97  _sw = serialWombat;
98  }
99  /*
100  @brief Initalize the SerialWombatMatrixKeypad.
101  @param controlPin Keypad scanning transitions will occur while this pin is being serviced by the Serial Wombat executive. Typically this will be the same as the row0 pin
102  @param row0pin pin attached to the topmost keypad row. On many marked keypads this row has 1,2,3 and A in it. Enter 255 if this column is unused
103  @param row1pin pin attached to the topcenter keypad row. On many marked keypads this row has 4,5,6 and B in it. Enter 255 if this row is unused
104  @param row2pin pin attached to the topmost keypad row. On many marked keypads this row has 7,8,9 and C in it. Enter 255 if this row is unused
105  @param row3pin pin attached to the topmost keypad row. On many marked keypads this row has *,0,# and D in it. Enter 255 if this row is unused
106  @param column0pin pin attached to the leftmost keypad column. On many marked keypads this column has 1,4,7 and * in it. Enter 255 if this column is unused
107  @param column1pin pin attached to the leftcenter keypad column. On many marked keypads this column has 1,5,8 and 0 in it. Enter 255 if this column is unused
108  @param column2pin pin attached to the rightcenter keypad column. On many marked keypads this column has 3,5,9 and # in it. Enter 255 if this column is unused
109  @param column3pin pin attached to the rightmost keypad column. On many marked keypads this column has A,B,C and D in it. Enter 255 if this column is unused
110  @param bufferMode 0: Public data is Binary of 16 keys (Default) 1: Public data is last key index pressed 2: Public data is last key pressed or 16 for no key index 3: Public data is Ascii of last key pressed
111  @param queueMode 0: Button presses are queued as indexes 1: Button Presses are queued as ASCII
112  */
113  int16_t begin(uint8_t controlPin,
114  uint8_t row0pin, uint8_t row1pin, uint8_t row2pin, uint8_t row3pin,
115  uint8_t column0pin, uint8_t column1pin, uint8_t column2pin, uint8_t column3pin,
116  uint8_t bufferMode = 0, uint8_t queueMode = 1)
117  {
118  _pin = controlPin;
119 
120  uint8_t tx[] = { (uint8_t)SerialWombatCommands::CONFIGURE_PIN_MODE0,
121  _pin,
122  (uint8_t)PIN_MODE_MATRIX_KEYPAD ,
123  row0pin,
124  row1pin,
125  row2pin,
126  row3pin,
127  column0pin };
128  int16_t result = _sw.sendPacket(tx);
129  if (result < 0)
130  {
131  return result;
132  }
133 
134  uint8_t tx5[] = { (uint8_t)SerialWombatCommands::CONFIGURE_PIN_MODE5,
135  _pin,
136  (uint8_t)PIN_MODE_MATRIX_KEYPAD ,
137  column1pin,
138  column2pin,
139  column3pin,
140  bufferMode,
141  queueMode };
142  return _sw.sendPacket(tx5);
143  }
144 
145 
159  int16_t writeQueueMask(uint16_t mask)
160  {
161  uint8_t tx[8] = { (uint8_t)SerialWombatCommands::CONFIGURE_PIN_MODE7,
162  _pin, (uint8_t)PIN_MODE_MATRIX_KEYPAD,
163  SW_LE16(mask),0x55,0x55,0x55 };
164  return _sw.sendPacket(tx);
165  }
166 
171  int available()
172  {
173  uint8_t tx[8] = { 201, _pin, (uint8_t)PIN_MODE_MATRIX_KEYPAD, 0,0x55,0x55,0x55,0x55 };
174  uint8_t rx[8];
175  _sw.sendPacket(tx, rx);
176  return (rx[4]);
177  }
178 
183  int read()
184  {
185  uint8_t tx[8] = { 202, _pin,(uint8_t)PIN_MODE_MATRIX_KEYPAD, 1,0x55,0x55,0x55,0x55 };
186  uint8_t rx[8];
187  if (_sw.sendPacket(tx, rx) < 0)
188  {
189  return -1;
190  }
191 
192  if (rx[3] != 0)
193  {
194  return (rx[4]);
195  }
196  else
197  {
198  return (-1);
199  }
200  }
202  void flush()
203  {
204 
205  }
210  int peek()
211  {
212  uint8_t tx[8] = { 203, _pin,(uint8_t)PIN_MODE_MATRIX_KEYPAD,0x55,0x55,0x55,0x55,0x55 };
213  uint8_t rx[8];
214  _sw.sendPacket(tx, rx);
215  if (rx[4] > 0)
216  {
217  return (rx[5]);
218  }
219  else
220  {
221  return (-1);
222  }
223  }
224 
232  size_t write(uint8_t data)
233 {
234 
235  return (1);
236 }
237 
246  size_t write(const uint8_t* buffer, size_t size)
247 {
248  return(size);
249 }
250 
256  {
257  return(0);
258  }
259 
270  size_t readBytes(char* buffer, size_t length)
271 {
272  int index = 0;
273  int bytesAvailable = 0;
274  uint32_t timeoutMillis = millis() + timeout;
275  while (length > 0 && timeoutMillis > millis())
276  {
277  int bytecount = 4;
278  if (length < 4)
279  {
280  bytecount = length;
281  }
282  {
283 
284  uint8_t tx[8] = { 202, _pin,(uint8_t)PIN_MODE_MATRIX_KEYPAD, (uint8_t)bytecount,0x55,0x55,0x55,0x55 };
285  uint8_t rx[8];
286  _sw.sendPacket(tx, rx);
287  bytesAvailable = rx[3];
288 
289  if (bytesAvailable == 0)
290  {
291  continue;
292  }
293  else
294  {
295  timeoutMillis = millis() + timeout;
296  }
297  uint8_t bytesReturned = bytecount;
298  if (rx[3] < bytecount)
299  {
300  bytesReturned = rx[3];
301  }
302  for (int i = 0; i < bytesReturned; ++i)
303  {
304  buffer[index] = rx[i + 4];
305  ++index;
306  --bytesAvailable;
307  --length;
308 
309  }
310  }
311 
312  }
313  return (index);
314 }
315 
319  void setTimeout(long timeout_mS)
320  {
321  if (timeout_mS == 0)
322  {
323  timeout = 0x80000000;
324  }
325  else
326  {
327  timeout = timeout_mS;
328  }
329  }
330 
331 
336  {
337  return kp;
338  }
339 
340 
342  uint8_t _pin = 255;
343 protected:
344  uint32_t timeout = 1;
345 };
346 
347 
355 {
356 public:
364  {
365  _keypad = kp;
366  _keyIndex = keyIndex;
367  }
368 
377  bool digitalRead()
378 {
379  uint8_t tx[] = { (uint8_t)SerialWombatCommands::CONFIGURE_PIN_MODE6,
380  _keypad._pin,
382  0,
383  _keyIndex,0x55,0x55,0x55 };
384  uint8_t rx[8];
385  int result = _keypad._sw.sendPacket(tx, rx);
386  if (result >= 0)
387  {
388  transitions = rx[4] + 256 * rx[5];
389 
390  return (rx[3] > 0);
391  }
392  return(0);
393 }
401 {
402  uint8_t tx[] = { (uint8_t)SerialWombatCommands::CONFIGURE_PIN_MODE6,
403  _keypad._pin,
405  0,
406  _keyIndex,0x55,0x55,0x55 };
407  uint8_t rx[8];
408  int result = _keypad._sw.sendPacket(tx, rx);
409  if (result >= 0)
410  {
411  transitions = rx[4] + 256 * rx[5];
412  uint16_t time = rx[6] + 256 * rx[7];
413  if (rx[3] == 0)
414  {
415  return(time);
416  }
417  }
418  return(0);
419 }
420 
427 {
428  uint8_t tx[] = { (uint8_t)SerialWombatCommands::CONFIGURE_PIN_MODE6,
429  _keypad._pin,
431  0,
432  _keyIndex,0x55,0x55,0x55 };
433  uint8_t rx[8];
434  int result = _keypad._sw.sendPacket(tx, rx);
435  if (result >= 0)
436  {
437  transitions = rx[4] + 256 * rx[5];
438  uint16_t time = rx[6] + 256 * rx[7];
439  if (rx[3] == 1)
440  {
441  return(time);
442  }
443  }
444  return(0);
445 }
446 
457 {
458  return digitalRead();
459 }
460 
461 private:
462  SerialWombatMatrixKeypad& _keypad;
463  uint8_t _keyIndex;
464 };
465 
SerialWombatChip
Class for a Serial Wombat chip. Each Serial Wombat chip on a project should have its own instance.
Definition: SerialWombat.h:283
SerialWombatMatrixKeypad::begin
int16_t begin(uint8_t controlPin, uint8_t row0pin, uint8_t row1pin, uint8_t row2pin, uint8_t row3pin, uint8_t column0pin, uint8_t column1pin, uint8_t column2pin, uint8_t column3pin, uint8_t bufferMode=0, uint8_t queueMode=1)
Definition: SerialWombatMatrixKeypad.h:113
SerialWombatMatrixButton::SerialWombatMatrixButton
SerialWombatMatrixButton(SerialWombatMatrixKeypad &kp, uint8_t keyIndex)
Instantiate a SerialWombatMatrixButton.
Definition: SerialWombatMatrixKeypad.h:363
SerialWombatMatrixKeypad::write
size_t write(const uint8_t *buffer, size_t size)
Write bytes to the SerialWombatMatrixKeypad queue (Does nothing)
Definition: SerialWombatMatrixKeypad.h:246
SerialWombatMatrixKeypad::flush
void flush()
Discard all bytes from the SerialWombatMatrixKeypad queue.
Definition: SerialWombatMatrixKeypad.h:202
SerialWombatMatrixKeypad::writeQueueMask
int16_t writeQueueMask(uint16_t mask)
Set a binary mask for which keys are added to Queue.
Definition: SerialWombatMatrixKeypad.h:159
SerialWombatCommands::CONFIGURE_PIN_MODE0
@ CONFIGURE_PIN_MODE0
(200)
SerialWombatMatrixButton::readTransitionsState
bool readTransitionsState()
Queries the number of transistions that have occured on the button.
Definition: SerialWombatMatrixKeypad.h:456
SerialWombatCommands::CONFIGURE_PIN_MODE7
@ CONFIGURE_PIN_MODE7
(207)
SerialWombatMatrixKeypad::SerialWombatMatrixKeypad
SerialWombatMatrixKeypad(SerialWombatChip &serialWombat)
Constructor for the SerialWombatMatrixKeypad class.
Definition: SerialWombatMatrixKeypad.h:95
SerialWombatMatrixButton
Class that runs on top of SerialWombatMatrixKeypad to treat a key as an individual button.
Definition: SerialWombatMatrixKeypad.h:354
SerialWombat.h
SerialWombatAbstractButton::transitions
uint16_t transitions
Number of transitions returned by last call to readTransitionsState()
Definition: SerialWombatAbstractButton.h:72
PIN_MODE_MATRIX_KEYPAD
@ PIN_MODE_MATRIX_KEYPAD
(15)
Definition: SerialWombat.h:255
SerialWombatMatrixKeypad::peek
int peek()
Query the SerialWombatMatrixKeypad queue for the next avaialble byte, but don't remove it from the qu...
Definition: SerialWombatMatrixKeypad.h:210
SerialWombatMatrixKeypad::write
size_t write(uint8_t data)
Write a byte to the SerialWombatMatrixKeypad queue (Does Nothing)
Definition: SerialWombatMatrixKeypad.h:232
SerialWombatMatrixKeypad::operator=
SerialWombatMatrixKeypad operator=(SerialWombatMatrixKeypad &kp)
used to allow reference copy. Not for user use.
Definition: SerialWombatMatrixKeypad.h:335
SerialWombatMatrixKeypad::readBytes
size_t readBytes(char *buffer, size_t length)
Reads a specified number of bytes from the SerialWombatMatrixKeypad queue queue.
Definition: SerialWombatMatrixKeypad.h:270
SerialWombatChip::sendPacket
int sendPacket(uint8_t tx[], uint8_t rx[])
Send an 8 byte packet to the Serial Wombat chip and wait for 8 bytes back.
Definition: SerialWombat.cpp:114
SerialWombatMatrixKeypad::read
int read()
Reads a byte from the SerialWombatMatrixKeypad queue.
Definition: SerialWombatMatrixKeypad.h:183
SerialWombatMatrixKeypad::setTimeout
void setTimeout(long timeout_mS)
implemented to fulfill Stream requirement.
Definition: SerialWombatMatrixKeypad.h:319
SerialWombatMatrixKeypad::_pin
uint8_t _pin
Definition: SerialWombatMatrixKeypad.h:342
SerialWombatMatrixButton::readDurationInTrueState_mS
uint16_t readDurationInTrueState_mS()
return the number of mS that the button has been in true state
Definition: SerialWombatMatrixKeypad.h:426
SerialWombatMatrixKeypad::timeout
uint32_t timeout
Definition: SerialWombatMatrixKeypad.h:344
SerialWombatMatrixKeypad::_sw
SerialWombatChip & _sw
Definition: SerialWombatMatrixKeypad.h:341
SerialWombatMatrixButton::digitalRead
bool digitalRead()
Returns the state of the input.
Definition: SerialWombatMatrixKeypad.h:377
SW_LE16
#define SW_LE16(_a)
Convert a uint16_t to two bytes in little endian format for array initialization.
Definition: SerialWombat.h:41
SerialWombatCommands::CONFIGURE_PIN_MODE5
@ CONFIGURE_PIN_MODE5
(205)
SerialWombatMatrixKeypad::available
int available()
Queries the SerialWombatMatrixKeypad for number bytes available to read.
Definition: SerialWombatMatrixKeypad.h:171
SerialWombatMatrixKeypad::availableForWrite
int availableForWrite()
Number of bytes avaialble to write to SerialWombatMatrixKeypad queue. Returns 0.
Definition: SerialWombatMatrixKeypad.h:255
SerialWombatMatrixButton::readDurationInFalseState_mS
uint16_t readDurationInFalseState_mS()
return the number of mS that the button has been in false state
Definition: SerialWombatMatrixKeypad.h:400
SerialWombatMatrixKeypad
A class for the Serial Wombat SW18AB chips which scans matrix keypads up to 4x4.
Definition: SerialWombatMatrixKeypad.h:87
SerialWombatCommands::CONFIGURE_PIN_MODE6
@ CONFIGURE_PIN_MODE6
(206)
SerialWombatAbstractButton
SerialWombat18CapTouch, SerialWombatDebouncedInput and SerialWombatMatrixButton inherit from this cla...
Definition: SerialWombatAbstractButton.h:40