diff --git a/docs/Reference.md b/docs/Reference.md index b9af9d3..9f73bcf 100644 --- a/docs/Reference.md +++ b/docs/Reference.md @@ -168,20 +168,22 @@ The following methods are supported: * 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)` - * 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*, though HomeSpan will convert *value* into the appropriate type for each Characteristic (e.g. value=5.5 is converted to 5 if used with an integer-based 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 prior call to `setRange()` - * accepts any *value* within the allowed min/max range regardless of the setting of step size. Step size is only used by the Home App to limit the increments of adjustment for sliders, and will use a rounded version of *value* for display purposes of the slider while retaining the actual numerical value internally + * 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*, 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* values specified - * only applicable for Characteristics that support value ranges, else error is thrown - * can only set set once per Characteristic. Calling setRange twice for the same Characteristic throws an error - * works with any integer or floating-based parameters, though HomeSpan will recast the values into the appropriate format for the Characteristic, which means if you specify *step*=0.5 for a UINT8 Characteristic, *step* will be truncated to zero - * *step* is an optional parameter. If unspecified, or set to zero or a negative number, the default HAP step size remains unchanged - * Returns a pointer to the Characteristic itself so that the method can be chained during instantiation + * overrides the default HAP range for a Characteristic with the *min*, *max*, and *step* parameters specified + * *step* is optional; if unspecified (or set to a non-positive number), the default HAP step size remains unchanged + * works with any integer or floating-based parameters, though HomeSpan will recast the parameters into the appropriate type for each Characteristic (e.g. calling `setRange(50.5,70.3,0.5)` on an integer-based Characteristic results in *min*=50, *max*=70, and *step*=0) + * an error is thrown if: + * called on a Characteristic that does not suport range changes, or + * called more than once on the same Characteristic + * returns a pointer to the Characteristic itself so that the method can be chained during instantiation * example: `(new Characteristic::Brightness(50))->setRange(10,100,5);` ## *SpanButton(int pin, uint16_t longTime, uint16_t singleTime, uint16_t doubleTime)*