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

Update Blinkable.md

This commit is contained in:
HomeSpan 2023-07-03 07:00:21 -05:00 committed by GitHub
parent 7861494e1a
commit 866225757f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 30 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
docs/Blinkable.md
View File

@ -1,85 +1,49 @@
# HomeSpan Status # Creating a Custom Status LED with the Blinkable Interface
The optional ***homeSpan*** method, `void setStatusCallback(void (*func)(HS_STATUS status))`, can be used to create a callback function, *func*, that HomeSpan calls whenever its status changes. HomeSpan passes *func* a single argument, *status*, of type *HS_STATUS*, defined as follows: The HomeSpan Status LED conveys information about the device to the user through different blinking patterns. The *homeSpan* `setStatusPin()` and `setStatusPixel()` methods allow you to choose, respectively, either a standard LED or a NeoPixel LED as the Status LED. However, the Status LED can be set to any object that implements the **Blinkable** interface[^1] using the *homeSpan* method `setStatusDevice(Blinkable *sDev)`, where *sDev* is a Blinkable object.
To create your own Blinkable object, start by creating a child class derived from **Blinkable**. Next, add a constructor that defines the pins and performs any initializations if needed. Finally, define the following methods that **Blinkable** calls to blink the device:
* `void on()` - turns on the device (e.g. causes an LED to light)
* `void off()` - turns off the device (e.g. causes an LED to go dark)
* `virtual getPin()` - returns the pin number of the device (any number is fine; does not have to be an actual ESP32 pin)
For example, the following defines a Blinkable object for an inverted LED that turns *on* when an ESP32 pin is LOW, and turns *off* when the ESP32 pin is HIGH:
```C++ ```C++
enum HS_STATUS {
HS_WIFI_NEEDED, // WiFi Credentials have not yet been set/stored // CREATE THIS STRUCTURE SOMEWHERE NEAR TOP OF SKETCH
HS_WIFI_CONNECTING, // HomeSpan is trying to connect to the network specified in the stored WiFi Credentials
HS_PAIRING_NEEDED, // HomeSpan is connected to central WiFi network, but device has not yet been paired to HomeKit struct invertedLED : Blinkable { // create a child class derived from Blinkable
HS_PAIRED, // HomeSpan is connected to central WiFi network and ther device has been paired to HomeKit
HS_ENTERING_CONFIG_MODE, // User has requested the device to enter into Command Mode int pin; // variable to store the pin number
HS_CONFIG_MODE_EXIT, // HomeSpan is in Command Mode with "Exit Command Mode" specified as choice
HS_CONFIG_MODE_REBOOT, // HomeSpan is in Command Mode with "Reboot" specified as choice invertedLED(int pin) : pin{pin} { // constructor that initializes the pin parameter
HS_CONFIG_MODE_LAUNCH_AP, // HomeSpan is in Command Mode with "Launch Access Point" specified as choice pinMode(pin,OUTPUT); // set the pin to OUTPUT
HS_CONFIG_MODE_UNPAIR, // HomeSpan is in Command Mode with "Unpair Device" specified as choice digitalWrite(pin,HIGH); // set pin HIGH (which is off for an inverted LED)
HS_CONFIG_MODE_ERASE_WIFI, // HomeSpan is in Command Mode with "Erase WiFi Credentials" specified as choice }
HS_CONFIG_MODE_EXIT_SELECTED, // User has selected "Exit Command Mode"
HS_CONFIG_MODE_REBOOT_SELECTED, // User has select "Reboot" from the Command Mode void on() override { digitalWrite(pin,LOW); } // required function on() - sets pin LOW
HS_CONFIG_MODE_LAUNCH_AP_SELECTED, // User has selected "Launch AP Access" from the Command Mode void off() override { digitalWrite(pin,HIGH); } // required function off() - sets pin HIGH
HS_CONFIG_MODE_UNPAIR_SELECTED, // User has seleected "Unpair Device" from the Command Mode int getPin() override { return(pin); } // required function getPin() - returns pin number
HS_CONFIG_MODE_ERASE_WIFI_SELECTED, // User has selected "Erase WiFi Credentials" from the Command Mode
HS_REBOOTING, // HomeSpan is in the process of rebooting the device
HS_FACTORY_RESET, // HomeSpan is in the process of performing a Factory Reset of device
HS_AP_STARTED, // HomeSpan has started the Access Point but no one has yet connected
HS_AP_CONNECTED, // The Access Point is started and a user device has been connected
HS_AP_TERMINATED, // HomeSpan has terminated the Access Point
HS_OTA_STARTED // HomeSpan is in the process of recveived an Over-the-Air software update
}; };
```
The ***homeSpan*** method `char* statusString(HS_STATUS s)`, is a convenience function for converting any of the above enumerations to short, pre-defined character string messages as follows: ...
```C++ // THEN USE THE STRUCTURE IN SETUP() TO SET THE STATUS LED
const char* Span::statusString(HS_STATUS s){
switch(s){
case HS_WIFI_NEEDED: return("WiFi Credentials Needed");
case HS_WIFI_CONNECTING: return("WiFi Connecting");
case HS_PAIRING_NEEDED: return("Device not yet Paired");
case HS_PAIRED: return("Device Paired");
case HS_ENTERING_CONFIG_MODE: return("Entering Command Mode");
case HS_CONFIG_MODE_EXIT: return("1. Exit Command Mode");
case HS_CONFIG_MODE_REBOOT: return("2. Reboot Device");
case HS_CONFIG_MODE_LAUNCH_AP: return("3. Launch Access Point");
case HS_CONFIG_MODE_UNPAIR: return("4. Unpair Device");
case HS_CONFIG_MODE_ERASE_WIFI: return("5. Erase WiFi Credentials");
case HS_CONFIG_MODE_EXIT_SELECTED: return("Exiting Command Mode...");
case HS_CONFIG_MODE_REBOOT_SELECTED: return("Rebooting Device...");
case HS_CONFIG_MODE_LAUNCH_AP_SELECTED: return("Launching Access Point...");
case HS_CONFIG_MODE_UNPAIR_SELECTED: return("Unpairing Device...");
case HS_CONFIG_MODE_ERASE_WIFI_SELECTED: return("Erasing WiFi Credentials...");
case HS_REBOOTING: return("REBOOTING!");
case HS_FACTORY_RESET: return("Performing Factory Reset...");
case HS_AP_STARTED: return("Access Point Started");
case HS_AP_CONNECTED: return("Access Point Connected");
case HS_AP_TERMINATED: return("Access Point Terminated");
case HS_OTA_STARTED: return("OTA Update Started");
default: return("Unknown");
}
}
```
### Example:
```C++
#include "HomeSpan.h"
void setup(){ void setup(){
homeSpan.setStatusCallback(statusUpdate); // set callback function
...
homeSpan.begin();
...
}
// create a callback function that simply prints the pre-defined short messages on the Serial Monitor whenever the HomeSpan status changes homeSpan.setStatusDevice(new invertedLED(13)); // set Status LED to be a new Blinkable device attached to pin 13
void statusUpdate(HS_STATUS status){ ...
Serial.printf("\n*** HOMESPAN STATUS CHANGE: %s\n",homeSpan.statusString(status));
} }
``` ```
You can of course create any alternative messsages, or take any actions desired, in *func* and do not need to use the pre-defined strings above. [^1]: In C++, an *interface* is any abstract class that contains only pure virtual functions. You cannot instantiate an interface, but you can instantiate any derived child classes from the interface provided that you define each of the required virtual functions.
--- ---
[↩️](Reference.md) Back to the Reference API page [↩️](Reference.md) Back to the Reference API page