From 41f755039f5a3992b09820f9ebbc2c6a4bd31640 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Sat, 16 Mar 2024 14:29:36 -0500 Subject: [PATCH] Update Reference.md --- docs/Reference.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/Reference.md b/docs/Reference.md index dc45cbb..56109b9 100644 --- a/docs/Reference.md +++ b/docs/Reference.md @@ -399,7 +399,11 @@ This is a **base class** from which all HomeSpan Characteristics are derived, an * `void setVal(value [,boolean notify])` * 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()` + * throws a runtime warning if any of the conditions hold: + * the Characteristic is not configured with Event Notification (EV) permission enabled; or + * this method is being called from within the `update()` routine of a **SpanService** and `isUpdated()` is *true* for the Characteristic (i.e. it is being updated at the same time via the Home App); or + * *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()` + * the first two restrictions above do not apply to the use of `setVal()` from within the `update()` method of a **SpanService** if you are changing the value of a Characteristic in response to a *write-response* request from HomeKit * *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) * `SpanCharacteristic *setRange(min, max, step)`