diff --git a/examples/16-ProgrammableSwitches/16-ProgrammableSwitches.ino b/examples/16-ProgrammableSwitches/16-ProgrammableSwitches.ino index 3b9c92e..ecb3478 100644 --- a/examples/16-ProgrammableSwitches/16-ProgrammableSwitches.ino +++ b/examples/16-ProgrammableSwitches/16-ProgrammableSwitches.ino @@ -5,8 +5,6 @@ // ------------------------------------------------ // // // // Example 16: Stateless Programmable Switches // -// * using linked-services // -// // // // //////////////////////////////////////////////////////////// @@ -15,6 +13,27 @@ #include "DEV_Identify.h" void setup() { + + // Example 16 does not introduce any new HomeSpan functionality, but instead showcases a unique feature of HomeKit that you can readily access with HomeSpan. + // In all prior examples we used the ESP32 to control a local appliance - something connected directly to the ESP32 device. We've then seen how you can control + // the device via HomeKit's iOS or MacOS Home App, or by the addition of local pushbuttons connected directly to the ESP32 device. + + // In this example we do the opposite, and use buttons on the ESP32 to control OTHER HomeKit devices. + + // To do so, we use HomeKit's Stateless Programmable Switch Service. Similar to other read-only Services, such as the Temperature and Air Quality Sensors + // fully explored in Example 12, the Stateless Programmable Switch Service only listens for event notifications coming from HomeSpan and does not try to control + // or update anything on the HomeSpan Device. More specifically, the Stateless Programmable Switch Service listens for notifications of a SINGLE, DOUBLE, + // or LONG button press coming from HomeSpan. + + // What these button presses mean is outside the control of HomeSpan. Instead, you program their actions directly in the Home App. In this fashion, HomeSpan + // becomes a platform for generic buttons that you can program to control any other HomeKit accessory or even trigger HomeKit scenes. + + // Upon running this configuration and pairing to HomeKit, your Home App should reveal a new tile labeled "PushButton Switches." Clicking that tile will open up + // a new page where you can program the actions of each of the buttons. These actions can be changed at any time without any need to modify the HomeSpan code, + // or even reboot the device. + + // The code for this is quite simple, and as usual we've encapsulated all the functionality in a standalone file: DEV_ProgButton.h. Below we create two generic + // buttons, one connected to pin 23, and one connected to pin 5. See DEV_ProgButton.h for complete details. Serial.begin(115200); @@ -28,8 +47,13 @@ void setup() { new SpanAccessory(); new DEV_Identify("PushButton Switches","HomeSpan","123-ABC","Prog Switches","0.9",0); - new DEV_ProgButton(23,2); - new DEV_ProgButton(5,7); + // We've written DEV_ProgButton to take two arguments. The first is a pin number that DEV_ProgButton.h uses to create a SpanButton. The second is an index number + // that HomeKit uses as a label when you program the actions of each button in the Home App. The numbers do not have to be sequential, nor start with 1. They just need + // to be unique so HomeKit can distinguish them. Note that HomeKit does not require index numbers if you only have one Stateless Programmable Switch Service within any + // given Accessory. Since we have two, we must specify two unique index numbers. + + new DEV_ProgButton(23,1); // create Stateless Programmable Switch Service on pin 23 with index=1 + new DEV_ProgButton(5,2); // create Stateless Programmable Switch Service on pin 5 with index=2 } // end of setup() diff --git a/examples/16-ProgrammableSwitches/DEV_ProgButton.h b/examples/16-ProgrammableSwitches/DEV_ProgButton.h index f4396c9..22d58a7 100644 --- a/examples/16-ProgrammableSwitches/DEV_ProgButton.h +++ b/examples/16-ProgrammableSwitches/DEV_ProgButton.h @@ -9,8 +9,8 @@ struct DEV_ProgButton : Service::StatelessProgrammableSwitch { // Stateles DEV_ProgButton(int buttonPin, int index) : Service::StatelessProgrammableSwitch(){ - switchEvent=new Characteristic::ProgrammableSwitchEvent(); // ProgrammableSwitchEvent Characteristic - new Characteristic::ServiceLabelIndex(index); // set service label index + switchEvent=new Characteristic::ProgrammableSwitchEvent(); // Programmable Switch Event Characteristic (will be set to SINGLE, DOUBLE or LONG press) + new Characteristic::ServiceLabelIndex(index); // set service label index (only required if there is more than one Stateless Programmable Switch per Service) new SpanButton(buttonPin); // create new SpanButton @@ -22,6 +22,8 @@ struct DEV_ProgButton : Service::StatelessProgrammableSwitch { // Stateles } // end constructor + // We do NOT need to implement an update() method or a loop() method - just the button() method: + void button(int pin, int pressType) override { LOG1("Found button press on pin: "); // always a good idea to log messages @@ -30,6 +32,10 @@ struct DEV_ProgButton : Service::StatelessProgrammableSwitch { // Stateles LOG1(pressType==SpanButton::LONG?"LONG":(pressType==SpanButton::SINGLE)?"SINGLE":"DOUBLE"); LOG1("\n"); + // All the action occurs in this single line below. We simply set the value of the Programmable Switch Event Characteristic + // to the value provided by pressType. The values of pressType (0=SpanButton::SINGLE, 1=SpanButton::DOUBLE, and 2=SpanButton::LONG) + // were designed to match the required values of the Programmable Switch Event Characteristic. + switchEvent->setVal(pressType); // set the value of the switchEvent Characteristic }