Update Blinkable.md
This commit is contained in:
HomeSpan
GitHub
parent
7861494e1a
commit
866225757f
|
|
@ -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++
|
||||
enum HS_STATUS {
|
||||
HS_WIFI_NEEDED, // WiFi Credentials have not yet been set/stored
|
||||
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
|
||||
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
|
||||
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
|
||||
HS_CONFIG_MODE_LAUNCH_AP, // HomeSpan is in Command Mode with "Launch Access Point" specified as choice
|
||||
HS_CONFIG_MODE_UNPAIR, // HomeSpan is in Command Mode with "Unpair Device" specified as choice
|
||||
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
|
||||
HS_CONFIG_MODE_LAUNCH_AP_SELECTED, // User has selected "Launch AP Access" from the Command Mode
|
||||
HS_CONFIG_MODE_UNPAIR_SELECTED, // User has seleected "Unpair Device" from the Command Mode
|
||||
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
|
||||
|
||||
// CREATE THIS STRUCTURE SOMEWHERE NEAR TOP OF SKETCH
|
||||
|
||||
struct invertedLED : Blinkable { // create a child class derived from Blinkable
|
||||
|
||||
int pin; // variable to store the pin number
|
||||
|
||||
invertedLED(int pin) : pin{pin} { // constructor that initializes the pin parameter
|
||||
pinMode(pin,OUTPUT); // set the pin to OUTPUT
|
||||
digitalWrite(pin,HIGH); // set pin HIGH (which is off for an inverted LED)
|
||||
}
|
||||
|
||||
void on() override { digitalWrite(pin,LOW); } // required function on() - sets pin LOW
|
||||
void off() override { digitalWrite(pin,HIGH); } // required function off() - sets pin HIGH
|
||||
int getPin() override { return(pin); } // required function getPin() - returns pin number
|
||||
};
|
||||
```
|
||||
|
||||
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++
|
||||
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"
|
||||
// THEN USE THE STRUCTURE IN SETUP() TO SET THE STATUS LED
|
||||
|
||||
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
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue