From c153824b9567233e571144a2dab7afa971bb3760 Mon Sep 17 00:00:00 2001 From: Gregg Date: Sun, 1 Nov 2020 15:22:16 -0600 Subject: [PATCH] Updated SpanButton Examples And re-worked the logic in Example 15 to make full use of DOUBLE press functionality. To Do: Add commentary to Example 16. --- .../15-RealPushButtons/15-RealPushButtons.ino | 68 ++++++++------ examples/15-RealPushButtons/DEV_LED.h | 90 ++++++++++++------- .../16-ProgrammableSwitches/DEV_ProgButton.h | 2 - 3 files changed, 101 insertions(+), 59 deletions(-) diff --git a/examples/15-RealPushButtons/15-RealPushButtons.ino b/examples/15-RealPushButtons/15-RealPushButtons.ino index 793ed27..711d112 100644 --- a/examples/15-RealPushButtons/15-RealPushButtons.ino +++ b/examples/15-RealPushButtons/15-RealPushButtons.ino @@ -29,59 +29,77 @@ void setup() { // SpanButton() is a Service-level object, meaning it attaches itself to the last Service you define. Typically you would instantiate // one of more SpanButton() objects directly inside the constructor for your derived Service. - // SpanButton() supports two types of a triggers: a SHORT (momentary) button press, and a LONG (extended) button press. + // SpanButton() supports three types of a triggers: a SINGLE button press, a DOUBLE press, and a LONG (extended) press. - // The length of the press needed to trigger either a SHORT or LONG action can be specified by optional arguments to SpanButton(). - // Since most buttons create spurious noise when pressed (and then again when released), the default time to trigger a SHORT press is 5ms. + // The length of the presses needed to trigger these different types can be specified by optional arguments to SpanButton(). + // Since most buttons create spurious noise when pressed (and then again when released), the default time to trigger a SINGLE press is 5ms. // It's fine to change this to a longer value, but a shorter value is not recommended as this may allow spurious triggers unless // you debounce your switch with hardware. - // The SpanButton() constructor takes 3 arguments, in the following order: + // The SpanButton() constructor takes 4 arguments, in the following order: // // pin - the pin number to which the PushButton is attached (required) - // longTime - the length of time (in milliseconds) the button needs to be pushed to be considered a LONG press (optional; default=2000 ms) - // shortTime - the length of time (in milliseconds) the button needs to be pushed to be considered a SHORT press (optional; default=5 ms) + // longTime - the minimum length of time (in milliseconds) the button needs to be pushed to be considered a LONG press (optional; default=2000 ms) + // singleTime - the minimum length of time (in milliseconds) the button needs to be pushed to be considered a SINGLE press (optional; default=5 ms) + // doubleTime - the maximum length of time (in milliseconds) between button presses to create a DOUBLE press (optional; default=200 ms) // When a SpanButton() is instantiated, it sets the specified pin on the ESP32 to be an INPUT with PULL-UP, meaning that the pin will // normally return a value of HIGH when read. Your actual PushButton should be connected so that this pin is GROUNDED when the button // is pressed. // HomeSpan automatically polls all pins with associated SpanButton() objects and checks for LOW values, which indicates the button was - // pressed, but not yet released. It then starts a timer. If the button is released after being pressed for less than shortTime milliseconds, - // nothing happens. If the button is released after being pressed for more than shortTime milliseconds, but for less than longTime milliseconds, - // a SHORT press is triggered. And if the button is held for more than longTime milliseconds without being released, a LONG press is triggered. - // Once a LONG press is triggered the timer resets so that if you keep holding the button, another LONG press will be triggered in another - // longTime milliseconds. This continues until you finally release the button. + // pressed, but not yet released. It then starts a timer. If the button is released after being pressed for less than singleTime milliseconds, + // nothing happens. If the button is released after being pressed for more than singleTime milliseconds, but for less than longTime milliseconds, + // a SINGLE press is triggered, unless you press once again within doubleTime milliseconds to trigger a DOUBLE press. If the button is held for more + // than longTime milliseconds without being released, a LONG press is triggered. Once a LONG press is triggered the timer resets so that if you keep + // holding the button, another LONG press will be triggered in another longTime milliseconds. This continues until you finally release the button. + + // Note if you set longTime > singleTime, SpanButton() will only trigger LONG presses. Also, if you set doubleTime to zero, SpanButton() will not be + // able to trigger a DOUBLE press. // To use SpanButton() within a derived Service you need to implement a button() method. Similar to the loop() method, your button() // method will typically contain some combination of getVal() functions and setVal() functions, along with code that performs some set // of actions on the physical device (seting pins high or low, turning on fans, etc). However, in contrast to the loop() method, which // is called by HomeSpan every polling cycle, HomeSpan only calls the button() method when a button attached to the Service registers a - // SHORT or LONG press. + // SINGLE, DOUBLE, or LONG press. - // Also in contrast with the loop method, the button() method takes two arguments, an int and a boolean, and should defined as follows: + // Also in contrast with the loop method, the button() method takes two 'int' arguments, and should defined as follows: // - // void button(int pin, boolean isLong) + // void button(int pin, int pressType) // - // where "pin" is the pin number of the PushButton that was triggered, and "isLong" is a flag indicating whether SpanButton() detected a - // LONG press (isLong=true) or a SHORT press (isLong=false). Of course you can replace the variables "pin" and "isLong" with your own - // names. The only requirement is the defintiion conform to the "void button(int, boolean)" signature. When HomeSpan first starts up it checks - // all Services containing one or more SpanButton() instances to ensure you've implemented your own button(int, boolean) method. If not, - // HomeSpan will print a warning message on the Serial Monitor. Nothing bad happens if you instantiate a SpanButton() but forget to create - // the button() method, or you create it with the wrong parameters. Buy nothing good happens either - button presses are just ignored. + // where "pin" is the pin number of the PushButton that was triggered, and pressType is set to 0 for a SINGLE press, 1 for a DOUBLE press, + // and 2 for a LONG press. You can also use the pre-defined constants SpanButton::SINGLE, SpanButton::DOUBLE, and SpanButton::LONG in place + // of the numbers 0, 1, and 2 (this is recommended, though you will see in Example 16 why these integers can't be replaced by an C++ enum class). + + // Of course you can replace the variables "pin" and "pressType" with your own names. The only requirement is the definition conform to + // the "void button(int, int)" signature. When HomeSpan first starts up it checks all Services containing one or more SpanButton() instances to + // ensure you've implemented your own button(int, int) method. If not, HomeSpan will print a warning message on the Serial Monitor. Nothing bad + // happens if you instantiate a SpanButton() but forget to create the button() method, or you create it with the wrong parameters. But nothing good + // happens either - button presses are just ignored. // // C++ Note: For an extra check, you can also place the the contextual keyword "override" after your method definition as such: // - // void button(int buttonPin, boolean longPress) override {...your code...} + // void button(int buttonPin, int pressType) override {...your code...} // // Doing so allows the compiler to check that you are indeed over-riding the base class button() method and not inadvertently creating a new // button() method with an incorrect signature that will never be called by SpanButton(). In fact, you could add "override" to the definition // of your update() and loop() methods as well, since these are always supposed to over-ride the base-class method. - // To demonstrate how PushButtons works in practice, we will implement a Dimmable LED starting with the same LED code use in Example 11, - // but with 3 SpanButton() objects performing different functions that showcase the different parameters. As usual, all the code is implemented - // in DEV_LED.h, with NEW! comments highlighting changes from Example 11. You'll also notice that we've extended the constructor for this - // version of our derived Dimmable LED Service to include the pin numbers for each of our buttons. See DEV_LED.h for details. + // To demonstrate how SpanButtons works in practice, we will implement a Dimmable LED starting with the same LED code use in Example 11, + // but with 3 SpanButton() objects performing different functions that showcase the different types of presses. + // + // * A "power" SpanButton that will toggle the power in response a SINGLE press, turn on the power and set the brightness to a "favorite" level + // in response to the DOUBLE press, and set a new "favorite" level in response to a LONG press. + // + // * A "raise brightness" SpanButton that will increase the brightness by 1% in response to a SINGLE press, repeatedly increase the brightness + // by 10% in response to a LONG press, and jump to the maximum brightness in response to a DOUBLE press. + // + // * A "lower brightness" SpanButton that will decrease the brightness by 1% in response to a SINGLE press, repeatedly decrease the brightness + // by 10% in response to a LONG press, and jump to the minimum brightness in response to a DOUBLE press. + + // As usual, all the code is implemented in DEV_LED.h, with NEW! comments highlighting changes from Example 11. You'll also notice that we've + // extended the constructor for this version of our derived Dimmable LED Service to include the pin numbers for each of our buttons. + // See DEV_LED.h for details. Serial.begin(115200); diff --git a/examples/15-RealPushButtons/DEV_LED.h b/examples/15-RealPushButtons/DEV_LED.h index bd1ba63..7c74395 100644 --- a/examples/15-RealPushButtons/DEV_LED.h +++ b/examples/15-RealPushButtons/DEV_LED.h @@ -24,6 +24,7 @@ struct DEV_DimmableLED : Service::LightBulb { // Dimmable LED int channel; // PWM channel used for this LED (should be unique for each LED) SpanCharacteristic *power; // reference to the On Characteristic SpanCharacteristic *level; // reference to the Brightness Characteristic + int favoriteLevel=50; // NEW! keep track of a 'favorite' level // NEW! Consructor includes 3 additionl arguments to specify pin numbers for power, raise, and lower buttons @@ -31,21 +32,19 @@ struct DEV_DimmableLED : Service::LightBulb { // Dimmable LED power=new Characteristic::On(); - level=new Characteristic::Brightness(50); // Brightness Characteristic with an initial value of 50% - new SpanRange(5,100,1); // sets the range of the Brightness to be from a min of 5%, to a max of 100%, in steps of 1% + level=new Characteristic::Brightness(favoriteLevel); // Brightness Characteristic with an initial value equal to the favorite level + new SpanRange(5,100,1); // sets the range of the Brightness to be from a min of 5%, to a max of 100%, in steps of 1% // NEW! Below we create three SpanButton() objects. In the first we specify the pin number, as required, but allow SpanButton() to use - // its default values for a LONG press (2000 ms) and a SHORT press (5 ms). In the second we change the LONG press time to 1000 ms, which - // means we only have to hold the raise button for 1 second to trigger a LONG press that increases the brightness by 10%. In the the third, - // we change both the LONG press time to 3000 ms (which means holding the button for 3 full seconds before releasing to decrease the brightness - // by 10%), and the SHORT press time to 500 ms, which means holding down the button for at least half a second (but not longer than 3 seconds) - // to decrease the brightness by 1%. The logic for increasing/decreasing brightness, as well as turning on/off power, is found in the button() - // method below. Note that in practice you likely would NOT use different combinations of parameters for buttons that perform similar types of - // functions. We've only done so here to illustrate how the parameters work. + // its default values for a LONG press (2000 ms), a SINGLE press (5 ms), and a DOUBLE press (200 ms). In the second and third we change the + // default LONG press time to 500 ms, which works well for repeatedly increasing or decreasing the brightness. + + // All of the logic for increasing/decreasing brightness, turning on/off power, and setting/resetting a favorite brightness level is found + // in the button() method below. - new SpanButton(powerPin); // NEW! create new SpanButton to control power using PushButton on pin number "powerPin" - new SpanButton(raisePin,1000); // NEW! create new SpanButton to increase brightness using PushButton on pin number "raisePin" - new SpanButton(lowerPin,3000,500); // NEW! create new SpanButton to decrease brightness using PushButton on pin number "lowerPin" + new SpanButton(powerPin); // NEW! create new SpanButton to control power using pushbutton on pin number "powerPin" + new SpanButton(raisePin,500); // NEW! create new SpanButton to increase brightness using pushbutton on pin number "raisePin" + new SpanButton(lowerPin,500); // NEW! create new SpanButton to decrease brightness using pushbutton on pin number "lowerPin" this->channel=channel; // save the channel number (from 0-15) this->ledPin=ledPin; // save LED pin number @@ -91,37 +90,64 @@ struct DEV_DimmableLED : Service::LightBulb { // Dimmable LED // NEW! Here is the button() method where all the PushButton actions are defined. Take note of the signature, and use of the word "override" - void button(int pin, boolean isLong) override { + void button(int pin, int pressType) override { LOG1("Found button press on pin: "); // always a good idea to log messages LOG1(pin); LOG1(" type: "); - LOG1(isLong?"LONG":"SHORT"); + LOG1(pressType==SpanButton::LONG?"LONG":(pressType==SpanButton::SINGLE)?"SINGLE":"DOUBLE"); LOG1("\n"); - if(pin==powerPin && !isLong){ // if a SHORT press of the power PushButton... - power->setVal(1-power->getVal()); // ...toggle the value of the power Characteristic - } else - - if(pin==powerPin && isLong){ // if a LONG press of the power PushButton... - if(power->getVal()) // ...and power Characteristic is true (LED is on) - level->setVal(100); // set brightness level Characteristic to 100% - else // ...else, power Characteristic is false (LED os off) - level->setVal(5); // so set brightness level Characteristic to 5% + int newLevel; + + if(pin==powerPin){ + if(pressType==SpanButton::SINGLE){ // if a SINGLE press of the power button... + power->setVal(1-power->getVal()); // ...toggle the value of the power Characteristic + } else + + if(pressType==SpanButton::DOUBLE){ // if a DOUBLE press of the power button... + power->setVal(1); // ...turn on power + level->setVal(favoriteLevel); // ...and set brightness to the favorite level + } else + + if(pressType==SpanButton::LONG) { // if a LONG press of the power button... + favoriteLevel=level->getVal(); // ...save the current brightness level + LOG1("Saved new brightness level="); // ...and output log message + LOG1(favoriteLevel); + LOG1("\n"); + pwmPin->set(channel,(1-power->getVal())*level->getVal()); // blink the LED to indicate new level has been saved + delay(100); + pwmPin->set(channel,(1-power->getVal())*level->getVal()); + } + } else - if(pin==raisePin){ // if raise PushButton has been pressed - int newLevel=level->getVal()+(isLong?10:1); // get current brightness level and increase by either 10% (LONG press) or 1% (SHORT press) - if(newLevel>100) // don't allow new level to exceed maximium of 100% + if(pin==raisePin){ + if(pressType==SpanButton::DOUBLE){ // if a DOUBLE press of the raise button... + power->setVal(1); // ...turn on power + level->setVal(100); // ...and set brightness to the max level + } else { + + newLevel=level->getVal()+(pressType==SpanButton::LONG?10:1); // get current brightness level and increase by either 10% (LONG press) or 1% (SINGLE press) + if(newLevel>100) // don't allow new level to exceed maximium of 100% newLevel=100; - level->setVal(newLevel); // set the value of the brightness Characteristic to this new level + level->setVal(newLevel); // set the value of the brightness Characteristic to this new level + } + } else - if(pin==lowerPin){ // if lower PushButton has been pressed - int newLevel=level->getVal()-(isLong?10:1); // get current brightness level and decrease by either 10% (LONG press) or 1% (SHORT press) - if(newLevel<5) // don't allow new level to fall below minimum of 5% + if(pin==lowerPin){ + if(pressType==SpanButton::DOUBLE){ // if a DOUBLE press of the lower button... + power->setVal(1); // ...turn on power + level->setVal(5); // ...and set brightness to the min level + } else { + + newLevel=level->getVal()-(pressType==SpanButton::LONG?10:1); // get current brightness level and decrease by either 10% (LONG press) or 1% (SINGLE press) + if(newLevel<5) // don't allow new level to fall below minimum of 5% newLevel=5; - level->setVal(newLevel); // set the value of the brightness Characteristic to this new level + level->setVal(newLevel); // set the value of the brightness Characteristic to this new level + } + } // Don't forget to set the new power and level for the actual LED - the above code by itself only changes the values of the Characteristics @@ -134,7 +160,7 @@ struct DEV_DimmableLED : Service::LightBulb { // Dimmable LED // But in the button() method, getNewVal() means nothing, since the button() method is not called by HomeKit in response to a user request // from a HomeKit Controller interface. Instead, we are manually changing the values of one or more Characteristic using setVal() in response - // to LONG and SHORT PushButton requests. These changes are instantaneous, so we can retreive the new values with a subsequent call to getVal(), + // to SINGLE, DOUBLE, and LONG SpanButton requests. These changes are instantaneous, so we can retreive the new values with a subsequent call to getVal(), // as shown below. As usual, HomeSpan will send Event Notifications to all registered HomeKit Controllers letting them know about any changes // we made using setVal(). diff --git a/examples/16-ProgrammableSwitches/DEV_ProgButton.h b/examples/16-ProgrammableSwitches/DEV_ProgButton.h index 1d9a790..f4396c9 100644 --- a/examples/16-ProgrammableSwitches/DEV_ProgButton.h +++ b/examples/16-ProgrammableSwitches/DEV_ProgButton.h @@ -27,8 +27,6 @@ struct DEV_ProgButton : Service::StatelessProgrammableSwitch { // Stateles LOG1("Found button press on pin: "); // always a good idea to log messages LOG1(pin); LOG1(" type: "); - LOG1(pressType); - LOG1(" "); LOG1(pressType==SpanButton::LONG?"LONG":(pressType==SpanButton::SINGLE)?"SINGLE":"DOUBLE"); LOG1("\n");