diff --git a/examples/01-SimpleLightBulb/01-SimpleLightBulb.ino b/examples/01-SimpleLightBulb/01-SimpleLightBulb.ino index d17197d..8f1a706 100644 --- a/examples/01-SimpleLightBulb/01-SimpleLightBulb.ino +++ b/examples/01-SimpleLightBulb/01-SimpleLightBulb.ino @@ -66,30 +66,37 @@ void setup() { // Your HomeSpan code should be placed within the // The HomeSpan library creates a global object named "homeSpan" that encapsulates all HomeSpan functionality. // The begin() method is used to initialize HomeSpan and start all HomeSpan processes. - // The first two parameters are Category and Name, which are used by HomeKit to configure the icon and name of the device shown in your Home App - // when initially pairing your device. + // The first two parameters are Category and Name, which are used by HomeKit to configure the icon and name + // of the device shown in the Home App when initially pairing a HomeSpan device with your iPhone. + + // In addition, the Name you choose below will be used as the "default name" for all Accessory Tiles. When you first + // pair the device, the Home App will display this default name and allow you to change it (for each Accessory Tile) + // before pairing is complete. However, even after the device is paired you can always change the name of any + // Accessory Tile directly from the Home App via the set-up screen for any Tile. + + // IMPORTANT: The Name you choose below MUST BE UNIQUE across all your HomeSpan devices! homeSpan.begin(Category::Lighting,"HomeSpan LightBulb"); // initializes a HomeSpan device named "HomeSpan Lightbulb" with Category set to Lighting // Next, we construct a simple HAP Accessory Database with a single Accessory containing 3 Services, // each with their own required Characteristics. - new SpanAccessory(); // Begin by creating a new Accessory using SpanAccessory(), which takes no arguments - - new Service::AccessoryInformation(); // HAP requires every Accessory to implement an AccessoryInformation Service, which has 6 required Characteristics: - new Characteristic::Name("My Table Lamp"); // Name of the Accessory, which shows up on the HomeKit "tiles", and should be unique across Accessories - - // The next 4 Characteristics serve no function except for being displayed in HomeKit's setting panel for each Accessory. They are nevertheless required by HAP: - - new Characteristic::Manufacturer("HomeSpan"); // Manufacturer of the Accessory (arbitrary text string, and can be the same for every Accessory) - new Characteristic::SerialNumber("123-ABC"); // Serial Number of the Accessory (arbitrary text string, and can be the same for every Accessory) - new Characteristic::Model("120-Volt Lamp"); // Model of the Accessory (arbitrary text string, and can be the same for every Accessory) - new Characteristic::FirmwareRevision("0.9"); // Firmware of the Accessory (arbitrary text string, and can be the same for every Accessory) + new SpanAccessory(); // Begin by creating a new Accessory using SpanAccessory(), no arguments needed - // The last required Characteristic for the Accessory Information Service is the special Identify Characteristic. We'll learn more about this - // Characteristic in later examples. For now, you can just instantiate it without any arguments. + new Service::AccessoryInformation(); // HAP requires every Accessory to implement an AccessoryInformation Service + + // The only required Characteristic for the Accessory Information Service is the special Identify Characteristic. It takes no arguments: - new Characteristic::Identify(); // Create the required Identify + new Characteristic::Identify(); // Create the required Identify Characteristic + + // The Accessory Information Service also includes these four OPTIONAL Characteristics. They perform no function and are for + // informational purposes only --- their values are displayed in HomeKit's setting panel for each Accessory. Feel free + // to uncomment the lines and implement any combination of them, or none at all. + +// new Characteristic::Manufacturer("HomeSpan"); // Manufacturer of the Accessory (arbitrary text string, and can be the same for every Accessory) +// new Characteristic::SerialNumber("123-ABC"); // Serial Number of the Accessory (arbitrary text string, and can be the same for every Accessory) +// new Characteristic::Model("120-Volt Lamp"); // Model of the Accessory (arbitrary text string, and can be the same for every Accessory) +// new Characteristic::FirmwareRevision("0.9"); // Firmware of the Accessory (arbitrary text string, and can be the same for every Accessory) // *NOTE* HAP requires that the AccessoryInformation Service always be instantiated BEFORE any other Services, which is why we created it first. diff --git a/examples/02-TwoSimpleLightBulbs/02-TwoSimpleLightBulbs.ino b/examples/02-TwoSimpleLightBulbs/02-TwoSimpleLightBulbs.ino index dece10a..99588a6 100644 --- a/examples/02-TwoSimpleLightBulbs/02-TwoSimpleLightBulbs.ino +++ b/examples/02-TwoSimpleLightBulbs/02-TwoSimpleLightBulbs.ino @@ -44,18 +44,13 @@ void setup() { Serial.begin(115200); - homeSpan.begin(Category::Lighting,"HomeSpan LightBulbs"); // initialize HomeSpan - note the name is now "HomeSpan LightBulbs" + homeSpan.begin(Category::Lighting,"HomeSpan LightBulb"); // initializes a HomeSpan device named "HomeSpan Lightbulb" with Category set to Lighting // Here we create the first LightBulb Accessory just as in Example 1 - new SpanAccessory(); // Begin by creating a new Accessory using SpanAccessory(), which takes no arguments + new SpanAccessory(); // Begin by creating a new Accessory using SpanAccessory(), no arguments needed - new Service::AccessoryInformation(); // HAP requires every Accessory to implement an AccessoryInformation Service, which has 6 required Characteristics - new Characteristic::Name("My Table Lamp"); // Name of the Accessory, which shows up on the HomeKit "tiles", and should be unique across Accessories - new Characteristic::Manufacturer("HomeSpan"); // Manufacturer of the Accessory (arbitrary text string, and can be the same for every Accessory) - new Characteristic::SerialNumber("123-ABC"); // Serial Number of the Accessory (arbitrary text string, and can be the same for every Accessory) - new Characteristic::Model("120-Volt Lamp"); // Model of the Accessory (arbitrary text string, and can be the same for every Accessory) - new Characteristic::FirmwareRevision("0.9"); // Firmware of the Accessory (arbitrary text string, and can be the same for every Accessory) + new Service::AccessoryInformation(); // HAP requires every Accessory to implement an AccessoryInformation Service, with the required Identify Characteristic new Characteristic::Identify(); // Create the required Identify new Service::HAPProtocolInformation(); // Create the HAP Protcol Information Service @@ -64,16 +59,11 @@ void setup() { new Service::LightBulb(); // Create the Light Bulb Service new Characteristic::On(); // This Service requires the "On" Characterstic to turn the light on and off - // Now we create a second Accessory, which is just a duplicate of Accessory 1 with the exception of changing the Name from "My Table Lamp" to "My Floor Lamp" + // Now we create a second Accessory, which is just a duplicate of the first Accessory - new SpanAccessory(); // Begin by creating a new Accessory using SpanAccessory(), which takes no arguments + new SpanAccessory(); // Begin by creating a new Accessory using SpanAccessory(), no arguments needed - new Service::AccessoryInformation(); // HAP requires every Accessory to implement an AccessoryInformation Service, which has 6 required Characteristics - new Characteristic::Name("My Floor Lamp"); // Name of the Accessory, which shows up on the HomeKit "tiles", and should be unique across Accessories - new Characteristic::Manufacturer("HomeSpan"); // Manufacturer of the Accessory (arbitrary text string, and can be the same for every Accessory) - new Characteristic::SerialNumber("123-ABC"); // Serial Number of the Accessory (arbitrary text string, and can be the same for every Accessory) - new Characteristic::Model("120-Volt Lamp"); // Model of the Accessory (arbitrary text string, and can be the same for every Accessory) - new Characteristic::FirmwareRevision("0.9"); // Firmware of the Accessory (arbitrary text string, and can be the same for every Accessory) + new Service::AccessoryInformation(); // HAP requires every Accessory to implement an AccessoryInformation Service, with the required Identify Characteristic new Characteristic::Identify(); // Create the required Identify new Service::HAPProtocolInformation(); // Create the HAP Protcol Information Service @@ -82,7 +72,15 @@ void setup() { new Service::LightBulb(); // Create the Light Bulb Service new Characteristic::On(); // This Service requires the "On" Characterstic to turn the light on and off - // That's it - our device now has two Accessories! + // That's it - our device now has two Accessories, each displayed up as a separate Tile in the Home App! + + // Note that for a device with multiple Accessories, the Home App generates a default name for each Accessory Tile from the Name + // specified in homeSpan.begin(). In this case, the default name for the first Accessory Tile will be "HomeSpan Lightbulb", + // just as it was in Example 1, and the default name for the second Accessory Tile will be "HomeSpan Lightbulb 2". + + // You can of course change the name of each Accessory Tile from these defaults when prompted by the Home App during pairing. You + // can also change the name of any Accessory Tile, even after pairing, directly from the Home App by opening the settings page + // for any given Tile. // IMPORTANT: You should NOT have to re-pair your device with HomeKit when moving from Example 1 to Example 2. HomeSpan will note // that the Attribute Database has been updated, and will broadcast a new configuration number when the program restarts. This should diff --git a/examples/03-CeilingFanWithLight/03-CeilingFanWithLight.ino b/examples/03-CeilingFanWithLight/03-CeilingFanWithLight.ino index ec0ce8a..200da33 100644 --- a/examples/03-CeilingFanWithLight/03-CeilingFanWithLight.ino +++ b/examples/03-CeilingFanWithLight/03-CeilingFanWithLight.ino @@ -44,18 +44,11 @@ void setup() { Serial.begin(115200); // Start a serial connection - this is needed for you to type in your WiFi credentials - homeSpan.begin(Category::Fans,"HomeSpan Ceiling Fan"); // Begin a HomeSpan Session - note the Category has been set to "Fans" + homeSpan.begin(Category::Fans,"HomeSpan Ceiling Fan"); // Initialize HomeSpan - note the Category has been set to "Fans" - // We begin by creating a Light Bulb Accessory just as in Examples 1 and 2, but with Name now set to "My Ceiling Fan" - - new SpanAccessory(); // Begin by creating a new Accessory using SpanAccessory(), which takes no arguments + // We begin by creating a Light Bulb Accessory just as in Examples 1 and 2 - new Service::AccessoryInformation(); // HAP requires every Accessory to implement an AccessoryInformation Service, which has 6 required Characteristics - new Characteristic::Name("My Ceiling Fan"); // Name of the Accessory, which shows up on the HomeKit "tiles", and should be unique across Accessories - new Characteristic::Manufacturer("HomeSpan"); // Manufacturer of the Accessory (arbitrary text string, and can be the same for every Accessory) - new Characteristic::SerialNumber("123-ABC"); // Serial Number of the Accessory (arbitrary text string, and can be the same for every Accessory) - new Characteristic::Model("120-Volt Lamp"); // Model of the Accessory (arbitrary text string, and can be the same for every Accessory) - new Characteristic::FirmwareRevision("0.9"); // Firmware of the Accessory (arbitrary text string, and can be the same for every Accessory) + new Service::AccessoryInformation(); // HAP requires every Accessory to implement an AccessoryInformation Service, with the required Identify Characteristic new Characteristic::Identify(); // Create the required Identify new Service::HAPProtocolInformation(); // Create the HAP Protcol Information Service @@ -64,11 +57,14 @@ void setup() { new Service::LightBulb(); // Create the Light Bulb Service new Characteristic::On(); // This Service requires the "On" Characterstic to turn the light on and off - // Now we create the a Fan Service within this same Accessory + // Now we add a Fan Service within this same Accessory new Service::Fan(); // Create the Fan Service new Characteristic::Active(); // This Service requires the "Active" Characterstic to turn the fan on and off + // If everything worked correctly you should now see a single Tile named "HomeSpan Ceiling Fan" within the Home App. + // Clicking that Tile should open a window displaying two on/off controls - one for the Fan, and one for the Light. + // IMPORTANT: HomeKit Controllers often cache a lot of information. If your Controller does not update to match the above configuration, // simply select the Accessory in your Controller and under setting, select "Remove Accessory" and then re-pair. diff --git a/examples/04-AdvancedCeilingFan/04-AdvancedCeilingFan.ino b/examples/04-AdvancedCeilingFan/04-AdvancedCeilingFan.ino index f849b2b..87c76b7 100644 --- a/examples/04-AdvancedCeilingFan/04-AdvancedCeilingFan.ino +++ b/examples/04-AdvancedCeilingFan/04-AdvancedCeilingFan.ino @@ -49,12 +49,7 @@ void setup() { new SpanAccessory(); - new Service::AccessoryInformation(); - new Characteristic::Name("My Ceiling Fan"); - new Characteristic::Manufacturer("HomeSpan"); - new Characteristic::SerialNumber("123-ABC"); - new Characteristic::Model("120-Volt Lamp"); - new Characteristic::FirmwareRevision("0.9"); + new Service::AccessoryInformation(); new Characteristic::Identify(); new Service::HAPProtocolInformation(); diff --git a/examples/05-WorkingLED/05-WorkingLED.ino b/examples/05-WorkingLED/05-WorkingLED.ino index d1af08b..4316c6b 100644 --- a/examples/05-WorkingLED/05-WorkingLED.ino +++ b/examples/05-WorkingLED/05-WorkingLED.ino @@ -69,16 +69,11 @@ void setup() { Serial.begin(115200); - homeSpan.begin(Category::Lighting,"HomeSpan LEDs"); + homeSpan.begin(Category::Lighting,"HomeSpan LED"); new SpanAccessory(); new Service::AccessoryInformation(); - new Characteristic::Name("LED #1"); - new Characteristic::Manufacturer("HomeSpan"); - new Characteristic::SerialNumber("123-ABC"); - new Characteristic::Model("20mA LED"); - new Characteristic::FirmwareRevision("0.9"); new Characteristic::Identify(); new Service::HAPProtocolInformation(); @@ -102,11 +97,6 @@ void setup() { new SpanAccessory(); new Service::AccessoryInformation(); - new Characteristic::Name("LED #2"); - new Characteristic::Manufacturer("HomeSpan"); - new Characteristic::SerialNumber("123-ABC"); - new Characteristic::Model("20mA LED"); - new Characteristic::FirmwareRevision("0.9"); new Characteristic::Identify(); new Service::HAPProtocolInformation(); diff --git a/examples/06-DimmableLED/06-DimmableLED.ino b/examples/06-DimmableLED/06-DimmableLED.ino index b28fc82..71d255a 100644 --- a/examples/06-DimmableLED/06-DimmableLED.ino +++ b/examples/06-DimmableLED/06-DimmableLED.ino @@ -59,16 +59,11 @@ void setup() { Serial.begin(115200); - homeSpan.begin(Category::Lighting,"HomeSpan LEDs"); + homeSpan.begin(Category::Lighting,"HomeSpan LED"); new SpanAccessory(); new Service::AccessoryInformation(); - new Characteristic::Name("On/Off LED"); - new Characteristic::Manufacturer("HomeSpan"); - new Characteristic::SerialNumber("123-ABC"); - new Characteristic::Model("20mA LED"); - new Characteristic::FirmwareRevision("0.9"); new Characteristic::Identify(); new Service::HAPProtocolInformation(); @@ -79,11 +74,6 @@ void setup() { new SpanAccessory(); new Service::AccessoryInformation(); - new Characteristic::Name("Dimmable LED"); - new Characteristic::Manufacturer("HomeSpan"); - new Characteristic::SerialNumber("123-ABC"); - new Characteristic::Model("20mA LED"); - new Characteristic::FirmwareRevision("0.9"); new Characteristic::Identify(); new Service::HAPProtocolInformation(); diff --git a/examples/07-AccessoryNames/07-AccessoryNames.ino b/examples/07-AccessoryNames/07-AccessoryNames.ino new file mode 100644 index 0000000..5b2e0e5 --- /dev/null +++ b/examples/07-AccessoryNames/07-AccessoryNames.ino @@ -0,0 +1,92 @@ +/********************************************************************************* + * MIT License + * + * Copyright (c) 2020 Gregg E. Berman + * + * https://github.com/HomeSpan/HomeSpan + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + * + ********************************************************************************/ + +//////////////////////////////////////////////////////////// +// // +// HomeSpan: A HomeKit implementation for the ESP32 // +// ------------------------------------------------ // +// // +// Example 7: Changing an Accessory's default name // +// // +//////////////////////////////////////////////////////////// + + +#include "HomeSpan.h" +#include "DEV_LED.h" + +void setup() { + + // As discusses in previous examples, the Home App automatically generate default names for each Accessory Tile + // based on the Name provided in the second argument of homeSpan.begin(). And though you can change these names + // both during, and anytime after, pairing, HAP also allows you to customize the default names themselves, so + // something more intuitive is presented to the user when the device is first paired. + + // Changing the default name for an Accessory is done by adding the optional Characteristic Name(char *tileName) to the + // Accessory Information Service. This causes the Home App to use "tileName" as the default name for an Accessory + // Tile instead of generating one from the name used in homeSpan.begin(). Howevever, there is one caveat: The Name() + // Characteristic has no affect when used in the first Accessory of a device. The default name of the first Accessory + // Tile will always be showsn by the Home App as the name specified in homeSpan.begin() regardless of whether or not + // the Name() Characteristic has been added to the Accessory Information Service. + + // Below is a replay of Example 6 showing how the Name Characteristic can be used to change the default names of the second, + // but not the first, Accessory. + + Serial.begin(115200); + + homeSpan.begin(Category::Lighting,"HomeSpan LED"); // Note this results in the default name of "HomeSpan LED", "HomeSpan LED 2", etc. for each Accessory Tile + + new SpanAccessory(); + + new Service::AccessoryInformation(); + new Characteristic::Identify(); + new Characteristic::Name("Simply LED"); // This use of Name() will be ignored by the Home App. The default name for the Accessory will continue to be shown as "HomeSpan LED" + + new Service::HAPProtocolInformation(); + new Characteristic::Version("1.1.0"); + + new DEV_LED(16); // create an on/off LED attached to pin 16 (same as in Example 5) + + new SpanAccessory(); + + new Service::AccessoryInformation(); + new Characteristic::Identify(); + new Characteristic::Name("Dimmable LED"); // This DOES change the default name for the Accessory from "HomeSpan LED 2" to "Dimmable LED" + + new Service::HAPProtocolInformation(); + new Characteristic::Version("1.1.0"); + + new DEV_DimmableLED(17); + +} // end of setup() + +////////////////////////////////////// + +void loop(){ + + homeSpan.poll(); + +} // end of loop() diff --git a/examples/07-AccessoryNames/DEV_LED.h b/examples/07-AccessoryNames/DEV_LED.h new file mode 100644 index 0000000..d9445e9 --- /dev/null +++ b/examples/07-AccessoryNames/DEV_LED.h @@ -0,0 +1,69 @@ + +//////////////////////////////////// +// DEVICE-SPECIFIC LED SERVICES // +//////////////////////////////////// + +#include "extras/PwmPin.h" // NEW! Include this HomeSpan "extra" to create LED-compatible PWM signals on one or more pins + +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 + + boolean update(){ // update() method + + digitalWrite(ledPin,power->getNewVal()); + + return(true); // return true + + } // update +}; + +////////////////////////////////// + +// Here's the new code defining DEV_DimmableLED - changes from above are noted in the comments + +struct DEV_DimmableLED : Service::LightBulb { // Dimmable LED + + LedPin *ledPin; // NEW! Create reference to LED Pin instantiated below + SpanCharacteristic *power; // reference to the On Characteristic + SpanCharacteristic *level; // NEW! Create a reference to the Brightness Characteristic instantiated below + + DEV_DimmableLED(int pin) : Service::LightBulb(){ // constructor() method + + power=new Characteristic::On(); + + level=new Characteristic::Brightness(50); // NEW! Instantiate the Brightness Characteristic with an initial value of 50% (same as we did in Example 4) + level->setRange(5,100,1); // NEW! This sets the range of the Brightness to be from a min of 5%, to a max of 100%, in steps of 1% (different from Example 4 values) + + this->ledPin=new LedPin(pin); // NEW! Configures a PWM LED for output to the specified pin. Note pinMode() does NOT need to be called in advance + + } // end constructor + + boolean update(){ // update() method + + // Here we set the brightness of the LED by calling ledPin->set(brightness), where brightness=0-100. + // Note HomeKit sets the on/off status of a LightBulb separately from its brightness, which means HomeKit + // can request a LightBulb be turned off, but still retains the brightness level so that it does not need + // to be resent once the LightBulb is turned back on. + + // Multiplying the newValue of the On Characteristic ("power", which is a boolean) with the newValue of the + // Brightness Characteristic ("level", which is an integer) is a short-hand way of creating the logic to + // set the LED level to zero when the LightBulb is off, or to the current brightness level when it is on. + + ledPin->set(power->getNewVal()*level->getNewVal()); + + return(true); // return true + + } // update +}; + +////////////////////////////////// diff --git a/src/Settings.h b/src/Settings.h index 2c2279b..3da1fbb 100644 --- a/src/Settings.h +++ b/src/Settings.h @@ -36,7 +36,7 @@ #define HS_MAJOR 1 #define HS_MINOR 5 -#define HS_PATCH 0 +#define HS_PATCH 1 #define STRINGIFY(x) _STR(x) #define _STR(x) #x diff --git a/src/Span.h b/src/Span.h index c0155f7..c4d23a4 100644 --- a/src/Span.h +++ b/src/Span.h @@ -37,12 +37,12 @@ namespace Service { struct AccessoryInformation : SpanService { AccessoryInformation() : SpanService{"3E","AccessoryInformation"}{ - REQ(FirmwareRevision); REQ(Identify); - REQ(Manufacturer); - REQ(Model); - REQ(Name); - REQ(SerialNumber); + OPT(FirmwareRevision); + OPT(Manufacturer); + OPT(Model); + OPT(Name); + OPT(SerialNumber); OPT(HardwareRevision); }};