From fb0a8dacb7f676c86245694ababceedd71964cbe Mon Sep 17 00:00:00 2001 From: Gregg Date: Sun, 26 Jul 2020 11:36:14 -0500 Subject: [PATCH] Created Example 8 --- examples/Advanced/8-Bridges/8-Bridges.ino | 85 ++++++++++++++++++++++ examples/Advanced/8-Bridges/DEV_Identify.h | 63 ++++++++++++++++ examples/Advanced/8-Bridges/DEV_LED.h | 60 +++++++++++++++ 3 files changed, 208 insertions(+) create mode 100644 examples/Advanced/8-Bridges/8-Bridges.ino create mode 100644 examples/Advanced/8-Bridges/DEV_Identify.h create mode 100644 examples/Advanced/8-Bridges/DEV_LED.h diff --git a/examples/Advanced/8-Bridges/8-Bridges.ino b/examples/Advanced/8-Bridges/8-Bridges.ino new file mode 100644 index 0000000..1d97160 --- /dev/null +++ b/examples/Advanced/8-Bridges/8-Bridges.ino @@ -0,0 +1,85 @@ + +//////////////////////////////////////////////////////////// +// // +// HomeSpan: A HomeKit implementation for the ESP32 // +// ------------------------------------------------ // +// // +// Example 8: HomeKit Bridges and Bridge Accessories // +// ** the preferred method for HomeSpan ** // +// // +//////////////////////////////////////////////////////////// + +#include "HomeSpan.h" +#include "DEV_LED.h" +#include "DEV_Identify.h" + +void setup() { + + // Though we've seen in prior examples that one device can support multiple Accessories, HomeKit provides a more + // general multi-Accessory framework that is somewhat more robust and easier to use: HomeKit Bridges. + // A Bridge is a device that includes multiple Accessories, except that the FIRST defined Accessory contains + // nothing but the AccessoryInformation Service and the HAPProtcolInformation Service. When such a device is paired + // to HomeKit, it is automatically recognized as a Bridge. All of the other Accessories defined in the device are + // associated with this Bridge. If you unpair the Bridge from HomeKit, all associated Accessories are automatically + // removed. + // + // Adding, editing, and deleting the other Accessories occurs in the same manner as before, but because the device + // is paired as a Bridge, changes to the other Accessories is less likely to require you to un-pair and re-pair + // the device. HomeKit seems to be able to better process changes when they are done within a Bridge framework. + // + // One added bonus is that the HAPProtcolInformation Service only needs to be defined for the Bridge Accessory, and + // does not need to be repeated for other Accessories. + // + // Example 8 is functionally identical to Example 7, except that instead of defined two Accessories (one for the on/off + // LED and one for the dimmable LED), we define three Accessories, where the first acts as the Bridge. + + // As usual, all previous comments have been deleted and only new changes from the previous example are shown. + + // NOTE: To see how this works in practice, you'll need to unpair your device and re-pair it once the new code is loaded. + + Serial.begin(115200); + + homeSpan.begin(Category::Bridges,"HomeSpan Bridge"); // CHANGED! Note that we replaced Category::Lighting with Bridges (this changes the icon when pairing) + + // We begin by creating a Bridge Accessory, which look just like any other Accessory, + // except that is only contains DEV_Identify (which is derived from AccessoryInformation) + // and HAPProtcolInformation (required). Note that HomeKit will still call the identify + // update() routine upon pairing, so we specify the number of blinks to be 3. + + new SpanAccessory(); + new DEV_Identify("Bridge #1","HomeSpan","123-ABC","HS Bridge","0.9",3); + new Service::HAPProtocolInformation(); + new Characteristic::Version("1.1.0"); + + // Now we simply repeat the definitions of the previous LED Accessories, as per Example 7, with two exceptions: + // 1) We no longer need to include the HAPProtocolInformation Service. + // 2) We will set the number of blinks to zero, so that only the bridge accessory will cause the Built-In + // LED to blink. This becomes especially important if you had 20 Accessories defined and needed to wait a + // minute or more for all the blinking to finish while pairing. + + new SpanAccessory(); + new DEV_Identify("LED #1","HomeSpan","123-ABC","20mA LED","0.9",0); // CHANGED! The number of blinks is now set to zero + + // new Service::HAPProtocolInformation(); - DELETED - NO LONGER NEEDED + // new Characteristic::Version("1.1.0"); - DELETED - NO LONGER NEEDED + + new DEV_LED(16); // create an on/off LED attached to pin 16 + + new SpanAccessory(); + + new DEV_Identify("LED #2","HomeSpan","123-ABC","20mA LED","0.9",0); // CHANGED! The number of blinks is now set to zero + + // new Service::HAPProtocolInformation(); - DELETED - NO LONGER NEEDED + // new Characteristic::Version("1.1.0"); - DELETED - NO LONGER NEEDED + + new DEV_DimmableLED(0,17); // create a dimmable LED attached to pin 17 using PWM channel 0 + +} // end of setup() + +////////////////////////////////////// + +void loop(){ + + homeSpan.poll(); + +} // end of loop() diff --git a/examples/Advanced/8-Bridges/DEV_Identify.h b/examples/Advanced/8-Bridges/DEV_Identify.h new file mode 100644 index 0000000..17cd16f --- /dev/null +++ b/examples/Advanced/8-Bridges/DEV_Identify.h @@ -0,0 +1,63 @@ + +////////////////////////////////// +// DEVICE-SPECIFIC SERVICES // +////////////////////////////////// + +// Here we define the DEV_Identify Service as derived class of AccessoryInformation + +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 + + // Next we define the constructor using all the arguments needed to implement the required Characteristics + // of AccessoryInformation, plus one extra argument at the end called "nBlinks" we will use to specify how many + // times HomeSpan should blink the built-in LED when HomeKit calls this device's Identify routine during pairing. + + 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 + } + + // How HomeKit Identifies Devices: + // + // When HomeKit first pairs with a new device it "calls" that device's identify routine for every defined Accessory. + // To do so, HomeKit requests the Identify Characteristic for each defined AccessoryInformation Service to be set to "true". + // The Identify Characteristic is write-only, so no value is ever stored, even though HomeKit is requesting its value + // be updated. We can therefore use the same update() method as if the Identify Characteristic was the same as any + // other boolean Characteristic. + + // There are many ways to implement some form of identification. For an LED, you could blink it one or more times. + // For a LightBulb, you can flash it on and off. For window shade, you could raise and lower it. + // Most commerical devices don't do anything. Because HomeSpan can be used to control many different types of + // device, below we implement a very generic routine that simply blinks the internal LED of the ESP32 the + // number of times specified above. In principle, this code could call a user-defined routine that is different + // for each physcially-attached device (light, shade, fan, etc), but in practice this is overkill. + + // Note that the blink routine below starts by turning off the built-in LED and then leaves it on once it has blinked + // the specified number of times. This is because when HomeSpan starts up if confirms to user that it has connected + // to the WiFi network by turning on the built-in LED. Thus we want to leave it on when blinking is completed. + + StatusCode update(){ + + for(int i=0;iledPin=ledPin; + pinMode(ledPin,OUTPUT); + + } // end constructor + + StatusCode update(){ // update() method + + digitalWrite(ledPin,power->newValue.BOOL); + + return(StatusCode::OK); // return OK status code + + } // update +}; + +////////////////////////////////// + +struct DEV_DimmableLED : Service::LightBulb { // Dimmable LED + + PwmPin *pwmPin; // reference to PWM Pin + 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 + + DEV_DimmableLED(int channel, int ledPin) : Service::LightBulb(){ // constructor() method + + 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% + + this->channel=channel; // save the channel number (from 0-15) + this->pwmPin=new PwmPin(channel, ledPin); // configure the PWM channel and attach the specified ledPin. pinMode() does NOT need to be called. + + } // end constructor + + StatusCode update(){ // update() method + + pwmPin->set(channel,power->newValue.BOOL*level->newValue.INT); + + return(StatusCode::OK); // return OK status code + + } // update +}; + +//////////////////////////////////