.. | ||
docs | ||
examples | ||
src | ||
tests | ||
CHANGELOG.md | ||
CONTRIBUTING.md | ||
keywords.txt | ||
library.properties | ||
LICENSE | ||
README.md |
AceButton
An adjustable, compact, event-driven button library for Arduino platforms.
Version: 1.3.3 (2019-03-10)
Summary
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 buttons.
The library is called the ACE Button Library (or AceButton Library) 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 and 1 callback function:
AceButton
(class)ButtonConfig
(class)EventHandler
(typedef)
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 supported events are:
AceButton::kEventPressed
AceButton::kEventReleased
AceButton::kEventClicked
AceButton::kEventDoubleClicked
AceButton::kEventLongPressed
AceButton::kEventRepeatPressed
(TripleClicked is not supported but can be easily added to the library if requested.)
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 funcition - supports 6 event types:
- Pressed
- Released
- Clicked
- DoubleClicked
- LongPressed
- RepeatPressed
- can distinguish between Clicked and DoubleClicked
- adjustable configurations at runtime or compile-time
- timing parameters
digitalRead()
button read function can be overriddenmillis()
clock function can be overridden
- small memory footprint
- each
AceButton
consumes 14 bytes - each
ButtonConfig
consumes 20 bytes - one System
ButtonConfig
instance created automatically by the library
- each
- thoroughly unit tested using AUnit
- properly handles reboots while the button is pressed
- properly handles orphaned clicks, to prevent spurious double-clicks
- only 13-15 microseconds (on 16MHz ATmega328P) per polling call to
AceButton::check()
- can be instrumented to extract profiling numbers
- tested on Arduino AVR (UNO, Nano, etc), Teensy ARM (LC and 3.2), ESP8266 and ESP32 platforms
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
- proper handling of orphaned clicks
- proper handling of a reboot while button is pressed
Non-goals
An Arduino UNO or Nano has 16 times more flash memory (32KB) than static memory (2KB), so the library is optimized to minimize the static memory usage. The AceButton library is not optimized to create a small program size (i.e. flash memory), or for small CPU cycles (i.e. high execution speed). I assumed that if you are seriously optimizing for program size or CPU cycles, you will probably want to write everything yourself from scratch.
That said, the examples/AutoBenchmark program
shows that AceButton::check()
takes between 13-15 microseconds on a 16MHz
ATmega328P chip on average. Hopefully that is fast enough for the vast
majority of people.
HelloButton
Here is a simple program (see examples/HelloButton.ino
) 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, 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 stable release.
Source Code
The source files are organized as follows:
src/AceButton.h
- main header filesrc/ace_button/
- all implementation filessrc/ace_button/testing/
- internal testing filestests/
- unit tests which require AUnitexamples/
- example sketches
Docs
Besides this README.md file, the docs/ directory contains the Doxygen docs published on GitHub Pages. It can help you navigate an unfamiliar code base.
Examples
The following example sketches are provided:
- HelloButton.ino
- minimal program that reads a switch and control the built-in LED
- SingleButton.ino
- controls a single button wired with a pull-up resistor
- prints out a status line for every supported event
- SingleButtonPullDown.ino
- same as SingleButton.ino but with an external pull-down resistor
- Stopwatch.ino
- measures the speed of
AceButton:check()
with a start/stop/reset button - uses
kFeatureLongPress
- measures the speed of
- TunerButtons.ino
- implements 5 radio buttons (tune-up, tune-down, and 3 presets)
- shows multiple
ButtonConfig
instances - shows multiple
EventHandler
s - shows an example of how to use
getId()
- uses
kFeatureLongPress
,kFeatureRepeatPress
,kFeatureSuppressAfterLongPress
, andkFeatureSuppressAfterRepeatPress
- ClickVersusDoubleClickUsingReleased.ino
- a way to distinguish between a
kEventClicked
from akEventDoubleClicked
using akEventReleased
instead
- a way to distinguish between a
- ClickVersusDoubleClickUsingSuppression.ino
- another way to dstinguish between a
kEventClicked
from akEventDoubleClicked
using thekFeatureSuppressClickBeforeDoubleClick
flag at the cost of increasing the response time of thekEventClicked
event
- another way to dstinguish between a
- ClickVersusDoubleClickUsingBoth.ino
- an example that combines both the "UsingPressed" and "UsingSuppression" techniques
- CapacitiveButton
- reads a capacitive button using the CapacitiveSensor library
- AutoBenchmark.ino
- generates the timing stats (min/average/max) for the
AceButton::check()
method for various types of events (idle, press/release, click, double-click, and long-press)
- generates the timing stats (min/average/max) for the
Usage
There are 2 classes and one typedef that a user will normally interact with:
AceButton
(class)ButtonConfig
(class)EventHandler
(typedef)
We explain how to use these below.
Include Header and Use Namespace
Only a single header file AceButton.h
is required to use this library.
To prevent name clashes with other libraries that the calling code may use, all
classes are defined in the ace_button
namespace. To use the code without
prepending the ace_button::
prefix, use the using
directive:
#include <AceButton.h>
using namespace ace_button;
If you are dependent on just AceButton
, the following might be sufficient:
#include <AceButton.h>
using ace_button::AceButton;
Pin Wiring and Initialization
An Arduino microcontroller pin can be in an OUTPUT
mode, an INPUT
mode, or
an INPUT_PULLUP
mode. This mode is controlled by the pinMode()
method.
By default upon boot, the pin is set to the INPUT
mode. However, this INPUT
mode puts the pin into a high impedance state, which means that if there is no
wire connected to the pin, the voltage on the pin is indeterminant. When the
input pin is read (using digitalRead()
), the boolean value will be a random
value. If you are using the pin in INPUT
mode, you must connect an external
pull-up resistor (connected to Vcc) or pull-down resistor (connected to ground)
so that the voltage level of the pin is defined when there is nothing connected
to the pin (i.e. when the button is not pressed).
The INPUT_PULLUP
mode is a special INPUT
mode which tells the
microcontroller to connect an internal pull-up resistor to the pin. It is
activated by calling pintMode(pin, INPUT_PULLUP)
on the given pin
. This mode
is very convenient because it eliminates the external resistor, making the
wiring simpler.
The AceButton library itself does not call the pinMode()
function. The
calling application is responsible for calling pinMode()
. Normally, this
happens in the global setup()
method but the call can happen somewhere else if
the application requires it. The reason for decoupling the hardware
configuration from the AceButton library is mostly because the library does not
actually care about the specific hardware wiring of the button. It does not care
whether an external resistor is used, or the internal resistor is used. It only
cares about whether the resistor is a pull-up or a pull-down.
See https://www.arduino.cc/en/Tutorial/DigitalPins for additional information about the I/O pins on an Arduino.
AceButton Class
Each physical button will be handled by an instance of AceButton
. At a
minimum, the instance needs to be told the pin number of the button. This can
be done through the constructor:
const uint8_t BUTTON_PIN = 2;
AceButton button(BUTTON_PIN);
void setup() {
pinMode(BUTTON_PIN, INPUT_PULLUP);
...
}
Or we can use the init()
method in the setup()
:
AceButton button;
void setup() {
pinMode(BUTTON_PIN, INPUT_PULLUP);
button.init(BUTTON_PIN);
...
}
Both the constructor and the init()
function take 3 optional parameters:
AceButton(uint8_t pin = 0, uint8_t defaultReleasedState = HIGH, uint8_t id = 0);
void init(uint8_t pin = 0, uint8_t defaultReleasedState = HIGH, uint8_t id = 0);
pin
: the I/O pin number assigned to the buttondefaultReleasedState
: the logical value of the button when it is in its default "released" state (HIGH
using a pull-up resistor,LOW
for a pull-down pull-down resistor)id
: an optional, user-defined identifier for the the button, for example, an index into an array with additional information
The pin
must be defined either through the constructor or the init()
method.
But the other two parameters may be optional in many cases.
Finally, the AceButton::check()
method should be called from the loop()
method periodically. Roughly speaking, this should be about 4 times faster than
the value of getDebounceDelay()
so that the various event detection logic can
work properly. (If the debounce delay is 20 ms, AceButton::check()
should be
called every 5 ms or faster.)
void loop() {
...
button.check();
...
}
ButtonConfig Class
The core concept of the AceButton library is the separation of the
button (AceButton
) from its configuration (ButtonConfig
).
- The
AceButton
class has the logic for debouncing and detecting the various events (Pressed, Released, etc), and the various bookkeeping variables needed to implement the logic. These variables are associated with the specific instance of thatAceButton
. - The
ButtonConfig
class has the various timing parameters which control how much time is needed to detect certain events. This class also has the ability to override the default methods for reading the pin (readButton()
) and the clock (getClock()
). This ability allows unit tests to be written.
The ButtonConfig
can be created and assigned to one or more AceButton
instances using dependency injection through the AceButton(ButtonConfig*)
constructor. If this constructor is used, then the AceButton::init()
method
must be used to set the pin number of the button. For example:
const uint8_t PIN1 = 2;
const uint8_t PIN2 = 4;
ButtonConfig buttonConfig;
AceButton button1(&buttonConfig);
AceButton button2(&buttonConfig);
void setup() {
pinMode(PIN1, INPUT_PULLUP);
button1.init(PIN1);
pinMode(PIN2, INPUT_PULLUP);
button2.init(PIN2);
...
}
Another way to inject the ButtonConfig
dependency is to use the
AceButton::setButtonConfig()
method but it is recommended that you use the
constructor instead because the dependency is easier to follow.
System ButtonConfig
A single instance of ButtonConfig
called the "System ButtonConfig" is
automatically created by the library at startup. By default, all instances of
AceButton
are automatically assigned to this singleton instance. We explain in
the Single Button Simplifications section below how this simplifies the code
needed to handle a single button.
Configuring the EventHandler
The ButtonConfig
class provides a number of methods which are mostly
used internally by the AceButton
class. The one method which is expected
to be used by the calling client code is setEventHandler()
which
assigns the user-defined EventHandler
callback function to the ButtonConfig
instance. This is explained in more detail below in the
EventHandler Callback section.
Timing Parameters
Here are the methods to retrieve the timing parameters:
uint16_t getDebounceDelay();
(default: 20 ms)uint16_t getClickDelay();
(default: 200 ms)uint16_t getDoubleClickDelay();
(default: 400 ms)uint16_t getLongPressDelay();
(default: 1000 ms)uint16_t getRepeatPressDelay();
(default: 1000 ms)uint16_t getRepeatPressInterval();
(default: 200 ms)
The default values of each timing parameter can be changed at run-time using the following methods:
void setDebounceDelay(uint16_t debounceDelay);
void setClickDelay(uint16_t clickDelay);
void setDoubleClickDelay(uint16_t doubleClickDelay);
void setLongPressDelay(uint16_t longPressDelay);
void setRepeatPressDelay(uint16_t repeatPressDelay);
void setRepeatPressInterval(uint16_t repeatPressInterval);
Hardware Dependencies
The ButtonConfig
class has 2 methods which provide hooks to its external
hardware dependencies:
virtual unsigned long getClock();
virtual int readButton(uint8_t pin);
By default these are mapped to the underlying Arduino system functions respectively:
millis()
digitalRead()
Unit tests are possible because these methods are virtual
and the hardware
dependencies can be swapped out with fake ones.
Multiple ButtonConfig Instances
We have assumed that there is a 1-to-many relationship between a ButtonConfig
and the AceButton
. In other words, multiple buttons will normally be
associated with a single configuration. Each AceButton
has a pointer to an
instance of ButtonConfig
. So the cost of separating the ButtonConfig
from
AceButton
is 2 bytes in each instance of AceButton
. Note that this is
equivalent to adding virtual methods to AceButton
(which would add 2 bytes),
so in terms of static RAM size, this is a wash.
The library is designed to handle multiple buttons, and it assumes that the buttons are normally grouped together into a handful of types. For example, consider the buttons of a car radio. It has several types of buttons:
- the tuner buttons (2, up and down)
- the preset buttons (6)
- the AM/FM band button (1)
In this example, there are 9 buttons, but only 3 instances of ButtonConfig
would be needed.
EventHandler
The event handler is a callback function that gets called when the AceButton
class determines that an interesting event happened on the button. The
advantage of this mechanism is that all the complicated logic of determining
the various events happens inside the AceButton
class, and the user will
normally not need to worry about the details.
EventHandler Signature
The event handler has the following signature:
typedef void (*EventHandler)(AceButton* button, uint8_t eventType,
uint8_t buttonState);
The event handler is registered with the ButtonConfig
object, not with the
AceButton
object, although the convenience method
AceButton::setEventHandler()
is provided as a pass-through to the underlying
ButtonConfig
(see the Single Button Simplifications section below):
ButtonConfig buttonConfig;
void handleEvent(AceButton* button, uint8_t eventType, uint8_t buttonState) {
...
}
void setup() {
...
buttonConfig.setEventHandler(handleEvent);
...
}
The motivation for this design is to save static memory. If multiple buttons
are associated with a single ButtonConfig
, then it is not necessary for every
button of that type to hold the same pointer to the EventHandler
function. It
is only necessary to save that information once, in the ButtonConfig
object.
Pro Tip: Comment out the unused parameter(s) in the handleEvent()
method
to avoid the unused parameter
compiler warning:
void handleEvent(AceButton* /* button */, uint8_t eventType,
uint8_t /* buttonState */) {
...
}
The Arduino sketch compiler can get confused with the parameters commented out,
so you may need to add a forward declaration for the handleEvent()
method
before the setup()
method:
void handleEvent(AceButton*, uint8_t, uint8_t);
EventHandler Parameters
The EventHandler
function receives 3 parameters from the AceButton
:
aceButton
- pointer to the
AceButton
instance that generated this event - can be used to retrieve the
getPin()
or thegetId()
- pointer to the
eventType
- the type of this event given by the various
AceButton::kEventXxx
constants
- the type of this event given by the various
buttonState
- the
HIGH
orLOW
button state that generated this event
- the
The aceButton
pointer should be used only to extract information about the
button that triggered the event. It should not be used to modify the
button's internal variables in any way within the eventHandler. The logic in
AceButton::check()
assumes that those internal variable are held constant,
and if they are changed by the eventHandler, unpredictable results may occur.
(I was tempted to make the aceButton
a pointer to a const AceButton
but this cause too many viral changes to the code which seemed to increase
the complexity without too much benefit.)
If you are using only a single button, then you should need to check
only the eventType
.
It is not expected that buttonState
will be needed very often. It should be
sufficient to examine just the eventType
to determine the action that needs
to be performed. Part of the difficulty with this parameter is that it has the
value of LOW
or HIGH
, but the physical interpretation of those values depends
on whether the button was wired with a pull-up or pull-down resistor. The helper
function AceButton::isReleased(uint8_t buttonState)
is provided to make this
determination if you need it.
One EventHandler
Only a single EventHandler
per ButtonConfig
is supported. An alternative
would have been to register a separate event handler for each of the 6
kEventXxx
events. But each callback function requires 2 bytes of memory, and
it was assumed that in most cases, the calling client code would be interested
in only a few of these event types, so it seemed wasteful to allocate 12 bytes
when most of these would be unused. If the client code really wanted separate
event handlers, it can be easily emulated by invoking them through the main
event handler:
void handleEvent(AceButton* button, uint8_t eventType, uint8_t buttonState) {
switch (eventType) {
case AceButton:kEventPressed:
handleEventPressed(button, eventType, buttonState);
break;
case AceButton::kEventReleased:
handleEventReleased(button, eventType, buttonState);
break;
...
}
}
EventHandler Tips
The Arduino runtime environment is single-threaded, so the EventHandler
is
called in the middle of the AceButton::check()
method, in the same thread as
the check()
method. It is therefore important to write the EventHandler
code to run somewhat quickly, so that the delay doesn't negatively impact the
logic of the AceButton::check()
algorithm. Since AceButton::check()
should
run approximately every 5 ms, the user-provided EventHandler
should run
somewhat faster than 5 ms. Given a choice, it is probably better to use the
EventHandler
to set some flags or variables and return quickly, then do
additional processing from the loop()
method.
Speaking of threads, the API of the AceButton Library was designed to work in a multi-threaded environment, if that situation were to occur in the Arduino world.
Event Types
The supported events are defined by a list of constants in AceButton
:
AceButton::kEventPressed
(always enabled)AceButton::kEventReleased
(conditionally enabled)AceButton::kEventClicked
(default: disabled)AceButton::kEventDoubleClicked
(default: disabled)AceButton::kEventLongPressed
(default: disabled)AceButton::kEventRepeatPressed
(default: disabled)
These values are sent to the EventHandler
in the eventType
parameter.
Two of the events are enabled by default, four are disabled by default but can be enabled by using a Feature flag described below.
ButtonConfig Feature Flags
There are 9 flags defined in ButtonConfig
which can
control the behavior of AceButton
event handling:
ButtonConfig::kFeatureClick
ButtonConfig::kFeatureDoubleClick
ButtonConfig::kFeatureLongPress
ButtonConfig::kFeatureRepeatPress
ButtonConfig::kFeatureSuppressAfterClick
ButtonConfig::kFeatureSuppressAfterDoubleClick
ButtonConfig::kFeatureSuppressAfterLongPress
ButtonConfig::kFeatureSuppressAfterRepeatPress
ButtonConfig::kFeatureSuppressClickBeforeDoubleClick
ButtonConfig::kFeatureSuppressAll
These constants are used to set or clear the given flag:
ButtonConfig* config = button.getButtonConfig();
config->setFeature(ButtonConfig::kFeatureLongPress);
config->clearFeature(ButtonConfig::kFeatureLongPress);
if (config->isFeature(ButtonConfig::kFeatureLongPress)) {
...
}
The meaning of these flags are described below.
Event Activation
Of the 6 event types, 4 are disabled by default:
AceButton::kEventClicked
AceButton::kEventDoubleClicked
AceButton::kEventLongPressed
AceButton::kEventRepeatPressed
To receive these events, call ButtonConfig::setFeature()
with the following
flags respectively:
ButtonConfig::kFeatureClick
ButtonConfig::kFeatureDoubleClick
ButtonConfig::kFeatureLongPress
ButtonConfig::kFeatureRepeatPress
To disable these events, call ButtonConfig::clearFeature()
with one of these
flags.
Enabling kFeatureDoubleClick
automatically enables kFeatureClick
, because we
need to have a Clicked event before a DoubleClicked event can be detected.
It seems unlikely that both LongPress
and RepeatPress
events would be
useful at the same time, but both event types can be activated if you need it.
Event Suppression
Event types can be considered to be built up in layers, starting with the lowest level primitive events: Pressed and Released. Higher level events are built on top of the lower level events through various timing delays. When a higher level event is detected, it is sometimes useful to suppress the lower level event that was used to detect the higher level event.
For example, a Clicked event requires a Pressed event followed by a Released
event within a ButtonConfig::getClickDelay()
milliseconds (200 ms by
default). The Pressed event is always generated. If a Clicked event is
detected, we could choose to generate both a Released event and a Clicked
event, and this is the default behavior.
However, many times, it is useful to suppress the Released event if the Clicked
event is detected. The ButtonConfig
can be configured to suppress these lower
level events. Call the setFeature(feature)
method passing the various
kFeatureSuppressXxx
constants:
ButtonConfig::kFeatureSuppressAfterClick
- suppresses the Released event after a Clicked event is detected
- also suppresses the Released event from the first Clicked of a
DoubleClicked, since
kFeatureDoubleClick
automatically enableskFeatureClick
ButtonConfig::kFeatureSuppressAfterDoubleClick
- suppresses the Released event and the second Clicked event if a DoubleClicked event is detected
ButtonConfig::kFeatureSuppressAfterLongPress
- suppresses the Released event if a LongPressed event is detected
ButtonConfig::kFeatureSuppressAfterRepeatPress
- suppresses the Released event after the last RepeatPressed event
ButtonConfig::kFeatureSuppressAll
- a convenience parameter that is the equivalent of suppressing all of the previous events
ButtonConfig::kFeatureSuppressClickBeforeDoubleClick
- The first Clicked event is postponed by
getDoubleClickDelay()
millis until the code can determine if a DoubleClick has occurred. If so, then the postponed Clicked message to theEventHandler
is suppressed. - See the section Distinguishing Between a Clicked and DoubleClicked for more info.
- The first Clicked event is postponed by
By default, no suppression is performed.
As an example, to suppress the Released
event after a LongPressed
event
(this is actually often the case), you would do this:
ButtonConfig* config = button.getButtonConfig();
config->setFeature(ButtonConfig::kFeatureSuppressAfterLongPress);
The special convenient constant kFeatureSuppressAll
is equivalent of using all
suppression constants:
ButtonConfig* config = button.getButtonConfig();
config->setFeature(ButtonConfig::kFeatureSuppressAll);
All suppressions can be cleared by using:
ButtonConfig* config = button.getButtonConfig();
config->clearFeature(ButtonConfig::kFeatureSuppressAll);
Note, however, that the isFeature(ButtonConfig::kFeatureSuppressAll)
currently
means "isAnyFeature() implemented?" not "areAllFeatures() implemented?" We don't
expect isFeature()
to be used often (or at all) for kFeatureSuppressAll
.
Distinguishing Between a Clicked and DoubleClicked
On a project using only a small number of buttons (due to physical limits or the limited availability of pins), it may be desirable to distinguish between a single Clicked event and a DoubleClicked event from a single button. This is a challenging problem to solve because fundamentally, a DoubleClicked event must always generate a Clicked event, because a Clicked event must happen before it can become a DoubleClicked event.
Notice that on a desktop computer (running Windows, MacOS or Linux), a double-click on a mouse always generates both a Clicked and a DoubleClicked. The first Click selects the given desktop object (e.g. an icon or a window), and the DoubleClick performs some action on the selected object (e.g. open the icon, or resize the window).
The AceButton Library provides 3 solutions which may work for some projects:
Method 1: The kFeatureSuppressClickBeforeDoubleClick
flag causes the first
Clicked event to be detected, but the posting of the event message (i.e. the
call to the EventHandler
) is postponed until the state of the DoubleClicked
can be determined. If the DoubleClicked happens, then the first Clicked event
message is suppressed. If DoubleClicked does not occur, the long delayed
Clicked message is sent via the EventHandler
.
There are two noticeable disadvantages of this method. First, the response time
of all Clicked events is delayed by about 600 ms (kClickDelay + kDoubleClickDelay
) whether or not the DoubleClicked event happens. Second, the
user may not be able to accurately produce a Clicked event (due to the physical
characteristics of the button, or the user's dexterity).
It may also be worth noting that only the Clicked event is postponed. The accompanying Released event of the Clicked event is not postponed. So a single click action (without a DoubleClick) produces the following sequence of events to the EventHandler:
kEventPressed
- at time 0mskEventReleased
- at time 200mskEventClicked
- at time 600ms (200ms + 400ms)
The ButtonConfig
configuration looks like this:
ButtonConfig* buttonConfig = button.getButtonConfig();
buttonConfig->setFeature(ButtonConfig::kFeatureDoubleClick);
buttonConfig->setFeature(
ButtonConfig::kFeatureSuppressClickBeforeDoubleClick);
See the example code at
examples/ClickVersusDoubleClickUsingSuppression/
.
Method 2: A viable alternative is to use the Released event instead of the Clicked event to distinguish it from the DoubleClicked. For this method to work, we need to suppress the Released event after both Clicked and DoubleClicked.
The advantage of using this method is that there is no response time lag in the handling of the Released event. To the user, there is almost no difference between triggering on the Released event, versus triggering on the Clicked event.
The disadvantage of this method is that the Clicked event must be be ignored (because of the spurious Clicked event generated by the DoubleClicked). If the user accidentally presses and releases the button to quickly, it generates a Clicked event, which will cause the program to do nothing.
The ButtonConfig
configuration looks like this:
ButtonConfig* buttonConfig = button.getButtonConfig();
buttonConfig->setEventHandler(handleEvent);
buttonConfig->setFeature(ButtonConfig::kFeatureDoubleClick);
buttonConfig->setFeature(ButtonConfig::kFeatureSuppressAfterClick);
buttonConfig->setFeature(ButtonConfig::kFeatureSuppressAfterDoubleClick);
See the example code at
examples/ClickVersusDoubleClickUsingReleased/
.
Method 3: We could actually combine both Methods 1 and 2 so that either Released or a delayed Click is considered to be a "Click". This may be the best of both worlds.
The ButtonConfig
configuration looks like this:
ButtonConfig* buttonConfig = button.getButtonConfig();
buttonConfig->setEventHandler(handleEvent);
buttonConfig->setFeature(ButtonConfig::kFeatureDoubleClick);
buttonConfig->setFeature(
ButtonConfig::kFeatureSuppressClickBeforeDoubleClick);
buttonConfig->setFeature(ButtonConfig::kFeatureSuppressAfterClick);
buttonConfig->setFeature(ButtonConfig::kFeatureSuppressAfterDoubleClick);
See the example code at
examples/ClickVersusDoubleClickUsingBoth/
.
Single Button Simplifications
Although the AceButton library is designed to shine for multiple buttons, you may want to use it to handle just one button. The library provides some features to make this simple case easy.
- The library automatically creates one instance of
ButtonConfig
called a "System ButtonConfig". This System ButtonConfig can be retrieved using the class static methodButtonConfig::getSystemButtonConfig()
. - Every instance of
AceButton
is assigned an instance of the System ButtonConfig by default (which can be overridden manually). - A convenience method allows the
EventHandler
for the System ButtonConfig to be set easily throughAceButton
itself, instead of having to get the System ButtonConfig first, then set the event handler. In other words,button.setEventHandler(handleEvent)
is a synonym forbutton.getButtonConfig()->setEventHandler(handleEvent)
.
These simplifying features allow a single button to be configured and used like this:
AceButton button(BUTTON_PIN);
void setup() {
pinMode(BUTTON_PIN, INPUT_PULLUP);
button.setEventHandler(handleEvent);
...
}
void loop() {
button.check();
}
void handleEvent(AceButton* button, uint8_t eventType, uint8_t buttonState) {
...
}
To configure the System ButtonConfig, you may need to add something like
this to the setup()
section:
button.getButtonConfig()->setFeature(ButtonConfig::kFeatureLongPress);
Multiple Buttons
When transitioning from a single button to multiple buttons, it's important to
remember what's happening underneath the convenience methods. The single
AceButton
button is assigned to the System ButtonConfig that was created
automatically. When an EventHandler
is assigned to the button, it is actually
assigned to the System ButtonConfig. All subsequent instances of AceButton
will also be associated with this event handler, unless another ButtonConfig
is explicitly assigned.
See the example sketch TunerButtons.ino
to see how to use multiple
ButtonConfig
instances with multiple AceButton
instances.
Events After Reboot
A number of edge cases occur when the microcontroller is rebooted:
- if the button is held down, should the Pressed event be triggered?
- if the button is in its natural Released state, should the Released event happen?
- if the button is Pressed down, and
ButtonConfig
is configured to support RepeatPress events, should thekEventRepeatPressed
events be triggered initially?
I think most users would expect that in all these cases, the answer is no, the
microcontroller should not trigger an event until the button undergoes a
human-initiated change in state. The AceButton library implements this logic.
(It might be useful to make this configurable using a ButtonConfig
feature
flag but that is not implemented.)
On the other hand, it is sometimes useful to perform some special action if a
button is pressed while the device is rebooted. To support this use-case, call
the AceButton::isPressedRaw()
in the global setup()
method (after the
button is configured). It will directly call the digitalRead()
method
associated with the button pin and return true
if the button is in the
Pressed state.
Orphaned Clicks
When a Clicked event is generated, the AceButton
class looks for a
second Clicked event within a certain time delay (default 400 ms) to
determine if the second Clicked event is actually a DoubleClicked event.
All internal timestamps in AceButton
are stored as uint16_t
(i.e. an unsigned integer of 16 bits) in millisecond units. A 16-bit
unsigned counter rolls over after 65536 iterations. Therefore, if the second
Clicked event happens between (65.636 seconds, 66.036 seconds) after the first
Clicked event, a naive-logic would erroneously consider the (long-delayed)
second click as a double-click.
The AceButton
contains code that prevents this from happening.
Note that even if the AceButton
class uses an unsigned long
type (a 32-bit
integer on the Arduino), the overflow problem would still occur after 2^32
milliseconds (i.e. 49.7 days). To be strictly correct, the AceButton
class
would still need logic to take care of orphaned Clicked events.
Resource Consumption
Here are the sizes of the various classes on the 8-bit AVR microcontrollers (Arduino Uno, Nano, etc):
- sizeof(AceButton): 14
- sizeof(ButtonConfig): 20
(An early version of AceButton
, with only half of the functionality, consumed
40 bytes. It got down to 11 bytes before additional functionality increased it
to 14.)
Program size:
LibrarySizeBenchmark was used to determine the size of the library. For a single button, the library consumed:
- flash memory: 1100-1330 bytes
- static memory: 14-28 bytes
depending on the target board. See the README.md in the above link for more details.
CPU cycles:
The profiling numbers for AceButton::check()
can be found in
examples/AutoBenchmark.
In summary, the average numbers for various boards are:
- Arduino Nano: 13-15 microsesconds
- Teensy 3.2: 3 microseconds
- ESP8266: 8-9 microseconds
- ESP32: 2-3 microseconds
System Requirements
This library was developed and tested using:
I used MacOS 10.13.3 and Ubuntu Linux 17.10 for most of my development.
The library has been verified to work on the following hardware:
- Arduino Nano clone (16 MHz ATmega328P)
- Arduino UNO R3 clone (16 MHz ATmega328P)
- Arduino Pro Micro clone (16 MHz ATmega32U4)
- Teensy LC (48 MHz ARM Cortex-M0+)
- Teensy 3.2 (72 MHz ARM Cortex-M4)
- NodeMCU 1.0 clone (ESP-12E module, 80MHz ESP8266)
- ESP32 Dev Module (ESP-WROOM-32 module, 240MHz dual core Tensilica LX6)
Background Motivation
There are numerous "button" libraries out there for the Arduino. Why write another one? I wanted to add a button to an addressable strip LED controller, which was being refreshed at 120 Hz. I had a number of requirements:
- the button needed to support a LongPress event, in addition to the simple Press and Release events
- the button code must not interfere with the LED refresh code which was updating the LEDs at 120 Hz
- well-tested, I didn't want to be hunting down random and obscure bugs
Since the LED refresh code needed to run while the button code was waiting for a "LongPress" delay, it seemed that the cleanest API for a button library would use an event handler callback mechanism. This reduced the number of candidate libraries to a handful. Of these, only a few of them supported a LongPress event. I did not find the remaining ones flexible enough for my button needs in the future. Finally, I knew that it was tricky to write correct code for debouncing and detecting various events (e.g. DoubleClick, LongPress, RepeatPress). I looked for a library that contained unit tests, and I found none.
I decided to write my own and use the opportunity to learn how to create and publish an Arduino library.
Changelog
See CHANGELOG.md.
License
- Versions 1.0 to 1.0.6: Apache License 2.0
- Versions 1.1 and above: MIT License
I changed to the MIT License starting with version 1.1 because the MIT License is so simple to understand. I could not be sure that I understood what the Apache License 2.0 meant.
Feedback and Support
If you have any questions, comments, bug reports, or feature requests, please file a GitHub ticket or send me an email. I'd love to hear about how this software and its documentation can be improved. Instead of forking the repository to modify or add a feature for your own projects, let me have a chance to incorporate the change into the main repository so that your external dependencies are simpler and so that others can benefit. I can't promise that I will incorporate everything, but I will give your ideas serious consideration.
Author
Created by Brian T. Park (brian@xparks.net).