Also, updated error checking so that the UUID for both custom Services and custom Characteristics are checked for syntax. A fatal error is thrown if an ill-formatted UUID is found, since this will definitely prevent pairing with the HomeApp.
The UUID for HAP Services and Characteristics are NOT error checked, since these are fixed in HomeSpan.
Also, the custom Characteristics are not validated against the optional list for a service. If the user adds a custom Characteristic to a HAP Service, it is assumed to be valid. Similarly, none of the Characteristics (HAP of Custom) in a Custom Service are validated at all.
Use homeSpan.reserveSocketConnections(n) to reserve n sockets *not* to be used for HAP. Multiple calls can be used to cumulate a total number of reserved sockets. This makes is easy to add reserveSocketConnections(n) at multiple point in the code whenever a certain number of sockets need to be reserved for use with that portion of the code. For example enableOTA() calls reserveSocketConnections(1).
If both setMaxConnections(), and one or more reserveSocketConnections(), methods are called HomeSpan will use the more restrictive net value.
Callback function must be of type void()(boolean isPaired). Will be called when device is paired and when device is unpaired. Allows for user-defineable actions upon device pairing/unpairing.
Optional method to automatically turn off Status LED after a *duration* seconds. LED will resume normal operation any time it is re-triggered with a new pattern. This also resets the elapsed time used to check for autoOff.
This allows you to add an optional "description" to a Characteristic. This is not the same as the name of a Service and is generally not used by the Home App. However, it appears to be consumed by the Eve app, which can be helpful in some circumstances when developing custom characteristics.
This returns a vector of linked Services that can be used in a for-each loop as such:
for(auto services : getLinks()){ ... }
Must cast services into specific Service type to access anything not generic to the SpanService class
Second optional argument to setVal() determines whether or not HomeSpan sends notification of new value to HomeKit. Default if left blank is "true" for backwards compatibility.
And also converted ERRORS to WARNINGS when a Characteristic that is not in the REQ or OPT list is specified for a Service. This allows the user to add any Characteristic to any Service without forcing an Error (just a Warning).
Ranges are now checked for all Characteristics at the end of the configuration, instead of at the end of each Accessory definition. This is much cleaner and the output is easier to read.
To do: Revisit use of REQ and OPT - what should constitute a fatal error and what should be a warning.
To do: Revisit Character definitions - attempt to normalize using the methods implemented for Custom Characteristics
No need to specify both FORMAT and TYPE. For example, specifying UINT16 automatically sets type to be uint16_t.
To do: Explore if this can be used for standard Characteristics - revisit standard Characteristics definitions and structure to see if it can be simplified.
This will cause a Warning (not an Error) at compile time indicating the class has been deprecated and that the Characteristic::setRange() method should be used instead. Sketch will still run and SpanRange will still function correctly if used. Will delete from code base at some point in the future.
Re-worked code to allow for NO Status LED Pin and NO Control Pin. If Control Pin is not set explicitly with homeSpan.setControlPin(), there will be no Control Pin. There is no longer a default since there are too many board variations with S2 and C3 chips now supported. Same for Status Pin - it will not be defined unless set explicitly with homeSpan.setStatusPin(), with the exception that if LED_BUILTIN is defined (i.e. there is a built-in LED), then the Status LED Pin will default to LED_BUILTIN if not explicitly defined. MUST UPDATE DOCUMENTATION - THIS CHANGES DEFAULT BEHAVIOR OF HOMESPAN AND MAY REQUIRE UPDATES TO EXISTING SKETCHES
Simplified enableAutoStartAP() so it no longer takes any arguments. It now simply enables the auto launch of the WiFi Access Point at start-up if WiFi Credentials are not found.
New method setApFunction() will now be used to set an alternative method for the WiFi Access Point. This will be called anytime 'A' is typed into the CLI, which also covers the auto-launch of the AP at start-up a well as starting it via the Control Button, since both of these functions call processCommand('A').
To enable save/restore for a Characteristic, set second parameter to TRUE when instantiating. Since first parameter was optional as well, this requires setting it as well.
Next up: Must add logic to setVal() to store new value as well.
Allows the user to add a command function to the Command Line Interface. All User Commands are defined with a '@' prefix.
To Do: Document this new feature.
Also added new flag "staticRange" for all Characteristics that indicates whether the min/max range can be changed. An ERROR will be thrown if setRange is attempted for a Characteristic having staticRange=true.
Next TO DO: Complete entry of default min/max into all Characteristics (except BOOL and STRING) defined Span.h so that setRange() error checking works for all Characteristics.
Warning will be thrown if setVal() request is outside of mix/max range for the Characteristic, though min/max range not yet modified by SpanRange().
TO DO: Create new Characteristic methods setRange(typename T_MIN, typename T_MAX) and setRange(typename T_MIN, typename T_MAX, typename T_STEP) that will reset min/max, or min/max/step, and trigger required output in database. Add in checks to ensure setRange is NOT used to STRING or BOOLEAN. Also add check to ensure STEP is always>0. Add new UVAL for STEP that is normally zero, which indicates NO step size has been set (and does not need to be reported to database). Then, set warnings about SpanRange being deprecated at some point in the future.
Added Characteristics.h file that defines all static data for HAP Characteristics. Changed macros in Services.h to use this new HapChar structure.
Code is now more streamlined and ready for mix/max range-checking to be added.
Functionality is identical, but template has been moved into UVal structure along with setVal, which simplifies code and allows for other uses if needed.
Ensures robustness and is fully backwards compatible. User does NOT have to specify a template parameter, as the compiler determines this from the setVal() argument itself. Allows for any numeric type to be properly mapped to correct HAP format for the Characteristic.
This change is also needed to prepare for the refactoring of SpanRange, the addition of UVals to store HAP min/max, and new error-checking of min/max limits within setVal.
Updated setVal() logic to ensure that every possible combination of parameter type and Characteristic type is handled properly, and without generating a compile-time error related to ambiguous parameters.
New SpanService method addLink(SpanService *svc), where svc is a pointer to the SpanService that is being specified as a Linked Service for the current Service.
addLink() returns a pointer to "this" so may be chained
homeSpan.enableOTA() is now homeSpan.enableOTA(boolean auth=true). Set auth=false to disable password authentication. Set to true, or leave blank, to enable password authentication.
HomeSpan will call a user-defined function upon establishing WiFi connectivity.
Set function with homeSpan.setWifiCallback(f), where f must be of form void f().
Specify with homeSpan.setSketchVersion(char *).
Read back with homeSpan.getSketchVersion().
Also, MDNS now broadcasts three new fields:
hspn = HomeSpan Version
sketch = Sketch Version
ota = "yes" if OTA enabled, else "no"
These are all optional to HAP but useful if trying to keep track of version updates when using OTA and Serial Monitor is not available.
OTA pasword now stored in NVS. Use 'O' command to change from default. Note password is stored as MD5 hash, and is therefore unrecoverable. Changes to password DO NOT take effect until next reboot. Password CAN be changed even if OTA has not been enabled for sketch. Blank passwords are not allowed.
Stored password can only be erased with 'E' command.
Setup ID can now be stored in NVS and set dynamically with the 'Q' command. However, homeSpan.setQRID(char *id) will override if present, but will not change the default stored in the NVS. This default wil be used once again if homeSpan.setQRID() is removed from the sektch.
If the NVS is empty, the default is set to "HSPN" as in version 1.1.4.
Class used for the creation and storage of a pairing QR Code (just the text, not the actual graphic) from a HAP Setup Code, HAP Category, and HAP Setup ID. The resulting QR Code text is output to Serial Monitor whenever the SetUp Code is generated or changed. The user can type this text into any QR Generator to create a QR Code graphic for pairing the device to HomeKit (in lieu of creating a printed tag of the Setup Code formatted using the Scancardium font).
Though not needed for HomeSpan, this class implements all the settings and parameters (such as Version and Reserved) used to generate any Apple HomeKit QR Code.
This class is used internally by HomeSpan and is not intended for the end-user.
HomeSpan now broadcasts a Hashed Setup ID as MDNS "sh", which is used when pairing with a QR Code instead of a Setup Code. A text version of the resulting QR code is output to the Serial Monitor whenever the 9-digit Setup Code is generated or changed. The text version of the QR code can then be input into any QR Code Generator to create a pairable QR Code.
The default Setup ID used to create the Hashed Setup ID is "HSPN". This can be changed with homeSpan.setQRCode(const char *id), where id is exactly 4 alphanumeric characters. If not, the request to change the Setup ID is silently ignored and remains "HSPN."
HomeSpan defaults to running the HAP Server on port 80 (the standard HTTP port). This method allows the user to over-ride the default and have HomeSpan run the HAP Server on any other port.
ALSO: In updating this portion of the code, identified an additional parameter to the ESP32 version of WiFiServer that allows one to specify the number of simultaneous Server connections. The ESP32 default is 4, which suggests that the ESP32 was internally juggling connections that HomeSpan was keeping open (since the HomeSpan default is 8 connections).
This WiFiServer call has been updated to now specify both the port number AND the number of maximum simultaneous connections (to match whatever has been set by HomeSpan). This may or may not result in improving performance when more than 4 clients are connected.
LED_BUILTIN is NOT defined for all ESP32 boards - some do not have a built-in LED! Instead, Status LED now defaults to Pin 13, as opposed to LED_BUILTIN. Also, added a new method, homeSpan.getStatusPin(), to return the pin number used for the Status LED, whether or not it remains the default (13) or is changed by user with homeSpan.setStatusPin(pin). This method is now used in the DEV_Identify.h file for each example, instead of using LED_BUILTIN (which otherwise won't compile for boards without a built-in LED)
WiFi connection now occurs asynchronously so that if WiFi is lost, or cannot be connected at start-up, the device still operates intead of blocking while it tries to connect. The new logic should allow for a wider range of chips to connect.
1) Used `const char *` instead of `char *` where appropriate, including the need to create a dummy blank string for us in certain places.
2) Set initialization of WiFiClient to 0 instead of NULL, since WiFiClient is not a pointer (probably don't need to set it to anything since WiFiClient overrides the boolean operator anyway).
3) Cleaned up some of the messaging and logic when WiFi tries to connect so that users know to wait a bit.
4) Only remaining warning messages are for casting SpanService to (void *), which I think i unavailable (and is not forbidden).
To Do: Go through examples and check for warnings (will likely need to convert `char *` to `const char *` in many places.
If not specified, "aid" defaults to an index number representing the order in which the Accessories were created. Values are stored as uint32_t (which is more limited than HAP requirements of uint64_t, but makes the code easier).
TO DO: Must add validation to ensure duplicate aid values are not used.
button(int pin, boolean isLong) changed to button(int pin, int pressType), where pressType can be SpanButton::LONG, SpanButton::SINGLE, or SpanButton::DOUBLE. Updated Example 16 and confirmed everything works as expected.
To do: Review all prior examples and update SpanButton when needed. Also need to update Zephyr Vent Hood code!
Added ServiceLabelIndex Characteristic, which seems to be required as noted in HAP specifications. However, linking to a ServiceLabel Service does not appear to be required, so there is no need to build any Service-Linking logic into homeSpan - will wait for use-case to be identified.
To do: Add support for double-click to SpanButton, then include in Example 16.
Modified SpanCharacteristic::sprintfAttributes to streamline logic and add special handling for the ProgrammableSwitchEvent Characteristic as required by HAP: the value returned for the database or any read request must be set to null (i.e. "value":null). The only time the real value should be returned is when the device sends a EV/Notify message (when the button is pressed). Verified that the example works as expected!
TO DO: Add functionality to allow for Service Namespace and Index label so that you can have multiple programmable pushbuttons in one service - this requires logic for HAP LINKED SERVICE functionality.
Added validation to ensure all Accessories have a AccessoryInformation Service and all Accessories have a HAPProtocolInformation Service, unless the device is configured as a bridge, in which case only the first Accessory requires a HAPProtocolInformation Service.
Created HAPCharType and added vectors for required and optional characteristics to every service. Next up: add all HAP characteristic types to HAPCharType
Changing code so that it is possible to run HomeSpan without configuring WiFi. HomeSpan can already run without being paired, but requires WiFi at start-up. No reason to force WiFi to be used if device has buttons to operate the appliance withouth the need for WiFi or a connection to HomeKit. Work in progress...
Started adding lists to the first few Services in Service.h. This is a longer-term project to enable HomeSpan to validate a configuration and check that all Services have all required Characteristics and that any optional Characteristics defined are indeed permitted.
Full initialization now depends on "isInitialized" flag instead of monitoring Wifi connection, to protect against a loss of WiFi causing a re-initialization, instead of just a wifi reconnect with initWifi() alone.
SpanButton now instantiates PushButton instead of keeping track of its own triggering logic. This means that SpanButton longPress() is triggered by holding down the button for longTime WITHOUT the need to release. This is a desired change.
Next: Must update Example 15 to state that SpanButtons trigger a long press withouth needing to be released.
To do: Consider adding a "repeating mode" for longPress in which the SpanButton re-triggers every longTime while button continues to be pressed. Best way to implement is probably by creating a PushButton::extend() method.
Also moved StatusCode definitions from Settings.h to HAPConstants.h. There was no reason to have the user return a StatusCode of OK or UNABLE from update() since the only other choice was BUSY and HomeKit does not seem to distinguish errors. Either it's okay or not okay, which can more easily be represented by a simply return of TRUE or FALSE from update().
The user now needs to know nothing about StatusCodes. All Examples were modified to change StatusCode update() to boolean update() and return(StatusCode:OK) to return (true).
Much simpler.
This change allows the user to set the log-level with homeSpan.setLogLevel() instead of needing to change in Settings.h. Next up: Update Example that introduces VERBOSE to instead use setLogLevel(). Consider adding an interactive 'L' command to change this during run-time.
Also, added "#pragma once" to every *.h file to prevent duplication of definitions. TO DO: Review all #include to ensure sanity across all files.
These optional methods can be "chained" when instantiating a new SpanService to configure the Service as Primary or Hidden (or both). This alleviates the need to ServiceType to be propogated through the Service constructor.
Next Up: Eliminate ServiceType construct and update Examples to use setPrimary instead.
Created separate init() methods for PushButton and Blinker. Created HomeSpan:setControlPin and HomeSpan:setStatusPin that can be called from main setup() to modify the defaults. All default settings being migrated to Settings.h
And updated other SRP routines to complete implementation of use of stored verification code instead of live setup code.
Next up: Add method to change setup code in serial interface and implement similar code after network configuration routines.
This generates an SRP verification code from a setupCode and randomly-generated salt. Function creates the salt internally and returns both the resulting verification code and salt that was used. These are stored in NVS permanently.
Next Step: create SRP6A:loadVerifycode()
Move all configuration code into Network.cpp, eliminating any calls or connection to HAP.cpp. Network.cpp is now standalone for HomeSpan.cpp to call directly to handle ALL apects of WiFI and Setup Code initialization.
Also move TempBuffer from HAP.h to Utils.h so it can be used by Network.h
Allows for reset of HAP (press for 5 seconds, but less than 10) or Factory reset (press for 10 second). Use setResetPin to change from default of pint 21.
This is no longer needed since PushButtons can be easily emulated from within a Service loop() as per Example 14. Library is now fully up-to-date: TimedResets and SpanEvents have been fully removed.
Completed new framework for using loop() methods and deleted all code related to new SpanEvent() and event() loops. Re-worked Example 13 to utilize new framework and validated it functions as expected.
Service loops() called for only those Services with over-ridden loop() methods. TO DO: update event logic to follow new framework. Vector should point to all CHARACTERISTICS that are updated to setVal()
creating code to allow for multiple characteristics to be updated within event() call. To Do: define anogther sensor that supports multiple characteristics. also need to check that "new SpanEvent" works as expected from within a defined service.
putCharacteristics and checkNotifications now both call the same eventNotify routing. This is being done to prepare for services that will stream notifications back to client (like a temperature sensor, or pushbutton). TO DO: rename checkNotifications to check TimedResets, and rename SpanPut to something more generic.
Transtioned to all getter methods: getVal(), getNewVal(), updated(), using templates for all floats.
Finalized templates for getVal and getNewVal, including making <int> default so it does not have to be set for most getVal() and getNewVal() calls. Works for booleans as well. TO DO: Re-work and check ALL prior examples to ensure they use getVal, etc., and DON'T access value, newValue, isUpdated, directly.
Updated SpanRange to register itself automatically to the most recent Characteristic. This is more consistent with the overall framework and no longer requires user to access the range variable directly.
Gregg