├── README.md ├── examples ├── 01.SingleButton │ └── 01.SingleButton.ino ├── 02.SingleButtonEvents │ └── 02.SingleButtonEvents.ino ├── 03.SingleButtonDebounce │ └── 03.SingleButtonDebounce.ino ├── 04.SingleButtonAll │ └── 04.SingleButtonAll.ino ├── 05.MultipleButtonAll │ └── 05.MultipleButtonAll.ino ├── 06.ButtonCount │ └── 06.ButtonCount.ino └── 07.ButtonArray │ └── 07.ButtonArray.ino ├── keywords.txt ├── library.properties └── src ├── ezButton.cpp └── ezButton.h /README.md: -------------------------------------------------------------------------------- 1 | ## ezButton Library for Arduino, ESP32, ESP8266... 2 | This library is designed to make it easy to use push button, momentary switches, toggle switch, magnetic contact switch (door sensor)..​. It is easy to use for not only beginners but also experienced users. 3 | 4 | __ezButton__ stands for __Easy Button__ 5 | 6 | Features 7 | ---------------------------- 8 | * Uses the internal pull-up resistor by default to avoid the floating value 9 | * Supports debounce to eliminate the chattering phenomenon 10 | * Supports the pressed and released events 11 | * Supports the counting (for FALLING, RISING and BOTH) 12 | * Easy to use with multiple buttons 13 | * All functions are non-blocking 14 | * Support internal pull-up/pull-down, external pull-up/pull-down 15 | 16 | Available Examples 17 | ---------------------------- 18 | * [01.SingleButton](https://arduinogetstarted.com/library/button/example/arduino-single-button) 19 | * [02.SingleButtonEvents](https://arduinogetstarted.com/library/button/example/arduino-single-button-events) 20 | * [03.SingleButtonDebounce](https://arduinogetstarted.com/library/button/example/arduino-single-button-debounce) 21 | * [04.SingleButtonAll](https://arduinogetstarted.com/library/button/example/arduino-single-button-all) 22 | * [05.MultipleButtonAll](https://arduinogetstarted.com/library/button/example/arduino-multiple-button-all) 23 | * [06.ButtonCount](https://arduinogetstarted.com/library/button/example/arduino-button-count) 24 | * [07.ButtonArray](https://arduinogetstarted.com/library/button/example/arduino-button-array) 25 | 26 | 27 | Available Functions 28 | ---------------------------- 29 | * setDebounceTime() 30 | * getState() 31 | * getStateRaw() 32 | * isPressed() 33 | * isReleased() 34 | * setCountMode() 35 | * getCount() 36 | * resetCount() 37 | * loop() 38 | 39 | References 40 | ---------------------------- 41 | * [ezButton Library Reference](https://arduinogetstarted.com/tutorials/arduino-button-library) 42 | 43 | NOTE: 44 | ---------------------------- 45 | * If you are using the [button module](https://www.amazon.com/dp/B0DQ3WM7K1), set the pin to input mode with external pull-down resistor using `ezButton button(pin, EXTERNAL_PULLDOWN)`. In this configuration, the module outputs **LOW** when the button is not pressed and **HIGH** when the button is pressed. 46 | -------------------------------------------------------------------------------- /examples/01.SingleButton/01.SingleButton.ino: -------------------------------------------------------------------------------- 1 | /* 2 | * Created by ArduinoGetStarted.com 3 | * 4 | * This example code is in the public domain 5 | * 6 | * Tutorial page: https://arduinogetstarted.com/tutorials/arduino-button-library 7 | * 8 | * This example reads the state of a button without debounce and print it to Serial Monitor. 9 | */ 10 | 11 | #include 12 | 13 | ezButton button(7); // create ezButton object that attach to pin 7; 14 | 15 | void setup() { 16 | Serial.begin(9600); 17 | } 18 | 19 | void loop() { 20 | button.loop(); // MUST call the loop() function first 21 | 22 | int btnState = button.getState(); 23 | Serial.println(btnState); 24 | } 25 | -------------------------------------------------------------------------------- /examples/02.SingleButtonEvents/02.SingleButtonEvents.ino: -------------------------------------------------------------------------------- 1 | /* 2 | * Created by ArduinoGetStarted.com 3 | * 4 | * This example code is in the public domain 5 | * 6 | * Tutorial page: https://arduinogetstarted.com/tutorials/arduino-button-library 7 | * 8 | * This example detects the pressed and released events of a button without debounce. 9 | */ 10 | 11 | #include 12 | 13 | ezButton button(7); // create ezButton object that attach to pin 7; 14 | 15 | void setup() { 16 | Serial.begin(9600); 17 | } 18 | 19 | void loop() { 20 | button.loop(); // MUST call the loop() function first 21 | 22 | if(button.isPressed()) 23 | Serial.println("The button is pressed"); 24 | 25 | if(button.isReleased()) 26 | Serial.println("The button is released"); 27 | } -------------------------------------------------------------------------------- /examples/03.SingleButtonDebounce/03.SingleButtonDebounce.ino: -------------------------------------------------------------------------------- 1 | /* 2 | * Created by ArduinoGetStarted.com 3 | * 4 | * This example code is in the public domain 5 | * 6 | * Tutorial page: https://arduinogetstarted.com/tutorials/arduino-button-library 7 | * 8 | * This example reads the state of a button with debounce and print it to Serial Monitor. 9 | */ 10 | 11 | #include 12 | 13 | ezButton button(7); // create ezButton object that attach to pin 7; 14 | 15 | void setup() { 16 | Serial.begin(9600); 17 | button.setDebounceTime(50); // set debounce time to 50 milliseconds 18 | } 19 | 20 | void loop() { 21 | button.loop(); // MUST call the loop() function first 22 | 23 | if(button.isPressed()) 24 | Serial.println("The button is pressed"); 25 | 26 | if(button.isReleased()) 27 | Serial.println("The button is released"); 28 | } -------------------------------------------------------------------------------- /examples/04.SingleButtonAll/04.SingleButtonAll.ino: -------------------------------------------------------------------------------- 1 | /* 2 | * Created by ArduinoGetStarted.com 3 | * 4 | * This example code is in the public domain 5 | * 6 | * Tutorial page: https://arduinogetstarted.com/tutorials/arduino-button-library 7 | * 8 | * This example: 9 | * + uses debounce for a button. 10 | * + reads state of a button 11 | * + detects the pressed and released events of a button 12 | */ 13 | 14 | #include 15 | 16 | ezButton button(7); // create ezButton object that attach to pin 7; 17 | 18 | void setup() { 19 | Serial.begin(9600); 20 | button.setDebounceTime(50); // set debounce time to 50 milliseconds 21 | } 22 | 23 | void loop() { 24 | button.loop(); // MUST call the loop() function first 25 | 26 | int btnState = button.getState(); 27 | Serial.println(btnState); 28 | 29 | if(button.isPressed()) 30 | Serial.println("The button is pressed"); 31 | 32 | if(button.isReleased()) 33 | Serial.println("The button is released"); 34 | } -------------------------------------------------------------------------------- /examples/05.MultipleButtonAll/05.MultipleButtonAll.ino: -------------------------------------------------------------------------------- 1 | /* 2 | * Created by ArduinoGetStarted.com 3 | * 4 | * This example code is in the public domain 5 | * 6 | * Tutorial page: https://arduinogetstarted.com/tutorials/arduino-button-library 7 | * 8 | * This example: 9 | * + uses debounce for multiple buttons. 10 | * + reads state of multiple buttons 11 | * + detects the pressed and released events of multiple buttons 12 | */ 13 | 14 | #include 15 | 16 | ezButton button1(6); // create ezButton object that attach to pin 6; 17 | ezButton button2(7); // create ezButton object that attach to pin 7; 18 | ezButton button3(8); // create ezButton object that attach to pin 8; 19 | 20 | void setup() { 21 | Serial.begin(9600); 22 | button1.setDebounceTime(50); // set debounce time to 50 milliseconds 23 | button2.setDebounceTime(50); // set debounce time to 50 milliseconds 24 | button3.setDebounceTime(50); // set debounce time to 50 milliseconds 25 | } 26 | 27 | void loop() { 28 | button1.loop(); // MUST call the loop() function first 29 | button2.loop(); // MUST call the loop() function first 30 | button3.loop(); // MUST call the loop() function first 31 | 32 | int btn1State = button1.getState(); 33 | int btn2State = button2.getState(); 34 | int btn3State = button3.getState(); 35 | Serial.print("button 1 state: "); 36 | Serial.println(btn1State); 37 | Serial.print("button 2 state: "); 38 | Serial.println(btn2State); 39 | Serial.print("button 3 state: "); 40 | Serial.println(btn3State); 41 | 42 | if(button1.isPressed()) 43 | Serial.println("The button 1 is pressed"); 44 | 45 | if(button1.isReleased()) 46 | Serial.println("The button 1 is released"); 47 | 48 | if(button2.isPressed()) 49 | Serial.println("The button 2 is pressed"); 50 | 51 | if(button2.isReleased()) 52 | Serial.println("The button 2 is released"); 53 | 54 | if(button3.isPressed()) 55 | Serial.println("The button 3 is pressed"); 56 | 57 | if(button3.isReleased()) 58 | Serial.println("The button 3 is released"); 59 | } -------------------------------------------------------------------------------- /examples/06.ButtonCount/06.ButtonCount.ino: -------------------------------------------------------------------------------- 1 | /* 2 | * Created by ArduinoGetStarted.com 3 | * 4 | * This example code is in the public domain 5 | * 6 | * Tutorial page: https://arduinogetstarted.com/tutorials/arduino-button-library 7 | * 8 | * This example reads the number of the pressed count of a button with debounce and print it to Serial Monitor. 9 | */ 10 | 11 | #include 12 | 13 | ezButton button(7); // create ezButton object that attach to pin 7; 14 | 15 | void setup() { 16 | Serial.begin(9600); 17 | button.setDebounceTime(50); // set debounce time to 50 milliseconds 18 | button.setCountMode(COUNT_FALLING); 19 | } 20 | 21 | void loop() { 22 | button.loop(); // MUST call the loop() function first 23 | 24 | unsigned long count = button.getCount(); 25 | Serial.println(count); 26 | } -------------------------------------------------------------------------------- /examples/07.ButtonArray/07.ButtonArray.ino: -------------------------------------------------------------------------------- 1 | /* 2 | * Created by ArduinoGetStarted.com 3 | * 4 | * This example code is in the public domain 5 | * 6 | * Tutorial page: https://arduinogetstarted.com/tutorials/arduino-button-library 7 | * 8 | * This example shows how to use array of button. 9 | */ 10 | 11 | #include 12 | 13 | const int BUTTON_NUM = 5; 14 | 15 | const int BUTTON_1_PIN = 2; 16 | const int BUTTON_2_PIN = 3; 17 | const int BUTTON_3_PIN = 4; 18 | const int BUTTON_4_PIN = 5; 19 | const int BUTTON_5_PIN = 6; 20 | 21 | ezButton buttonArray[] = { 22 | ezButton(BUTTON_1_PIN), 23 | ezButton(BUTTON_2_PIN), 24 | ezButton(BUTTON_3_PIN), 25 | ezButton(BUTTON_4_PIN), 26 | ezButton(BUTTON_5_PIN) 27 | }; 28 | 29 | void setup() { 30 | Serial.begin(9600); 31 | 32 | for (byte i = 0; i < BUTTON_NUM; i++) { 33 | buttonArray[i].setDebounceTime(50); // set debounce time to 50 milliseconds 34 | } 35 | } 36 | 37 | void loop() { 38 | for (byte i = 0; i < BUTTON_NUM; i++) 39 | buttonArray[i].loop(); // MUST call the loop() function first 40 | 41 | for (byte i = 0; i < BUTTON_NUM; i++) { 42 | if (buttonArray[i].isPressed()) { 43 | Serial.print("The button "); 44 | Serial.print(i + 1); 45 | Serial.println(" is pressed"); 46 | } 47 | 48 | if (buttonArray[i].isReleased()) { 49 | Serial.print("The button "); 50 | Serial.print(i + 1); 51 | Serial.println(" is released"); 52 | } 53 | } 54 | } -------------------------------------------------------------------------------- /keywords.txt: -------------------------------------------------------------------------------- 1 | ####################################### 2 | # Syntax Coloring Map For ezButton 3 | ####################################### 4 | 5 | ####################################### 6 | # Datatypes (KEYWORD1) 7 | ####################################### 8 | 9 | ezButton KEYWORD1 10 | button KEYWORD1 11 | 12 | ####################################### 13 | # Methods and Functions (KEYWORD2) 14 | ####################################### 15 | 16 | setDebounceTime KEYWORD2 17 | getState KEYWORD2 18 | getStateRaw KEYWORD2 19 | isPressed KEYWORD2 20 | isReleased KEYWORD2 21 | setCountMode KEYWORD2 22 | getCount KEYWORD2 23 | resetCount KEYWORD2 24 | 25 | ####################################### 26 | # Constants (LITERAL1) 27 | ####################################### 28 | 29 | COUNT_FALLING LITERAL1 30 | COUNT_RISING LITERAL1 31 | COUNT_BOTH LITERAL1 32 | INTERNAL_PULLUP LITERAL1 33 | INTERNAL_PULLDOWN LITERAL1 34 | EXTERNAL_PULLUP LITERAL1 35 | EXTERNAL_PULLDOWN LITERAL1 -------------------------------------------------------------------------------- /library.properties: -------------------------------------------------------------------------------- 1 | name=ezButton 2 | version=1.0.6 3 | author=ArduinoGetStarted.com 4 | maintainer=ArduinoGetStarted.com (ArduinoGetStarted@gmail.com) 5 | sentence=Button library for Arduino, ESP32, ESP8266... 6 | paragraph=Button library supports debounce, pressed/released events and the press counting. It is easy to use with multiple buttons. The library can be used for push-button, momentary switches, toggle switch, magnetic contact switch (door sensor)... It is designed for not only beginners but also experienced users. 7 | category=Signal Input/Output 8 | url=https://arduinogetstarted.com/tutorials/arduino-button-library 9 | architectures=* 10 | includes=ezButton.h 11 | -------------------------------------------------------------------------------- /src/ezButton.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2019, ArduinoGetStarted.com. All rights reserved. 3 | * 4 | * Redistribution and use in source and binary forms, with or without 5 | * modification, are permitted provided that the following conditions 6 | * are met: 7 | * 8 | * - Redistributions of source code must retain the above copyright 9 | * notice, this list of conditions and the following disclaimer. 10 | * 11 | * - Redistributions in binary form must reproduce the above copyright 12 | * notice, this list of conditions and the following disclaimer in the 13 | * documentation and/or other materials provided with the distribution. 14 | * 15 | * - Neither the name of the ArduinoGetStarted.com nor the names of its 16 | * contributors may be used to endorse or promote products derived from 17 | * this software without specific prior written permission. 18 | * 19 | * THIS SOFTWARE IS PROVIDED BY ARDUINOGETSTARTED.COM "AS IS" AND ANY EXPRESS OR 20 | * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 21 | * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 22 | * DISCLAIMED. IN NO EVENT SHALL ARDUINOGETSTARTED.COM BE LIABLE FOR ANY DIRECT, 23 | * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 24 | * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 25 | * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26 | * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 27 | * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 28 | * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29 | * POSSIBILITY OF SUCH DAMAGE. 30 | */ 31 | 32 | #include 33 | 34 | ezButton::ezButton(int pin): ezButton(pin, INTERNAL_PULLUP) {}; 35 | 36 | ezButton::ezButton(int pin, int mode) { 37 | btnPin = pin; 38 | debounceTime = 0; 39 | count = 0; 40 | countMode = COUNT_FALLING; 41 | 42 | if (mode == INTERNAL_PULLUP || mode == INTERNAL_PULLDOWN) { 43 | pinMode(btnPin, mode); 44 | } else if (mode == EXTERNAL_PULLUP || mode == EXTERNAL_PULLDOWN) { 45 | pinMode(btnPin, INPUT); // External pull-up/pull-down, set as INPUT 46 | } 47 | 48 | // Set the pressed and unpressed states based on the mode 49 | if (mode == INTERNAL_PULLDOWN || mode == EXTERNAL_PULLDOWN) { 50 | pressedState = HIGH; 51 | unpressedState = LOW; 52 | } else { 53 | pressedState = LOW; 54 | unpressedState = HIGH; 55 | } 56 | 57 | previousSteadyState = digitalRead(btnPin); 58 | lastSteadyState = previousSteadyState; 59 | lastFlickerableState = previousSteadyState; 60 | 61 | lastDebounceTime = 0; 62 | } 63 | 64 | void ezButton::setDebounceTime(unsigned long time) { 65 | debounceTime = time; 66 | } 67 | 68 | int ezButton::getState(void) { 69 | return lastSteadyState; 70 | } 71 | 72 | int ezButton::getStateRaw(void) { 73 | return digitalRead(btnPin); 74 | } 75 | 76 | bool ezButton::isPressed(void) { 77 | if(previousSteadyState == unpressedState && lastSteadyState == pressedState) 78 | return true; 79 | else 80 | return false; 81 | } 82 | 83 | bool ezButton::isReleased(void) { 84 | if(previousSteadyState == pressedState && lastSteadyState == unpressedState) 85 | return true; 86 | else 87 | return false; 88 | } 89 | 90 | void ezButton::setCountMode(int mode) { 91 | countMode = mode; 92 | } 93 | 94 | unsigned long ezButton::getCount(void) { 95 | return count; 96 | } 97 | 98 | void ezButton::resetCount(void) { 99 | count = 0; 100 | } 101 | 102 | void ezButton::loop(void) { 103 | // read the state of the switch/button: 104 | int currentState = digitalRead(btnPin); 105 | unsigned long currentTime = millis(); 106 | 107 | // check to see if you just pressed the button 108 | // (i.e. the input went from LOW to HIGH), and you've waited long enough 109 | // since the last press to ignore any noise: 110 | 111 | // If the switch/button changed, due to noise or pressing: 112 | if (currentState != lastFlickerableState) { 113 | // reset the debouncing timer 114 | lastDebounceTime = currentTime; 115 | // save the the last flickerable state 116 | lastFlickerableState = currentState; 117 | } 118 | 119 | if ((currentTime - lastDebounceTime) >= debounceTime) { 120 | // whatever the reading is at, it's been there for longer than the debounce 121 | // delay, so take it as the actual current state: 122 | 123 | // save the the steady state 124 | previousSteadyState = lastSteadyState; 125 | lastSteadyState = currentState; 126 | } 127 | 128 | if(previousSteadyState != lastSteadyState){ 129 | if(countMode == COUNT_BOTH) 130 | count++; 131 | else if(countMode == COUNT_FALLING){ 132 | if(previousSteadyState == HIGH && lastSteadyState == LOW) 133 | count++; 134 | } 135 | else if(countMode == COUNT_RISING){ 136 | if(previousSteadyState == LOW && lastSteadyState == HIGH) 137 | count++; 138 | } 139 | } 140 | } 141 | -------------------------------------------------------------------------------- /src/ezButton.h: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2019, ArduinoGetStarted.com. All rights reserved. 3 | * 4 | * Redistribution and use in source and binary forms, with or without 5 | * modification, are permitted provided that the following conditions 6 | * are met: 7 | * 8 | * - Redistributions of source code must retain the above copyright 9 | * notice, this list of conditions and the following disclaimer. 10 | * 11 | * - Redistributions in binary form must reproduce the above copyright 12 | * notice, this list of conditions and the following disclaimer in the 13 | * documentation and/or other materials provided with the distribution. 14 | * 15 | * - Neither the name of the ArduinoGetStarted.com nor the names of its 16 | * contributors may be used to endorse or promote products derived from 17 | * this software without specific prior written permission. 18 | * 19 | * THIS SOFTWARE IS PROVIDED BY ARDUINOGETSTARTED.COM "AS IS" AND ANY EXPRESS OR 20 | * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 21 | * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 22 | * DISCLAIMED. IN NO EVENT SHALL ARDUINOGETSTARTED.COM BE LIABLE FOR ANY DIRECT, 23 | * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 24 | * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 25 | * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26 | * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 27 | * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 28 | * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29 | * POSSIBILITY OF SUCH DAMAGE. 30 | */ 31 | 32 | #ifndef ezButton_h 33 | #define ezButton_h 34 | 35 | #include 36 | 37 | #define COUNT_FALLING 0 38 | #define COUNT_RISING 1 39 | #define COUNT_BOTH 2 40 | 41 | // Constants for button modes 42 | #define INTERNAL_PULLUP INPUT_PULLUP 43 | #ifdef INPUT_PULLDOWN 44 | #define INTERNAL_PULLDOWN INPUT_PULLDOWN 45 | #else 46 | #define INTERNAL_PULLDOWN INPUT 47 | #endif 48 | 49 | #define EXTERNAL_PULLUP 0xFE 50 | #define EXTERNAL_PULLDOWN 0xFF 51 | 52 | class ezButton 53 | { 54 | private: 55 | int btnPin; 56 | unsigned long debounceTime; 57 | unsigned long count; 58 | int countMode; 59 | int pressedState; // the state when the button is considered pressed 60 | int unpressedState; // the state when the button is considered unpressed 61 | 62 | int previousSteadyState; // the previous steady state from the input pin, used to detect pressed and released event 63 | int lastSteadyState; // the last steady state from the input pin 64 | int lastFlickerableState; // the last flickerable state from the input pin 65 | 66 | unsigned long lastDebounceTime; // the last time the output pin was toggled 67 | 68 | public: 69 | ezButton(int pin); 70 | ezButton(int pin, int mode); 71 | void setDebounceTime(unsigned long time); 72 | int getState(void); 73 | int getStateRaw(void); 74 | bool isPressed(void); 75 | bool isReleased(void); 76 | void setCountMode(int mode); 77 | unsigned long getCount(void); 78 | void resetCount(void); 79 | void loop(void); 80 | }; 81 | 82 | #endif 83 | --------------------------------------------------------------------------------