Bounce Library

Bounce, written by Thomas Ouellet Fredericks, makes it easy to reliably read pushbuttons or mechanical sensors which have contacts that "chatter" or "bounce".

Download:

Included with the Teensyduino Installer
Latest Developments on Github

Hardware Requirements

Normally pushbuttons connect between a pin and ground, and the pin mode is set to INPUT_PULLUP. Any pin can be used, except those with LEDs.

Basic Usage

Bounce myButton = Bounce(pin, milliseconds);

Create a Bounce object called myButton, using "pin" and waiting for bouncing to end within "milliseconds" time. You may create multiple Bounce objects, for as many different pins as necessary.

myButton.update();

Read the button and update its status. This update() function must be called regularly, so input on the pin is properly recognized. Return is true if the input changes, or false otherwise.

myButton.fallingEdge();

Check for a high to low transition. For a pushbutton connected between the pin and ground, this corresponds to the button being pressed.

myButton.risingEdge();

Check for a low to high transition. For a pushbutton connected between the pin and ground, this corresponds to the button being released.

Other functions are available, as documented on the Arduino Bounce page.

Example With Contact Bouncing

This example does NOT use the Bounce library. You can use this code to test if your hardware has mechanical bounce.

It reads a pin as rapidly as possible. Each time the pin transitions from high to low, a count variable in incremented. The count is only printed 0.1 second after activity stops, to avoid any delay caused by Serial.print() from interfering with reading the pin quickly.

const int buttonPin = 12;

void setup() {
  pinMode(buttonPin, INPUT_PULLUP);
  Serial.begin(57600);
  Serial.println("Pushbutton bounce test:");
}

byte previousState = HIGH;         // what state was the button last time
unsigned int count = 0;            // how many times has it changed to low
unsigned long countAt = 0;         // when count changed
unsigned int countPrinted = 0;     // last count printed

void loop() {
  byte buttonState = digitalRead(buttonPin);
  if (buttonState != previousState) {
    if (buttonState == LOW) {
      count = count + 1;
      countAt = millis();
    }
    previousState = buttonState;
  } else {
    if (count != countPrinted) {
      unsigned long nowMillis = millis();
      if (nowMillis - countAt > 100) {
        Serial.print("count: ");
        Serial.println(count);
        countPrinted = count;
      }
    }
  }
}

As you can see, sometimes the count increases by more than 1. Some of the count increases in this example occured while releasing the button. The Bounce library solves these problems.

Without Bounce Library: Some Button Presses Cause Several Counts

Example Using Bounce Library

This example uses the Bounce library to read the pin, but otherwise has the same structure as the example above.

#include <Bounce.h>

const int buttonPin = 12;
Bounce pushbutton = Bounce(buttonPin, 10);  // 10 ms debounce

void setup() {
  pinMode(buttonPin, INPUT_PULLUP);
  Serial.begin(57600);
  Serial.println("Pushbutton Bounce library test:");
}

byte previousState = HIGH;         // what state was the button last time
unsigned int count = 0;            // how many times has it changed to low
unsigned long countAt = 0;         // when count changed
unsigned int countPrinted = 0;     // last count printed

void loop() {
  if (pushbutton.update()) {
    if (pushbutton.fallingEdge()) {
      count = count + 1;
      countAt = millis();
    }
  } else {
    if (count != countPrinted) {
      unsigned long nowMillis = millis();
      if (nowMillis - countAt > 100) {
        Serial.print("count: ");
        Serial.println(count);
        countPrinted = count;
      }
    }
  }
}

Because the Bounce library handles the mechanical bounce properly, the count increases exactly once for each button press. False counts during button release are also avoided.

With Bounce Library, Each Button Press Increments Count Once

Using Delays

Often instead of the Bounce library, a simple delay is used after reading a mechanical switch or pushbutton. In other programs, the (unintentional) delay from Serial.print() or other functions may be enough to eliminiate bouncing problems without the Bounce library.

Actual Bounce Waveforms

The board shown above uses 5 quality pushbuttons, which have very little mechanical chatter. In this waveform, the bouncing action ends within 10 µs.

Pushbutton on board shown above

TODO: measure a liquid-based tilt switch...

Links

Arduino Bounce Library page has more details to use Bounce.

This Contact Chatter Article has much more detail, mostly regarding relays, but the concepts are the same.