175 lines
10 KiB
C++
175 lines
10 KiB
C++
/*********************************************************************************
|
|
* MIT License
|
|
*
|
|
* Copyright (c) 2020-2024 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 11: Service Names: //
|
|
// * setting the names of individual Services //
|
|
// * "changing" the icons in a bridge Accessory //
|
|
// //
|
|
////////////////////////////////////////////////////////////////
|
|
|
|
#include "HomeSpan.h"
|
|
|
|
// INITIAL NOTE: Apple is constantly updating how the Home App Icons are chosen and how/if/where/when the Names for
|
|
// Accessories and Services are displayed. This example has been tested and verified as of iOS 17.2.1.
|
|
|
|
void setup() {
|
|
|
|
// As described in previous examples, when pairing a device the Home App will choose default names for each
|
|
// Accessory Tile, unless you override those default names with your own names by adding a Name Characteristic
|
|
// to the Accessory Information Service for each Accessory (except the first, which is typically the Bridge Accessory).
|
|
|
|
// The same process holds true for the names of the Services in an Accessory with multiple Services: if a Service is not named,
|
|
// the Home App will generate one. You can of course change the names of individual Services when prompted
|
|
// during the pairing process, or at any time after pairing from within the appropriate settings pages in the Home App.
|
|
|
|
// But more importantly, you can name Services in your sketch so that those name show up when pairing, saving you the need to
|
|
// rename them from the settings pages in the Home App.
|
|
|
|
// Whereas we previously used the *Name* Characteristic to provide names for Accessory Tiles, we use the *ConfiguredName* Characteristic
|
|
// to provide names for individual Services within each Accessory.
|
|
|
|
// One important distinction between Name and ConfigureName is that Name is only used by the Home App during pairing. After that,
|
|
// any changes you make to the name of an Accessory Tile from within the Home App are never communicated back to HomeSpan, and any changes
|
|
// you might make to those names in your sketch will not be reflected in the Home App unless you unpair and re-pair the device. In contrast,
|
|
// ConfiguredName works like any other Characteristic: changes made to ConfiguredName from within a sketch are proporgated to the Home App,
|
|
// and any edits you make to a Service's name in the Home App trigger a corresponding call to update() in HomeSpan so HomeSpan and the Home App
|
|
// are always in sync with regard to the names of any Services that includes the ConfiguredName Characteristic.
|
|
|
|
// NOTE: Service names (whether those generated by the Home App or specified via the ConfiguredName Characteristic) are only displayed on the
|
|
// control screen of an Accessory Tile if there are two more more Services of the same type. But even if a Service name does not appear in the Home App,
|
|
// it will still be used by Siri to control a specific Service within an Accessory by voice.
|
|
|
|
// In the example below we create 5 different functional Accessories, each illustrating how names, as well as icons, are chosen by the Home App
|
|
|
|
Serial.begin(115200);
|
|
|
|
// This device will be configured as a Bridge, with the Category set to Bridges
|
|
|
|
homeSpan.begin(Category::Bridges,"HomeSpan Bridge");
|
|
|
|
// Our initial Accessory is therefore the "Bridge" Accessory
|
|
|
|
new SpanAccessory();
|
|
new Service::AccessoryInformation();
|
|
new Characteristic::Identify();
|
|
|
|
// Our first "functional" Accessory is a combination of a LightBulb, Outlet, and Switch. Note that when pairing, the Home App generates
|
|
// default names of "Light", "Outlet", and "Switch" for these three Services, though these names are NOT displayed on the control screen
|
|
// of the Accessory since there is only one type of each Service. Also note that the Home App selects a LightBulb icon for the Accessory Tile
|
|
|
|
new SpanAccessory();
|
|
new Service::AccessoryInformation();
|
|
new Characteristic::Identify();
|
|
new Characteristic::Name("Light First"); // this sets the name of the Accessory Tile
|
|
new Service::LightBulb(); // the icon of the Accessory Tile will be a Lightbulb, since this is the first functional Service
|
|
new Characteristic::On();
|
|
new Service::Outlet();
|
|
new Characteristic::On();
|
|
new Characteristic::OutletInUse();
|
|
new Service::Switch();
|
|
new Characteristic::On();
|
|
|
|
// Our second Accessory is similar to the first, but here we define the Switch Service first. Note that the Home App now selects
|
|
// a Switch icon for the Accessory Tile
|
|
|
|
new SpanAccessory();
|
|
new Service::AccessoryInformation();
|
|
new Characteristic::Identify();
|
|
new Characteristic::Name("Switch First"); // this sets the name of the Accessory Tile
|
|
new Service::Switch(); // the icon of the Accessory Tile will be a Switch, since this is the first functional Service
|
|
new Characteristic::On();
|
|
new Service::Outlet();
|
|
new Characteristic::On();
|
|
new Characteristic::OutletInUse();
|
|
new Service::LightBulb();
|
|
new Characteristic::On();
|
|
|
|
// Our third Accessory is similar to the second, but here we define 2 Switches, 2 LightBulbs, but still only 1 Outlet. This time, during pairing
|
|
// the Home App generates default names of Switch, Switch 2, Light, Light 2, and Outlet. Importantly, note that on the control screen for
|
|
// this Accessory, the Home App now displays the names of the Switches ("Switch" and "Switch 2") as well as the LightBulbs ("Light" and "Light 2")
|
|
// under each corresponding control, but it does NOT display the name "Outlet" under the Outlet control since there is only one Outlet Service
|
|
|
|
new SpanAccessory();
|
|
new Service::AccessoryInformation();
|
|
new Characteristic::Identify();
|
|
new Characteristic::Name("Two Switches"); // this sets the name of the Accessory Tile
|
|
new Service::Switch(); // the icon of the Accessory Tile will be a Switch, since this is the first functional Service
|
|
new Characteristic::On();
|
|
new Service::Switch();
|
|
new Characteristic::On();
|
|
new Service::Outlet();
|
|
new Characteristic::On();
|
|
new Characteristic::OutletInUse();
|
|
new Service::LightBulb();
|
|
new Characteristic::On();
|
|
new Service::LightBulb();
|
|
new Characteristic::On();
|
|
|
|
// Our fourth and final Accessory is the same as the third, but this time we use the ConfiguredName Characteristic to define a name for each Service.
|
|
// When pairing, you should see the Home App now uses the names below instead of generating default names as it did in the other examples. You
|
|
// should also see these names displayed under each control on the control screen for the Accessory, with the exception of the Outlet Service.
|
|
// Though we did provide a name for the Outlet, since there is only one Outlet Service in this Accessory, the Home App does not display its name.
|
|
// Howevever, if from the settings screen for this Accessory you further navigate to the "Accessories" page, you will indeed see the names for each
|
|
// Service exactly as specified below, including the Outlet name "Aux Power"
|
|
|
|
new SpanAccessory();
|
|
new Service::AccessoryInformation();
|
|
new Characteristic::Identify();
|
|
new Characteristic::Name("Central Control"); // this sets the name of the Accessory Tile
|
|
new Service::Switch(); // the icon of the Accessory Tile will be a Switch, since this is the first functional Service
|
|
new Characteristic::On();
|
|
new Characteristic::ConfiguredName("High Voltage"); // this sets the name of the first Switch Service
|
|
new Service::Switch();
|
|
new Characteristic::On();
|
|
new Characteristic::ConfiguredName("Low Voltage"); // this sets the name of the second Switch Service
|
|
new Service::Outlet();
|
|
new Characteristic::On();
|
|
new Characteristic::OutletInUse();
|
|
new Characteristic::ConfiguredName("Aux Power"); // this sets the name of the Outlet Service
|
|
new Service::LightBulb();
|
|
new Characteristic::On();
|
|
new Characteristic::ConfiguredName("Main Lights"); // this sets the name of the first LightBulb Service
|
|
new Service::LightBulb();
|
|
new Characteristic::On();
|
|
new Characteristic::ConfiguredName("Accent Lights"); // this sets the name of the second LightBulb Service
|
|
|
|
|
|
} // end of setup()
|
|
|
|
//////////////////////////////////////
|
|
|
|
void loop(){
|
|
|
|
homeSpan.poll();
|
|
|
|
} // end of loop()
|