Seich
/
HomeSpan
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated comments in some examples.

This commit is contained in:
Gregg 2020-11-23 08:33:39 -06:00
parent 8670132c86
commit 5585765a48
3 changed files with 16 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
examples/01-SimpleLightBulb/01-SimpleLightBulb.ino
View File

@ -38,7 +38,7 @@
// WELCOME TO HOMESPAN! // WELCOME TO HOMESPAN!
// This first example introduces the HomeSpan library and demonstrates how to implement a simple HomeKit on/off light control // This first example introduces the HomeSpan library and demonstrates how to implement a simple on/off light control
// using a combination of HomeSpan Accessory, Service, and Characteristic objects. Once this sketch has been uploaded // using a combination of HomeSpan Accessory, Service, and Characteristic objects. Once this sketch has been uploaded
// to your HomeSpan device and the device is paired to your home, a new "lightbulb" tile will appear in the Home App of your iPhone, // to your HomeSpan device and the device is paired to your home, a new "lightbulb" tile will appear in the Home App of your iPhone,
// iPad, or Mac. // iPad, or Mac.
@ -46,12 +46,14 @@
// Though the tile will be fully operational (i.e. you can change the status of the lightbulb from "on" or "off"), we won't yet connect // Though the tile will be fully operational (i.e. you can change the status of the lightbulb from "on" or "off"), we won't yet connect
// an actual light or LED to the HomeSpan device, so nothing real will light up. Instead, in this and the next few examples, we'll focus // an actual light or LED to the HomeSpan device, so nothing real will light up. Instead, in this and the next few examples, we'll focus
// on learning about the different ways HomeKit controls can be configured. Starting in Example 5, we'll connect an LED to the device // on learning about the different ways HomeKit controls can be configured. Starting in Example 5, we'll connect an LED to the device
// and introduce the methods you'll need to implement to actually turn the LED on and off from your Home App. // and introduce the methods that actually turn the LED on and off from your Home App.
// These examples are best understood when reviewed in conjunction with the documentation provided on the HomeSpan GitHub page. // NOTE: All HomeSpan examples are best understood when reviewed in conjunction with the documentation provided on the HomeSpan GitHub page.
// See https://github.com/HomeSpan/HomeSpan for details and references. The examples also make frequent reference to // See https://github.com/HomeSpan/HomeSpan for details and references. In particular, you may want to review the HomeSpan API Overview
// Apple's HomeKit Accessory Protocol Specification, known as HAP. You can download this directly from Apple // page before proceeding.
// at https://developer.apple.com/support/homekit-accessory-protocol.
// These examples also make frequent reference to Apple's HomeKit Accessory Protocol Specification, known as HAP. You can download this
// directly from Apple at https://developer.apple.com/support/homekit-accessory-protocol.
// LET'S GET STARTED... // LET'S GET STARTED...
@ -64,44 +66,14 @@ 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 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 begin() method is used to initialize HomeSpan and start all HomeSpan processes.
// Required parameters are Category and Name, which are used by HomeKit to configure the icon and name of the device shown in your Home App // 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. A list of all defined categories can be found at https://github.com/HomeSpan/HomeSpan/docs/Categories.md // when initially pairing your device.
// and match those specified by Apple in Section 13 of the HAP guide (which of course you have downloaded as recommended above!).
// HomeSpan's category names are defined in a C++ namespace appropriately called Category, so you'll need to use the prefix Category:: when
// specifying categories.
homeSpan.begin(Category::Lighting,"HomeSpan LightBulb"); // initializes a HomeSpan device named "HomeSpan Lightbulb" with Category set to Lighting homeSpan.begin(Category::Lighting,"HomeSpan LightBulb"); // initializes a HomeSpan device named "HomeSpan Lightbulb" with Category set to Lighting
// Next, some general information about Apple HomeKit before we proceed... // Next, we construct a simple HAP Accessory Database with a single Accessory containing 3 Services,
// each with their own required Characteristics.
// Every HomeKit device consists of one or more Accessories. Each Accessory contains one or more Services, and
// every Service contains one or more Characteristics. HAP defines all allowable Services and specifies which Characteristics
// are required or optional for each Service.
// An Accessory is typically a complete appliance, such as a table lamp or ceiling fan. Services are the main components of the
// appliance - a ceiling fan Accessory will typically have a fan Service and a light bulb Service. Characteristics define
// how each Service operates.
// Some Characteristics are read-only and describe the name or properties of a Service. Other Characteristics
// can be both written and read by HomeKit - these are the interesting ones since they enable actions to occur,
// such as turning on or off a light, or setting its brightness.
// HAP also requires various informational Services that describe the overall Accessory.
// HAP calls the entirety of all Accessories, Services, and Characteristics used in a device the "Accessory Attributes Database" of
// that device. A complete list of HomeKit Services can be found in Section 8 of the HAP guide. The subset of those Services that
// have been implemented in HomeSpan can be found at https://github.com/HomeSpan/HomeSpan/docs/ServiceList.md. and are defined in the
// Services namespace. A complete list of all HomeKit Characteristics used by these Services can be found in Section 9 of the HAP guide,
// and are defined by HomeSpan in the Characteristics namespace.
// Users construct a HomeKit device's Accessory Attribute Database by instantiating one or more Accessories, each with their own
// HAP Services and HAP Characteristics. To make this as easy as possible, HomeSpan self-registers each object and assembles the database
// in the order in which you instantiate the objects. You do not need to create variables for any of the objects nor know anything about
// their underlying HAP codes. HomeSpan takes care of all of this for you.
// For this example, our Database will comprise 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 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 Service::AccessoryInformation(); // HAP requires every Accessory to implement an AccessoryInformation Service, which has 6 required Characteristics:
@ -120,7 +92,7 @@ void setup() { // Your HomeSpan code should be placed within the
new Characteristic::Identify(); // Create the required Identify new Characteristic::Identify(); // Create the required Identify
// HAP also requires every Accessory (with the exception of those in Bridges, as we will see later) to implement the HAP Protocol Information Service. // HAP also requires every Accessory (with the exception of those in Bridges, as we will see later) to implement the HAP Protocol Information Service.
// This Serrvice supports a single required Characteristic that defines the version number of HAP used by the device. // This Service supports a single required Characteristic that defines the version number of HAP used by the device.
// HAP Release R2 requires this version to be set to "1.1.0" // HAP Release R2 requires this version to be set to "1.1.0"
new Service::HAPProtocolInformation(); // Create the HAP Protcol Information Service new Service::HAPProtocolInformation(); // Create the HAP Protcol Information Service
@ -143,7 +115,7 @@ void setup() { // Your HomeSpan code should be placed within the
void loop(){ void loop(){
// The code in setup above implements the Accessory Attribute Database, but performs no operations. HomeSpan itself must be // The code in setup above implements the Accessory Attribute Database, but performs no operations. HomeSpan itself must be
// continuously polled to look for requests from Controllers, such as an iOS or MacOS device. The poll() method below is all that // continuously polled to look for requests from Controllers, such as the Home App on your iPhone. The poll() method below is all that
// is needed to perform this continuously in each iteration of loop() // is needed to perform this continuously in each iteration of loop()
homeSpan.poll(); // run HomeSpan! homeSpan.poll(); // run HomeSpan!

2
examples/08-Bridges/08-Bridges.ino
View File

@ -56,7 +56,7 @@ void setup() {
// One added bonus is that the HAPProtcolInformation Service only needs to be defined for the Bridge Accessory, and // One added bonus is that the HAPProtcolInformation Service only needs to be defined for the Bridge Accessory, and
// does not need to be repeated for other Accessories. // does not need to be repeated for other Accessories.
// //
// Example 8 is functionally identical to Example 7, except that instead of defined two Accessories (one for the on/off // Example 8 is functionally identical to Example 7, except that instead of defining two Accessories (one for the on/off
// LED and one for the dimmable LED), we define three Accessories, where the first acts as the Bridge. // LED and one for the dimmable LED), we define three Accessories, where the first acts as the Bridge.
// As usual, all previous comments have been deleted and only new changes from the previous example are shown. // As usual, all previous comments have been deleted and only new changes from the previous example are shown.

2
examples/12-ServiceLoops/12-ServiceLoops.ino
View File

@ -52,7 +52,7 @@ void setup() {
// In this fashion, the loop() method is similar to the main loop() method in the Arduino IDE itself - except it can be customized for each Service. // In this fashion, the loop() method is similar to the main loop() method in the Arduino IDE itself - except it can be customized for each Service.
// In this Example 12 we explore the use of loop() methods to implement two new accessories - a Temperature Sensor and an Air Quality Sensor. Of course // In this Example 12 we explore the use of loop() methods to implement two new accessories - a Temperature Sensor and an Air Quality Sensor. Of course
// we won't actually have these physical devices attached to the ESP32 for the purpoe of this example, but we will simulate "reading" their properties. // we won't actually have these physical devices attached to the ESP32 for the purpose of this example, but we will simulate "reading" their properties.
// This is one of the main purposes of implementing a loop() method. It allows you to read a sensor or perform some sort of repetitive, Service-specific // This is one of the main purposes of implementing a loop() method. It allows you to read a sensor or perform some sort of repetitive, Service-specific
// action. // action.