EasyButton

Arduino library to debounce buttons, detect presses, releases, long presses and sequences


Keywords
signal, input, output, arduino, arduino-library, button, debounce, debounce-button, debounce-buttons, detect-presses, easybutton, esp32, esp32-arduino, esp8266, esp8266-arduino, platformio, pushbutton, switch, touch, touch-button, trigger
License
MIT
Install
platformio lib install 5741

Documentation

EasyButton

Join the chat at https://gitter.im/easy-button/chat License

Arduino library to debounce buttons, detect presses, releases, long presses and sequences

💡 Attention! If using ESP32, be aware that some of the pins does not have software pullup/down functions. Use an external pull-up resistor, 10K works well. Refer to Pull-up Resistors.

What it is for

This library is for debouncing and reading momentary contact switches like tactile buttons. It uses callbacks to trigger actions when a Button is pressed once or held for a given duration. It also provides a sequence counter to be able to rise an event when a given pattern of presses has been matched.

How to install

Install the library using one of the following options

How to use

Include the library

#include <EasyButton.h>

Create the Button instance

Create an instance of EasyButton class for each button that you want to use, and pass the pin number as an argument.

// Button instance
EasyButton button(BUTTON_PIN);

The class constructor takes the following additional arguments:

debounce_time : Debounce time in milliseconds.

pullup_enable : Use or not the internal pullup resistor. Enabled by default.

If using ESP32, be aware that some of the pins does not have software pullup/down functions. Use an external pullup resistor, 10K works well. Refer to Pull-up Resistors.

invert : Inverts button's logic. If true, low = pressed else high = pressed.

Please refer to this image to see the resistor configuration for each mode

// EasyButton class's constructor signature
EasyButton(uint8_t pin, uint32_t debounce_time = 35, uint8_t pullup_enable = true, uint8_t invert = true)

Initialize Button Object

// Initialize Button Object
button.begin();

Continuously read the status of the Button

void loop() {
    // Continuously read the status of the button. 
    button.read();
}

Available methods in the library

  • onPressed

    Triggers a callback function when the Button has been pressed and released. The callback function will be called each time the Button is pressed.

    // Single pressed
    button.onPressed(onPressedCallback);
  • onPressedFor

    Triggers a callback function when the Button has been pressed and hold for at least the given duration time. This method takes two parameters as arguments. The first argument is the duration in milliseconds and the second is the callback function to be called.

    // Pressed for a duration
    int duration = 2000;
    button.onPressedFor(duration, onPressedCallback);
  • onSequence

    Triggers a callback function when the Button presses matches the given sequence pattern. This method takes three parameters as arguments. The first argument is the number of times to press the Button in order to trigger the sequence event. The second argument is the timeout in which the sequence has to reproduce in order to trigger the sequence event. Third argument is the callback function to be called.

    // Sequence of presses
    int number_of_presses = 5;	// Number of presses for the sequence
    int sequence_timeout = 2000;	// Sequence timeout
    button.onSequence(number_of_presses, sequence_timeout, onSequenceMatchedCallback);

Additional methods available

There some other methods available that might be useful for you in some scenarios.

  • isPressed

    Returns true if the Button state was pressed at the last read.

    // isPressed
    bool pressed = button.isPressed();
  • isReleased

    Returns true if the Button state was released at the last read.

    // isReleased
    bool released = button.isReleased();
  • wasPressed

    Returns true if the Button state at the last read was pressed.

    // wasPressed
    bool was_pressed = button.wasPressed();
  • wasReleased

    Returns true if the Button state at the last read was released.

    // wasReleased
    bool was_released = button.wasReleased();
  • pressedFor

    Returns true if the Button state at the last read was pressed, and has been in that state for at least the given number of milliseconds.

    // pressedFor
    int pressedForTime = 2000;
    bool pressed_for = button.pressedFor(pressedForTime);
  • releasedFor

    Returns true if the Button state at the last read was released, and has been in that state for at least the given number of milliseconds.

    // releasedFor
    int releasedForTime = 2000;
    bool released_for = button.releasedFor(releasedForTime);

    Examples

    Pressed

    PressedForDuration

    Sequence

Copyright

MIT © Evert Arias