Button Driver

Overview

The Button class provides a flexible interface for managing physical buttons on the TM4C1294XL LaunchPad. It supports debounce filtering, single and double clicks, long presses, and user-defined callbacks for each type of event.

This driver simplifies working with input switches by abstracting GPIO configuration, debounce logic, and timing-based event detection.

Compatible with TivaWare Supports OneButton-style API

---

Features

• Debounce filtering (configurable in milliseconds)
• Single, double, and multi-click detection
• Long press detection (start, during, and stop events)
• Callback registration for all major events
• Automatic GPIO configuration based on Energia pins.h
• Pull-up or pull-down selection
• Flag-based methods (wasPressed(), wasReleased(), isPressed(), etc.)
• Lightweight FSM-based implementation for polling or interrupt-driven systems

---

How to use the Library

You can use the Button driver in two main ways: basic polling or advanced callback registration.

Basic Polling

This example shows how to create a Button object for the user button (S1) on the TM4C1294XL LaunchPad and check its state in the main loop.

How it works

When the button is pressed, the wasPressed() method returns true once, allowing you to execute code in response to the event.

#include "button.h"

Button btn(S1); // Initialize with default debounce and pull-up

int main(void) {
    uint32_t gSystemClock = SysCtlClockFreqSet(
        SYSCTL_XTAL_25MHZ | SYSCTL_OSC_MAIN | SYSCTL_USE_PLL | SYSCTL_CFG_VCO_480,
        120000000);

    btn.begin();
    btn.setDebounceMs(50); // Optional: set debounce time to 50 ms
    btn.setClickMs(100);  // Optional: set click window to 100 ms

    while (1) {
        btn.tick(); // Call periodically
        if (btn.wasPressed()) {
            // Do something when pressed
        }
    }
}

Advanced Callbacks Registration

The Button class allows you to register callback functions for various button events. Below is an example demonstrating how to set up callbacks for press, click, double-click, long press start, and long press stop events.

How it works

When the button state changes, the corresponding callback function is invoked automatically. This allows you to separate event handling logic from the main loop.

#include "button.h"

Button btn(S1); // Initialize with default debounce and pull-up

// Callback functions

static void onClick() {
    // Code to execute on single click
}

static void onDoubleClick() {
    // Code to execute on double click
}

static void onLongPressStart() {
    // Code to execute when long press starts
}

static void onLongPressStop() {
    // Code to execute when long press stops
}

int main(void) {
    uint32_t gSystemClock = SysCtlClockFreqSet(
        SYSCTL_XTAL_25MHZ | SYSCTL_OSC_MAIN | SYSCTL_USE_PLL | SYSCTL_CFG_VCO_480,
        120000000);

    btn.begin();
    btn.setDebounceMs(50); // Optional: set debounce time to 50 ms
    btn.setClickMs(100);  // Optional: set click window to 100 ms

    // Register callbacks
    btn.attachClick(&onClick);
    btn.attachDoubleClick(&onDoubleClick);
    btn.attachPress(&onLongPressStart);
    btn.attachRelease(&onLongPressStop);

    while (1) {
        btn.tick(); // Call periodically
    }
}

API Summary

Constructors

Button(uint8_t pin);

Creates a button object and sets up timing thresholds in logical ticks (~20 ms each).

Configuration

Method	Description
void begin()	Initializes GPIO and pad configuration.
void setPull(ButtonPull pull)	Reconfigure internal pull-up or pull-down.
void setDebounceMs(int ms)	Set debounce time.
void setClickMs(unsigned int ms)	Time window for distinguishing single/double clicks.
void setPressMs(unsigned int ms)	Threshold for long press detection.
void setLongPressIntervalMs(unsigned int ms)	Interval for continuous long-press callbacks.

State Queries

Method	Description
bool wasPressed()	Returns true once when pressed, resets flag.
bool wasReleased()	Returns true once when released, resets flag.
bool isPressed()	Returns current physical level.
bool isDoubleClicked()	Returns true if a double-click occurred since last query.
unsigned int getHoldTime()	Duration in ms the button was last held down.

Callback Attachments

Event	Methods
Click	attachClick(fn)
Double Click	attachDoubleClick(fn)
Long Press Start	attachLongPressStart(fn)
Long Press Stop	attachLongPressStop(fn)
During Long Press	attachDuringLongPress(fn)
Idle	attachIdle(fn)

Integration Notes

• Call tick() every 10–20 ms in your main loop or a timer interrupt.
• Always call begin() after system clock initialization.
• Adjust debounce and click thresholds to match hardware bounce characteristics.
• The driver can be used with polling, GPIO interrupts, or timer ISRs.

---

Dependencies

• driverlib/gpio.h
• driverlib/sysctl.h

---

Example projects

You can find a complete example project implementing this functionality

Button with audio feedback Example code for generating tones with PWM on the TM4C1294XL LaunchPad when pressing and releasing buttons.

Button Blink Machine Example code for blinking an LED in response to button presses.

Summary

License and Credits

Developed for educational use in ECE3849 — Real-Time Embedded Systems. Inspired by the Arduino OneButton library, adapted for TivaWare with performance and structure improvements.

Author: Edwin R. Version 1.0