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

Created Example 8

This commit is contained in:
Gregg 2020-07-26 11:36:14 -05:00
parent ce17b08d4d
commit fb0a8dacb7
3 changed files with 208 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
examples/Advanced/8-Bridges/8-Bridges.ino Normal file
View File

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

63
examples/Advanced/8-Bridges/DEV_Identify.h Normal file
View File

@ -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;i<nBlinks;i++){
digitalWrite(LED_BUILTIN,LOW);
delay(250);
digitalWrite(LED_BUILTIN,HIGH);
delay(250);
}
return(StatusCode::OK);
} // update
};

60
examples/Advanced/8-Bridges/DEV_LED.h Normal file
View File

@ -0,0 +1,60 @@
////////////////////////////////////
// DEVICE-SPECIFIC LED SERVICES //
////////////////////////////////////
#include "extras/PwmPin.h" // allows PWM control of LED brightness
struct DEV_LED : Service::LightBulb { // ON/OFF LED
int ledPin; // pin number defined for this LED
SpanCharacteristic *power; // reference to the On Characteristic
DEV_LED(int ledPin) : Service::LightBulb(){ // constructor() method
power=new Characteristic::On();
this->ledPin=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
};
//////////////////////////////////