Updates to MomentaryButton and LatchingButton.

Added functionality to MomentaryButton and LatchingButton to make them easier to use.  Added additional examples.

Author: lendres

README.md

@@ -1,6 +1,6 @@
 # ButtonSuite
 
-A class for adding functionality to push (momentary) buttons.  This library allows a simple momentary push button to be used as a momentary button, latching button, counter, or enumerator.  This library uses the Bounce2 library to add debouncing functionality.
+A library for adding functionality to push (momentary) buttons.  This library allows a simple momentary push button to be used as a momentary button, latching button, counter, or enumerator.  This library uses the Bounce2 library to add debouncing functionality.
 
 ## Types of Buttons
 This library contains two categories of button types.  The first category is two state buttons; these are either on or off.  The second category provides incrementing buttons that can perform different types of counting.  These two categories of buttons are described here.  See "Software Design" below for information about how the source code implements these behaviors.

examples/LatchingButton_Demo_01/LatchingButton_Demo_01.ino

@@ -10,6 +10,15 @@
 	should be used.
 */
 
+/*
+	Please note the difference between the examples MomentaryButton_Demo_02 and 
+	LatchingButton_Demo_01.  Both examples toggle an LED on and off but one uses
+	a MomentaryButton and one uses the LatchingButton.  While the behavior is the
+	same for these simple examples, there is an important difference.  In the case
+	of the MomentaryButton, the state of the LED (on or off) is not known.  For the
+	LatchingButton, it is known what state the button (and therefore LED) is in.
+*/
+
 #include "LatchingButton.h"
 
 // Change these if your button or LED are on other pins.
@@ -29,7 +38,7 @@ void setup()
 void loop()
 {
 	// Press the button once to turn it on, and again to turn it off.
-	if (button.getStatus() == ISPRESSED)
+	if (button.isLatched())
 	{
 		digitalWrite(ledPin, HIGH);
 	}

examples/LatchingButton_Demo_02/LatchingButton_Demo_02.ino

@@ -24,9 +24,6 @@ LatchingButton button(buttonPin);
 
 void setup()
 {
-	Serial.begin(9600);
-	Serial.println("*** Latching Button Demo 02 ***");
-
 	// Setup the output LED.
 	pinMode(ledPin, OUTPUT);
 	digitalWrite(ledPin, LOW);
@@ -35,12 +32,7 @@ void setup()
 void loop()
 {
 	// Press the button once to turn it on, and again to turn it off.
-	bool buttonStatus = button.getStatus();
-	
-	Serial.print("Button status: ");
-	Serial.println(buttonStatus);
-
-	if (buttonStatus == ISPRESSED)
+	if (button.getStatus() == ISPRESSED)
 	{
 		digitalWrite(ledPin, HIGH);
 	}

examples/MomentaryButton_Demo_01/MomentaryButton_Demo_01.ino

@@ -27,13 +27,13 @@ void setup()
 
 void loop()
 {
-	// Press the button once to turn it on, and again to turn it off.
-	if (button.getStatus() == ISPRESSED)
+	// Press the button to turn the LED on and release it to turn it off.
+	if (button.isPressed())
 	{
 		digitalWrite(ledPin, HIGH);
 	}
 	else
 	{
 		digitalWrite(ledPin, LOW);
 	}
-}
+}

examples/MomentaryButton_Demo_02/MomentaryButton_Demo_02.ino

@@ -0,0 +1,47 @@
+/*
+	Toggles an LED between on and off with each press of the button.
+
+	The button should be wired such that when pressed, the "buttonPin" is
+	connected to ground.
+
+	The LED should be wired with the "ledPin" to the positive lead and the
+	negative lead should be connected to ground.  A current limiting resistor
+	should be used.
+*/
+
+/*
+	Please note the difference between the examples MomentaryButton_Demo_02 and 
+	LatchingButton_Demo_01.  Both examples toggle an LED on and off but one uses
+	a MomentaryButton and one uses the LatchingButton.  While the behavior is the
+	same for these simple examples, there is an important difference.  In the case
+	of the MomentaryButton, the state of the LED (on or off) is not known.  For the
+	LatchingButton, it is known what state the button (and therefore LED) is in.
+*/
+
+#include "MomentaryButton.h"
+
+// Change these if your button or LED are on other pins.
+int buttonPin	= 8;
+int ledPin		= 9;
+
+// The MomentaryButton will automatically configure the button pin.
+MomentaryButton button(buttonPin);
+
+void setup()
+{
+	// Setup the output LED.
+	pinMode(ledPin, OUTPUT);
+	digitalWrite(ledPin, LOW);
+}
+
+void loop()
+{
+	// Press the button once to turn the LED on and again it to turn it off.  This only captures button release
+	// events, i.e., nothing happens when the button is pressed down, only after the release.
+	if (button.wasPressed())
+	{
+		// The button was pressed, so toggle the LED state.  To toggle it, the current value is read (digitalRead)
+		// and negated.  The result is written back to the pin to change its state.
+		digitalWrite(ledPin, !digitalRead(ledPin));
+	}
+}

examples/MomentaryButton_Demo_03/MomentaryButton_Demo_03.ino

@@ -0,0 +1,39 @@
+/*
+	Toggles an LED between on and off with each press of the button.
+
+	The button should be wired such that when pressed, the "buttonPin" is
+	connected to ground.
+
+	The LED should be wired with the "ledPin" to the positive lead and the
+	negative lead should be connected to ground.  A current limiting resistor
+	should be used.
+*/
+
+#include "MomentaryButton.h"
+
+// Change these if your button or LED are on other pins.
+int buttonPin	= 8;
+int ledPin		= 9;
+
+// The MomentaryButton will automatically configure the button pin.
+MomentaryButton button(buttonPin);
+
+void setup()
+{
+	// Setup the output LED.
+	pinMode(ledPin, OUTPUT);
+	digitalWrite(ledPin, LOW);
+}
+
+void loop()
+{
+	// Press the button to turn the LED on and release it to turn it off.
+	if (button.getStatus() == ISPRESSED)
+	{
+		digitalWrite(ledPin, HIGH);
+	}
+	else
+	{
+		digitalWrite(ledPin, LOW);
+	}
+}

examples/SwitchRunTimeBahavior_Demo_01/SwitchRunTimeBahavior_Demo_01.ino

@@ -32,7 +32,7 @@ MomentaryButton momentaryButton(buttonPin);
 AlwaysOnButton	onButton(buttonPin);
 
 // Used for timing and switching between the two states.
-unsigned long	intervalStartTime; 
+unsigned long	intervalStartTime;
 const int		intervalLength		= 5000;
 int				currentState;
 

src/ButtonBase.cpp

@@ -52,18 +52,20 @@ void ButtonBase::setDebounceInterval(int debounceInterval)
 
 BUTTONSTATUS ButtonBase::update()
 {
+	// See ButtonEnums.h for the definitions of the different button states.
+
 	// Have the debouncer update.  This does most of the work of handling the button state.
 	// The debouncer determines the current state, if the state changed since the last time
 	// "update" was called, what the time between state changes was, and so on.
 	_debouncer.update();
 
-	// Catch transitions from HIGH to LOW.  This is the button press.
+	// Catch transitions from HIGH to LOW.  This happens right when the button is pressed down.
 	if (_debouncer.fell())
 	{
 		#ifdef BUTTONSUITEDEBUG
-			Serial.println("ButtonBase::update: WASPRESSED");
+			Serial.println("ButtonBase::update: JUSTPRESSED");
 		#endif
-		return WASPRESSED;
+		return JUSTPRESSED;
 	}
 
 	// Look to see if the button is currently pressed.

src/ButtonEnums.h

@@ -32,7 +32,7 @@
 enum BUTTONSTATUS
 {
 	// Was just pressed down (first call to "update" after the button was pressed).
-	WASPRESSED,
+	JUSTPRESSED,
 
 	// Is still pressed down.
 	ISPRESSED,

src/LatchingButton.cpp

@@ -53,15 +53,23 @@ void LatchingButton::setLongPressInterval(int longPressInterval)
   _longPressInterval = longPressInterval;
 }
 
+bool LatchingButton::isLatched()
+{
+	getStatus();
+	return _latched;
+}
+
 BUTTONSTATUS LatchingButton::getStatus()
 {
-	// Catch transitions from HIGH to LOW.
-	switch (update())
+	// Get the status.
+	BUTTONSTATUS buttonStatus = update();
+
+	switch (buttonStatus)
 	{
-		case WASPRESSED:
+		case JUSTPRESSED:
 		{
 			// Capture the event of the button press.  Some classes may require this to act on it.
-			return WASPRESSED;
+			return JUSTPRESSED;
 		}
 
 		case WASSHORTPRESSED:
@@ -88,7 +96,9 @@ BUTTONSTATUS LatchingButton::getStatus()
 		case NOTPRESSED:
 		default:
 		{
-			// Nothing happened so we return based on the state.
+			// Nothing changed with the button, so we return a value based on the latched state.
+			// This means that it does not matter if the button is currently pressed or not pressed,
+			// it returns pressed when latched and not pressed when not latched.
 			return convertStateToButtonStatus();
 		}
 	}