Skip to content
/ Button2 Public

Arduino/ESP button library that provides callback functions to track single, double, triple and long clicks. It also takes care of debouncing.

License

MIT license
540 stars 86 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

LennartHennigs/Button2

BranchesTags

Repository files navigation

Button2

Arduino/ESP library to simplify working with buttons.

Description

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!

How To Use

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().

Definition

  • Include the library on top
 #include "Button2.h"
  • Define the button either using the constructor or the begin() function.
  void begin(byte attachTo, byte buttonMode = INPUT_PULLUP, bool activeLow  = true);

Button Types

  • You can use the class for "real" buttons (pullup, pulldown, and active low).
  • Per default the button pins are defined as INPUT_PULLUP. You can override this upon creation.
   #include "Button2.h"
   #define BUTTON_PIN D3

   Button2 button;

   void setup() {
     button.begin(BUTTON_PIN);
  }
  • You can also the library with other types of buttons, e.g. capacitive touch or ones handled via I2C. See the section on defining custom handlers below.

Callback Handler

  • 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().

Longpress Handling

  • There are two possible callback functions: 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.
  • setLongClickDetectedRetriggerEnable(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.

The Loop

  • For the class to work, you need to call the button's 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();
  }
  • As the 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.
  • Please see the examples below for more details.

Using an timer interrupt instead

  • Alternatively, you can call the button's loop() function via a timer interrupt.
  • I haven't tried this extensively, USE THIS AT YOUR OWN RISK!
  • You need make sure that the interval is quick enough that it can detect your timeouts (see below).
  • There is an example for the ESP32 ESP32TimerInterrupt.ino that I tested.

Timeouts

  • The default timeouts for events are (in ms):
  #define BTN_DEBOUNCE_MS 50
  #define BTN_LONGCLICK_MS 200
  #define BTN_DOUBLECLICK_MS 300
  • You can define your own timeouts by using these setter functions:
    • void setDebounceTime(unsigned int ms)
    • void setLongClickTime(unsigned int ms)
    • void setDoubleClickTime(unsigned int ms)
  • There are also getter functions available, if needed.

Using Button2 in the main loop()

  • Even though I suggest to use handlers for tracking events, you can also use Button2 to check button's state in the main loop
  • bool wasPressed() allows you to check whether the button was pressed
  • clickType read(bool keepState = false) gives you the type of click that took place
  • clickType wait(bool keepState = false) combines read() and wasPressed() and halts execution until a button click was detected. Thus, it is blocking code.
  • The clickType is an enum defined as...
    enum clickType {
      single_click,
      double_click,
      triple_click,
      long_click,
      empty
    };
  • Note: When using the empty enum value in your code, it's recommended to use the scoped syntax clickType::empty to avoid potential naming conflicts with other libraries (particularly when using libraries that do using namespace std; which imports std::empty() from the C++17 standard library).
// Recommended - explicit scope avoids ambiguity
if (button.getType() == clickType::empty) {
  // handle no click
}

// Also works, but may cause compilation errors with some library combinations
if (button.getType() == empty) {
  // handle no click
}
  • There are also dedicated waits (waitForClick(), waitForDouble(), waitForTriple() and waitForLong()) to detect a specific type
  • The read() 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().
  • Check out the ButtonLoop.ino example to see it in action

Status Functions

  • There are several status functions available to check the status of a button:
unsigned int wasPressedFor() const;
byte getNumberOfClicks() const;
byte getType() const;
bool isPressed() const;
bool isPressedRaw() const;
bool wasPressed() const;

wasPressedFor() - Press Duration

Returns the duration (in milliseconds) that the button was held down during the most recent press.

Important: For multi-click scenarios (double/triple clicks), this returns the duration of the most recent click only, not the cumulative time across all clicks.

Examples:

  • Single click held for 500ms → wasPressedFor() returns 500
  • Long click held for 1200ms → wasPressedFor() returns 1200
  • Double click (1st press: 50ms, 2nd press: 80ms) → wasPressedFor() returns 80
  • Triple click (1st: 40ms, 2nd: 60ms, 3rd: 70ms) → wasPressedFor() returns 70

This behavior was confirmed in issue #35.

IDs for Button Instances

  • Each button instance gets a unique (auto incremented) ID upon creation.
  • You can get a buttons' ID via getID().
  • Alternatively, you can use setID(int newID) to set a new one. But then you need to make sure that they are unique.

Virtual Buttons and Custom State Handlers

Button2 supports "virtual buttons" - buttons not directly connected to GPIO pins. This is useful for:

  • I2C/SPI port expander buttons (e.g., PCF8574, MCP23017)
  • Capacitive touch sensors (e.g., ESP32 touch pins, TTP223)
  • Custom button sources (e.g., M5Stack Core2 touch buttons)
  • Any non-standard input that can be read as a digital state

Setup Requirements

To use a virtual button, you need:

  1. Use BTN_VIRTUAL_PIN instead of a real pin number when calling begin()
  2. Define a state handler function that returns the current button state
  3. Initialize your hardware either manually or via the optional initialization callback parameter

begin() accepts an optional initialization callback parameter. This is especially useful for virtual buttons that require hardware setup (I2C, SPI, touch sensors, etc.). The callback is invoked immediately by begin(), ensuring your hardware is ready before the button starts polling.

Efficient Pattern for Multiple I2C Buttons

Important: When using multiple buttons on an I2C port expander (PCF8574, MCP23017, etc.), read the entire port once per loop cycle and cache the value. Each button's state handler then reads from the cache using bit masking. This minimizes I2C bus traffic from N transactions per cycle to just 1.

See I2CPortExpanderButtons.ino for a complete example showing this efficient caching pattern (issue #70).

Virtual Button Examples

This feature was enhanced in issue #69 to support initialization callbacks.

Callback Handler Support and Compatibility

Button2 uses callback handlers for button events. On platforms that support C++11 and <functional> (such as ESP32 and ESP8266), Button2 uses std::function for maximum flexibility, allowing you to use lambdas and other advanced C++ features as handlers.

On platforms that do not support std::function (such as AVR/Arduino Uno), Button2 falls back to using regular function pointers for handlers.

std::function Support

Button2 automatically detects and enables std::function support on platforms with C++11 or later, except AVR (Arduino Uno, Nano, Mega).

Supported platforms:

  • ESP32 (all variants)
  • ESP8266
  • Teensy
  • Raspberry Pi Pico (RP2040)
  • SAMD (Arduino Zero, MKR series)
  • STM32
  • nRF52
  • Other C++11+ platforms with STL support

Not supported:

  • AVR (Arduino Uno, Nano, Mega) - uses function pointers instead

The library automatically detects support using #if __cplusplus >= 201103L && !defined(__AVR__). This improvement was implemented in response to issue #58.

Forcing or Disabling std::function Support

You can override the automatic detection by defining these macros before including Button2:

  • To force-enable: #define BUTTON2_HAS_STD_FUNCTION
  • To force-disable: #define BUTTON2_DISABLE_STD_FUNCTION

This is useful if you are using a custom toolchain or want to override the default detection logic.

Note: On platforms that use std::function, Button2 uses std::move internally when assigning handlers for better performance and efficiency.

Troubleshooting

  • If you see errors about <functional> not being found, your platform does not have C++11 STL support. Supported platforms include ESP32, ESP8266, Teensy, RP2040, SAMD, STM32, and other modern boards. AVR boards (Uno, Nano, Mega) automatically use function pointers instead. You can force-disable with #define BUTTON2_DISABLE_STD_FUNCTION before including Button2.

Examples

Class Definition

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, bool activeLow = true);

void begin(byte attachTo, byte buttonMode = INPUT_PULLUP, bool 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();

bool isPressed() const;
bool 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();

Installation

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.

License

MIT License

Copyright (c) 2017-2025 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.

About

Arduino/ESP button library that provides callback functions to track single, double, triple and long clicks. It also takes care of debouncing.

Topics

c-plus-plus arduino esp8266 embedded hardware touch esp32 button mbed arduino-library

Resources

Readme

License

MIT license
Activity

Stars

540 stars

Watchers

13 watching

Forks

86 forks
Report repository

Releases 36

2.5.0 Latest
Oct 25, 2025
+ 35 releases

Sponsor this project

Packages

No packages published

Contributors 11

Languages