Back to Switch Debouncing Presentation

DeBounce Library Documentation

The switch DeBounce library provides a simple C++ class for handling switches using the state machine derived in the switch debouncing presentation here.  Like all Arduino libraries, the files must be put in a folder under the /path/to/arduino/installation/Libraries folder.  So, download and extract the three files from the .zip file into a folder named DeBounce under Libraries.

DeBounce::init

The first member function is:
void DeBounce::init(unsigned char pin, unsigned char level, unsigned long duration)

• pin is the Arduino pin that the switch is attached to.  I typically define my pin assignments like this:
  const uint8_t SW1_PIN = 2;
• level is either HIGH or LOW, depending on if you have the pin pulled up or down.  If you want to use internal pullup, you will have to edit the DeBounce.cpp file and change INPUT to INPUT_PULLUP.  It is the level read from the pin when the switch is not being pushed.  We call this “red” level.  When the switch is pressed, the pin reads at the “green” level.
• duration is the number of microseconds that the signal remains at level after the switch is released.  I typically use 4000 for push buttons being pressed by humans.

So, something like this:

#include "DeBounce.h"
DeBounce myswitch;
const unsigned char SW1_PIN = 2;
const unsigned long DURATION = 4000;
void setup()
{
     myswitch.init(SW1_PIN, LOW, DURATION);
}

DeBounce::handleInput

The next member function is:
unsigned char DeBounce::handleInput()
This is the member function that you use in the loop() routine to poll the switch.  It will return a value that indicates where in the state machine the switch software is.  There are no parameters to this function.  I typically put this call into a switch statement so that I can handle the various return values.  This must be called “frequently”, which means more than twice during the settle duration specified with the third parameter of the init() call.  Better would be thousands of times during the settle duration.  The code in handleInput() is very thin for the common case of the switch being up or down.  It does more work on transitions and bounces.

switch(myswitch.handleInput())
{
   case DeBounce_UP:
   break;
. . .
   case DeBounce_PRESS:
   break;
}

The state machine

• STATE_IDLE
  • switch is level – return DeBounce_UP and go to STATE_IDLE
  • switch is !level – return DeBounce_FIRST_RISING and go to STATE_GREEN
• STATE_GREEN
  • switch is level – return DeBounce_FALLING and go to STATE_RED
  • switch is !level – return DeBounce_DOWN and stay in STATE_GREEN
• STATE_RED
  • switch is level and we have been in this state for <= duration – return DeBounce_UP and stay in STATE_RED
  • switch is level and we have been in this state for > duration – return DeBounce_PRESS and go to STATE_IDLE
  • switch is !level – return DeBounce_RISING and go to STATE_GREEN

 The return values

• DeBounce_UP – the switch is up.  This is the most common case and is not interesting.
• DeBounce_DOWN – the switch is down.  This is the second most common case and is not interesting.
• DeBounce_FIRST_RISING – the switch just went down.  This is the most important return value.  It indicates that the user has pushed the button down.  You should immediately acknowledge this fact by turning on an LED or beeping.
• DeBounce_FALLING – the switch just went up (or bounced up).  This is not interesting
• DeBounce_RISING – the switch bounced.  This is not interesting.
• DeBounce_PRESS – the switch has been released and things have settled.  This is not when you should take action.  You can turn off the LED that you turned on at DeBounce_FIRST_RISING

DeBounce::getDuration

The last member function is:
unsigned long DeBounce::getDuration()
This is used to query how long the button has been or was pushed down.  You can call this function when you get DeBounce_PRESS  to see how many microseconds elapsed between DeBounce_FIRST_RISING and the last DeBounce_FALLING (i.e. how long the switch was down).  If you call this function after DeBounce_FIRST_RISING  but before DeBounce_PRESS, you will get the length of time the switch has been down.