|
| 1 | +# Pushbutton library for Arduino |
| 2 | + |
| 3 | +Version: 1.1.0<br/> |
| 4 | +Release date: 2014-12-01<br/> |
| 5 | +[www.pololu.com](http://www.pololu.com/) |
| 6 | + |
| 7 | +## Summary |
| 8 | + |
| 9 | +This is a library for the Arduino IDE that helps interface with pushbuttons by either reading the state of the button or monitoring it for press/release events. |
| 10 | + |
| 11 | +## Supported platforms |
| 12 | + |
| 13 | +This library is designed to work with the Arduino IDE versions 1.0.x and 1.5.x, and will probably not work with older versions. |
| 14 | + |
| 15 | +This library supports any Arduino-compatible board. |
| 16 | + |
| 17 | +## Getting started |
| 18 | + |
| 19 | +### Hardware |
| 20 | + |
| 21 | +This library supports many different ways of connecting a button to your board. The simplest way is to select a pin that is not being used for anything else and to connect a [normally-open momentary pushbutton](http://www.pololu.com/product/1400) from that pin to ground. |
| 22 | + |
| 23 | +### Software |
| 24 | + |
| 25 | +Download the [pushbutton-arduino library from github](http://pololu.github.io/), decompress it, and drag the "Pushbutton" folder into the "libraries" subdirectory inside your Arduino sketchbook directory. You can view your sketchbook location by selecting File->Preferences in the Arduino environment; if there is not already a "libraries" folder in that location, you should create it yourself. After installing the library, restart the Arduino environment. Example code for using this library can be found in the File->Examples menu. |
| 26 | + |
| 27 | +## Creating a Pushbutton object |
| 28 | + |
| 29 | +To create a Pushbutton object with default settings, which enables the internal pull-up on the pin and interprets a high pin value as the default (unpressed) state of the button, put this line near the top of your sketch: |
| 30 | + |
| 31 | +~~~{.cpp} |
| 32 | +Pushbutton button(BUTTON_PIN); |
| 33 | +~~~ |
| 34 | + |
| 35 | +Optional arguments can be passed to the constructor to specify other button types and connection methods; see the documentation links below for details. |
| 36 | + |
| 37 | +## Reading the state of the button |
| 38 | + |
| 39 | +The `isPressed()` function can be used to directly read the state of the button. This function simply calls `digitalRead` to get the current state of the button and does not take care of any debouncing. |
| 40 | + |
| 41 | +~~~{.cpp} |
| 42 | +if (button.isPressed()) |
| 43 | +{ |
| 44 | + // The button is currently pressed. |
| 45 | +} |
| 46 | +~~~ |
| 47 | + |
| 48 | +## Waiting for an event |
| 49 | + |
| 50 | +The Pushbutton class has several functions that wait for an event on the button. These functions take care of debouncing for you. |
| 51 | + |
| 52 | +The `waitForPress()` function waits until the button is pressed. The `waitForRelease()` function waits until the button is released. |
| 53 | + |
| 54 | +Note that if the button is already pressed when `waitForPress()` is called, it will return quickly (in 10 ms). If you want to perform an action when the user presses the button but want to avoid performing the action multiple times while the user holds the button down, you will need to call `waitForRelease()`: |
| 55 | + |
| 56 | +~~~{.cpp} |
| 57 | +void loop() { |
| 58 | + button.waitForPress(); |
| 59 | + // Perform action here. |
| 60 | + button.waitForRelease(); |
| 61 | +} |
| 62 | +~~~ |
| 63 | + |
| 64 | +The `waitForButton()` function waits until the button is pressed, and then waits until the button is released. This function could be used like this: |
| 65 | + |
| 66 | +~~~{.cpp} |
| 67 | +void loop() { |
| 68 | + button.waitForButton(); |
| 69 | + // Perform action here. |
| 70 | +} |
| 71 | +~~~ |
| 72 | + |
| 73 | +These functions wait for an event to happen before returning, so your board cannot do much else while it is waiting. They are appropriate for simple programs where a button press is the only event you need to respond to in the main loop. |
| 74 | + |
| 75 | +## Monitoring for an event |
| 76 | + |
| 77 | +The Pushbutton class provides two non-blocking that allow you to monitor the button for transitions. These functions are powerful and can be used in almost any situation. |
| 78 | + |
| 79 | +The `getSingleDebouncedButtonPress()` function will return true once for each time it detects the button changing from the released state to the pressed state. The `getSingleDebouncedButtonRelease()` function will return true once for each time it detects the button changing from the pressed state to the released state. |
| 80 | + |
| 81 | +These functions are non-blocking and are meant to be called repeatedly in a loop: |
| 82 | + |
| 83 | +~~~{.cpp} |
| 84 | +void loop() { |
| 85 | + if (button.getSingleDebouncedButtonPress()) |
| 86 | + { |
| 87 | + // The button was pressed, so perform some action. |
| 88 | + } |
| 89 | + // Perform other tasks |
| 90 | +} |
| 91 | +~~~ |
| 92 | + |
| 93 | +## Documentation |
| 94 | + |
| 95 | +For complete documentation of this library, including many features that were not mentioned here, see [the Pushbutton.h file documentation](https://pololu.github.io/pushbutton-arduino/_pushbutton_8h.html) from https://pololu.github.io/fastgpio-arduino. |
| 96 | + |
| 97 | +## Version history |
| 98 | + |
| 99 | +* 1.1.0 (2014 Dec 01): |
| 100 | +** Added the PushbuttonBase class, which allows custom pushbutton classes with their own unique ways of reading the state of the button. |
| 101 | +** Fixed a problem in the logic for getSingleDebouncedPress(). |
| 102 | +** Added the PushbuttonStateMachine class to reduce code duplication. |
| 103 | +** Moved the library to its own repository at https://github.com/pololu/pushbutton-arduino. |
| 104 | +* 1.0.1 (2014 Jan 22): Fixed it to work properly with multiple instances. Improved the debouncing logic and reduced the width of PrevTimeMillis variables. This release was from commit pololu/zumo-shield@8c4e8f5. |
| 105 | +* 1.0.0 (2012 Nov 09): Original release. At this time, the Pushbutton library lived in https://github.com/pololu/zumo-shield and this release was from commit pololu/zumo-shield@a02cf00. |
0 commit comments