/********************************************************************************* * MIT License * * Copyright (c) 2020-2022 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" 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, such as a Ceiling Fan with a Light. // When pairing, the Home App will choose default names for each Service (such as Fan, Fan 2, Light, Light 2) depending on the types // of Services included. Similar to the names of Accessory Tiles, you can 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. More importantly, // you can override the default Service names generated by the Home App by simply adding the Name Characteristic to any Service. // However, note that Service names (whether or not overridden) only appear in the Home App if there is a chance of ambiguity, // such as a Accessory with two 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 first Accessory is the "Bridge" Accessory new SpanAccessory(); new Service::AccessoryInformation(); new Characteristic::Identify(); // Our second Accessory is a Ceiling Fan with a single Light. There are three things to note: // // * when pairing, the Home App will generate default names of "Light" and "Fan" for the two Services. // However, these names are not displayed on the control screen of the Accessory since there is no // ambiguity between the Light and Fan controls - the Home App displays them differently // // * the icon used by the Home App for the Accessory Tile is a Lightbulb. Why does it choose this instead of a Fan icon? // Recall from Example 3 that for Accessories with multiple Services, if there is any ambiguity of which icon to use, // the Home App chooses based on the Category of the device. But since this device is configured as a Bridge, the // Category provides no helpful information to the Home App. In such cases the Home App picks an icon for the // Accessory Tile that matches the first functional Service in the Accessory, which in this instance in a LightBulb // // * when opening the control screen by clicking the Accessory Tile, the LightBulb control will appear on the left, and // the Fan control will appear on the right new SpanAccessory(); new Service::AccessoryInformation(); new Characteristic::Identify(); new Characteristic::Name("Light with Fan"); // 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::Fan(); new Characteristic::Active(); // Our third Accessory is identical to the second, except we swapped the order of the Lightbulb and Fan Services. // The result is that the Home App now displays the Accessory Tile with a Fan icon intead of a Lightbulb icon. // Also, when opening the control screen by clicking on the Accessory Tile, the Fan control will now appear on the // left, and the LightBulb control on the right. new SpanAccessory(); new Service::AccessoryInformation(); new Characteristic::Identify(); new Characteristic::Name("Fan with Light"); // this sets the name of the Accessory Tile new Service::Fan(); // the icon of the Accessory Tile will be a Fan, since this is the first functional Service new Characteristic::Active(); new Service::LightBulb(); new Characteristic::On(); // Our fourth Accessory shows what happens if we implement two identical LightBulb Services (without any Fan Service). // Since both Services are LightBulbs, the Home App sensibly picks a Lightbulb icon for the Accessory Tile. However, // when you click the Accessory Tile and open the control screen, you'll note that the Home App now does display the names // of the Service beneath each control. In this case the Home App uses the default names "Light 1" and "Light 2". The Home App // presumably shows the names of each Service since the two controls are identical and there is otherwise no way of telling which // control operates which light. new SpanAccessory(); new Service::AccessoryInformation(); new Characteristic::Identify(); new Characteristic::Name("Ceiling Lights"); // this sets the name of the Accessory Tile new Service::LightBulb(); new Characteristic::On(); new Service::LightBulb(); new Characteristic::On(); // Our fifth Accessory combines a single Fan Service with two identical LightBulb Services. Since the first functional Service implemented // is a Fan, the Home App will pick a Fan icon for the Accessory Tile. Also, since we added Name Characteristics to two LightBulb // Services, their default names generated by the Home App ("Light 1" and "Light 2") will be changed to the names specified. Finally, // note that the Home App displays a more compact form of controls on the control screen since there are three Services. The arrangement // and style of the controls will depend on what combination of Characteristics are implemented for each Service. new SpanAccessory(); new Service::AccessoryInformation(); new Characteristic::Identify(); new Characteristic::Name("Fan with Lights"); // this sets the name of the Accessory Tile new Service::Fan(); new Characteristic::Active(); new Service::LightBulb(); new Characteristic::Name("Main Light"); // this changes the default name of this LightBulb Service from "Light 1" to "Main Light" new Characteristic::On(); new Service::LightBulb(); new Characteristic::Name("Night Light"); // this changes the default name of this LightBulb Service from "Light 2" to "Night Light" new Characteristic::On(); // Our sixth Accessory is similar to the fifth, except we added some more features to some of the Services. Note how this changes // the layout of the controls on the control screen. new SpanAccessory(); new Service::AccessoryInformation(); new Characteristic::Identify(); new Characteristic::Name("Multi-Function Fan"); new Service::Fan(); new Characteristic::Active(); new Characteristic::RotationDirection(); // add a control to change the direcion of rotation new Characteristic::RotationSpeed(0); // add a control to set the rotation speed new Service::LightBulb(); new Characteristic::Name("Main Light"); new Characteristic::On(); new Characteristic::Brightness(100); // make this light dimmable (with intitial value set to 100%) new Service::LightBulb(); new Characteristic::Name("Night Light"); // don't add anything new to this light new Characteristic::On(); } // end of setup() ////////////////////////////////////// void loop(){ homeSpan.poll(); } // end of loop()