////////////////////////////////////////////////////////////
//                                                        //
//    HomeSpan: A HomeKit implementation for the ESP32    //
//    ------------------------------------------------    //
//                                                        //
// Example 15: Real PushButtons                           //
//             * manually controlling a Dimmable LED      //
//                                                        //
//                                                        //
////////////////////////////////////////////////////////////

#include "HomeSpan.h" 
#include "DEV_LED.h"     
#include "DEV_Identify.h"       

void setup() {

  // In Example 14 we saw how to emulate a PushButton tile within HomeKit by automatically resetting a Characteristic so that
  // it "turns off" after a short period of time.  However, sometimes we want to be able to physically control a device with actual
  // PushButtons (or momentary switches) that trigger an action, such as turning on a light or fan, or opening a garage door.
  // Additionally, we want HomeKit to reflect any changes in the device as a result of such manual actions - HomeKit should know
  // when the light has been turned on or off manually.

  // One way to accomplish would be via custom code added to the loop() method of your derived Service that monitors the button,
  // checks when it is pressed, debounces button noise, performs some actions when pressed, and informs HomeKit of the actions with
  // the setVal() method. Or you can use HomeSpan's built-in SpanButton() object.

  // 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.
  
  // 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.
  // 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:
  //
  //  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)

  // 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.    

  // 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.

  // Also in contrast with the loop method, the button() method takes two arguments, an int and a boolean, and should defined as follows:
  //
  // void button(int pin, boolean isLong)
  //
  // 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.
  //
  // 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...}
  //
  // 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.
  
  Serial.begin(115200);

  homeSpan.begin(Category::Bridges,"HomeSpan Bridge");

  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 SpanAccessory();                                                          
    new DEV_Identify("PushButton LED","HomeSpan","123-ABC","20mA LED","0.9",0);
    
    new DEV_DimmableLED(0,17,23,5,18);          // NEW! added three extra arguments to specify the pin numbers for three SpanButtons() - see DEV_LED.h
 
} // end of setup()

//////////////////////////////////////

void loop(){
  
  homeSpan.poll();
  
} // end of loop()