https://github.com/Xylopyrographer/BooleanButton
README file
BooleanButton Library Copyright (C) 2023 Xylopyrographer, released under GNU GPL v3.0
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License v3.0 as published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/gpl.html
The BooleanButton library is for monitoring the state of a boolean variable, treating that variable as if it were a physical button (creates a virtual button if you like). "Long presses" of arbitrary length can be detected. Works well in state machine constructs. Use the read() function to read each monitored variable in the main loop, which should execute as fast as possible.
Why would you want this? While doing some work on controlling the backlight of an LED display with an embedded capacitive touch panel, I noted the results returned from the touch panel driver library were "twitchy", depending on how the panel was touched. The panel was in essence acting like a physical momentary contact push button. Rather than re-invent the wheel, and having experience with the very excellent JC_Button library, I modified that so it could treat any boolean variable as a virtual momentary push button.
Thus, if you have a need to monitor the state of a boolean — how long it's been in a state, when last changed, its current state, etc. this may just be the library you need.
The following example sketches are included with the BooleanButton library:
- SimpleOnOff: Turns an LED on and off.
- LongPress: Demonstrates detecting long and short variable changes.
- UpDown: Counts up or down, one number at a time or rapidly by monitoring the states of two variables.
The constructor defines a virtual boolean button object.
BoolBtn( theBoolean, dbTime, invert );
theBoolean: pointer (address) to a boolean variable to be monitored. (type = * bool)
dbTime: Debounce time in milliseconds. Defaults to 25ms if not given. (type = unsigned long)
invert: false reverses the interpretation of the variable being monitored; true is interpreted as false and vice versa. Defaults to false if not given. (type = bool)
None.
// variable "theVariable" is to be monitored, 25ms debounce, logic not inverted
bool theVariable;
BoolBtn myVirBtn( &theVariable );
// same as above but needs a longer debounce time (50ms)
bool theVariable;
BoolBtn myVirBtn( &theVariable, 50 );
// monitor "theVariable", with a 25ms debounce time but invert the variable state
bool theVariable;
BoolBtn myVirBtn( &theVariable, 25, true );
Initializes the BoolBtn object.
myVirBtn.begin();
None.
None.
myVirBtn.begin();
Reads and returns the debounced state of the variable being monitored and returns a boolean value (true or false) accordingly.
The read() function needs to execute very frequently in order for the sketch to be responsive. A good place for read() is at the top of loop(). Often, the return value from read() will not be needed if the other functions below are used.
myVirBtn.read();
None.
true if the variable is true, else false. (type = bool)
myVirBtn.read();
These functions check the variable state as found from the last call to read() and return true or false accordingly. These functions do not cause the variable to be read.
myVirBtn.isPressed();
myVirBtn.isReleased();
None.
true or false, depending on whether the variable is true (false) or not. (type = bool)
if ( myVirBtn.isPressed() ) {
//do something
}
else {
//do something else
}
These functions check the variable state to see if it changed between the last two calls to read() and returns true or false accordingly. These functions do not cause the variable to be read. Note that these functions may be more useful than isPressed() and isReleased() since they actually detect a change in the state of the variable, which is usually what is wanted in order to cause some action.
myVirBtn.wasPressed();
myVirBtn.wasReleased();
None.
true or false, depending on whether the variable changed state or not. (type = boolean).
if ( myVirBtn.wasPressed() ) {
//do something
}
Checks that the variable has not changed state for at least the variable debounce time.
This function does not cause the variable to be read. Using this function preceded by multiple calls to read() can be used during setup() to force or ensure the variable state is debounced before proceeding.
myVirBtn.isStable();
None.
true if the variable has not changed state for at least the debounce time (dbTime) as specified when calling the constructor, false otherwise. (type = boolean).
#define BUTTON_PIN 14
pinMode( BUTTON_PIN, INPUT_PULLUP );
bool pinState = !digitalRead( BUTTON_PIN );
BoolBtn myVirBtn( &pinState );
myVirBtn.begin();
while ( myVirBtn.isStable() != true ) {
pinState = !digitalRead( BUTTON_PIN ); // refresh the variable being monitored
myVirBtn.read();
}
These functions check to see if the variable is true (or false), and has been in that state for the specified time in milliseconds. Returns true or false accordingly. These functions are useful to detect "long presses". Note that these functions do not cause the variable to be read.
theVariable.pressedFor(ms);
theVariable.releasedFor(ms);
ms: The number of milliseconds (unsigned long)
true or false, depending on whether the variable is true (false) for the specified time. (type = bool)
if ( theVariable.pressedFor(1000) ) {
// variable has been true for 1000 ms
}
Under certain circumstances, it may be useful to know when a variable last changed state. lastChange() returns the time the variable last changed state, in milliseconds (the value is derived from the Arduino millis() function).
theVariable.lastChange();
None.
The time in milliseconds when the variable last changed state. (type = unsigned long)
unsigned long msLastChange = theVariable.lastChange();
BooleanButton is a virtual clone of the JC_Button library written by Jack Christensen, available at https://github.com/JChristensen/JC_Button. This work is fully acknowledged and credited.
Since BooleanButton creates a virtual physical button from a boolean variable, the syntax of JC_Button was retained — hopefully to anchor the concept.
Many thanks Jack!
- Initial release.
- Bug -
read()would return the state of the variable as soon as the variable becametrueinstead of after debouncing. - Fixed. - Revised the names of the
.hand.cppfiles in/srcto align with Arduino library conventions. - Breaking change: In all examples, revised the
#include <BoolButton>line to#include <BooleanButton>to match the changes above. Sketches using the original name (BoolButton) will need to be likewise changed toBooleanButton. My apologies. - add
isStable()library function. - Revised
README.mddocument to clarify the Constructor examples and values returned from the library functions.