Updating examples 1-7 to conform with latest iOS changes

This commit is contained in:
Gregg 2022-04-04 06:13:30 -05:00
parent 91f6ecb958
commit 98f812ba0c
10 changed files with 215 additions and 78 deletions

View File

@ -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.

View File

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

View File

@ -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.

View File

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

View File

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

View File

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

View File

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

View File

@ -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
};
//////////////////////////////////

View File

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

View File

@ -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);
}};