From ce011de7679856497964a93ef219cea2eb977408 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Thu, 30 Dec 2021 08:31:38 -0600 Subject: [PATCH 1/3] Update FAQ.md --- docs/FAQ.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index 996e84a..249d727 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -47,7 +47,11 @@ #### Can you add a Web Server to HomeSpan? * Yes, provided you implement your Web Server using standard ESP32-Arduino libraries, such as `WebServer.h`. See [ProgrammableHub](https://github.com/HomeSpan/ProgrammableHub) for an illustrative example of how to easily integrate a Web Server into HomeSpan. This project also covers various other advanced topics, including TCP slot management, dynamic creation of Accessories, and saving arbitrary data in the ESP32's NVS. -* Note *ESP32AsyncWebServer* cannot be used since it requires a TCP stack that is unfortunately incompatible with HomeSpan. +* Note *ESP32AsyncWebServer* cannot be used since it requires a TCP stack that is unfortunately incompatible with HomeSpan. + +#### Can HomeSpan be used for commercial devices? + +* No, a MFi license is needed to create commercial devices. HomeSpan was developed using Apple's HAP-R2 specs, which Apple provides for [non-commercial devices that won't be distributed or sold](https://developers.apple.com/homekit/faq/). Though I believe the commercial specifications are functionally the same, there is a slight, but critical, difference in the pairing protocol between HAP-R2 and MFi. Note that when you pair a HomeSpan device (or any device that is based on HAP-R2, such as Apple's HAP-R2 ADK, Espressif's non-commercial ADK, HomeBridge, etc.) the Home App on your iPhone will flag the device as uncertified and require you to grant it permission to proceed with pairing. This warning message about the device being uncertified does not appear on commercial devices, presumably because Apply provides the licensee with a custom MFi authorization code that is recognized by the iPhone. --- From c27d2440e6f48a9bc0efd2b129c81828e1f99899 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Sat, 19 Mar 2022 14:05:50 -0500 Subject: [PATCH 2/3] Update Reference.md --- docs/Reference.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/Reference.md b/docs/Reference.md index 7762734..8db18e0 100644 --- a/docs/Reference.md +++ b/docs/Reference.md @@ -224,22 +224,31 @@ This is a **base class** from which all HomeSpan Characteristics are derived, an The following methods are supported: * `type T getVal()` - * 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();` * example with template excluded : `int tilt = Characteristic::CurrentTiltAngle->getVal();` * `type T getNewVal()` - * 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) + +* `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) + * `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) From 1acb9fe2f58b11ded1b519a87b0df493a9ee76b6 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Sat, 19 Mar 2022 18:16:04 -0500 Subject: [PATCH 3/3] Update Reference.md --- docs/Reference.md | 38 +++++++++++++++++++++----------------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/docs/Reference.md b/docs/Reference.md index 8db18e0..65ae60a 100644 --- a/docs/Reference.md +++ b/docs/Reference.md @@ -221,7 +221,7 @@ 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()` * 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*. @@ -230,28 +230,13 @@ The following methods are supported: * `type T getNewVal()` * 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 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) -* `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) - -* `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 * *step* is optional; if unspecified (or set to a non-positive number), the default HAP step size remains unchanged @@ -270,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