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

Update Overview.md

This commit is contained in:
HomeSpan 2020-11-21 21:26:15 -06:00 committed by GitHub
parent 10b2906d60
commit 5319601846
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 11 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
docs/Overview.md
View File

@ -1,19 +1,7 @@
# HomeSpan Overview # HomeSpan API Overview
*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.* *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* (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 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
# Overview of the HomeSpan API
The basic structure of a HomeSpan sketch is as follows: The basic structure of a HomeSpan sketch is as follows:
```C++ ```C++
@ -233,13 +221,17 @@ with the instantiation of the TableLamp Service as such:
new TableLamp(17); new TableLamp(17);
``` ```
where 17 specifies the ESP32 pin number that is connected to the hypothetical relay used to turn the Table Lamp on and off. Our completed HomeSpan sketch looks like this: where 17 specifies the ESP32 pin number that is connected to the hypothetical relay used to turn the Table Lamp on and off.
Our completed HomeSpan sketch to operate a Table Lamp looks like this:
```C++ ```C++
/* HomeSpan Table Lamp Example */ /* HomeSpan Table Lamp Example */
#include "HomeSpan.h" // include the HomeSpan library #include "HomeSpan.h" // include the HomeSpan library
//// Define the TableLamp Service ////
struct TableLamp : Service::LightBulb{ struct TableLamp : Service::LightBulb{
int lampPin; // store the pin number connected to a hypothetical relay that turns the Table Lamp on/off int lampPin; // store the pin number connected to a hypothetical relay that turns the Table Lamp on/off
@ -263,6 +255,8 @@ struct TableLamp : Service::LightBulb{
}; };
//// INITIALIZE HOMESPAN AND CREATE THE HAP ACCESSORY ATTRIBUTE DATABASE ////
void setup() { void setup() {
Serial.begin(115200); // start the Serial interface Serial.begin(115200); // start the Serial interface
@ -286,6 +280,8 @@ void setup() {
} // end of setup() } // end of setup()
//// RUN HOMESPAN ////
void loop(){ void loop(){
homeSpan.poll(); homeSpan.poll();
@ -293,28 +289,7 @@ void loop(){
} // end of loop() } // end of loop()
``` ```
This fully working example is ready to be uploaded to your ESP32 device where is can be used to operate a hypothetical table lamp connected by a relay to pin 17. Alternatively, you can simply connect an LED to pin 17 and see how it works! Congratulations, you've created your first HomeSpan Sketch.
Need to discuss micro-controller usage to connect to real-world devices (not to connect to other web servers)
Need to discuss control button and status led
Need to discuss configuring using the CLI and the WiFi Access Point
Overview of programming paradigm
Point to the tutorials
Point to the HomeSpan Library Reference