Merge branch 'dev' of https://github.com/HomeSpan/HomeSpan into dev

docs/CLI.md

@@ -59,6 +59,9 @@ In addition to listening for incoming HAP requests, HomeSpan also continuously p
 * **A** - start the HomeSpan Setup Access Point
   * This command starts HomeSpan's temporary Access Point, which provides users with an alternate methods for configuring a device's WiFi Credentials and HomeKit Setup Code.  Starting the Access Point with this command is identical to starting it via the Control Button.  See the [HomeSpan User Guide](UserGuide.md) for complete details.
   
+* **V** - erases the values of any saved Characteristics
+  * As Characteristics are updated via the Home App, their latest values can be (optionally) saved in the device's non-volatile storage (NVS).  If the device should ever lose power this allows HomeSpan to restore the latest values of saved Characteristic upon the next start-up.  Typing 'V' from the CLI deletes all previously-saved Characteristic values from the NVS, though it does not alter the current values of those Characteristics.  This is useful in the event that saved Characteristics become out-of-sync with their stored values during the development phase of your sketch when adding, deleting, and changing the configuration of new Accessories, Services, and Characteristics.
+  
 * **U** - unpair device by deleting all Controller data
   * This deletes all data stored about Controllers that have been paired with the device, which forces HomeSpan to reset its internal state to unpaired.  Normally, unpairing is done by HomeKit at the direction of an end-user via the Home App on an iPhone.  However, HomeKit requests to unpair a device are not subject to any confirmation from that device.  HomeKit simply assumes that once it requests a device to unpair, the device has received the message and has reset its pairing state accordingly.  In the event that HomeKit unpairs a HomeSpan device, but the device does not receive or properly process the request, its pairing status will be out of sync with HomeKit.  Forcing HomeKit to reset its internal state to unpaired using this command resolves the issue and allows HomeSpan to be re-paired with HomeKit.
   * Note that if you run this command when HomeKit thinks it is still paired to the device, pairing status will be out of sync in the opposite direction.  HomeKit Controllers will continue to send HAP requests to the device, thinking it is paired, but HomeSpan will ignore all these requests since it no longer recognizes any of the Controllers as being paired.  To resolve this issue, you must instruct HomeKit to unpair the device via the Home App, after which you can re-pair the device if needed.

docs/Reference.md

@@ -148,15 +148,19 @@ The following methods are supported:
       * 1=double press (SpanButton::DOUBLE)
       * 2=long press (SpanButton::LONG)
     
-## *SpanCharacteristic(value)*
+## *SpanCharacteristic(value [,boolean nvsStore])*
   
 This is a **base class** from which all HomeSpan Characteristics are derived, and should **not** be directly instantiated.  Rather, to create a new Characteristic instantiate one of the HomeSpan Characteristics defined in the [Characteristic](ServiceList.md) namespace.
 
 * instantiated Characteristics are added to the HomeSpan HAP Database and associated with the last Service instantiated
 * instantiating a Characteristic without first instantiating a Service throws an error during initialization
-* a single, optional argument is used to set the initial value of the Characteristic at startup
-* throws a runtime warning if value is outside of the min/max range for the Characteristic, where min/max is either the HAP default, or any new values set via a call to `setRange()`
-* example: `new Characteristic::Brightness(50);`
+* the first argument optionally allows you to set the initial *value* of the Characteristic at startup.  If *value* is not specified, HomeSpan will supply a reasonable default for the Characteristic
+* throws a runtime warning if *value* is outside of the min/max range for the Characteristic, where min/max is either the HAP default, or any new values set via a call to `setRange()`
+* the second optional argument, if set to `true`, instructs HomeSpan to save updates to this Characteristic's value in the device's non-volative storage (NVS) for restoration at startup if the device should lose power.  If not specified, *nvsStore* will default to `false` (no storage)
+* examples:
+  * `new Characteristic::Brightness();`           Brightness initialized to default value
+  * `new Characteristic::Brightness(50);`         Brightness initialized to 50
+  * `new Characteristic::Brightness(50,true);`    Brightness initialized to 50; updates saved in NVS
 
 The following methods are supported:
 

docs/Tutorials.md

@@ -92,6 +92,11 @@ Example 17 introduces the HAP concept of Linked Services and demonstrates how th
 
 * creating Linked Services using the `addLink()` method
 
+### [Example 18 - SavingStatus](../examples/18-SavingStatus)
+Example 18 demonstrates, through the implementaton of two Dimmable LEDs, how the values of Characteristics can be automatically saved in the device's non-volatile storage (NVS) for restoration upon start-up if the device is loses power.   New HomeSpan API topics covered in this example include:
+
+* instructing HomeSpan to store the value of a Characteristic in NVS by setting the second parameter of the constuctor to `true`
+
 ---
 
 [↩️](README.md) Back to the Welcome page