From b87dcd96d993661ab67d1b825d453813e3245f5e Mon Sep 17 00:00:00 2001 From: JChristensen Date: Mon, 11 Mar 2019 07:43:43 -0400 Subject: [PATCH] Add ToggleButton derived class. --- README.md | 87 ++++++++++++++++++++++++++++++++++++-- examples/Toggle/Toggle.ino | 45 ++++++++++++++++++++ keywords.txt | 3 ++ library.properties | 4 +- src/JC_Button.h | 38 +++++++++++++++++ 5 files changed, 171 insertions(+), 6 deletions(-) create mode 100644 examples/Toggle/Toggle.ino diff --git a/README.md b/README.md index 8af0688..7a65aaf 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ https://github.com/JChristensen/JC_Button README file ## License -Arduino Button Library Copyright (C) 2018 Jack Christensen GNU GPL v3.0 +Arduino Button Library Copyright (C) 2018-2019 Jack Christensen GNU GPL v3.0 This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License v3.0 as published by the Free Software Foundation. @@ -16,14 +16,18 @@ The Button library is for debouncing and reading momentary contact switches like The simplest way to use a button with an AVR microcontroller is to wire the button between a GPIO pin and ground, and turn on the AVR internal pullup resistor. The Button class constructor takes four arguments, but three have default values that work for a button wired in this manner. +A derived class, ToggleButton, implements button objects that need only "push-on, push-off" functionality. + ## Examples The following example sketches are included with the **Button** library: - **SimpleOnOff**: Just turns the Arduino's pin 13 LED on and off. - **LongPress**: Demonstrates detecting long and short button presses. - **UpDown**: Counts up or down, one number at a time or rapidly by holding the button down. +- **Toggle**: Demonstrates ToggleButton functionality. + -## Constructor +## Constructors ### Button(pin, dbTime, puEnable, invert) ##### Description @@ -50,7 +54,38 @@ Button myButton(3, 50); Button myButton(4, 25, false, false); ``` -## Library Functions + +### ToggleButton(pin, initialState, dbTime, puEnable, invert) +##### Description +The constructor defines a toggle button object, which has "push-on, push-off" functionality. The initial state can be on or off. See the section, [ToggleButton Library Functions](https://github.com/JChristensen/JC_Button#togglebutton-library-functions) for functions that apply specifically to the ToggleButton object. The ToggleButton class is derived from the Button class, so all Button functions are available, but because it is inherently a more limited concept, the special ToggleButton functions will be most useful, along with `begin()` and `read()`. +##### Syntax +`ToggleButton(pin, initialState, dbTime, puEnable, invert);` +##### Required parameter +**pin:** Arduino pin number that the button is connected to *(byte)* +##### Optional parameters +**initialState:** Initial state for the button. Defaults to off (false) if not given. *(bool)* +**dbTime:** Debounce time in milliseconds. Defaults to 25ms if not given. *(unsigned long)* +**puEnable:** *true* to enable the microcontroller's internal pull-up resistor, else *false*. Defaults to *true* if not given. *(bool)* +**invert:** *false* interprets a high logic level to mean the button is pressed, *true* interprets a low level as pressed. *true* should be used when a pull-up resistor is employed, *false* for a pull-down resistor. Defaults to *true* if not given. *(bool)* +##### Returns +None. +##### Example +```c++ +// button connected from pin 2 to ground, initial state off, +// 25ms debounce, pullup enabled, logic inverted +ToggleButton myToggle(2); + +// same as above but this button is initially "on" and also +// needs a longer debounce time (50ms). +ToggleButton myToggle(3, true, 50); + +// a button wired from the MCU pin to Vcc with an external pull-down resistor, +// initial state is off. +Button myButton(4, false, 25, false, false); + +``` + +## Button Library Functions ### begin() ##### Description @@ -73,7 +108,7 @@ Reads the button and returns a *boolean* value (*true* or *false*) to indicate w ##### Parameters None. ##### Returns -*true* if the button is pressed, *else* false *(bool)* +*true* if the button is pressed, else *false* *(bool)* ##### Example ```c++ myButton.read(); @@ -153,3 +188,47 @@ The time in milliseconds when the button last changed state *(unsigned long)* ```c++ unsigned long msLastChange = myButton.lastChange(); ``` + +## ToggleButton Library Functions + +### changed() +##### Description +Returns a boolean value (true or false) to indicate whether the toggle button changed state the last time `read()` was called. +##### Syntax +`myToggle.changed();` +##### Parameters +None. +##### Returns +*true* if the toggle state changed, else *false* *(bool)* +##### Example +```c++ +if (myToggle.changed()) +{ + // do something +} +else +{ + // do something different +} +``` + +### toggleState() +##### Description +Returns a boolean value (true or false) to indicate the toggle button state as of the last time `read()` was called. +##### Syntax +`myToggle.toggleState();` +##### Parameters +None. +##### Returns +*true* if the toggle is "on", else *false* *(bool)* +##### Example +```c++ +if (myToggle.toggleState()) +{ + // do something +} +else +{ + // do something different +} +``` \ No newline at end of file diff --git a/examples/Toggle/Toggle.ino b/examples/Toggle/Toggle.ino new file mode 100644 index 0000000..52a9809 --- /dev/null +++ b/examples/Toggle/Toggle.ino @@ -0,0 +1,45 @@ +// Arduino Button Library +// https://github.com/JChristensen/JC_Button +// Copyright (C) 2018 by Jack Christensen and licensed under +// GNU GPL v3.0, https://www.gnu.org/licenses/gpl.html +// +// Example sketch to demonstrate toggle buttons. + +#include // https://github.com/JChristensen/JC_Button + +// pin assignments +const byte + LED1_PIN(5), // connect an LED to ground, through an appropriate current limiting resistor + LED2_PIN(6), // connect an LED to ground, through an appropriate current limiting resistor + BUTTON1_PIN(7), // connect a button switch from this pin to ground + BUTTON2_PIN(8); // connect a button switch from this pin to ground + +ToggleButton // define the buttons + btn1(BUTTON1_PIN), // this button's initial state is off + btn2(BUTTON2_PIN, true); // this button's initial state is on + +void setup() +{ + // initialize the button objects + btn1.begin(); + btn2.begin(); + + // set the LED pins as outputs + pinMode(LED1_PIN, OUTPUT); + pinMode(LED2_PIN, OUTPUT); + + // show the initial states + digitalWrite(LED1_PIN, btn1.toggleState()); + digitalWrite(LED2_PIN, btn2.toggleState()); +} + +void loop() +{ + // read the buttons + btn1.read(); + btn2.read(); + + // if button state changed, update the LEDs + if (btn1.changed()) digitalWrite(LED1_PIN, btn1.toggleState()); + if (btn2.changed()) digitalWrite(LED2_PIN, btn2.toggleState()); +} diff --git a/keywords.txt b/keywords.txt index ebcc701..f47cb71 100644 --- a/keywords.txt +++ b/keywords.txt @@ -1,4 +1,5 @@ Button KEYWORD1 +ToggleButton KEYWORD1 begin KEYWORD2 read KEYWORD2 isPressed KEYWORD2 @@ -8,3 +9,5 @@ wasReleased KEYWORD2 pressedFor KEYWORD2 releasedFor KEYWORD2 lastChange KEYWORD2 +changed KEYWORD2 +toggleState KEYWORD2 diff --git a/library.properties b/library.properties index 5e418e8..d25242b 100644 --- a/library.properties +++ b/library.properties @@ -1,9 +1,9 @@ name=JC_Button -version=2.0.1 +version=2.1.0 author=Jack Christensen maintainer=Jack Christensen sentence=Arduino library to debounce button switches, detect presses, releases, and long presses. -paragraph=The Button library is for debouncing and reading momentary contact switches like tactile button switches. "Long presses" of arbitrary length can be detected. Works well in state machine constructs. Use the read() function to read each button in the main loop, which should execute as fast as possible. +paragraph=Copyright (C) 2018-2019 by Jack Christensen and licensed under GNU GPL v3.0. category=Signal Input/Output url=https://github.com/JChristensen/JC_Button architectures=avr diff --git a/src/JC_Button.h b/src/JC_Button.h index f079e6c..7170294 100644 --- a/src/JC_Button.h +++ b/src/JC_Button.h @@ -70,4 +70,42 @@ class Button uint32_t m_time; // time of current state (ms from millis) uint32_t m_lastChange; // time of last state change (ms) }; + +// a derived class for a "push-on, push-off" (toggle) type button. +// initial state can be given, default is off (false). +class ToggleButton : public Button +{ + public: + + // constructor is similar to Button, but includes the initial state for the toggle. + ToggleButton(uint8_t pin, bool initialState=false, uint32_t dbTime=25, uint8_t puEnable=true, uint8_t invert=true) + : Button(pin, dbTime, puEnable, invert), m_toggleState(initialState) {} + + // read the button and return its state. + // should be called frequently. + bool read() + { + Button::read(); + if (wasPressed()) + { + m_toggleState = !m_toggleState; + m_changed = true; + } + else + { + m_changed = false; + } + return m_toggleState; + } + + // has the state changed? + bool changed() {return m_changed;} + + // return the current state + bool toggleState() {return m_toggleState;} + + private: + bool m_toggleState; + bool m_changed; +}; #endif