AceButton

An adjustable, compact, event-driven button library for Arduino platforms.

This library provides classes which accept inputs from a mechanical button connected to a digital input pin on the Arduino. The library should be able to handle momentary buttons, maintained buttons, and switches, but it was designed primarily for momentary (aka push) buttons.

The library is named "AceButton" because:

• many configurations of the button are adjustable, either at compile-time or run-time
• the library is optimized to create compact objects which take up a minimal amount of static memory
• the library detects changes in the button state and sends events to a user-defined EventHandler callback function

Most of the features of the library can be accessed through 2 classes, using either a callback function or an interface:

• AceButton (class)
• ButtonConfig (class)
• EventHandler (typedef for callback function)
• IEventHandler (interface)

The AceButton class contains the logic for debouncing and determining if a particular event has occurred.

The ButtonConfig class holds various timing parameters, the event handler, code for reading the button, and code for getting the internal clock.

The EventHandler is a user-defined callback function with a specific signature which is registered with the ButtonConfig object. When the library detects interesting events, the callback function is called by the library, allowing the client code to handle the event.

The IEventHandler is an interface (pure abstract class) that provides an alternative to the EventHandler. Instead of using a callback function, an object of type IEventHandler can be used to handle the button events.

The supported events are:

• AceButton::kEventPressed
• AceButton::kEventReleased
• AceButton::kEventClicked
• AceButton::kEventDoubleClicked
• AceButton::kEventLongPressed
• AceButton::kEventRepeatPressed
• AceButton::kEventLongReleased (v1.8)
• AceButton::kEventHeartBeat (v1.10)

The basic ButtonConfig class assumes that each button is connected to a single digital input pin. In some situations, the number of buttons that we want is greater than the number of input pins available. This library provides 2 subclasses of ButtonConfig which may be useful:

• EncodedButtonConfig
  • Supports binary encoded buttons, to read 2^N - 1 buttons using N pins (e.g. 7 buttons using 3 digital pins).
• LadderButtonConfig
  • Supports 1-8 buttons (maybe more) on a single analog pin through a resistor ladder. The analogRead() method is used to read the different voltage levels corresponding to each button.

Both EncodedButtonConfig and LadderButtonConfig support all events listed above (e.g. kEventClicked and kEventDoubleClicked).

Version: 1.10.1 (2023-05-25)

Changelog: CHANGELOG.md

Table of Contents

• Features
• HelloButton
• Installation
  • External Dependencies
  • Source Code
• Documentation
  • Examples
• Usage
  • Include Header and Use Namespace
  • Pin Wiring and Initialization
  • AceButton Class
    • Sampling Rate
    • Compiler Error on Pin 0
  • ButtonConfig Class
    • System ButtonConfig
    • Configuring the EventHandler
    • Timing Parameters
    • Hardware Dependencies
    • Multiple ButtonConfig Instances
  • EventHandler Typedef
    • EventHandler Signature
    • EventHandler Parameters
    • One EventHandler Per ButtonConfig
    • EventHandler Tips
  • Event Types
  • ButtonConfig Feature Flags
    • Event Activation
    • Event Suppression
  • Single Button Simplifications
  • Multiple Buttons
• Advanced Topics
  • Object-based Event Handler
  • Distinguishing Clicked and DoubleClicked
  • Distinguishing Pressed and LongPressed
  • Events After Reboot
  • Orphaned Clicks
  • Binary Encoded Buttons
  • Resistor Ladder Buttons
  • Dynamic Allocation on the Heap
  • Digital Write Fast
  • Heart Beat Event
• Resource Consumption
  • SizeOf Classes
  • Flash And Static Memory
  • CPU Cycles
• System Requirements
  • Hardware
  • Tool Chain
  • Operating System
• Background Motivation
• Non-goals
• Bugs and Limitations
• License
• Feedback and Support
• Author

Features

Here are the high-level features of the AceButton library:

• debounces the mechanical contact
• supports both pull-up and pull-down wiring
• event-driven through a user-defined EventHandler callback function
• event-driven through an object-based IEventHandler (>= v1.6)
• supports the following event types:
  • kEventPressed
  • kEventReleased
  • kEventClicked
  • kEventDoubleClicked
  • kEventLongPressed
  • kEventRepeatPressed
  • kEventLongReleased
  • kEventHeartBeat
• adjustable configurations at runtime or compile-time
  • timing parameters
  • digitalRead() button read function can be overridden
  • millis() clock function can be overridden
• small memory footprint
  • each AceButton consumes 17 bytes (8-bit) or 20 bytes (32-bit)
  • each ButtonConfig consumes 20 bytes (8-bit) or 24 bytes (32-bit)
  • one System ButtonConfig instance created automatically by the library
  • 970-2180 bytes of flash memory for the simple case of 1 AceButton and 1 ButtonConfig, depending on 8-bit or 32-bit processors
• supports multiple buttons on shared pins using various circuits
  • Binary Encoded buttons (e.g. 7 buttons using 3 pins)
  • Resistor Ladder buttons (e.g. 5 buttons on a single analog pin)
• only 13-15 microseconds (on 16MHz ATmega328P) per polling call to AceButton::check()
• extensive testing
  • thoroughly unit tested using AUnit
  • tested on Arduino AVR (UNO, Nano, Micro etc), Teensy ARM (LC and 3.2), SAMD21 (Arduino Zero compatible), ESP8266 and ESP32

Compared to other Arduino button libraries, I think the unique or exceptional features of the AceButton library are:

• many supported event types (e.g. LongPressed and RepeatPressed)
• able to distinguish between Clicked and DoubleClicked
• small memory usage
• thorough unit testing
• support for multiple buttons using Binary Encoding or a Resistor Ladder

HelloButton

Here is a simple program (see examples/HelloButton) which controls the builtin LED on the Arduino board using a momentary button connected to PIN 2.

#include <AceButton.h>
using namespace ace_button;

const int BUTTON_PIN = 2;
const int LED_ON = HIGH;
const int LED_OFF = LOW;

AceButton button(BUTTON_PIN);

void handleEvent(AceButton*, uint8_t, uint8_t);

void setup() {
  pinMode(LED_BUILTIN, OUTPUT);
  pinMode(BUTTON_PIN, INPUT_PULLUP);
  button.setEventHandler(handleEvent);
}

void loop() {
  button.check();
}

void handleEvent(AceButton* /*button*/, uint8_t eventType,
    uint8_t /*buttonState*/) {
  switch (eventType) {
    case AceButton::kEventPressed:
      digitalWrite(LED_BUILTIN, LED_ON);
      break;
    case AceButton::kEventReleased:
      digitalWrite(LED_BUILTIN, LED_OFF);
      break;
  }
}

(The button and buttonState parameters are commented out to avoid an unused parameter warning from the compiler. We can't remove the parameters completely because the method signature is defined by the EventHandler typedef.)

Installation

The latest stable release is available in the Arduino IDE Library Manager. Search for "AceButton". Click install.

The development version can be installed by cloning the GitHub repository (https://github.com/bxparks/AceButton), checking out the develop branch, then manually copying over the contents to the ./libraries directory used by the Arduino IDE. (The result is a directory named ./libraries/AceButton.)

The master branch contains the tagged stable releases.

External Dependencies

The core of the library is self-contained and has no external dependencies.

The some programs in examples/ may depend on: * AceCommon (https://github.com/bxparks/AceCommon)

The unit tests under tests depend on: * AUnit (https://github.com/bxparks/AUnit)

Source Code

The source files are organized as follows: * src/AceButton.h - main header file * src/ace_button/ - all implementation files * src/ace_button/testing/ - internal testing files * tests/ - unit tests which require AUnit * examples/ - example sketches

Documentation

• this README.md
• docs/binary_encoding/README.md
  • Explanation of reading buttons through binary encoding using the Encoded4To2ButtonConfig, Encoded8To3ButtonConfig, EncodedButtonConfig classes
• docs/resistor_ladder/README.md
  • Explanation of reading buttons through a resistor ladder using the LadderButtonConfig class
• Doxygen docs published on GitHub Pages which can help navigate an unfamiliar code base.

Examples

The following example sketches are provided:

• Basic Single Button
  • HelloButton
    • minimal program that reads a switch and control the built-in LED
  • SingleButton
    • single button wired with an internal pull-up resistor
  • SingleButtonPullDown
    • same as SingleButton but with an external pull-down resistor
  • SingleButtonUsingIEventHandler
    • same as SingleButton using an object-based IEventHandler
  • Stopwatch
    • measures the speed of AceButton:check() with a start/stop/reset
    • button uses kFeatureLongPress
• Multiple Buttons
  • TwoButtonsUsingOneButtonConfig
    • two buttons using one ButtonConfig
  • TwoButtonsUsingTwoButtonConfigs
    • two buttons using two ButtonConfigs
  • ThreeButtonsUsingOneButtonConfig
    • three buttons using one ButtonConfig
    • used as a reference for ThreeButtonsUsingOneButtonConfigFast (below)
  • TunerButtons
    • implements 5 radio buttons (tune-up, tune-down, and 3 presets)
    • shows multiple ButtonConfig and EventHandler instances
    • shows an example of how to use getId()
    • uses kFeatureLongPress, kFeatureRepeatPress, kFeatureSuppressAfterLongPress, and kFeatureSuppressAfterRepeatPress
  • ArrayButtons
    • shows how to define an array of AceButton and initialize them using the init() method in a loop
  • SimultaneousButtons
    • detecting simultaneous Pressed and Released of 2 buttons using a custom IEventHandler
• Distinguishing Click versus Double-Click
  • ClickVersusDoubleClickUsingReleased
    • using a kEventReleased instead
  • ClickVersusDoubleClickUsingSuppression
    • using the kFeatureSuppressClickBeforeDoubleClick flag at the cost of increasing the response time
  • ClickVersusDoubleClickUsingBoth
    • combining both the "UsingReleased" and "UsingSuppression" techniques
  • See Distinguishing Clicked and DoubleClicked subsection below for more info.
• Distinguishing Pressed and LongPressed
  • examples/PressVersusLongPress
  • See the Distinguishing Pressed and LongPressed subsection below for more info.
• CapacitiveButton
  • reads a capacitive button using the CapacitiveSensor library
• HeartBeat
  • demo of activating the new (v1.10) kEventHeartBeat feature, and using it to generate 2 custom events: kCustomEventLongPressed (similar to kEventLongPressed) and kCustomEventLongReleased (no built-in equiva