Seich
/
HomeSpan
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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.
This commit is contained in:
Gregg 2020-11-01 15:22:16 -06:00
parent e2f11630fa
commit c153824b95
3 changed files with 101 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
examples/15-RealPushButtons/15-RealPushButtons.ino
View File

@ -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);

74
examples/15-RealPushButtons/DEV_LED.h
View File

@ -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%
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.
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"
// 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,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,39 +90,66 @@ 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...
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(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%
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(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(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(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
}
} 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(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
}
}
// 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
// within HomeKit! We still need to take an action on the actual LED itself.
@ -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().

2
examples/16-ProgrammableSwitches/DEV_ProgButton.h
View File

@ -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");