Update

Dlloydev · Dlloydev · commit 1ff89b0a4ae0 · 2022-05-26T02:02:48.000-04:00
New pressCode() function and example.
Readme updated.
diff --git a/README.md b/README.md
@@ -1,48 +1,26 @@
 # Toggle    [![arduino-library-badge](https://www.ardu-badge.com/badge/Toggle.svg?)](https://www.ardu-badge.com/Toggle) [![PlatformIO Registry](https://badges.registry.platformio.org/packages/dlloydev/library/Toggle.svg)](https://registry.platformio.org/libraries/dlloydev/Toggle)
 
- Arduino bounce library for deglitching and debouncing hardware, signals and data. Works with all switch types, port expander and other 8-bit data sources. Three algorithm modes available. Robust mode ignores up to several consecutive spurious transitions.
+ Arduino button library for deglitching and debouncing switch contacts and logic data. Works with all switch types, port expander and other 8-bit data sources. Three algorithm modes available that can ignore up to several consecutive spurious transitions.
 
 ## Features
 
 ### Flexible Inputs
 
-The inputs can be from a single pin or several pins allowing the use of 2 or 3-position switches and up to seven debounced states. When linking to a data (byte) input, the debouncer can work with any selected bit or it can debounce all 8-bits in one Toggle instance. This method can be used for debouncing serial data from I/O expanders, sensors or stored values.  Examples:  [`Input_Bit_Test.ino`](https://github.com/Dlloydev/Toggle/blob/main/examples/Input_Bit_Test/Input_Bit_Test.ino) , [`Input_Bit.ino`](https://github.com/Dlloydev/Toggle/blob/main/examples/Input_Bit/Input_Bit.ino),  [`Input_Port_Test.ino`](https://github.com/Dlloydev/Toggle/blob/main/examples/Input_Port_Test/Input_Port_Test.ino) and [`Input_Port.ino`](https://github.com/Dlloydev/Toggle/blob/main/examples/Input_Port/Input_Port.ino).
-
-From the `Input_Port_Test.ino` example, this is the serial output with leading 0's added:
-
-```c++
-In: 00000000 Out: 00000000
-In: 10000001 Out: 00000000
-In: 10100011 Out: 00000000
-In: 00100111 Out: 00000001
-In: 00001110 Out: 00000011
-In: 00011110 Out: 00000111
-In: 00101111 Out: 00001111
-In: 01110110 Out: 00001111
-In: 11111100 Out: 00101111
-In: 11011000 Out: 01111110
-In: 01110000 Out: 01111100
-In: 01100011 Out: 01111000
-In: 11000000 Out: 01110000
-In: 10000100 Out: 01100000
-In: 00000000 Out: 01000000
-```
-
-Looking at the columns (bit data) top to bottom, it can be seen that the debounced `Out` data lags by only 2 samples (rows). It also can be seen that the input debouncer can tolerate a very noisy signal with up to 2 consecutive 1's or 0's that are anomalous or spurious in the `In` data.
+The inputs can be from a single pin or several pins allowing the use of 2 or 3-position switches and up to seven debounced states. When linking to a data (byte) input, the debouncer can work with any selected bit or it can debounce all 8-bits in one Toggle instance. Examples:  [`Input_Bit_Test.ino`](https://github.com/Dlloydev/Toggle/blob/main/examples/Input_Bit_Test/Input_Bit_Test.ino) , [`Input_Bit.ino`](https://github.com/Dlloydev/Toggle/blob/main/examples/Input_Bit/Input_Bit.ino),  [`Input_Port_Test.ino`](https://github.com/Dlloydev/Toggle/blob/main/examples/Input_Port_Test/Input_Port_Test.ino) and [`Input_Port.ino`](https://github.com/Dlloydev/Toggle/blob/main/examples/Input_Port/Input_Port.ino).
 
 ### Algorithms
 
 ```c++
 setAlgorithm(2);   // Robust Mode, 2 glitches ignored
-setAlgorithm(1);   // Normal Mode, 1 glitch ignored
-setAlgorithm(0);   // Quick Mode, responds to spurious transitions
+setAlgorithm(1);   // Average Mode, 1 glitch ignored
+setAlgorithm(0);   // Common Mode, can respond to spurious transitions
 ```
 
 In Robust Mode, the algorithm adds only 2 sample periods of time lag to the output signal. A 3-sample stable period is required for an output bit to change. Therefore, to set an output bit, 3 consecutive 1's are required. When 3 consecutive 0's are detected, that bit value is cleared. 
 
 ### Sampling
 
-Rather than use a basic timer strategy, the Toggle library uses sampling and only requires up to three samples on the input to to provide a clean (debounced) output. The sample period defaults to 5000μs (5ms) which works well the default Robust Mode. With these defaults, only 15ms is required for detecting a button switch being pressed or released. This may seem low when thinking of regular debouncig, but in order for this method to falsely detect a transition, it would require that there be a gap of greater than 15ms between bounces. From *[A Guide to Debouncing](http://www.ganssle.com/item/debouncing-switches-contacts-code.htm)*, (Anatomy of a Bounce):
+Rather than use a basic timer strategy, the Toggle library uses sampling and only requires up to three samples on the input to to provide a clean (debounced) output. The sample period defaults to 5000 μs (5 ms) which works well the default Robust Mode. With these defaults, only 15ms is required for detecting a button switch being pressed or released. This may seem low when thinking of regular debouncig, but in order for this method to falsely detect a transition, it would require that there be a gap of greater than 15ms between bounces. From *[A Guide to Debouncing](http://www.ganssle.com/item/debouncing-switches-contacts-code.htm)*, (Anatomy of a Bounce):
 
 > *Consider switch E again, that one with the pretty face that hides a  vicious 157 msec bouncing heart. One test showed the switch going to a  solid one for 81 msec, after which it dropped to a perfect zero for 42  msec before finally assuming its correct high state. Think what that  would do to pretty much any debounce code!* 
 
@@ -394,6 +372,30 @@ if (retrigger(500)) {
 
  
 
+## pressCode()
+
+##### Description
+
+- Up to 225 possible codes with one button. The returned code (*byte*) is easy to interpret when viewed in hex format. For example, `47` is 4 long, 7 short presses. `F2` is double-click, `F7` is 7 `F`ast clicks. 
+- Fast-click mode is detected if the first 2 clicks (presses) are less than 0.4 sec, then counts any extra presses if the duration is less than 1 sec, up to 15 max (code `FF`) 
+- Detection of long (greater than 1 sec) presses and short (less than 1 sec) presses occurs if the first press is 0.4 sec or longer. 
+- Detect up to 15 short presses
+- Detect up to 14 long presses
+- Returns code after button is released for 1.4 sec
+- simplifies your code while adding maximum functionality to one button
+
+##### Example
+
+```c++
+byte pCode = sw1.pressCode(1); // (1) serial print results
+```
+
+##### Example Sketch
+
+[Press_Code.ino](https://github.com/Dlloydev/Toggle/blob/main/examples/Press_Code/Press_Code.ino)
+
+
+
 ## Set and Get Functions
 
 
@@ -511,8 +513,8 @@ Elapsed milliseconds *(unsigned int)*.
 Sets the debouncer algorithm to one of three modes.
 
 - **Robust Mode (2):** This is the default mode where up to 2 spurious signal transitions (glitches) are ignored. This adds 2 sample periods time lag to the output signal.
-- **Normal Response (1):** This is mode ignores up to 1 spurious signal transition (glitch) and adds 1 sample period time lag to the output signal.
-- **Quick Response (0):** This is mode is similar to most debouncers where the response is near instant to a button or switch press, and the release won't be recognized until a debounce time period has expired. In this case, the debounce time period is calculated and set at 10 times the sample period.
+- **Average Mode (1):** This is mode ignores up to 1 spurious signal transition (glitch) and adds 1 sample period time lag to the output signal.
+- **Common Mode (0):** This is mode is similar to most debouncers where the response is near instant to a button or switch press, and the release won't be recognized until a debounce time period has expired. In this case, the debounce time period is calculated and set at 10 times the sample period.
 
 ##### Syntax
 
diff --git a/examples/Press_Code/Press_Code.ino b/examples/Press_Code/Press_Code.ino
@@ -0,0 +1,26 @@
+/************************************************************************
+  Press Code Example:
+  ===================
+  A simple example that demonstrates how fast-clicks, short presses and
+  long presses can be automatically detected and combined into a byte code.
+  In debug mode, the serial monitor shows timing results and code.
+  ***********************************************************************/
+
+#include <Toggle.h>
+
+const byte buttonPin = 2;
+byte code;
+
+Toggle sw1(buttonPin);
+
+void setup() {
+  while (!Serial) { }; // Leonardo
+  Serial.begin(115200);
+  sw1.begin(buttonPin);
+}
+
+void loop() {
+  sw1.poll();
+  sw1.pressCode(1); // open serial monitor to view results
+  //code = sw1.pressCode(); // no debug
+}
diff --git a/keywords.txt b/keywords.txt
@@ -31,7 +31,6 @@ setInvertMode	KEYWORD2
 setSamplePeriodUs	KEYWORD2
 setTimerMode	KEYWORD2
 getTimerMode	KEYWORD2
-clearTimer	KEYWORD2
 getElapsedMs	KEYWORD2
 isPressed	KEYWORD2
 isReleased	KEYWORD2
@@ -43,7 +42,8 @@ blink	KEYWORD2
 pressedFor	KEYWORD2
 releasedFor	KEYWORD2
 retrigger	KEYWORD2
-debounceInput	KEYWORD2
+retrigger	KEYWORD2
+pressCode	KEYWORD2
 isUP	KEYWORD2
 isMID	KEYWORD2
 isDN	KEYWORD2
@@ -61,3 +61,5 @@ input_pullup	LITERAL1
 input_pulldown	LITERAL1
 input_bit	LITERAL1
 input_port	LITERAL1
+MULTI	LITERAL1
+LONG	LITERAL1
diff --git a/library.json b/library.json
@@ -1,6 +1,6 @@
 {
   "name": "Toggle",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "description": "Arduino bounce library for deglitching and debouncing hardware, signals and data. Works with all switch types, port expander and other 8-bit data sources. Flexible algorithm with Robust, Normal and Quick response modes.",
   "keywords": "debounce, toggle, button, switch, data, deglitch",
   "repository":
diff --git a/library.properties b/library.properties
@@ -1,5 +1,5 @@
 name=Toggle
-version=3.0.2
+version=3.1.0
 author=David Lloyd
 maintainer=David Lloyd <dlloydev@testcor.ca>
 sentence=Arduino bounce library for deglitching and debouncing hardware, signals and data. Works with all switch types, port expander and other 8-bit data sources.
diff --git a/src/Toggle.cpp b/src/Toggle.cpp
@@ -1,5 +1,5 @@
 /************************************************
-   Toggle Library for Arduino - Version 3.0.2
+   Toggle Library for Arduino - Version 3.1.0
    by dlloydev https://github.com/Dlloydev/Toggle
    Licensed under the MIT License.
  ************************************************/
@@ -15,7 +15,8 @@ void Toggle::begin(uint8_t inA, uint8_t inB) {
     csr &= ~0b00001000;   // clear first run
     _inA = inA;
     _inB = inB;
-    sampleUs = micros();
+    us_timestamp = micros();
+    startUs = us_timestamp;
     if (_inA != 255) {
       if (_inputMode == inMode::input_pullup) pinMode(_inA, INPUT_PULLUP);
       else if (_inputMode == inMode::input) pinMode(_inA, INPUT);
@@ -35,9 +36,8 @@ void Toggle::begin(uint8_t inA, uint8_t inB) {
 
 void Toggle::poll(uint8_t bit) {
   begin(_inA, _inB); // runs one only
-  if (micros() - sampleUs > _samplePeriodUs) {
-    sampleUs += _samplePeriodUs;
-    sampleCount++;
+  if (micros() - us_timestamp > us_period) {
+    us_timestamp += us_period;
     if (_inputMode == inMode::input || _inputMode == inMode::input_pullup || _inputMode == inMode::input_pulldown) {
       if (_inA) dat = digitalRead(_inA);
       if (_inB) dat += digitalRead(_inB) * 2;
@@ -70,8 +70,8 @@ void Toggle::setInvertMode(bool invert) {
   else csr &= ~0b00000100; //clear
 }
 
-void Toggle::setSamplePeriodUs(uint16_t samplePeriodUs) {
-  _samplePeriodUs = samplePeriodUs;
+void Toggle::setSamplePeriodUs(uint16_t period) {
+  us_period = period;
 }
 
 /************* button state functions ****************/
@@ -134,17 +134,6 @@ uint8_t Toggle::getTimerMode() {
   return (lsr & 0b11000000) >> 6;
 }
 
-void Toggle::clearTimer() {
-  if (getTimerMode() == 0 && (onChange() == 1)) sampleCount = 0;       // onPress
-  else if (getTimerMode() == 1 && (onChange() == 2)) sampleCount = 0;  // onRelease
-  else if (getTimerMode() == 2 && onChange()) sampleCount = 0;         // onChange
-}
-
-uint16_t Toggle::getElapsedMs() {
-  if ((sampleCount * (_samplePeriodUs >> 10)) > 60000) sampleCount--;
-  return sampleCount * (_samplePeriodUs >> 10);
-}
-
 bool Toggle::blink(uint16_t ms) {
   return (bool)(ms > (getElapsedMs()));
 }
@@ -168,12 +157,80 @@ bool Toggle::releasedFor(uint16_t ms) {
 bool Toggle::retrigger(uint16_t ms) {
   if (getTimerMode()) setTimerMode(0); // start onPress
   if (isPressed() && getElapsedMs() > ms) {
-    clearTimer();
+    //clearTimer();
     return true;
   }
   return false;
 }
 
+uint32_t Toggle::getElapsedMs() {
+  return (micros() - startUs) * 0.001;
+}
+
+uint8_t Toggle::pressCode() {
+  static uint8_t pCode = 0, code = 0;
+  static uint32_t elapsedMs = 0;
+
+  //Serial.print(F(" startUs: ")); Serial.print(startUs); Serial.print(F("  "));
+  //Serial.print(F(" elapsedMS: ")); Serial.print(getElapsedMs()); Serial.print(F("  "));
+  //Serial.print(F(" pCode: ")); Serial.print(pCode, HEX); Serial.print(F("  "));
+
+  switch (_state) {
+    case PB_DEFAULT:
+      setTimerMode(2); // onChange
+      elapsedMs = getElapsedMs();
+      if (pCode && (elapsedMs > CLICK::LONG)) _state = PB_DONE;
+      if (onChange()) startUs = micros();
+      if (onPress()) {
+        //Serial.print(F(" releasedMs: ")); Serial.print(elapsedMs); Serial.print(F("  "));
+        _state = PB_ON_PRESS;
+      }
+      if (onRelease()) {
+        //Serial.print(F(" pressedMs: ")); Serial.print(elapsedMs); Serial.print(F("  "));
+        _state = PB_ON_RELEASE;
+      }
+      break;
+
+    case PB_ON_PRESS:
+      _state = PB_DEFAULT;
+      break;
+
+    case PB_ON_RELEASE:
+      if ((elapsedMs < CLICK::MULTI) && (!pCode || (pCode > 0xEF))) _state = PB_MULTI_CLICKS;
+      else if (elapsedMs < CLICK::LONG) _state = PB_SHORT_CLICKS;
+      else _state = PB_LONG_CLICKS;
+      break;
+
+    case PB_MULTI_CLICKS:
+      pCode |= 0xF0;
+      if ((pCode & 0x0F) < 0x0F) pCode += 1;
+      _state = PB_DEFAULT;
+      break;
+
+    case PB_SHORT_CLICKS:
+      if ((pCode & 0x0F) < 0x0F) pCode += 1;
+      _state = PB_DEFAULT;
+      break;
+
+    case PB_LONG_CLICKS:
+      if ((pCode & 0xE0) < 0xE0) pCode += 0x10;
+      _state = PB_DEFAULT;
+      break;
+
+    case PB_DONE:
+      code = pCode;
+      pCode = 0;
+      _state = PB_DEFAULT;
+      return code;
+      break;
+
+    default:
+      _state = PB_DEFAULT;
+      break;
+  }
+  return code;
+}
+
 /************** debouncer ***********************************************************************
   The debounceInput() function by default uses a robust algorithm that ignores up to 2 spurious
   signal transitions (glitches) and only adds up to 2 sample periods time lag to the output signal.
@@ -208,12 +265,10 @@ uint8_t Toggle::debounceInput(uint8_t bit) {
   if ((pOut & (1 << bit)) && !isReleased(bit)) {
     lsr |=  0b00000001; // set onPress
     lsr &= ~0b00000010; // clear onRelease
-    clearTimer();
   } else {
     if ((!(pOut & (1 << bit))) && isReleased(bit)) {
       lsr |=  0b00000010; // set onRelease
       lsr &= ~0b00000001; // clear onPress
-      clearTimer();
     }
   }
   ppDat = pDat;
diff --git a/src/Toggle.h b/src/Toggle.h
@@ -9,7 +9,7 @@ class Toggle {
 
     enum class inMode : uint8_t {input = 0, input_pullup = 2, input_pulldown = 9, input_bit = 250, input_port = 251};
 
-    Toggle();                                        // default constructor
+    Toggle();
     Toggle(uint8_t *in);
     Toggle(uint8_t inA, uint8_t inB = 255) {
       _inA = inA;
@@ -25,8 +25,7 @@ class Toggle {
     void setSamplePeriodUs(uint16_t samplePeriodUs); // sample period in microseconds
     void setTimerMode(uint8_t mode = 0);             // start onPress(0), onRelease(1), onChange(2)
     uint8_t getTimerMode();                          // start onPress(0), onRelease(1), onChange(2)
-    void clearTimer();                               // clears timer count on specified state change mode
-    uint16_t getElapsedMs();                         // get elapsed ms since the last state change selected by timer mode
+    uint32_t getElapsedMs();                         // get elapsed ms since the last state change selected by timer mode
 
     bool isPressed(uint8_t bit = 0);                 // returns true if pressed
     bool isReleased(uint8_t bit = 0);                // returns true if released
@@ -39,6 +38,7 @@ class Toggle {
     bool pressedFor(uint16_t ms);                    // returns true if pressed for at least the given ms
     bool releasedFor(uint16_t ms);                   // returns true if released for at least the given ms
     bool retrigger(uint16_t ms);                     // returns true each time the given ms expires while the button is pressed
+    uint8_t pressCode();                             // returns byte code for number of fast, short and long clicks
 
     bool isUP();                                     // functions for using 2 inputs with 3-position switches
     bool isMID();
@@ -50,15 +50,28 @@ class Toggle {
 
   private:
 
+    enum CLICK : uint32_t {MULTI = 400, LONG = 1000};
+    enum fsm_t : uint8_t {  // finite state machine
+      PB_DEFAULT = 0,
+      PB_ON_PRESS = 1,
+      PB_ON_RELEASE = 2,
+      PB_MULTI_CLICKS = 3,
+      PB_SHORT_CLICKS = 4,
+      PB_LONG_CLICKS = 5,
+      PB_DONE = 6
+    };
+
+    fsm_t _state = PB_DEFAULT;
+
     uint8_t debounceInput(uint8_t bit = 0);          // input debouncer
 
     inMode _inputMode = inMode::input_pullup;        // input mode
     uint8_t _inA, _inB;                              // input pin
     uint8_t *_in;                                    // referenced to input variable
     uint8_t dat, pDat, ppDat;                        // current, previous and 2nd previos input data
-    uint16_t _samplePeriodUs = 5000;                 // sample period μs
-    uint16_t sampleCount;                            // sample count
-    uint32_t sampleUs;                               // sample time μs
+    uint16_t us_period = 5000;                       // sample period μs
+    uint32_t startUs = 0;                            // for timing transitions
+    uint32_t us_timestamp;                           // most recent sample time μs
     uint8_t out = 0xFF, pOut = 0xFF;                 // debounced output and previous debounced output
     uint8_t csr = 0b10101010;                        // B7-B4: debounceCount, B3: first run B2: invert, B1-B0 algorithm
     uint8_t lsr = 0b00000000;                        // B7-6: mode, B5 lastState, B4 toggle, B1 onRelease, B0 onPress

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "Toggle",`
`3`		`- "version": "3.0.2",`
	`3`	`+ "version": "3.1.0",`
`4`	`4`	`"description": "Arduino bounce library for deglitching and debouncing hardware, signals and data. Works with all switch types, port expander and other 8-bit data sources. Flexible algorithm with Robust, Normal and Quick response modes.",`
`5`	`5`	`"keywords": "debounce, toggle, button, switch, data, deglitch",`
`6`	`6`	`"repository":`