Arduino/ESP library to simplify working with buttons.
This library allows you to use callback functions to track single, double, triple and long clicks. Alternatively, it provides function to use in your main loop()
.
The library also takes care of debouncing. Using this lib will reduce and simplify your source code significantly.
It has been tested with Arduino, ESP8266 and ESP32 devices.
To see the latest changes to the library please take a look at the Changelog.
If you find this library helpful please consider giving it a ⭐️ at GitHub and/or buy me a ☕️.
Thank you!
This library allows you to define a button and uses callback functions to detect different types of button interactions.
If you don't want to use callback there are also functions available for using it in your code's main loop()
.
#include "Button2.h"
constructor
or the begin()
function. void begin(byte attachTo, byte buttonMode = INPUT_PULLUP, boolean activeLow = true);
INPUT_PULLUP
. You can override this upon creation. #include "Button2.h"
#define BUTTON_PIN D3
Button2 button;
void setup() {
button.begin(BUTTON_PIN);
}
Instead of frequently checking the button state in your main loop()
this class allows you to assign callback functions.
You can define callback functions to track various types of clicks:
setTapHandler()
will be be called when any click occurs. This is the most basic handler. It ignores all timings built-in the library for double or triple click detection.setClickHandler()
will be triggered after a single click occurred.setChangedHandler()
, setPressedHandler()
and setReleasedHandler()
allow to detect basic interactions.setLongClickDetectedHandler()
will be triggered as soon as the long click timeout has passed.setLongClickHandler()
will be triggered after the button has released.setDoubleClickHandler()
and setTripleClickHandler()
detect complex interactions.Note: You will experience a short delay with setClickHandler()
and setLongClickHandler()
as need to check whether a long or multi-click is in progress. For immediate feedback use setTapHandler()
or setLongClickDetectedHandler()
You can assign callback functions for single or for multiple buttons.
You can track individual or multiple events with a single handler.
Please take a look at the included examples (see below) to get an overview over the different callback handlers and their usage.
All callback functions need a Button2
reference parameter. There the reference to the triggered button is stored. This can used to call status functions, e.g. wasPressedFor()
.
setLongClickDetectedHandler()
and setLongClickHandler()
.setLongClickDetectedHandler()
will be called as soon as the defined timeout has passed.setLongClickHandler()
will only be called after the button has been released.setLongClickDetectedRetriggerable(bool retriggerable)
allows you to define whether want to get multiple notifications for a single long click depending on the timeout.getLongClickCount()
gets you the number of long clicks – this is useful when retriggerable
is set.loop()
member function in your sketch's loop()
function. #include "Button2.h"
#define BUTTON_PIN D3
Button2 button;
void handleTap(Button2& b) {
// check for really long clicks
if (b.wasPressedFor() > 1000) {
// do something
}
}
void setup() {
button.begin(BUTTON_PIN);
button.setTapHandler(handleTap);
}
void loop() {
button.loop();
}
loop()
function needs to be called continuously, delay()
and other blocking functions will interfere with the detection of clicks. Consider cleaning up your loop or call the loop()
function via an interrupt.loop()
function via a timer interrupt. #define BTN_DEBOUNCE_MS 50
#define BTN_LONGCLICK_MS 200
#define BTN_DOUBLECLICK_MS 300
void setDebounceTime(unsigned int ms)
void setLongClickTime(unsigned int ms)
void setDoubleClickTime(unsigned int ms)
loop()
bool wasPressed()
allows you to check whether the button was pressedclickType read(bool keepState = false)
gives you the type of click that took placeclickType wait(bool keepState = false)
combines read()
and wasPressed()
and halts execution until a button click was detected. Thus, it is blocking code.clickType
is an enum defined as... enum clickType {
single_click,
double_click,
triple_click,
long_click,
empty
};
waitForClick()
, waitForDouble()
, waitForTriple()
and waitForLong()
) to detect a specific typeread()
and the wait functions will reset the state of wasPressed()
unless specified otherwise (via a bool
parameter)resetPressedState()
allows you to clear value returned by wasPressed()
– it is similar to passing keepState = false
for read()
or wait()
.unsigned int wasPressedFor() const;
byte getNumberOfClicks() const;
byte getType() const;
boolean isPressed() const;
boolean isPressedRaw() const;
bool wasPressed() const;
getID()
.setID(int newID)
to set a new one. But then you need to make sure that they are unique.setButtonStateFunction()
to assign it to your Button2 instancebutton.begin(VIRTUAL_PIN);
The button class offers a few additional functions, please take a look at the Class Definition below.
See below the constructors and member functions the library provides:
Button2();
Button2(byte attachTo, byte buttonMode = INPUT_PULLUP, boolean activeLow = true);
void begin(byte attachTo, byte buttonMode = INPUT_PULLUP, boolean activeLow = true);
void setDebounceTime(unsigned int ms);
void setLongClickTime(unsigned int ms);
void setDoubleClickTime(unsigned int ms);
unsigned int getDebounceTime();
unsigned int getLongClickTime();
unsigned int getDoubleClickTime();
byte getPin();
void reset();
void setButtonStateFunction(StateCallbackFunction f);
void setChangedHandler(CallbackFunction f);
void setPressedHandler(CallbackFunction f);
void setReleasedHandler(CallbackFunction f);
void setTapHandler(CallbackFunction f);
void setClickHandler(CallbackFunction f);
void setDoubleClickHandler(CallbackFunction f);
void setTripleClickHandler(CallbackFunction f);
void setLongClickHandler(CallbackFunction f);
void setLongClickDetectedHandler(CallbackFunction f);
void setLongClickDetectedRetriggerable(bool retriggerable);
void byte getLongClickCount() const;
unsigned int wasPressedFor() const;
void resetPressedState();
byte resetClickCount();
boolean isPressed() const;
boolean isPressedRaw() const;
bool wasPressed() const;
clickType read(bool keepState = false);
clickType wait(bool keepState = false);
void waitForClick(bool keepState = false);
void waitForDouble(bool keepState = false);
void waitForTriple(bool keepState = false);
void waitForLong(bool keepState = false);
byte getNumberOfClicks() const;
byte getType() const;
String clickToString(clickType type) const;
int getID() const;
void setID(int newID);
bool operator == (Button2 &rhs);
void loop();
Open the Arduino IDE choose "Sketch > Include Library" and search for "Button2". Or download the ZIP archive (https://github.com/lennarthennigs/Button2/zipball/master), and choose "Sketch > Include Library > Add .ZIP Library..." and select the downloaded file.
MIT License
Copyright (c) 2017-2023 Lennart Hennigs
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.