diff --git a/examples/Expert/14-TargetStates/14-TargetStates.ino b/examples/Expert/14-TargetStates/14-TargetStates.ino new file mode 100644 index 0000000..f61574f --- /dev/null +++ b/examples/Expert/14-TargetStates/14-TargetStates.ino @@ -0,0 +1,96 @@ + +//////////////////////////////////////////////////////////// +// // +// HomeSpan: A HomeKit implementation for the ESP32 // +// ------------------------------------------------ // +// // +// Example 14: Target States and Current States // +// // +//////////////////////////////////////////////////////////// + +#include "HomeSpan.h" +#include "DEV_Identify.h" +#include "DEV_Sensors.h" +#include "DEV_Doors.h" + +void setup() { + + // HomeKit is designed for two-way communication: HomeSpan devices not only receive and act on operational instructions from HomeKit Controllers, but + // HomeSpan can also send HomeKit unsolicited messages regarding changes to the state of the device. Though it may not be apparent, this has already been + // ocurring in the background in all prior examples. This is because when a HomeKit Controller sends an operational request to any HomeKit device, it expects + // to receive a status message back indicating whether the request was successful or not. This is the purpose of returning StatusCode:OK in custom update() + // methods. With this information returned, HomeKit can update its own status and properly reflect a change in the device, such as by showing a light is now + // turned on instead of off. However, HomeKit unfortunately does NOT inform any other HomeKit Controllers of this new information. So if you have two iPhones + // and use one to turn on a light, the other first iPhone does not relay a message to the second iPhone that a light has been turned on. This is the case even + // if you are using an AppleTV or HomePod as a central hub for HomeKit. + + // Normally this does not matter much, since the second iPhone will naturally update itself as to the status of all HomeKit devices as soon as the HomeKit + // application is launched on that iPhone. It does this by sending every HomeKit device a message asking for a status update. In this fashion the second + // iPhone quickly synchronizes itself as soon as the HomeKit app is opened, but ONLY when it is first opened (or re-opened if you first close it). But if you + // have two iPhones BOTH opened to the HomeKit app (or one iPhone and one Mac opened to the HomeKit app) and you use one Controller app to turn on a light, the + // resulting change in status of that light will NOT be reflected in the second Controller app, unless you close tha app and re-open (at which point it goes + // through the request procedure discussed above). This is very annoying and counterintuitive. + + // Fortunately, HomeKit provides a solution to this in the form of an Event Notification protcol. This protcol allows a device to send unsoliciated messages + // to all Controllers that have previously registered themselves with the device indicating the Characteristics for which they would like to receive an event + // message from the device whenever there is a change in the status of one or more of those Characteristics. + + // The good news is that HomeSpan takes care of this automatically. To see this for yourself, use two iPhones (or an iPhone and Mac) with any of the previous examples + // and open the HomeKit app on both. Any changes you make to the device using one of the Controllers, such as turning on an LED, is immediately reflected + // in the other Controller. Not quite magic, but close. + + // A different use of Event Notifications was also working behind in the scenes in Example 10 - Timed Resets. In this case, HomeSpan sent an unsolited Event message + // to all registered Controllers letting them know that a device that was previously turned on, is now in fact turned off. + + // In this Example 13 we explore the explicit use of Event Notifications to support Services that require constants updates from the device to all HomeKit Controllers. + // The two Services we will use below are a Temperature Sensor and an Air Quality Sensor. Neither of these Services have any operational controls. They cannot be + // turn on or off, or operated in any way. As such, they do not need to implement an update() method, since HomeKit Controllers will never ask them to change + // any of their Characteristics. + + // Rather, HomeKit is expecting to get periodic Event Notification messages from such Services so that the HomeKit Controllers can accurately reflect the status + // and values of the Characteristics for those Services, such as the temperature, in the HomeKit Controller. + + // There are two steps to accomplishing this. The first is to implement an event() method for each Service that uses a setVal() function to change the values + // for one or more Characteristics for that Service. The second step is to instantiate a new SpanEvent() object for each Service that you want HomeSpan to invoke your + // event() method. The SpanEvent object take only one argument - the number of milliseconds to wait between calls to a Service's event() method. + + // As usual, all of the logic for this is encapsulated in new standalone derived Services. You'll find fully-commented definitions for the DEV_TempSensor() and + // the DEV_AirQualitySensor() Services instantiated below, in the DEV_Sensors.h file. Note that this example is for instructional purposes only -- we do not actually + // connect a Temperature Sensor or Air Quality Sensor to our ESP32 device. As such, we did not define the Services to take any arguments to specify pin numbers or any + // other information needed to implement an actual sensor. Instead, in order to see how real a device would work, we will send Event messages by manufacturing simulated + // updates. See DEV_Sensors.h for complete details. + + // Once you understand these examples, you should be able to use Event Notifications for any combination of HomeKit Services with Characteristics that require your device to + // send periodic update messages to HomeKit Controllers, ranging from Smoke Alarms to Door Sensors. + + Serial.begin(115200); + + homeSpan.begin(Category::Bridges,"HomeSpan Bridge"); + + + new SpanAccessory(); + new DEV_Identify("Bridge #1","HomeSpan","123-ABC","HS Bridge","0.9",3); + new Service::HAPProtocolInformation(); + new Characteristic::Version("1.1.0"); + + new SpanAccessory(); + new DEV_Identify("Temp Sensor","HomeSpan","123-ABC","Sensor","0.9",0); + new DEV_TempSensor(); // Create a Temperature Sensor (see DEV_Sensors.h for definition) + + new SpanAccessory(); + new DEV_Identify("Air Quality","HomeSpan","123-ABC","Sensor","0.9",0); + new DEV_AirQualitySensor(); // Create an Air Quality Sensor (see DEV_Sensors.h for definition) + + new SpanAccessory(); + new DEV_Identify("Garage Door","HomeSpan","123-ABC","Door","0.9",0); + new DEV_GarageDoor(); // Create a Garage Door Opener (see DEV_Doors.h for definition) + +} // end of setup() + +////////////////////////////////////// + +void loop(){ + + homeSpan.poll(); + +} // end of loop() diff --git a/examples/Expert/14-TargetStates/DEV_Doors.h b/examples/Expert/14-TargetStates/DEV_Doors.h new file mode 100644 index 0000000..ac24817 --- /dev/null +++ b/examples/Expert/14-TargetStates/DEV_Doors.h @@ -0,0 +1,53 @@ + +//////////////////////////////////// +// DEVICE-SPECIFIC LED SERVICES // +//////////////////////////////////// + +struct DEV_GarageDoor : Service::GarageDoorOpener { // A Garage Door Opener + + SpanCharacteristic *current; + SpanCharacteristic *target; + SpanCharacteristic *obstruction; + + unsigned long alarmTime; + + DEV_GarageDoor(ServiceType sType=ServiceType::Regular) : Service::GarageDoorOpener(sType){ // constructor() method + + new SpanEvent(1000); // check for events on this Service every 1 second + + current=new Characteristic::CurrentDoorState(0); + target=new Characteristic::TargetDoorState(0); + obstruction=new Characteristic::ObstructionDetected(false); + + Serial.print("Configuring Garage Door Opener"); // initialization message + Serial.print("\n"); + + } // end constructor + + StatusCode update(){ // update() method + + if(target->getNewVal()==0){ + LOG1("Opening Garage Door\n"); + current->setVal(2); + } else { + LOG1("Closing Garage Door\n"); + current->setVal(3); + } + + alarmTime=millis()+10000; + + return(StatusCode::OK); // return OK status code + + } // update + + void event(){ // event() method + + if(current->getVal()==target->getVal()) + return; + + if(millis()>alarmTime) + current->setVal(target->getVal()); + + } // event + +}; diff --git a/examples/Expert/14-TargetStates/DEV_Identify.h b/examples/Expert/14-TargetStates/DEV_Identify.h new file mode 100644 index 0000000..95ba92a --- /dev/null +++ b/examples/Expert/14-TargetStates/DEV_Identify.h @@ -0,0 +1,40 @@ + +////////////////////////////////// +// DEVICE-SPECIFIC SERVICES // +////////////////////////////////// + +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 + + // NEW! modified constructor() method to include optional ServiceType argument + + DEV_Identify(char *name, char *manu, char *sn, char *model, char *version, int nBlinks, ServiceType sType=ServiceType::Regular) : Service::AccessoryInformation(sType){ + + 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 + } + + StatusCode update(){ + + for(int i=0;i as the template parameter; + // add 0.5 degrees Celsius; and then store the result in a float variable named "temperature." This will simulate an increment of + // 0.5 degrees Celsius (a little less than 1 degree F) every 5 seconds. We will cap the temperature to 35.0 degrees C, after which + // it resets to 10.0 and starts over. + + // All of the action happens in the last line, in which we set the value of the temp Characteristic to the new value of temperature. + // This tells HomeKit to send an Event Notification message to all available Controllers making them aware of the new temperature. + // Note that setVal() is NOT a template function and does not require you to specify as a template parameter. This is because + // setVal() can determine the type from the argument you specify. If there is any chance of ambiguity, you can always specifically + // cast the argument such: setVal((float)temperature). + + void event(){ + + float temperature=temp->getVal()+0.5; // here we "simulate" a half-degree temperature change... + if(temperature>35.0) // ...but cap the maximum at 35 degrees before starting over at 10 degrees + temperature=10.0; + + temp->setVal(temperature); // don't forgot to update the temperature Characteristic to the new value! + + } // event + +}; + +////////////////////////////////// + +struct DEV_AirQualitySensor : Service::AirQualitySensor { // A standalone Air Quality sensor + + // An Air Quality Sensor is similar to a Temperature Sensor except that it supports a wide variety of measurements. + // We will use three of them. The first is required, the second two are optional. + + SpanCharacteristic *airQuality; // reference to the Air Quality Characteristic, which is an integer from 0 to 5 + SpanCharacteristic *o3Density; // reference to the Ozone Density Characteristic, which is a float from 0 to 1000 + SpanCharacteristic *no2Density; // reference to the Nitrogen Dioxide Characteristic, which is a float from 0 to 1000 + + DEV_AirQualitySensor(ServiceType sType=ServiceType::Regular) : Service::AirQualitySensor(sType){ // constructor() method + + new SpanEvent(10000); // check for events on this Service every 10 seconds + + airQuality=new Characteristic::AirQuality(1); // instantiate the Air Quality Characteristic and set initial value to 1 + o3Density=new Characteristic::OzoneDensity(300.0); // instantiate the Ozone Density Characteristic and set initial value to 300.0 + no2Density=new Characteristic::NitrogenDioxideDensity(700.0); // instantiate the Nitrogen Dioxide Density Characteristic and set initial value to 700.0 + + Serial.print("Configuring Air Quality Sensor"); // initialization message + Serial.print("\n"); + + } // end constructor + + void event(){ + + airQuality->setVal((airQuality->getVal()+1)%6); // simulate a change in Air Quality by incrementing the current value by one, and keeping in range 0-5 + o3Density->setVal((double)random(200,500)); // change the Ozone Density to some random value between 200 and 499. Note use of (double) cast since random returns an integer + + // Note we are NOT updating the Nitrogen Dioxide Density Characteristic. This should therefore remain steady at its initial value of 700.0 + + } // event +}; + +////////////////////////////////// + +// What you should see in your HomeKit Application +// ----------------------------------------------- + +// If you load the above example, your HomeKit App should display two new tiles: one labeled "Temp Sensor" and the other labeled "Air Quality". +// The Temp Sensor tile should indicate a temperature in the range of 10C to 35C (50F to 95F), which automatically increments and updates 0.5C every 5 seconds. +// The Air Quality tile should cycle through "quality" states once every 10 seconds. States are displayed in HomeKit as "Unknown", "Excellent", "Good", "Fair", +// "Inferior" and "Poor". + +// Note that HomeKit only displays the values of a subset of Characteristics within the tile itself. In the case of an Air Quality Sensor, +// only the quality state of the Air Quality is displayed. To see the values of other Characteristics, such as Ozone Density and Nitrogen Dioxide Density, you need to click +// on the tile, AND open the settings screen (it would be nicer if HomeKit displayed these values on the control screen instead of making you open the settings screen). +// On the setting screen you should see the values of all three of the Characteristics we instantiated: Air Quality, Nitrogen Dioxide Density, and Ozone Density. +// Both the Air Quality and Ozone Density should change every 10 seconds. The Nitrogen Dioxide Density should remain steady at the initial value of 700.0, since we +// never use setVal() to update this Characteristic. + +// If you run HomeSpan at a VERBOSITY level of 2 (as specified in the library's Settings.h file), you can see that under the hood HomeSpan is sending Event Notification +// messages to all registered controllers every 5 seconds for the Temp Sensor, and every 10 seconds for the Air Quality Sensor. If you look carefully you'll see that +// the Event Notification message for the Air Quality Sensor only include two values - one for the Air Quality state and one for the Ozone Density. HomeSpan is NOT +// sending a value for the Nitrogen Dioxide Density Characteristic since it has not been changed with a setVal() function. This is an important design feature and +// shows that the instantiation of a new SpanEvent only determines how often the event() method is checked by HomeSpan, not whether Event Notifications are actually sent. +// If the event() method ALWAYS updates a Characteristic, then an Event Notification will always be generated. However, if event() does not update a Characteristic, +// or only updates it under certain circumstances, then no message will be generated. This allows you to create a SpanEvent that frequenty checks a Service for an +// event update, without generating Event Notifications that simply repeat the existing value of a Characteristic. We will see how this comes into play in the next example. + +// FINAL NOTE: The number of decimals HomeKit displays for temperature in the HomeKit app is independent of the step size of the value itself. This seems to be +// hardcoded by HomeKit: for Fahrenheit a Temperature Sensor tile shows no decimals and ROUNDS to the nearest whole degree (e.g. 72, 73, 74 degrees); for Celsius +// the tile allows for half-degree resolution and ROUNDS accordingly (e.g. 22.7 is displayed as 22.5 and 22.8 is displayed as 23.0). diff --git a/src/Services.h b/src/Services.h index d89c04d..5a8da1c 100644 --- a/src/Services.h +++ b/src/Services.h @@ -89,6 +89,8 @@ namespace Characteristic { struct ColorTemperature : SpanCharacteristic { ColorTemperature(uint32_t value=50) : SpanCharacteristic{"CE",PR+PW+EV,(uint32_t)value}{} }; + struct CurrentDoorState : SpanCharacteristic { CurrentDoorState(uint8_t value=1) : SpanCharacteristic{"E",PR+EV,(uint8_t)value}{} }; + struct CurrentTemperature : SpanCharacteristic { CurrentTemperature(double value=0) : SpanCharacteristic{"11",PR+EV,(double)value}{} }; struct FirmwareRevision : SpanCharacteristic { FirmwareRevision(char *value) : SpanCharacteristic{"52",PR,(char *)value}{} }; @@ -105,6 +107,8 @@ namespace Characteristic { struct NitrogenDioxideDensity : SpanCharacteristic { NitrogenDioxideDensity(double value=0) : SpanCharacteristic{"C4",PR+EV,(double)value}{} }; + struct ObstructionDetected : SpanCharacteristic { ObstructionDetected(boolean value=false) : SpanCharacteristic{"24",PR+EV,(boolean)value}{} }; + struct On : SpanCharacteristic { On(boolean value=false) : SpanCharacteristic{"25",PR+PW+EV,(boolean)value}{} }; struct OutletInUse : SpanCharacteristic { OutletInUse(boolean value=false) : SpanCharacteristic{"26",PR+EV,(boolean)value}{} }; @@ -141,6 +145,8 @@ namespace Characteristic { struct SwingMode : SpanCharacteristic { SwingMode(uint8_t value=0) : SpanCharacteristic{"B6",PR+PW+EV,(uint8_t)value}{} }; + struct TargetDoorState : SpanCharacteristic { TargetDoorState(uint8_t value=1) : SpanCharacteristic{"32",PR+PW+EV,(uint8_t)value}{} }; + struct TemperatureDisplayUnits : SpanCharacteristic { TemperatureDisplayUnits(uint8_t value=0) : SpanCharacteristic{"36",PR+PW+EV,(uint8_t)value}{} }; struct Version : SpanCharacteristic { Version(char *value) : SpanCharacteristic{"37",PR,(char *)value}{} };