From 2f8cd511ddb227de535aadf9e04ae2c3c9e85376 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Sun, 7 Mar 2021 08:45:24 -0600 Subject: [PATCH 1/3] Update Reference.md --- docs/Reference.md | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/docs/Reference.md b/docs/Reference.md index aeb2a9f..718192f 100644 --- a/docs/Reference.md +++ b/docs/Reference.md @@ -171,15 +171,16 @@ The following methods are supported: * `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 + * example: `(new Characteristic::Brightness(50))->setRange(10,100,5);` -## *SpanRange(int min, int max, int step)* - -Creating an instance of this **class** overrides the default HAP range for a Characteristic with the *min*, *max*, and *step* values specified. - -* instantiated Ranges are added to the HomeSpan HAP Database and associated with the last Characteristic instantiated -* instantiating a Range without first instantiating a Characteristic throws an error during initialization -* example: `new Characteristic::Brightness(50); new SpanRange(10,100,5);` - ## *SpanButton(int pin, uint16_t longTime, uint16_t singleTime, uint16_t doubleTime)* Creating an instance of this **class** attaches a pushbutton handler to the ESP32 *pin* specified. @@ -213,6 +214,15 @@ If REQUIRED is defined in the main sketch prior to including the HomeSpan librar ```C++ #define REQUIRED VERISON(2,1,3) // throws a compile-time error unless HomeSpan library used is version 2.1.3 or later ``` +### *SpanRange(int min, int max, int step)* + +Creating an instance of this **class** overrides the default HAP range for a Characteristic with the *min*, *max*, and *step* values specified. + +* instantiated Ranges are added to the HomeSpan HAP Database and associated with the last Characteristic instantiated +* instantiating a Range without first instantiating a Characteristic throws an error during initialization +* example: `new Characteristic::Brightness(50); new SpanRange(10,100,5);` +* **this is a legacy function that is limited to integer-based parameters, and has been re-coded to simply call the more generic `setRange(min, max, step)` method** +* **please use setRange(min, max, step) for all new sketches** --- From 9e124ab7719f3b7adbe2adc084fc31de08370304 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Sun, 7 Mar 2021 08:46:46 -0600 Subject: [PATCH 2/3] Update Reference.md --- docs/Reference.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/Reference.md b/docs/Reference.md index 718192f..85fb1da 100644 --- a/docs/Reference.md +++ b/docs/Reference.md @@ -214,14 +214,16 @@ If REQUIRED is defined in the main sketch prior to including the HomeSpan librar ```C++ #define REQUIRED VERISON(2,1,3) // throws a compile-time error unless HomeSpan library used is version 2.1.3 or later ``` -### *SpanRange(int min, int max, int step)* +--- + +## *SpanRange(int min, int max, int step)* Creating an instance of this **class** overrides the default HAP range for a Characteristic with the *min*, *max*, and *step* values specified. * instantiated Ranges are added to the HomeSpan HAP Database and associated with the last Characteristic instantiated * instantiating a Range without first instantiating a Characteristic throws an error during initialization * example: `new Characteristic::Brightness(50); new SpanRange(10,100,5);` -* **this is a legacy function that is limited to integer-based parameters, and has been re-coded to simply call the more generic `setRange(min, max, step)` method** +* this is a legacy function that is limited to integer-based parameters, and has been re-coded to simply call the more generic `setRange(min, max, step)` method * **please use setRange(min, max, step) for all new sketches** --- From 209836c1704d1ac39f9afea6b54efd798be848d4 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Sun, 7 Mar 2021 08:52:18 -0600 Subject: [PATCH 3/3] Update Reference.md --- docs/Reference.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/Reference.md b/docs/Reference.md index 85fb1da..8dcf86c 100644 --- a/docs/Reference.md +++ b/docs/Reference.md @@ -151,6 +151,7 @@ This is a **base class** from which all HomeSpan Characteristics are derived, an * 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 following methods are supported: @@ -167,7 +168,8 @@ 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. + * 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 + * 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()` * `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)