172 lines
10 KiB
C++
172 lines
10 KiB
C++
/*********************************************************************************
|
|
* 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()
|