From 3cd1c52796fd9555ac9ea3b5effdda7eea8a8765 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Tue, 17 Nov 2020 07:24:49 -0600 Subject: [PATCH 1/3] Update Overview.md --- docs/Overview.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/Overview.md b/docs/Overview.md index 9dfa91c..525b5ad 100644 --- a/docs/Overview.md +++ b/docs/Overview.md @@ -1,6 +1,10 @@ # HomeSpan Overview -*(coming soon)* +*Note: This page references a lot of HomeKit HAP terminology. If you are new to HomeKit development, you may want to start by first reviewing the [HomeKit Primer](HomeKitPrimer.md) page.* + +HomeSpan is an Arduino-style C++ library designed for ESP32 devices to take on the role of a *HAP Accessory Server*, which allows the device to be paired to, and communicate with, any *HAP Client*, such as Apple's Home App on an iPhone, iPad, or Mac. + +There are three primary functions of HomeSpan. The first is to implement all the required HomeKit protocols needed for you to define and then expose one or more HAP Accessory Objects, each with their own HAP Services and HAP Characteristics Need to discuss development environment From 787f23649a870602a004694e3ad82ccabee14dcf Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Sat, 21 Nov 2020 13:13:21 -0600 Subject: [PATCH 2/3] Update Overview.md --- docs/Overview.md | 33 +++++++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/docs/Overview.md b/docs/Overview.md index 525b5ad..5d52981 100644 --- a/docs/Overview.md +++ b/docs/Overview.md @@ -2,9 +2,38 @@ *Note: This page references a lot of HomeKit HAP terminology. If you are new to HomeKit development, you may want to start by first reviewing the [HomeKit Primer](HomeKitPrimer.md) page.* -HomeSpan is an Arduino-style C++ library designed for ESP32 devices to take on the role of a *HAP Accessory Server*, which allows the device to be paired to, and communicate with, any *HAP Client*, such as Apple's Home App on an iPhone, iPad, or Mac. +HomeSpan is an Arduino-style C++ library designed for ESP32 devices to take on the role of a *HAP Accessory Server* (i.e. a HomeKit Device), which allows the device to be paired to, and communicate with, any *HAP Client*, such as Apple's Home App on an iPhone, iPad, or Mac. + +There are three primary components of HomeSpan: + +1. **The HomeSpan API** - a collection of objects, methods, and functions you implement inside an Arduino-style sketch to create your HomeKit device. + +1. **The HomeSpan Command-Line Interface (CLI)** - a series of diagnostics that HomeSpan outputs to the Arduino Serial Monitor, and a series of command you can enter into the Serial Monitor to request more diagnostic information, to perform some basic housekeeping functions (e.g. a Factory Reset), and to configure the device with WiFi Credentials and a HomeKit Setup Code. + +1. **An End-User Environment** - allows an end-user to configure a standalone HomeSpan device using only a simple Control Button and the device's Status LED + +### Creating a HomeSpan Sketch + +The structure of a HomeSpan sketch is as follows: + +```C++ +#include "HomeSpan.h" // include the HomeSpan library + +void setup() { + + Serial.begin(115200); // start the Serial interface + + /// HOMESPAN SETUP CODE /// + +} // end of setup() + +void loop(){ + +/// HOMESPAN LOOP CODE /// + +} // end of loop() +``` -There are three primary functions of HomeSpan. The first is to implement all the required HomeKit protocols needed for you to define and then expose one or more HAP Accessory Objects, each with their own HAP Services and HAP Characteristics Need to discuss development environment From 6ff6b84846c1d2f641b690f9bb60292652a836a8 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Sat, 21 Nov 2020 14:05:50 -0600 Subject: [PATCH 3/3] Update Overview.md --- docs/Overview.md | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/Overview.md b/docs/Overview.md index 5d52981..cc9f2d7 100644 --- a/docs/Overview.md +++ b/docs/Overview.md @@ -8,13 +8,13 @@ There are three primary components of HomeSpan: 1. **The HomeSpan API** - a collection of objects, methods, and functions you implement inside an Arduino-style sketch to create your HomeKit device. -1. **The HomeSpan Command-Line Interface (CLI)** - a series of diagnostics that HomeSpan outputs to the Arduino Serial Monitor, and a series of command you can enter into the Serial Monitor to request more diagnostic information, to perform some basic housekeeping functions (e.g. a Factory Reset), and to configure the device with WiFi Credentials and a HomeKit Setup Code. +1. **The HomeSpan Command-Line Interface (CLI)** - a series of diagnostics that HomeSpan outputs to the Arduino Serial Monitor, and a series of commands you can enter into the Serial Monitor to request more diagnostic information, to perform some basic housekeeping functions (such as a Factory Reset), and to configure the device with WiFi Credentials and a HomeKit Setup Code. 1. **An End-User Environment** - allows an end-user to configure a standalone HomeSpan device using only a simple Control Button and the device's Status LED -### Creating a HomeSpan Sketch +### Overview of the HomeSpan API -The structure of a HomeSpan sketch is as follows: +The basic structure of a HomeSpan sketch is as follows: ```C++ #include "HomeSpan.h" // include the HomeSpan library @@ -23,19 +23,39 @@ void setup() { Serial.begin(115200); // start the Serial interface - /// HOMESPAN SETUP CODE /// + /// HOMESPAN SETUP CODE GOES HERE /// } // end of setup() void loop(){ -/// HOMESPAN LOOP CODE /// + /// HOMESPAN LOOP CODE GOES HERE /// } // end of loop() ``` +Inclusion of HomeSpan.h creates a global object called `homeSpan` that implements a variety of methods. The two most important are `begin()` and `poll()`. The `begin()` method, which takes a number of optional parameters, initializes HomeSpan and is placed near the begining of the `setup()` section. The `poll()` method, which take no arguments, is placed inside `loop()` and is what causes HomeSpan to run all its code. This is generally the only function placed in the `loop()` section. Our sketch now looks like this: + +```C++ +#include "HomeSpan.h" // include the HomeSpan library + +void setup() { + + Serial.begin(115200); // start the Serial interface + + homeSpan.begin(); // initialize HomeSpan + + /// CONFIGURATION OF ACCESSORY ATTRIBUTE DATABASE GOES HERE /// + +} // end of setup() + +void loop(){ + + homeSpan.poll(); + +} // end of loop() +``` -Need to discuss development environment Need to discuss micro-controller usage to connect to real-world devices (not to connect to other web servers)