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

Re-worked Examples 5-10 

Updated to reflect use of getVal(), getNewVal(), and updated(), intead of directly accessing the underlying member variables.
This commit is contained in:
Gregg 2020-08-04 21:58:57 -05:00
parent cf91f2c265
commit f2a5e5e4f5
16 changed files with 73 additions and 139 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
examples/Advanced/10-TimedResets/DEV_Blinker.h
View File

@ -35,7 +35,7 @@ struct DEV_Blinker : Service::LightBulb { // LED Blinker
// Note that in practice you'll want to set the reset time to 500ms or less to better emulate a pushbutton. // Note that in practice you'll want to set the reset time to 500ms or less to better emulate a pushbutton.
// We've used a full 2 seconds in this example for illustrative purposes only. // We've used a full 2 seconds in this example for illustrative purposes only.
new SpanTimedReset(1000); // *** NEW!! instantiate SpanTimedRest with a delay of 2000 milliseconds new SpanTimedReset(1000); // *** NEW!! instantiate SpanTimedReset with a delay of 2000 milliseconds
this->ledPin=ledPin; this->ledPin=ledPin;
this->nBlinks=nBlinks; // NEW! number of blinks this->nBlinks=nBlinks; // NEW! number of blinks
@ -55,11 +55,11 @@ struct DEV_Blinker : Service::LightBulb { // LED Blinker
// the number of times specified, and leave it in the off position when finished. // the number of times specified, and leave it in the off position when finished.
// This line is deleted... // This line is deleted...
// digitalWrite(ledPin,power->newValue.BOOL); // digitalWrite(ledPin,power->getNewVal());
// and is replaced by... // and is replaced by...
if(power->newValue.BOOL){ // check to ensure HomeKit is requesting we "turn on" this device (else ignore) if(power->getNewVal()){ // check to ensure HomeKit is requesting we "turn on" this device (else ignore)
LOG1("Activating the LED Blinker on pin="); LOG1("Activating the LED Blinker on pin=");
LOG1(ledPin); LOG1(ledPin);
@ -72,7 +72,7 @@ struct DEV_Blinker : Service::LightBulb { // LED Blinker
delay(250); // wait 250 ms delay(250); // wait 250 ms
} }
} // if power->newValue==true } // if newVal=true
// Note that the delays above of 100ms and 250ms are for illustrative purposes only // Note that the delays above of 100ms and 250ms are for illustrative purposes only
// (and so you can see the LED blink). In practice, if you were controlling an IR LED // (and so you can see the LED blink). In practice, if you were controlling an IR LED

25
examples/Advanced/10-TimedResets/DEV_Identify.h
View File

@ -3,17 +3,11 @@
// DEVICE-SPECIFIC SERVICES // // DEVICE-SPECIFIC SERVICES //
////////////////////////////////// //////////////////////////////////
// Here we define the DEV_Identify Service as derived class of AccessoryInformation
struct DEV_Identify : Service::AccessoryInformation { struct DEV_Identify : Service::AccessoryInformation {
int nBlinks; // number of times to blink built-in LED in identify routine int nBlinks; // number of times to blink built-in LED in identify routine
SpanCharacteristic *identify; // reference to the Identify Characteristic 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(){ 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::Name(name); // create all the required Characteristics with values set based on above arguments
@ -28,25 +22,6 @@ struct DEV_Identify : Service::AccessoryInformation {
pinMode(LED_BUILTIN,OUTPUT); // make sure built-in LED is set for output 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(){ StatusCode update(){
for(int i=0;i<nBlinks;i++){ for(int i=0;i<nBlinks;i++){

4
examples/Advanced/11-RGB_LED/11-RGB_LED.ino
View File

@ -16,9 +16,9 @@
void setup() { void setup() {
// Example 11 illustrates how to control an RGB LED to set any color and brightness. // Example 11 illustrates how to control an RGB LED to set any color and brightness.
// The config below should look familiar by now. We've created a new derived Service, // The configuration below should look familiar by now. We've created a new derived Service,
// call RgbLED to house all the required logic. You'll find all the code in DEV_LED.h. // call RgbLED to house all the required logic. You'll find all the code in DEV_LED.h.
// For completeness, the config also contains an on/off LED and a dimmable LED as shown // For completeness, this configuration also contains an on/off LED and a dimmable LED as shown
// in prior examples. // in prior examples.
Serial.begin(115200); Serial.begin(115200);

4
examples/Advanced/8-Bridges/8-Bridges.ino
View File

@ -58,7 +58,7 @@ void setup() {
// minute or more for all the blinking to finish while pairing. // minute or more for all the blinking to finish while pairing.
new SpanAccessory(); 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 DEV_Identify("On/Off LED","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 Service::HAPProtocolInformation(); - DELETED - NO LONGER NEEDED
// new Characteristic::Version("1.1.0"); - DELETED - NO LONGER NEEDED // new Characteristic::Version("1.1.0"); - DELETED - NO LONGER NEEDED
@ -67,7 +67,7 @@ void setup() {
new SpanAccessory(); 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 DEV_Identify("Dimmable LED","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 Service::HAPProtocolInformation(); - DELETED - NO LONGER NEEDED
// new Characteristic::Version("1.1.0"); - DELETED - NO LONGER NEEDED // new Characteristic::Version("1.1.0"); - DELETED - NO LONGER NEEDED

25
examples/Advanced/8-Bridges/DEV_Identify.h
View File

@ -3,17 +3,11 @@
// DEVICE-SPECIFIC SERVICES // // DEVICE-SPECIFIC SERVICES //
////////////////////////////////// //////////////////////////////////
// Here we define the DEV_Identify Service as derived class of AccessoryInformation
struct DEV_Identify : Service::AccessoryInformation { struct DEV_Identify : Service::AccessoryInformation {
int nBlinks; // number of times to blink built-in LED in identify routine int nBlinks; // number of times to blink built-in LED in identify routine
SpanCharacteristic *identify; // reference to the Identify Characteristic 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(){ 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::Name(name); // create all the required Characteristics with values set based on above arguments
@ -28,25 +22,6 @@ struct DEV_Identify : Service::AccessoryInformation {
pinMode(LED_BUILTIN,OUTPUT); // make sure built-in LED is set for output 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(){ StatusCode update(){
for(int i=0;i<nBlinks;i++){ for(int i=0;i<nBlinks;i++){

4
examples/Advanced/8-Bridges/DEV_LED.h
View File

@ -20,7 +20,7 @@ struct DEV_LED : Service::LightBulb { // ON/OFF LED
StatusCode update(){ // update() method StatusCode update(){ // update() method
digitalWrite(ledPin,power->newValue.BOOL); digitalWrite(ledPin,power->getNewVal());
return(StatusCode::OK); // return OK status code return(StatusCode::OK); // return OK status code
@ -50,7 +50,7 @@ struct DEV_DimmableLED : Service::LightBulb { // Dimmable LED
StatusCode update(){ // update() method StatusCode update(){ // update() method
pwmPin->set(channel,power->newValue.BOOL*level->newValue.INT); pwmPin->set(channel,power->getNewVal()*level->getNewVal());
return(StatusCode::OK); // return OK status code return(StatusCode::OK); // return OK status code

4
examples/Advanced/9-MessageLogging/9-MessageLogging.ino
View File

@ -51,13 +51,13 @@ void setup() {
// Defines an ON/OFF LED Accessory attached to pin 16 // Defines an ON/OFF LED Accessory attached to pin 16
new SpanAccessory(); new SpanAccessory();
new DEV_Identify("LED #1","HomeSpan","123-ABC","20mA LED","0.9",0); new DEV_Identify("On/Off LED","HomeSpan","123-ABC","20mA LED","0.9",0);
new DEV_LED(16); new DEV_LED(16);
// Defines a Dimmable LED Accessory attached to pin 17 using PWM channel 0 // Defines a Dimmable LED Accessory attached to pin 17 using PWM channel 0
new SpanAccessory(); new SpanAccessory();
new DEV_Identify("LED #2","HomeSpan","123-ABC","20mA LED","0.9",0); new DEV_Identify("Dimmable LED","HomeSpan","123-ABC","20mA LED","0.9",0);
new DEV_DimmableLED(0,17); new DEV_DimmableLED(0,17);
} // end of setup() } // end of setup()

25
examples/Advanced/9-MessageLogging/DEV_Identify.h
View File

@ -3,17 +3,11 @@
// DEVICE-SPECIFIC SERVICES // // DEVICE-SPECIFIC SERVICES //
////////////////////////////////// //////////////////////////////////
// Here we define the DEV_Identify Service as derived class of AccessoryInformation
struct DEV_Identify : Service::AccessoryInformation { struct DEV_Identify : Service::AccessoryInformation {
int nBlinks; // number of times to blink built-in LED in identify routine int nBlinks; // number of times to blink built-in LED in identify routine
SpanCharacteristic *identify; // reference to the Identify Characteristic 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(){ 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::Name(name); // create all the required Characteristics with values set based on above arguments
@ -28,25 +22,6 @@ struct DEV_Identify : Service::AccessoryInformation {
pinMode(LED_BUILTIN,OUTPUT); // make sure built-in LED is set for output 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(){ StatusCode update(){
for(int i=0;i<nBlinks;i++){ for(int i=0;i<nBlinks;i++){

20
examples/Advanced/9-MessageLogging/DEV_LED.h
View File

@ -37,12 +37,12 @@ struct DEV_LED : Service::LightBulb { // ON/OFF LED
LOG1("Updating On/Off LED on pin="); LOG1("Updating On/Off LED on pin=");
LOG1(ledPin); LOG1(ledPin);
LOG1(": Current Power="); LOG1(": Current Power=");
LOG1(power->value.BOOL?"true":"false"); LOG1(power->getVal()?"true":"false");
LOG1(" New Power="); LOG1(" New Power=");
LOG1(power->newValue.BOOL?"true":"false"); LOG1(power->getNewVal()?"true":"false");
LOG1("\n"); LOG1("\n");
digitalWrite(ledPin,power->newValue.BOOL); digitalWrite(ledPin,power->getNewVal());
return(StatusCode::OK); // return OK status code return(StatusCode::OK); // return OK status code
@ -97,9 +97,9 @@ struct DEV_DimmableLED : Service::LightBulb { // Dimmable LED
LOG1("Updating Dimmable LED on pin="); LOG1("Updating Dimmable LED on pin=");
LOG1(ledPin); LOG1(ledPin);
LOG1(": Current Power="); LOG1(": Current Power=");
LOG1(power->value.BOOL?"true":"false"); LOG1(power->getVal()?"true":"false");
LOG1(" Current Brightness="); LOG1(" Current Brightness=");
LOG1(level->value.INT); LOG1(level->getVal());
// Note that since Dimmable_LED has two updateable Characteristics, // Note that since Dimmable_LED has two updateable Characteristics,
// HomeKit may be requesting either or both to be updated. We can // HomeKit may be requesting either or both to be updated. We can
@ -109,19 +109,19 @@ struct DEV_DimmableLED : Service::LightBulb { // Dimmable LED
// one of the Characteristics in a Service, either power, level, or both // one of the Characteristics in a Service, either power, level, or both
// will have its "isUpdated" flag set. // will have its "isUpdated" flag set.
if(power->isUpdated){ if(power->updated()){
LOG1(" New Power="); LOG1(" New Power=");
LOG1(power->newValue.BOOL?"true":"false"); LOG1(power->getNewVal()?"true":"false");
} }
if(level->isUpdated){ if(level->updated()){
LOG1(" New Brightness="); LOG1(" New Brightness=");
LOG1(level->newValue.INT); LOG1(level->getNewVal());
} }
LOG1("\n"); LOG1("\n");
pwmPin->set(channel,power->newValue.BOOL*level->newValue.INT); pwmPin->set(channel,power->getNewVal()*level->getNewVal());
return(StatusCode::OK); // return OK status code return(StatusCode::OK); // return OK status code

8
examples/Intermediate/5-WorkingLED/5-WorkingLED.ino
View File

@ -22,8 +22,8 @@ void setup() {
// these control did not actually operate anything on the ESP32. To operate actual devices HomeSpan needs to be programmed to // these control did not actually operate anything on the ESP32. To operate actual devices HomeSpan needs to be programmed to
// respond to "update" requests from HomeKit by performing some form of operation. // respond to "update" requests from HomeKit by performing some form of operation.
// Though HomeKit sends "update' requests to individual Characteristics,this is not intuitive and leads to complex coding requirements // Though HomeKit sends "updat" requests to individual Characteristics, this is not intuitive and leads to complex coding requirements
// when a Service has more than one Characteristic, such as "On" and "Brightness." To make this MUCH easier for the user, HomeSpan // when a Service has more than one Characteristic, such as both "On" and "Brightness." To make this MUCH easier for the user, HomeSpan
// uses a framework in which Services are updated instead of individual Characteristics. It does so by calling the update() method of // uses a framework in which Services are updated instead of individual Characteristics. It does so by calling the update() method of
// each Service with flags indicating all the Characteristics in that Service that HomeKit requested to update. The user simply // each Service with flags indicating all the Characteristics in that Service that HomeKit requested to update. The user simply
// implements code to perform the actual operation, and returns a status flag (okay or not okay). HomeSpan takes care of all the underlying // implements code to perform the actual operation, and returns a status flag (okay or not okay). HomeSpan takes care of all the underlying
@ -34,7 +34,9 @@ void setup() {
// method with your own code. The easiest way to do this is by creating a DERIVED class based on one of the built-in HomeSpan Services. // method with your own code. The easiest way to do this is by creating a DERIVED class based on one of the built-in HomeSpan Services.
// Within this derived class you can perform initial set-up routines (if needed), over-ride the update() method with your own code, and even create // Within this derived class you can perform initial set-up routines (if needed), over-ride the update() method with your own code, and even create
// any other methods or class-specific variables you need to fully operate complex devices. Most importantly, the derived class can take arguments // any other methods or class-specific variables you need to fully operate complex devices. Most importantly, the derived class can take arguments
// so that you can make them more generic, re-use them multiple times (as will be seen below), and convert them to standalone modules (see Example 7). // so that you can make them more generic, re-use them multiple times (as will be seen below), and convert them to standalone modules (see below).
// All of the HomeKit Services implemented by HomeSpan can be found in the Services.h file. Any can be used as the parent for a derived Service.
// We begin by repeating nearly the same code from Example 2, but with a few key changes. For ease of reading, all prior comments have been removed // We begin by repeating nearly the same code from Example 2, but with a few key changes. For ease of reading, all prior comments have been removed
// from lines that simply repeat Example 2, and new comments have been added to explictly show the new code. // from lines that simply repeat Example 2, and new comments have been added to explictly show the new code.

63
examples/Intermediate/5-WorkingLED/DEV_LED.h
View File

@ -25,7 +25,7 @@ struct DEV_LED : Service::LightBulb { // First we create a derived
StatusCode update(){ StatusCode update(){
digitalWrite(ledPin,power->newValue.BOOL); // use a standard Arduino function to turn on/off ledPin based on the boolean variable power->newValue.BOOL (see below for more info) digitalWrite(ledPin,power->getNewVal()); // use a standard Arduino function to turn on/off ledPin based on the return of a call to power->getNewVal() (see below for more info)
return(StatusCode::OK); // return OK status code. There are other possibilties we will explore in later examples. return(StatusCode::OK); // return OK status code. There are other possibilties we will explore in later examples.
@ -34,7 +34,8 @@ struct DEV_LED : Service::LightBulb { // First we create a derived
////////////////////////////////// //////////////////////////////////
// How update() works: // HOW update() WORKS:
// ------------------
// //
// Whenever a HomeKit controller requests HomeSpan to update a Characteristic, HomeSpan calls the update() method for the SERVICE that contains the // Whenever a HomeKit controller requests HomeSpan to update a Characteristic, HomeSpan calls the update() method for the SERVICE that contains the
// Characteristic. It calls this only one time, even if multiple Characteristics updates are requested for that Service. For example, if you // Characteristic. It calls this only one time, even if multiple Characteristics updates are requested for that Service. For example, if you
@ -46,36 +47,41 @@ struct DEV_LED : Service::LightBulb { // First we create a derived
// that change at the same time. In the example above, we only have a single Characteristic to deal with, so this does not mean much. But in later // that change at the same time. In the example above, we only have a single Characteristic to deal with, so this does not mean much. But in later
// examples we'll see how this works with multiple Characteristics. // examples we'll see how this works with multiple Characteristics.
// How to access Characteristic values: // HOW TO ACCESS A CHARACTERISTIC'S NEW AND CURRENT VALUES
// -------------------------------------------------------
// //
// HomeSpan stores the values for its Characteristics in a union structure that allows for different types. The current value of a Characteristic // HomeSpan stores the values for its Characteristics in a union structure that allows for different types, such as floats, booleans, etc. The specific
// is stored in a union named "value" whereas upon an update request, the requested value is stored in a union named "newValue." To access the data // types are defined by HAP for each Characteristic. Looking up whether a Characteristic is a uint8 or uint16 can be tiresome, so HomeSpan abstracts
// underlying either "value" or "newValue" you need to select the element of the union that matches the type. This is arguably sloppy, but using // all these details. Since C++ adheres to strict variable typing, this is done through the use of template methods. Every Characteristic supports
// C++ templates did not seem to make the process any less cumbersome. The names of each element are based on those specified in HAP Table 6-5, and map // the following two methods:
// to the Arduino data types as follows:
// //
// BOOL -> (boolean) // getVal<type>() - returns the CURRENT value of the Characterisic, after casting into "type"
// UINT8 -> (uint8_t) // getNewVal<type>() - returns the NEW value (i.e. to be updated) of the Characteritic, after casting into "type"
// UINT16 -> (uint16_t)
// UINT32 -> (uint32_t)
// UINT64 -> (uint64_t)
// INT -> (int)
// FLOAT -> (double)
// STRING -> (const char *)
// //
// In the above example we created pointer named "power" to point to our newly-created "On" Characteristic. Hence, to access the current value of that // For example, MyChar->getVal<int>() returns the current value of SpanCharacterstic MyChar as an int, REGARDLESS of how the value is stored by HomeSpan.
// Characteristic we use "power->value.BOOL" To access to new value requested by HomeKit for this update, we use "power->newValue.BOOL" as shown above. // Similarly, MyChar->getVal<double>() returns a value as a double, even it is stored as as a boolean (in which case you'll either get 0.00 or 1.00).
// In most cases, we can manage the update by just reading the newValue requested, regardless of the whatever the current value is, but access to the // Of course you need to make sure you understand the range of expected values so that you don't try to access a value stored as 2-byte int using getVal<uint8_t>().
// current value is available if neeed. // But it's perfectly okay to use getVal<int>() to access the value of a Characteristic that HAP insists on storing as a float, even though its range is
// strictly between 0 and 100 in steps of 1. Knowing the range and step size is all you need to know in determining you can access this as an <int> or even a <uint8_t>.
//
// Because most Characteristic values can properly be cast into int, getVal and getNewVal both default to <int> if the template parameter is not specified.
// As you can see above, we retrieved the new value HomeKit requested for the On Characteristic that we named "power" by simply calling power->getNewVal().
// Since no template parameter is specified, getNewVal() will return an int. And since the On Characteristic is natively stored as a boolean, getNewVal()
// will either return a 0 or a 1, depending on whether HomeKit is requesting the Characteristic to be turned off or on.
//
// You may also note that in the above example we needed to use getNewVal(), but did not use getVal() anywhere. This is because we know exactly what
// to do if HomeKit requests an LED to be turned on or off. The current status of the LED (on or off) does not matter. In latter examples we will see
// instances where the current state of the device DOES matter, and we will need to access both current and new values.
//
// Finally, there is one additional method for Characteristics that is not used above but will be in later examples: updated(). This method returns a
// boolean indicating whether HomeKit has requested a Characteristic to be updated, which means that getNewVal() will contain the new value it wants to set
// for that Characteristic. For a Service with only one Characteristic, as above, we don't need to ask if "power" was updated using power->updated() because
// the fact the the update() method for the Service is being called means that HomeKit is requesting an update, and the only thing to update is "power".
// But for Services with two or more Characteristics, update() can be called with a request to update only a subset of the Characteristics. We will
// find good use for the updated() method in later, multi-Characteristic examples.
// How to determine the value type for any Characteristic: // WHAT THE RETURN CODE FOR update() MEANS
// // ---------------------------------------
// All HomeKit Characteristics that have been implemented in HomeSpan are defined in "Services.h" in the HomeSpan library. The top part of "Services.h" defines
// all the implemented Services. The bottom part defines the collection of Characteristics needed for those Services. Within the definition of each
// Characteristic you'll see the HAP ID number, as well as the data type, such as (boolean), (uint16_t), etc. Select the corresponding element name
// from the table above to access the underlying "value" or "newValue" data elements.
// What the return code means:
// //
// HomeKit requires each Characteristic to return a status code when an attempt to update it's value is made. HomeSpan automatically takes care of // HomeKit requires each Characteristic to return a status code when an attempt to update it's value is made. HomeSpan automatically takes care of
// some of errors, such as a Characteristic not being found, or a request to update a Characteristic that is read only. In these cases update() is never // some of errors, such as a Characteristic not being found, or a request to update a Characteristic that is read only. In these cases update() is never
@ -99,3 +105,4 @@ struct DEV_LED : Service::LightBulb { // First we create a derived
// Final note: There are very few reasons you should need to return an error code since so much checking is done in advance by either HomeSpan or HomeKit // Final note: There are very few reasons you should need to return an error code since so much checking is done in advance by either HomeSpan or HomeKit
// itself. For instance, HomeKit does not allow you to use the Controller, or even Siri, to change the brightness of LightBulb to a value outside the // itself. For instance, HomeKit does not allow you to use the Controller, or even Siri, to change the brightness of LightBulb to a value outside the
// range of allowable values you specified. This means that any update() requests you receive should only contain newValue data element that are in-range. // range of allowable values you specified. This means that any update() requests you receive should only contain newValue data element that are in-range.
//

4
examples/Intermediate/6-DimmableLED/6-DimmableLED.ino
View File

@ -38,7 +38,7 @@ void setup() {
new SpanAccessory(); new SpanAccessory();
new Service::AccessoryInformation(); new Service::AccessoryInformation();
new Characteristic::Name("LED #1"); new Characteristic::Name("On/Off LED");
new Characteristic::Manufacturer("HomeSpan"); new Characteristic::Manufacturer("HomeSpan");
new Characteristic::SerialNumber("123-ABC"); new Characteristic::SerialNumber("123-ABC");
new Characteristic::Model("20mA LED"); new Characteristic::Model("20mA LED");
@ -53,7 +53,7 @@ void setup() {
new SpanAccessory(); new SpanAccessory();
new Service::AccessoryInformation(); new Service::AccessoryInformation();
new Characteristic::Name("LED #2"); new Characteristic::Name("Dimmable LED");
new Characteristic::Manufacturer("HomeSpan"); new Characteristic::Manufacturer("HomeSpan");
new Characteristic::SerialNumber("123-ABC"); new Characteristic::SerialNumber("123-ABC");
new Characteristic::Model("20mA LED"); new Characteristic::Model("20mA LED");

4
examples/Intermediate/6-DimmableLED/DEV_LED.h
View File

@ -20,7 +20,7 @@ struct DEV_LED : Service::LightBulb { // ON/OFF LED
StatusCode update(){ // update() method StatusCode update(){ // update() method
digitalWrite(ledPin,power->newValue.BOOL); digitalWrite(ledPin,power->getNewVal());
return(StatusCode::OK); // return OK status code return(StatusCode::OK); // return OK status code
@ -60,7 +60,7 @@ struct DEV_DimmableLED : Service::LightBulb { // Dimmable LED
// newValue of the Brightness Characteristic (as an int) is a short-hand way of creating the logic to // newValue of the Brightness Characteristic (as an int) is a short-hand way of creating the logic to
// set the PWM level when the LED is off (always zero) or on (whatever the brightness level is). // set the PWM level when the LED is off (always zero) or on (whatever the brightness level is).
pwmPin->set(channel,power->newValue.BOOL*level->newValue.INT); pwmPin->set(channel,power->getNewVal()*level->getNewVal());
return(StatusCode::OK); // return OK status code return(StatusCode::OK); // return OK status code

8
examples/Intermediate/7-IdentifyRoutines/7-IdentifyRoutines.ino
View File

@ -39,7 +39,7 @@ void setup() {
// we'll delete these line (comment them out)... // we'll delete these line (comment them out)...
// new Service::AccessoryInformation(); // new Service::AccessoryInformation();
// new Characteristic::Name("LED #1"); // new Characteristic::Name("On/Off LED");
// new Characteristic::Manufacturer("HomeSpan"); // new Characteristic::Manufacturer("HomeSpan");
// new Characteristic::SerialNumber("123-ABC"); // new Characteristic::SerialNumber("123-ABC");
// new Characteristic::Model("20mA LED"); // new Characteristic::Model("20mA LED");
@ -50,7 +50,7 @@ void setup() {
// details on how this is defined. Note there is an extra argument at the end we set to 3. // details on how this is defined. Note there is an extra argument at the end we set to 3.
// This optional argument will be used to run the identify routine (see code for details) // This optional argument will be used to run the identify routine (see code for details)
new DEV_Identify("LED #1","HomeSpan","123-ABC","20mA LED","0.9",3); // NEW! This implements all the Characteristics above new DEV_Identify("On/Off LED","HomeSpan","123-ABC","20mA LED","0.9",3); // NEW! This implements all the Characteristics above
new Service::HAPProtocolInformation(); new Service::HAPProtocolInformation();
new Characteristic::Version("1.1.0"); new Characteristic::Version("1.1.0");
@ -62,7 +62,7 @@ void setup() {
// Same as above, we can replace all of this... // Same as above, we can replace all of this...
// new Service::AccessoryInformation(); // new Service::AccessoryInformation();
// new Characteristic::Name("LED #2"); // new Characteristic::Name("Dimmable LED");
// new Characteristic::Manufacturer("HomeSpan"); // new Characteristic::Manufacturer("HomeSpan");
// new Characteristic::SerialNumber("123-ABC"); // new Characteristic::SerialNumber("123-ABC");
// new Characteristic::Model("20mA LED"); // new Characteristic::Model("20mA LED");
@ -71,7 +71,7 @@ void setup() {
// ...with this (note we set last argument to 5 this time - see code for what this does) // ...with this (note we set last argument to 5 this time - see code for what this does)
new DEV_Identify("LED #2","HomeSpan","123-ABC","20mA LED","0.9",5); // NEW! This implements all the Characteristics above new DEV_Identify("Dimmable LED","HomeSpan","123-ABC","20mA LED","0.9",5); // NEW! This implements all the Characteristics above
new Service::HAPProtocolInformation(); new Service::HAPProtocolInformation();
new Characteristic::Version("1.1.0"); new Characteristic::Version("1.1.0");

4
examples/Intermediate/7-IdentifyRoutines/DEV_LED.h
View File

@ -20,7 +20,7 @@ struct DEV_LED : Service::LightBulb { // ON/OFF LED
StatusCode update(){ // update() method StatusCode update(){ // update() method
digitalWrite(ledPin,power->newValue.BOOL); digitalWrite(ledPin,power->getNewVal());
return(StatusCode::OK); // return OK status code return(StatusCode::OK); // return OK status code
@ -50,7 +50,7 @@ struct DEV_DimmableLED : Service::LightBulb { // Dimmable LED
StatusCode update(){ // update() method StatusCode update(){ // update() method
pwmPin->set(channel,power->newValue.BOOL*level->newValue.INT); pwmPin->set(channel,power->getNewVal()*level->getNewVal());
return(StatusCode::OK); // return OK status code return(StatusCode::OK); // return OK status code

2
src/extras/PwmPin.h
View File

@ -20,6 +20,6 @@ class PwmPin {
void set(uint8_t channel, uint8_t level); // sets the PWM duty of channel to level (0-100) void set(uint8_t channel, uint8_t level); // sets the PWM duty of channel to level (0-100)
int getPin(){return pin;} // returns the pin number int getPin(){return pin;} // returns the pin number
static void HSVtoRGB(float h, float s, float v, float *r, float *g, float *b ); static void HSVtoRGB(float h, float s, float v, float *r, float *g, float *b ); // converts Hue/Saturation/Brightness to R/G/B
}; };