AceButton Documentation

AceButton is an adjustable, compact, and event-driven button library designed for Arduino platforms. It handles mechanical button inputs (momentary, maintained, or switches) and provides debouncing logic.

Key features include:

• Event-driven architecture: Uses EventHandler callbacks or the IEventHandler interface to respond to button state changes.
• Multiple event types: Supports events like kEventPressed, kEventReleased, kEventClicked, kEventDoubleClicked, kEventLongPressed, kEventRepeatPressed, kEventLongReleased, and kEventHeartBeat.
• Low resource usage: Optimized for minimal static memory and CPU cycles.
• Flexible hardware support: Supports standard digital pins, Binary Encoded buttons (multiple buttons on few pins), and Resistor Ladder buttons (multiple buttons on one analog pin).

Binary encoding allows you to support $2^N - 1$ buttons using only $N$ pins. This is useful when you have a limited number of microcontroller pins.

Key constraints:

• No simultaneous presses: You cannot detect multiple buttons being pressed at the same time using this method.
• Hardware implementation: The software is agnostic to how you implement the encoding (diodes, logic gates, or integrated circuits like the 74LS148), but the hardware must pull the pins LOW when a button is pressed.
• Pull-up resistors: You must configure the pins using pinMode(PIN, INPUT_PULLUP).

This is the recommended wiring method. Each button has its own dedicated resistor connected in parallel with a pull-up resistor ($Rp$).

Characteristics:

• Pros:
  • Simple Calculation: The voltage ratio is simply $V(i)/V_{cc} = R_p / (R(i) + R_p)$.
  • Isolation: Replacing or changing one resistor only affects that specific button's voltage level, not the others.
  • Power Efficient: No current flows when no buttons are pressed, making it ideal for battery-powered devices.
  • Scalable: Requires $N+1$ resistors for $N$ buttons.
• Safety: Use a small resistor (e.g., 220 $\Omega$ or 330 $\Omega$) as $R0$ to limit current in case of mis-wiring.

// Voltage ratio formula for Circuit 3:
V(i)/Vcc = Rp / (R(i) + Rp)

The library separates button logic from configuration using two main classes:

1. AceButton: Handles debouncing, event detection (Pressed, Clicked, etc.), and maintains the state for a specific physical button.
2. ButtonConfig: Stores timing parameters (debounce delay, click delay, etc.) and provides hooks for hardware dependencies (getClock() and readButton()).

This separation allows multiple AceButton instances to share a single ButtonConfig (e.g., a group of buttons with identical timing requirements), saving memory.

const uint8_t PIN1 = 2;
const uint8_t PIN2 = 4;

ButtonConfig buttonConfig;
AceButton button1(&buttonConfig, PIN1);
AceButton button2(&buttonConfig, PIN2);

To support a large number of buttons using only a few pins, you can use Binary Encoding (e.g., with a 74LS148 chip or diodes). AceButton provides specialized ButtonConfig subclasses for this:

• Encoded4To2ButtonConfig: 3 buttons using 2 pins.
• Encoded8To3ButtonConfig: 7 buttons using 3 pins.
• EncodedButtonConfig: $M = 2^N - 1$ buttons using $N$ pins.

Refer to docs/binary_encoding/README.md for implementation details.

Benchmark results are reported in microseconds. The samples column indicates the number of TimingStats::update() calls performed during the test.

Scenarios measured include:

• idle: One AceButton::check() call with no events.
• press/release: One AceButton::check() call with Press and Release events.
• click: One AceButton::check() call with a Click event.
• double_click: One AceButton::check() call with a DoubleClick event.
• long_press/repeat_press: One AceButton::check() call with LongPress and RepeatPress events.
• Configuration-specific benchmarks: Various ButtonConfig types (e.g., ButtonConfigFast1, Encoded4To2ButtonConfig, LadderButtonConfig) are tested to show their specific overhead.

AceButton supports reading multiple buttons through a reduced number of pins using binary encoding. This is achieved through specific configuration classes that decode the pin states into button events.

Available configuration classes:

• Encoded4To2ButtonConfig: Decodes $M$ buttons using $N$ pins (e.g., 3 buttons using 2 pins).
• Encoded8To3ButtonConfig: Decodes $M$ buttons using $N$ pins (e.g., 7 buttons using 3 pins).
• EncodedButtonConfig: A general M-to-N class for arbitrary configurations (e.g., 15 buttons using 4 pins).