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

Update README.md

This commit is contained in:
HomeSpan 2020-11-11 18:05:37 -06:00 committed by GitHub
parent 506a5e81bf
commit a766e9132f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 6 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
README.md
View File

@ -87,21 +87,22 @@ HomeSpan includes a light-weight Command-Line Interface (CLI) for developers tha
#### WiFi Credentials and HomeKit Setup Codes
Though HomeSpan devices can be used on a standalone basis, to control the a HomeSpan device through Apple HomeKit (which is the whole point of HomeSpan), the device needs to be connected to a WiFi network. This means HomeSpan needs to know your home WiFi network name and WiFi password. HomeSpan refers to these are your *WiFi Credentials*. Rather then requiring you to hardcode your WiFi Credentials as part of every HomeSpan sketch (which is both insecure and inflexible), HomeSpan stores your WiFi Credentials in a non-volatile storage (NVS) partition in the ESP32 that is reserved as part of the flash memory on the device, similar to how an EEPROM would operate. You can set, change, and even erase, the WiFi Credentials stored on any HomeSpan device directly from the HomeSpan CLI without ever modifying the code, or even having access to the code.
Though HomeSpan devices can be used on a standalone basis, to control the a HomeSpan device through Apple HomeKit (which is the whole point of HomeSpan), the device needs to be connected to a WiFi network. This means HomeSpan needs to know your home WiFi network name and WiFi password. HomeSpan refers to these are your *WiFi Credentials*. Rather then requiring you to hardcode your WiFi Credentials as part of every HomeSpan sketch (which is neither secure nor easy to update), HomeSpan stores your WiFi Credentials in a non-volatile storage (NVS) partition in the ESP32 that is reserved as part of the flash memory on the device, similar to how an EEPROM would operate. You can set, change, and even erase, the WiFi Credentials stored on any HomeSpan device directly from the HomeSpan CLI without ever modifying the code, or even having access to the code.
Every HomeSpan device requires an 8-digit Setup Code to be able to pair to Apple HomeKit. This code is also stored in an NVS partition rather than hardcoded into a HomeSpan sketch. When HomeSpan is run for the first time on a new device, it configures itself with a default code of **466-37-72**. This can be changed any time from the HomeSpan CLI.
Every HomeSpan device also requires an 8-digit Setup Code to be able to pair to Apple HomeKit. This code is similarly stored in an NVS partition rather than hardcoded into a HomeSpan sketch. When HomeSpan is run for the first time on a new device, it configures itself with a default code of **466-37-72**. This can be changed any time from the HomeSpan CLI.
Please see the [HomeSpan Command-Line Interface](docs/CLI.md) page for complete details on all the CLI.
# HomeSpan End-User Controls
Once a HomeSpan device has been programmed and configured from within the Arduino IDE, it is typically operated on a standalone basis without any connection to a computer. Provided that the device is paired to HomeKit, you'll be able to operate any applicances connected to the device, such as a light or fan, directly through the Home App on your iPhone, iPad, or Mac, or through Siri. However, without the device being connected to a computer, you won't have access to the HomeSpan CLI and therefore can't use the CLI to perform configuration operations, such initiating a Factory Reset, updating your WiFi Credentials, or changing the Setup Code.
Once a HomeSpan device has been programmed and configured using the Arduino IDE, it is typically operated on a standalone basis without any connection to a computer. Provided that the device is paired to HomeKit, you'll be able to operate any applicances connected to the device, such as a light or fan, directly through the Home App on your iPhone, iPad, or Mac, or through Siri. However, without the device being connected to a computer, you won't have access to the HomeSpan CLI and therefore can't use the CLI to perform configuration operations, such initiating a Factory Reset, updating your WiFi Credentials, or changing the Setup Code.
To solve for this, HomeSpan provides end-users with an alternate method for making configuration changes directly from the device itself. A single pushbutton on the device, coupled with single LED that blinks in different patterns to inform you of the device's status, is all that is needed for you to switch the device into configuration mode, perform some basic housekeeping functions, and launch HomeSpan's
To solve for this, HomeSpan provides end-users (who may not be developers and have no idea what an Arduino IDE is) with an alternative method for making configuration changes to a standalone device. To implement this method, HomeSpan requires the addition of a dedicated *Control Button* and dedicated *Status LED* on the device itself. The Control Button can be any simple normally-open pushbutton that you connect between an ESP32 pin of your choice and ground. The Status LED can be an external component connected to an ESP32 pin of your choice, or it can be any built-in LED already included on your ESP32 board. Using just these two components, end-users can switch the device into configuration mode, perform some basic housekeeping functions, and even launch HomeSpan's temporary WiFi network. This network provides end-users with a simple web interface they can access with an iPhone to set or update the WiFi Credentials and Setup Code stored on the device.
Please see the [HomeSpan User Guide](docs/UserGuide.md) page for complete details on all end-user functions and features.
# Resources and Documentation
*in progress*
[End-User Guide](docs/UserGuide.md)