Update Reference.md

docs/Reference.md

@@ -78,11 +78,11 @@ The following methods are supported:
 * `SpanService *setHidden()`
   * specifies that this is hidden Service for the Accessory.  Returns a pointer to the Service itself so that the method can be chained during instantiation.
 * `virtual boolean update()`
-  * HomeSpan calls this method upon receiving a request from a HomeKit Controller to update one or more Characteristics associated with the Service.  Users should override this method with code that implements that requested updates and returns *true* or *false* if the update succeeds or fails
+  * HomeSpan calls this method upon receiving a request from a HomeKit Controller to update one or more Characteristics associated with the Service.  Users should override this method with code that implements that requested updates using one or more of the SpanCharacteristic methods below.  Method **must** return *true* if update succeeds, or *false* if not.
 * `virtual void loop()`
-  * HomeSpan calls this method every time `homeSpan.poll()` is executed.  Users should override this method with code that monitors for state changes in Characteristics that require HomeKit Controllers to be notified.
+  * HomeSpan calls this method every time `homeSpan.poll()` is executed.  Users should override this method with code that monitors for state changes in Characteristics that require HomeKit Controllers to be notified using one or more of the SpanCharacteristic methods below.
 * `virtual void button(int pin, int pressType)`
-  * HomeSpan calls this method whenever a SpanButton() object associated with the Service is triggered.  Users should override this method with code that implements any actions to be taken in response to the SpanButton() trigger
+  * HomeSpan calls this method whenever a SpanButton() object associated with the Service is triggered.  Users should override this method with code that implements any actions to be taken in response to the SpanButton() trigger using one or more of the SpanCharacteristic methods below.
     * *pin* - the ESP32 pin associated with the SpanButton() object
     * *pressType* - 
       * 0=single press (SpanButton::SINGLE)
@@ -101,6 +101,19 @@ This is a **base class** from which all HomeSpan Characteristics are derived, an
 The following methods are supported:
 
 * `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 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*.
-  * Example with template specified: `double temp = Characteristic::CurrentTemperature->getVal<double>();`
+  * example with template specified: `double temp = Characteristic::CurrentTemperature->getVal<double>();`
-  * Example with template excluded : `int tilt = Characteristic::CurrentTiltAngle->getVal();`
+  * 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<>()`
+  
+* `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(int value)`
+* `void setVal(double value)`
+  * sets the value of the Characteristic to *value*, and notifies all HomeKit Controllers of the change.  Works with any integer, boolean, or floating-based numerical value.
+  
+* `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)