ButtonStates Arduino Library

The ButtonStates library provides a simple interface for detecting and debouncing button presses on Arduino boards. It can distinguish between single, double, and long clicks, and also maintains internal counters for each type of click event.

Features

• Debouncing: Uses a bitwise history register to filter out mechanical bouncing.
• Single Click Detection: Identifies stable presses.
• Double Click Detection: Recognizes a second press within a configurable time window.
• Long Click Detection: Determines when a button has been held down for a specified duration.
• Threshold Configuration: Allows adjusting the time thresholds for double-click and long-click recognition at runtime.
• Flip-Flop Support: Maintains a flipflop variable toggled on single clicks, useful for toggling LEDs or other stateful logic.

Installation

1. Download or Clone:

   • Download the repository as a ZIP from GitHub or clone it:

     git clone https://github.com/yourusername/ButtonStates.git

2. Move to Arduino Libraries Folder:

   • Extract or copy the ButtonStates folder into your Arduino libraries directory:
     • Windows: Documents\Arduino\libraries
     • macOS: Documents/Arduino/libraries
     • Linux: Documents/Arduino/libraries

3. Restart the Arduino IDE:

   • After installation, restart the Arduino IDE so it recognizes the new library.

Usage

1. Include the Library:

   #include <ButtonStates.h>

2. Create a ButtonStates Instance: Provide the pin number connected to the button (with an internal pull-up):

ButtonStates button(2); // Button on pin 2

3. Setup: In your setup() function, optionally set the time thresholds:

void setup() {
  Serial.begin(9600);
  // Optional: set double-click and long-click thresholds (in ms)
  button.setThresholds(300, 300); // double click at 300ms, long click at 300ms
}

4. Loop: In loop(), call one of the trigger methods based on your needs:

triggerSingle() detects only single clicks. triggerDouble() detects single and double clicks. triggerLong() detects single, double, and long clicks.

Example using triggerLong():

void loop() {
  uint8_t clickType = button.triggerLong();

  switch (clickType) {
    case SINGLECLICK:
      Serial.println("Single Click Detected");
      break;
    case DOUBLECLICK:
      Serial.println("Double Click Detected");
      break;
    case LONGCLICK:
      Serial.println("Long Click Detected");
      break;
    default:
      // NOCLICK means no event detected this iteration
      break;
  }

  // Access counters and flipflop state:
  // button.singleClicks, button.doubleClicks, button.longClicks
  // button.flipflop
}

API Reference

• Constructor:

ButtonStates(int pin);

Initializes the button state machine on the given pin (configured as INPUT_PULLUP).

• Thresholds:

void setThresholds(uint16_t doubleClick, uint16_t longClick);

Sets the maximum gap (ms) for a double-click and the minimum press duration (ms) for a long click.

• Trigger Methods:

uint8_t triggerSingle(); // Returns SINGLECLICK or NOCLICK
uint8_t triggerDouble(); // Returns SINGLECLICK, DOUBLECLICK, or NOCLICK
uint8_t triggerLong();   // Returns SINGLECLICK, DOUBLECLICK, LONGCLICK, or NOCLICK

• Return values:

  • NOCLICK (0)
  • SINGLECLICK (1)
  • DOUBLECLICK (2)
  • LONGCLICK (3)

• Flip-Flop:

void fliptheflop();

Toggles flipflop (0 or 1). Some trigger methods already toggle flipflop on single clicks.

• Counters:

uint8_t singleClicks;
uint8_t doubleClicks;
uint8_t longClicks;

Keep track of how many times each event has occurred.

• Flip-Flop State:

uint8_t flipflop;

Indicates the current state (HIGH or LOW), toggled on certain events.

• Example

Full Example Sketch:

#include <Arduino.h>
#include <ButtonStates.h>

ButtonStates button(2);

void setup() {
  Serial.begin(9600);
  button.setThresholds(300, 500); // Double-click within 300ms, long-click after 500ms
}

void loop() {
  uint8_t event = button.triggerLong();

  if (event == SINGLECLICK) {
    Serial.println("Single click!");
  } else if (event == DOUBLECLICK) {
    Serial.println("Double click!");
  } else if (event == LONGCLICK) {
    Serial.println("Long click!");
  }

  // Use flipflop to toggle a built-in LED on pin 13
  digitalWrite(13, button.flipflop ? HIGH : LOW);
}

License

This project is released under the MIT License. See LICENSE for details.

Contributing

Contributions are welcome! Please open issues or submit pull requests on GitHub.