Seich
/
HomeSpan
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update Reference.md

This commit is contained in:
HomeSpan 2021-10-30 16:58:02 -05:00 committed by GitHub
parent 59eb8e4cf3
commit 3cdd12f7b6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 27 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
docs/Reference.md
View File

@ -273,6 +273,33 @@ 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
```
### *#define CUSTOM_CHAR(name,uuid,perms,format,defaultValue,minValue,maxValue,staticRange)*
Creates a custom Characteristic that can be added to any Service. Custom Characteristics are generally ignored by the Home App but may be used by other third-party applications (such as Eve for HomeKit). Parameters are as follows (note that quotes should NOT be used in any of the string parameters):
* *name* - the name of the custom Characteristic. This will be added to the Characteristic namespace so that it is accessed the same as any HomeSpan Characteristic
* *uuid* - the UUID of the Characteristic as defined by the manufacturer. Must be *exactly* 36 characters in the form XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, where *X* represent a valid hexidecimal digit. Leading zeros are required if needed as described more fully in HAP-R2 Section 6.6.1
* *perms* - additive list of permissions as described in HAP-R2 Table 6-4. Valid values are PR, PW, EV, AA, TW, HD, and WR
* *format* - specifies the format of the Characteristic value, as described in HAP-R2 Table 6-5. Valid value are BOOL, UINT8, UINT16, UNIT32, UINT64, INT, FLOAT, and STRING. Note that the HomeSpan does not presently support the TLV8 or DATA formats
* *defaultValue* - specifies the default value of the Characteristic if not defined during instantiation
* *minValue* - specifies the default minimum range for a valid value, which may be able to be overriden by a call to `setRange()`
* *minValue* - specifies the default minimum range for a valid value, which may be able to be overriden by a call to `setRange()`
* *staticRange* - set to *true* if *minValue* and *maxValue* are static and cannot be overridden with a call to `setRange()`. Set to *false* if calls to `setRange()` are allowed
As an example, the following creates a custom Characteristic named "Voltage" with a UUID code that is recognized by Eve for HomeKit. The parameters show that the Characteristic is read-only (PR) and notifications are enabled (EV). The default range of allowed values is 0-240, with a default of 120. The range *can* be overridden by subsequent calls to `setRange()`:
```C++
CUSTOM_CHAR(Voltage, E863F10A-079E-48FF-8F27-9C2605A29F52, PR+EV, UINT16, 120, 0, 240, false);
...
new Service::LightBulb();
new Characteristic::Name("Low-Voltage Lamp");
new Characteristic::On(0);
new Characteristic::Brightness(50);
new Characteristic::Voltage(12); // adds Voltage Characteristics and sets initial value to 12 volts
```
Note that Custom Characteristics must be created prior to calling `homeSpan.begin()`
---
#### Deprecated functions (available for backwards compatibility with older sketches):