Update Reference.md

docs/Reference.md

@@ -221,27 +221,21 @@ This is a **base class** from which all HomeSpan Characteristics are derived, an
   * `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:
+#### The following methods are supported for numerical-based Characteristics (e.g. *int*, *float*...):
 
 * `type T getVal<T>()`
-  * a template method that returns the **current** value of the Characteristic, after casting into the type *T* specified (e.g. *int*, *double*, etc.).  If template parameter is excluded, value will be cast to *int*.
+  * a template method that returns the **current** value of a numerical-based Characteristic, after casting into the type *T* specified (e.g. *int*, *double*, etc.).  If template parameter is excluded, value will be cast to *int*.
   * example with template specified: `double temp = Characteristic::CurrentTemperature->getVal<double>();`
   * example with template excluded : `int tilt = Characteristic::CurrentTiltAngle->getVal();`
 
 * `type T getNewVal<T>()`
-  * a template method that returns the desired **new** value to which a HomeKit Controller has requested to the Characteristic be updated.  Same casting rules as for `getVal<>()`
+  * a template method that returns the desired **new** value to which a HomeKit Controller has requested the Characteristic be updated.  Same casting rules as for `getVal<>()`.  Only applicable for numerical-based Characteristics
-  
+    
-* `boolean updated()`
-  * returns *true* if a HomeKit Controller has requested an update to the value of the Characteristic, otherwise *false*.  The requested value itself can retrieved with `getNewVal<>()`
-  
 * `void setVal(value [,boolean notify])`
-  * sets the value of the Characteristic to *value*, and, if *notify* is set to true, notifies all HomeKit Controllers of the change.  The *notify* flag is optional and will be set to true if not specified.  Setting the *notify* flag to false allows you to update a Characateristic without notifying any HomeKit Controllers, which is useful for Characteristics that HomeKit automatically adjusts (such as a countdown timer) but will be requested from the Accessory if the Home App closes and is then re-opened
+  * sets the value of a numerical-based Characteristic to *value*, and, if *notify* is set to true, notifies all HomeKit Controllers of the change.  The *notify* flag is optional and will be set to true if not specified.  Setting the *notify* flag to false allows you to update a Characateristic without notifying any HomeKit Controllers, which is useful for Characteristics that HomeKit automatically adjusts (such as a countdown timer) but will be requested from the Accessory if the Home App closes and is then re-opened
   * works with any integer, boolean, or floating-based numerical *value*, though HomeSpan will convert *value* into the appropriate type for each Characteristic (e.g. calling `setValue(5.5)` on an integer-based Characteristic results in *value*=5)
   * 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 min/max range set via a prior call to `setRange()`
   * *value* is **not** restricted to being an increment of the step size; for example it is perfectly valid to call `setVal(43.5)` after calling `setRange(0,100,5)` on a floating-based Characteristic even though 43.5 does does not align with the step size specified.  The Home App will properly retain the value as 43.5, though it will round to the nearest step size increment (in this case 45) when used in a slider graphic (such as setting the temperature of a thermostat)
-  
-* `int timeVal()`
-  * returns time elapsed (in millis) since value of the Characteristic was last updated (whether by `setVal()` or as the result of a successful update request from a HomeKit Controller)
 
 * `SpanCharacteristic *setRange(min, max, step)`
   * overrides the default HAP range for a Characteristic with the *min*, *max*, and *step* parameters specified
@@ -261,6 +255,25 @@ The following methods are supported:
   * returns a pointer to the Characteristic itself so that the method can be chained during instantiation
   * example: `(new Characteristic::SecuritySystemTargetState())->setValidValues(3,0,1,3);` creates a new Valid Value list of length=3 containing the values 0, 1, and 3.  This has the effect of informing HomeKit that a SecuritySystemTargetState value of 2 (Night Arm) is not valid and should not be shown as a choice in the Home App
 
+#### The following methods are supported for string-based Characteristics (i.e. a null-terminated C-style array of characters):
+
+* `char *getString()`
+  * equivalent to `getVal()`, but used exclusively for string-characteristics (i.e. a null-terminated array of characters)
+  
+* `char *getNewString()`
+  * equivalent to `getNewVal()`, but used exclusively for string-characteristics (i.e. a null-terminated array of characters)
+
+* `void setString(const char *value)`
+  * equivalent to `setVal(value)`, but used exclusively for string-characteristics (i.e. a null-terminated array of characters)
+
+#### The following methods are supported for all Characteristics:
+
+* `boolean updated()`
+  * returns *true* if a HomeKit Controller has requested an update to the value of the Characteristic, otherwise *false*.  The requested value itself can retrieved with `getNewVal<>()` or `getNewString()`
+
+* `int timeVal()`
+  * returns time elapsed (in millis) since value of the Characteristic was last updated (whether by `setVal()`, `setString()` or as the result of a successful update request from a HomeKit Controller)
+
 * `SpanCharacteristic *setPerms(uint8_t perms)`
   * changes the default permissions for a Characteristic to *perms*, where *perms* is an additive list of permissions as described in HAP-R2 Table 6-4.  Valid values are PR, PW, EV, AA, TW, HD, and WR
   * returns a pointer to the Characteristic itself so that the method can be chained during instantiation