Arduino OneButton Library

This Arduino library is improving the usage of a singe button for input. It shows how to use an digital input pin with a single pushbutton attached for detecting some of the typical button press events like single clicks, double clicks and long-time pressing. This enables you to reuse the same button for multiple functions and lowers the hardware investments.

This is also a sample for implementing simple finite-state machines by using the simple pattern above.

You can find more details on this library at http://www.mathertel.de/Arduino/OneButtonLibrary.aspx

The change log of this library can be found in CHANGELOG.

Getting Started

Clone this repository into Arduino/Libraries or use the built-in Arduino IDE Library manager to install a copy of this library. You can find more detail about installing libraries here, on Arduino's website.

#include <Arduino.h>
#include <OneButton.h>

Each physical button requires its own OneButton instance. You can initialize them like this:

Initialize a Button to GND

#define BUTTON_PIN 4

/**
 * Initialize a new OneButton instance for a button
 * connected to digital pin 4 and GND, which is active low
 * and uses the internal pull-up resistor.
 */

OneButton btn = OneButton(
  BUTTON_PIN,  // Input pin for the button
  true,        // Button is active LOW
  true         // Enable internal pull-up resistor
);

Initialize a Button to VCC

#define BUTTON_PIN 4

/**
 * Initialize a new OneButton instance for a button
 * connected to digital pin 4, which is active high.
 * As this does not use any internal resistor
 * an external resistor (4.7k) may be required to create a LOW signal when the button is not pressed.
 */

OneButton btn = OneButton(
  BUTTON_PIN,  // Input pin for the button
  false,       // Button is active high
  false        // Disable internal pull-up resistor
);

Attach State Events

Once you have your button initialized, you can handle events by attaching them to the button instance. Events can either be static functions or lambdas (without captured variables).

// Handler function for a single click:
static void handleClick() {
  Serial.println("Clicked!");
}

// Single Click event attachment
btn.attachClick(handleClick);

// Double Click event attachment with lambda
btn.attachDoubleClick([]() {
  Serial.println("Double Pressed!");
});

// Handler function for MultiClick the button with self pointer as a parameter
static void handleMultiClick(OneButton *oneButton) {
  Serial.println("MultiClick pin=%d debouncedValue=%d!", oneButton->pin(), oneButton->debouncedValue());
}

// MultiClick button event attachment with self pointer as a parameter
btn.attachMultiClick(handleMultiClick, &btn);

Don't forget to tick()

In order for OneButton to work correctly, you must call tick() on each button instance within your main loop(). If you're not getting any button events, this is probably why.

void loop() {
  btn.tick();

  // Do other things...
}

Usage with lambdas that capture context

You can't pass a lambda-with-context to an argument which expects a function pointer. To work that around, use paramtererizedCallbackFunction. We pass the context (so the pointer to the object we want to access) to the library and it will give it back to the lambda.

okBtn.attachClick([](void *ctx){Serial.println(*((BtnHandler*)ctx) -> state);}, this);

See also discussion in Issue #112.

State Events

Here's a full list of events handled by this library:

Event Timing

Valid events occur when tick() is called after a specified number of milliseconds. You can use the following functions to change the timing.

Note: Attaching a double click will increase the delay for detecting a single click. If a double click event is not attached, the library will assume a valid single click after one click duration, otherwise it must wait for the double click timeout to pass. This is because a single click callback must not to be triggered in case of a double click event.

You may change these default values but be aware that when you specify too short times it is hard to click twice or you will create a press instead of a click.

The former functions setDebounceTicks, setClickTicks and setPressTicks are marked deprecated. The term Ticks in these functions where confusing. Replace them with the ...Ms function calls. There is no functional change on them.

Additional Functions

OneButton also provides a couple additional functions to use for querying button status:

tick() and reset()

You can specify a logic level when calling tick(bool), which will skip reading the pin and use that level instead. If you wish to reset the internal state of your buttons, call reset().

Troubleshooting

If your buttons aren't acting they way they should, check these items:

1. Check your wiring and pin numbers.
2. Did you call tick() on each button instance in your loop?
3. Did you alter your clock timers in any way without adjusting ticks?