From d5ff5c506d0062da2384e2214c8cb4eac797b487 Mon Sep 17 00:00:00 2001
From: Gregg <gregg.berman@me.com>
Date: Mon, 17 Aug 2020 07:00:47 -0500
Subject: [PATCH] Example 10NEW -> Example 14

Updated Example 10NEW to fully reflect the use of loop() methods instead of TimedResets to emulate a push button.  Renamed Example 10 to Example 14, since it must come after we introduce loops().  Deleted both original Example 10 and Example 10NEW
---
 .../Advanced/10-TimedResets/DEV_Blinker.h     | 93 -------------------
 .../10NEW-TimedResets/10NEW-TimedResets.ino   | 80 ----------------
 .../Advanced/10NEW-TimedResets/DEV_Identify.h | 38 --------
 .../14-Pushbuttons/14-Pushbuttons.ino}        | 37 ++++----
 .../14-Pushbuttons}/DEV_Blinker.h             | 49 +++++-----
 .../14-Pushbuttons}/DEV_Identify.h            |  0
 6 files changed, 39 insertions(+), 258 deletions(-)
 delete mode 100644 examples/Advanced/10-TimedResets/DEV_Blinker.h
 delete mode 100644 examples/Advanced/10NEW-TimedResets/10NEW-TimedResets.ino
 delete mode 100644 examples/Advanced/10NEW-TimedResets/DEV_Identify.h
 rename examples/{Advanced/10-TimedResets/10-TimedResets.ino => Expert/14-Pushbuttons/14-Pushbuttons.ino} (59%)
 rename examples/{Advanced/10NEW-TimedResets => Expert/14-Pushbuttons}/DEV_Blinker.h (54%)
 rename examples/{Advanced/10-TimedResets => Expert/14-Pushbuttons}/DEV_Identify.h (100%)

diff --git a/examples/Advanced/10-TimedResets/DEV_Blinker.h b/examples/Advanced/10-TimedResets/DEV_Blinker.h
deleted file mode 100644
index deaec4f..0000000
--- a/examples/Advanced/10-TimedResets/DEV_Blinker.h
+++ /dev/null
@@ -1,93 +0,0 @@
-
-////////////////////////////////////
-//   DEVICE-SPECIFIC LED SERVICES //
-////////////////////////////////////
-
-// NOTE: This example is constructed only for the purpose of demonstrating how to
-// use SpanTimedReset() to emulate a pushbutton in HomeSpan.  The length of the blinking
-// routine is much longer than HomeSpan should spend on an update().  To see how this
-// effects HomeKit, try changing the number of blinks to 50, or keep it at 3 and
-// increase the delay times in update() so that the blink routine takes 10 seconds or more.
-// When activated, HomeKit will think the device has become non-responsive.
-//
-// In practice, pushbuton emulation is used for very short routines, such as driving
-// an IR LED or an RF transmitter to send a code to a remote device.
-
-struct DEV_Blinker : Service::LightBulb {           // LED Blinker
-
-  int ledPin;                                       // pin number defined for this LED
-  int nBlinks;                                      // NEW! number of times to blink
-  
-  SpanCharacteristic *power;                        // reference to the On Characteristic
-  
-  DEV_Blinker(int ledPin, int nBlinks) : Service::LightBulb(){       // constructor() method
-
-    power=new Characteristic::On();                 
-
-    // Here we create a new Timed Reset of 2000 milliseconds. Similar to SpanRange(), SpanTimedReset() automatically
-    // attaches to the last Characteristic instantiated, which in this case the the "power" Characteristic::On above.
-    // SpanTimedReset() will notify HomeKit that the Characteristic has been turned off by HomeSpan 2000 milliseconds
-    // after HomeKit requests it be turned on.  This DOES NOT cause HomeKit to send an "off" request to HomeSpan (with
-    // one exception --- see * below). Rather, HomeSpan is notifying HomeKit that HomeSpan itself has turned "off" the
-    // Characteristic, and that HomeKit should reflect this new "off" status in the Tile shown for this device in the
-    // HomeKit Controller.
-    //
-    // Note that in practice you'll want to set the reset time to 500ms or less to better emulate a pushbutton.
-    // We've used a full 2 seconds in this example for illustrative purposes only.
-    
-    new SpanTimedReset(1000);                        // *** NEW!! instantiate SpanTimedReset with a delay of 2000 milliseconds
-    
-    this->ledPin=ledPin;                            
-    this->nBlinks=nBlinks;                           // NEW! number of blinks
-    pinMode(ledPin,OUTPUT);                         
-    
-    Serial.print("Configuring LED Blinker: Pin=");   // initialization message
-    Serial.print(ledPin);
-    Serial.print("  Blinks=");                       // NEW! add output message for number of blinks
-    Serial.print(nBlinks);
-    Serial.print("\n");
-
-  } // end constructor
-
-  StatusCode update(){                              // update() method
-
-    // Instead of turning on or off the LED according to newValue, we blink it for
-    // the number of times specified, and leave it in the off position when finished.
-    // This line is deleted...
-    
-    // digitalWrite(ledPin,power->getNewVal());      
-
-    // and is replaced by...
-
-    if(power->getNewVal()){                       // check to ensure HomeKit is requesting we "turn on" this device (else ignore)
-
-      LOG1("Activating the LED Blinker on pin=");
-      LOG1(ledPin);
-      LOG1("\n");
-
-      for(int i=0;i<nBlinks;i++){                     // loop over number of blinks specified
-        digitalWrite(ledPin,HIGH);                    // turn pin on
-        delay(100);                                   // wait 100 ms
-        digitalWrite(ledPin,LOW);                     // turn pin off
-        delay(250);                                   // wait 250 ms
-      }
-      
-    } // if newVal=true
-
-    // Note that the delays above of 100ms and 250ms are for illustrative purposes only
-    // (and so you can see the LED blink). In practice, if you were controlling an IR LED
-    // or an RF transmitter, the whole signal would likely transmit in 10ms total.
-    
-    return(StatusCode::OK);                         // return OK status code
-  
-  } // update
-};
-      
-//////////////////////////////////
-
-// * EXCEPTION:  There is an apparent bug in HomeKit such that if you have an Accessory with three or more
-// Services, and the Accessory receives a notification message from the device, AND the HomeKit interface is
-// open to show the detailed control for Service in the Accessory, then for some reason HomeKit tries to
-// update the device with the same status it just received from the device, even though this is contrary to
-// the purpose of notification requests.  This is why it's a good idea to check that newValue.BOOL==true.  It
-// avoids triggering the device if for some reason HomeKit should send a reqeust to update newValue to false.
diff --git a/examples/Advanced/10NEW-TimedResets/10NEW-TimedResets.ino b/examples/Advanced/10NEW-TimedResets/10NEW-TimedResets.ino
deleted file mode 100644
index 5ee9057..0000000
--- a/examples/Advanced/10NEW-TimedResets/10NEW-TimedResets.ino
+++ /dev/null
@@ -1,80 +0,0 @@
-
-////////////////////////////////////////////////////////////
-//                                                        //
-//    HomeSpan: A HomeKit implementation for the ESP32    //
-//    ------------------------------------------------    //
-//                                                        //
-// Example 10: Timed Resets - emulating a "pushbutton"    //
-//             in HomeKit                                 //
-//                                                        //
-////////////////////////////////////////////////////////////
-
-#include "HomeSpan.h" 
-#include "DEV_Blinker.h"     
-#include "DEV_Identify.h"       
-
-void setup() {
-
-   // Though HomeKit and the HomeKit Accessory Protocol (HAP) Specification provide a very flexible framework
-   // for creating iOS- and MacOS-controlled devices, they does not contain every possible desired feature.
-   //
-   // One very common Characteristic HomeKit does not seem to contain is a simple pushbutton, like the type you
-   // would find on a remote control.  Unlike switches that can be "on" or "off", a pushbutton has no state.
-   // Rather, a pushbutton performs some action when it's pushed, and that's all it does until it's pushed
-   // again.
-   //
-   // Though HomeKit does not contain such a Characteristic, it's easy to emulate in HomeSpan.  To do so, simply
-   // define a Service with a boolen Characteristic (such as the On Characteristic), and create an update()
-   // method to peform the operations to be executed when the "pushbutton" is "pressed".  The update() method
-   // should ignore the newValue requested by HomeKit, since the only thing that matters is that update() is called.
-   // 
-   // You could stop there and have something in HomeKit that acts like a pushbutton, but it won't look like a
-   // pushbutton because every time you press the tile for your device in HomeKit, the Controller will toggle
-   // between showing it's on and showing it's off.  Pressing a tile that shows the status is already on, in order
-   // to cause HomeKit to trigger the update() to perform a new action, is not very satisfying.
-   //
-   // Ideally, we'd like HomeKit to acknowledge you've pressed the tile for the device, maybe by lighting up for a
-   // second or so, and then it should reset to the "off" position.  This would emulate a light-up pushbutton.
-   //
-   // Fortunately, HomeSpan includes a way of doing exactly this, using an object called SpanTimedReset().  Similar
-   // to SpanRange(), you create a new SpanTimedReset() object with a single argument representing the number of
-   // milliseconds HomeSpan should wait before telling HomeKit to reset, or "turn off", the device tile it just turned
-   // on when you pressed it.  How does SpanTimedReset() know which Characteristic it should attach itself to?
-   // Similar to all other HomeSpan objects, SpanTimedReset() attaches to the last object you instantiated (and
-   // will throw an error message at start-up if you try to instantiate a new SpanTimedReset() object without having just
-   // instantiated a boolean Characteristic of some type).
-   //
-   // In Example 10 below we create a single pushbutton that blinks an LED three times.  This is not very useful, but
-   // you can think about the LED as an IR LED that is transmitting a Volume-Up command to a TV, or an RF signal to
-   // some remote device, like a ceiling fan.
-   //
-   // All the functionality is wrapped up in a newly-defined "DEV_Blinker" Service, which can be found in DEV_Blinker.h.
-   // This new Service is a copy of the DEV_LED service we've been working so far, with modifications to make it into 
-   // a generic blinking LED.  As usual, changes and new lines are notably commented.
-  
-  Serial.begin(115200);
-
-  homeSpan.begin(Category::Bridges,"HomeSpan Bridge");
-  
-  // Defines the Bridge Accessory
- 
-  new SpanAccessory();  
-    new DEV_Identify("Bridge #1","HomeSpan","123-ABC","HS Bridge","0.9",3);
-    new Service::HAPProtocolInformation();
-      new Characteristic::Version("1.1.0");
-  
-  // *** NEW *** defines an LED Blinker Accessory attached to pin 16 which blinks 3 times
-
-  new SpanAccessory();                                                          
-    new DEV_Identify("LED Blinker","HomeSpan","123-ABC","20mA LED","0.9",0);
-    new DEV_Blinker(16,3);                                                      // DEV_Blinker takes two arguments - pin, and number of times to blink
-
-} // end of setup()
-
-//////////////////////////////////////
-
-void loop(){
-  
-  homeSpan.poll();
-  
-} // end of loop()
diff --git a/examples/Advanced/10NEW-TimedResets/DEV_Identify.h b/examples/Advanced/10NEW-TimedResets/DEV_Identify.h
deleted file mode 100644
index 7e6826f..0000000
--- a/examples/Advanced/10NEW-TimedResets/DEV_Identify.h
+++ /dev/null
@@ -1,38 +0,0 @@
-
-//////////////////////////////////
-//   DEVICE-SPECIFIC SERVICES   //
-//////////////////////////////////
-
-struct DEV_Identify : Service::AccessoryInformation {
-
-  int nBlinks;                    // number of times to blink built-in LED in identify routine
-  SpanCharacteristic *identify;   // reference to the Identify Characteristic
-  
-  DEV_Identify(char *name, char *manu, char *sn, char *model, char *version, int nBlinks) : Service::AccessoryInformation(){
-    
-    new Characteristic::Name(name);                   // create all the required Characteristics with values set based on above arguments
-    new Characteristic::Manufacturer(manu);
-    new Characteristic::SerialNumber(sn);    
-    new Characteristic::Model(model);
-    new Characteristic::FirmwareRevision(version);
-    identify=new Characteristic::Identify();          // store a reference to the Identify Characteristic for use below
-
-    this->nBlinks=nBlinks;                            // store the number of times to blink the built-in LED
-
-    pinMode(LED_BUILTIN,OUTPUT);                      // make sure built-in LED is set for output
-  }
-
-  StatusCode update(){
-       
-    for(int i=0;i<nBlinks;i++){
-      digitalWrite(LED_BUILTIN,LOW);
-      delay(250);
-      digitalWrite(LED_BUILTIN,HIGH);
-      delay(250);
-    }
-
-    return(StatusCode::OK);
-    
-  } // update
-  
-};
diff --git a/examples/Advanced/10-TimedResets/10-TimedResets.ino b/examples/Expert/14-Pushbuttons/14-Pushbuttons.ino
similarity index 59%
rename from examples/Advanced/10-TimedResets/10-TimedResets.ino
rename to examples/Expert/14-Pushbuttons/14-Pushbuttons.ino
index 5ee9057..ee11277 100644
--- a/examples/Advanced/10-TimedResets/10-TimedResets.ino
+++ b/examples/Expert/14-Pushbuttons/14-Pushbuttons.ino
@@ -4,8 +4,7 @@
 //    HomeSpan: A HomeKit implementation for the ESP32    //
 //    ------------------------------------------------    //
 //                                                        //
-// Example 10: Timed Resets - emulating a "pushbutton"    //
-//             in HomeKit                                 //
+// Example 14: Pushbuttons                                //
 //                                                        //
 ////////////////////////////////////////////////////////////
 
@@ -25,32 +24,30 @@ void setup() {
    //
    // Though HomeKit does not contain such a Characteristic, it's easy to emulate in HomeSpan.  To do so, simply
    // define a Service with a boolen Characteristic (such as the On Characteristic), and create an update()
-   // method to peform the operations to be executed when the "pushbutton" is "pressed".  The update() method
-   // should ignore the newValue requested by HomeKit, since the only thing that matters is that update() is called.
+   // method to peform the operations to be executed when the "pushbutton" is "pressed" (i.e. set to true).
    // 
    // You could stop there and have something in HomeKit that acts like a pushbutton, but it won't look like a
    // pushbutton because every time you press the tile for your device in HomeKit, the Controller will toggle
-   // between showing it's on and showing it's off.  Pressing a tile that shows the status is already on, in order
-   // to cause HomeKit to trigger the update() to perform a new action, is not very satisfying.
+   // between showing it's on and showing it's off.  Pressing a tile that shows the status is already ON, and will
+   // change to OFF, when you actually want to re-trigger some sort of "on" action is not very satisfying.
    //
-   // Ideally, we'd like HomeKit to acknowledge you've pressed the tile for the device, maybe by lighting up for a
-   // second or so, and then it should reset to the "off" position.  This would emulate a light-up pushbutton.
+   // Ideally, we'd like HomeKit to acknowledge you've pressed the tile for the device by lighting up, sending
+   // a request to update(), AND THEN resetting itself automatically to the "off" position a second or two later.
+   // This would indeed emulate a light-up pushbutton.
    //
-   // Fortunately, HomeSpan includes a way of doing exactly this, using an object called SpanTimedReset().  Similar
-   // to SpanRange(), you create a new SpanTimedReset() object with a single argument representing the number of
-   // milliseconds HomeSpan should wait before telling HomeKit to reset, or "turn off", the device tile it just turned
-   // on when you pressed it.  How does SpanTimedReset() know which Characteristic it should attach itself to?
-   // Similar to all other HomeSpan objects, SpanTimedReset() attaches to the last object you instantiated (and
-   // will throw an error message at start-up if you try to instantiate a new SpanTimedReset() object without having just
-   // instantiated a boolean Characteristic of some type).
+   // Fortunately, it is easy to emulate this in HomeSpan through the use of a Service's loop() function. Simply
+   // code a derived Service as you normally would with its own update() method, and implement a loop() method
+   // that "resets" one or more Characteristics after a set period of time.  This is similar to what we did in the
+   // with loop() methods in the prior two examples, except a lot simpler since the only logic is to set the value
+   // of a Characteristic to "off" after a few seconds using timeVal() and setVal().
    //
-   // In Example 10 below we create a single pushbutton that blinks an LED three times.  This is not very useful, but
-   // you can think about the LED as an IR LED that is transmitting a Volume-Up command to a TV, or an RF signal to
-   // some remote device, like a ceiling fan.
+   // Example 14 demonstrates this by implementing a "pushbutton" Service to blink an LED three times.  By itself, this
+   // is not very useful.  But it is a good model for showing how to implement an IR LED that sends a Volume-Up command to
+   // a TV; or an RF Transmitter to control to some remote device, like a ceiling fan.
    //
    // All the functionality is wrapped up in a newly-defined "DEV_Blinker" Service, which can be found in DEV_Blinker.h.
-   // This new Service is a copy of the DEV_LED service we've been working so far, with modifications to make it into 
-   // a generic blinking LED.  As usual, changes and new lines are notably commented.
+   // This new Service is a copy of the DEV_LED service from Example 9, with modifications to make it into a generic
+   // blinking LED.  As usual, changes and new lines between this Example 14, and original Example 9, are notably commented.
   
   Serial.begin(115200);
 
diff --git a/examples/Advanced/10NEW-TimedResets/DEV_Blinker.h b/examples/Expert/14-Pushbuttons/DEV_Blinker.h
similarity index 54%
rename from examples/Advanced/10NEW-TimedResets/DEV_Blinker.h
rename to examples/Expert/14-Pushbuttons/DEV_Blinker.h
index 8839c14..7adcb3e 100644
--- a/examples/Advanced/10NEW-TimedResets/DEV_Blinker.h
+++ b/examples/Expert/14-Pushbuttons/DEV_Blinker.h
@@ -4,15 +4,18 @@
 ////////////////////////////////////
 
 // NOTE: This example is constructed only for the purpose of demonstrating how to
-// use SpanTimedReset() to emulate a pushbutton in HomeSpan.  The length of the blinking
-// routine is much longer than HomeSpan should spend on an update().  To see how this
-// effects HomeKit, try changing the number of blinks to 50, or keep it at 3 and
-// increase the delay times in update() so that the blink routine takes 10 seconds or more.
-// When activated, HomeKit will think the device has become non-responsive.
-//
+// emulate a pushbutton in HomeSpan.  The length of the blinking routine is MUCH longer
+// than HomeSpan should spend on an update().  To see how this effects HomeKit, try changing
+// the number of blinks to 50, or keep it at 3 and increase the delay times in update() so
+// that the blink routine takes 10 seconds or more. When activated, HomeKit will think the
+// device has become non-responsive if it does not receive a return message from update() within
+// a certain period of time.
+
 // In practice, pushbuton emulation is used for very short routines, such as driving
 // an IR LED or an RF transmitter to send a code to a remote device.
 
+// New and changed lines in comparison with Example 9 are noted as "NEW!"
+
 struct DEV_Blinker : Service::LightBulb {           // LED Blinker
 
   int ledPin;                                       // pin number defined for this LED
@@ -23,17 +26,6 @@ struct DEV_Blinker : Service::LightBulb {           // LED Blinker
   DEV_Blinker(int ledPin, int nBlinks) : Service::LightBulb(){       // constructor() method
 
     power=new Characteristic::On();                 
-
-    // Here we create a new Timed Reset of 2000 milliseconds. Similar to SpanRange(), SpanTimedReset() automatically
-    // attaches to the last Characteristic instantiated, which in this case the the "power" Characteristic::On above.
-    // SpanTimedReset() will notify HomeKit that the Characteristic has been turned off by HomeSpan 2000 milliseconds
-    // after HomeKit requests it be turned on.  This DOES NOT cause HomeKit to send an "off" request to HomeSpan (with
-    // one exception --- see * below). Rather, HomeSpan is notifying HomeKit that HomeSpan itself has turned "off" the
-    // Characteristic, and that HomeKit should reflect this new "off" status in the Tile shown for this device in the
-    // HomeKit Controller.
-    //
-    // Note that in practice you'll want to set the reset time to 500ms or less to better emulate a pushbutton.
-    // We've used a full 2 seconds in this example for illustrative purposes only.
         
     this->ledPin=ledPin;                            
     this->nBlinks=nBlinks;                           // NEW! number of blinks
@@ -49,7 +41,7 @@ struct DEV_Blinker : Service::LightBulb {           // LED Blinker
 
   StatusCode update(){                              // update() method
 
-    // Instead of turning on or off the LED according to newValue, we blink it for
+    // NEW! Instead of turning on or off the LED according to newValue, we blink it for
     // the number of times specified, and leave it in the off position when finished.
     // This line is deleted...
     
@@ -80,11 +72,14 @@ struct DEV_Blinker : Service::LightBulb {           // LED Blinker
   
   } // update
 
+  // NEW! Here we implement a very simple loop() method that checks to see if the power Characteristic
+  // is "on" for at least 3 seconds.  If so, it resets the value to "off" (false).
+
   void loop(){
 
-    if(power->getVal() && power->timeVal()>3000){
-      LOG1("Resetting Blinking LED Control\n");
-      power->setVal(false);
+    if(power->getVal() && power->timeVal()>3000){   // check that power is true, and that time since last modification is greater than 3 seconds 
+      LOG1("Resetting Blinking LED Control\n");     // log message  
+      power->setVal(false);                         // set power to false
     }      
     
   } // loop
@@ -93,9 +88,9 @@ struct DEV_Blinker : Service::LightBulb {           // LED Blinker
       
 //////////////////////////////////
 
-// * EXCEPTION:  There is an apparent bug in HomeKit such that if you have an Accessory with three or more
-// Services, and the Accessory receives a notification message from the device, AND the HomeKit interface is
-// open to show the detailed control for Service in the Accessory, then for some reason HomeKit tries to
-// update the device with the same status it just received from the device, even though this is contrary to
-// the purpose of notification requests.  This is why it's a good idea to check that newValue.BOOL==true.  It
-// avoids triggering the device if for some reason HomeKit should send a reqeust to update newValue to false.
+// HomeKit Bug Note:  There is an apparent bug in HomeKit uncovered during the development of this example.
+// If you have an Accessory with three or more Services, and the Accessory receives a notification message
+// from the device, AND the HomeKit interface is open to show the detailed control for this Service tile
+// in the HomeKit app, then for some reason HomeKit sends an update() request back to the device asking to 
+// set the Characteristic to the value that it just received from an Event Notification.  HomeKit is not supposed
+// to send update requests in response to an Event Notification.
diff --git a/examples/Advanced/10-TimedResets/DEV_Identify.h b/examples/Expert/14-Pushbuttons/DEV_Identify.h
similarity index 100%
rename from examples/Advanced/10-TimedResets/DEV_Identify.h
rename to examples/Expert/14-Pushbuttons/DEV_Identify.h