From aed2936b112a2261287d8447524342b1dc418beb Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Wed, 25 Nov 2020 19:27:38 -0600 Subject: [PATCH] Update Reference.md --- docs/Reference.md | 59 ++++++++++++++++++++++++++--------------------- 1 file changed, 33 insertions(+), 26 deletions(-) diff --git a/docs/Reference.md b/docs/Reference.md index 8234ebd..8d07dc7 100644 --- a/docs/Reference.md +++ b/docs/Reference.md @@ -6,60 +6,67 @@ The HomeSpan Library is invoked by including *HomeSpan.h* in your Arduino sketch #include "HomeSpan.h" ``` +## *homeSpan* (object) + At runtime this HomeSpan will create a global object named `homeSpan` that supports the following methods: * `void begin(Category catID, char *displayName, char *hostNameBase, char *modelName)` - * Initializes HomeSpan. - * **Must** be called at the beginning of each sketch before any other HomeSpan functions and is typically placed near the top of the Arduino `setup()` method, but **after** `Serial.begin()` so that initialization diagnostics can be output to the Serial Monitor. - * All arguments are **optional**. - * *catID* - the HAP Category HomeSpan broadcasts for pairing to HomeKit. Default is Category::Lighting. See [HomeSpan Accessory Categories](Categories.md) for a complete list. - * *displayName* - the MDNS display name broadcast by HomeSpan. Default is "HomeSpan Server". - * *hostNameBase* - the full MDNS host name is broadcast by HomeSpan as *hostNameBase-DeviceID*.local, where DeviceID is a unique 6-byte code generated automatically by HomeSpan. Default is "HomeSpan". - * *modelName* - the HAP model name HomeSpan broadcasts for pairing to HomeKit. Default is "HomeSpan-ESP32". + * initializes HomeSpan + * **must** be called at the beginning of each sketch before any other HomeSpan functions and is typically placed near the top of the Arduino `setup()` method, but **after** `Serial.begin()` so that initialization diagnostics can be output to the Serial Monitor + * all arguments are **optional** + * *catID* - the HAP Category HomeSpan broadcasts for pairing to HomeKit. Default is Category::Lighting. See [HomeSpan Accessory Categories](Categories.md) for a complete list + * *displayName* - the MDNS display name broadcast by HomeSpan. Default is "HomeSpan Server" + * *hostNameBase* - the full MDNS host name is broadcast by HomeSpan as *hostNameBase-DeviceID*.local, where DeviceID is a unique 6-byte code generated automatically by HomeSpan. Default is "HomeSpan" + * *modelName* - the HAP model name HomeSpan broadcasts for pairing to HomeKit. Default is "HomeSpan-ESP32" + * example: `homeSpan.begin(Category::Fans, "Living Room Ceiling Fan");` * `void poll()` - * Checks for HAP requests, local commands, and device activity. - * **Must** be called repeatedly in each sketch and is typically placed at the top of the Arduino `loop()` method. + * checks for HAP requests, local commands, and device activity + * **must** be called repeatedly in each sketch and is typically placed at the top of the Arduino `loop()` method The following **optional** `homeSpan` methods override various HomeSpan initialization parameters used in `begin()`, and therefore **should** be called before `begin()` to take effect. If a method is *not* called, HomeSpan uses the default parameter indicated below: * `void setControlPin(uint8_t pin)` - * Sets the ESP32 pin to use for the HomeSpan Control Button (default=21). + * sets the ESP32 pin to use for the HomeSpan Control Button (default=21) * `void setStatusPin(uint8_t pin)` - * Sets the ESP32 pin to use for the HomeSpan Status LED (default=LED_BUILTIN). + * sets the ESP32 pin to use for the HomeSpan Status LED (default=LED_BUILTIN) * `void setApSSID(char *ssid)` - * Sets the SSID (network name) of the HomeSpan Setup Access Point (default="HomeSpan-Setup"). + * sets the SSID (network name) of the HomeSpan Setup Access Point (default="HomeSpan-Setup") * `void setApPassword(char *pwd)` - * Sets the password of the HomeSpan Setup Access Point (default="homespan"). + * sets the password of the HomeSpan Setup Access Point (default="homespan") * `void setApTimeout(uint16_t nSec)` - * Sets the duration (in seconds) that the HomeSpan Setup Access Point, once activated, stays alive before timing out (default=300 seconds). + * sets the duration (in seconds) that the HomeSpan Setup Access Point, once activated, stays alive before timing out (default=300 seconds) * `void setCommandTimeout(uint16_t nSec)` - * Sets the duration (in seconds) that the HomeSpan End-User Command Mode, once activated, stays alive before timing out (default=120 seconds). + * sets the duration (in seconds) that the HomeSpan End-User Command Mode, once activated, stays alive before timing out (default=120 seconds) * `void setLogLevel(uint8_t level)` - * Sets the logging level for diagnostic messages, where: + * sets the logging level for diagnostic messages, where: * 0 = top-level status messages only (default), * 1 = all status messages, and - * 2 = all status messages plus all HAP communication packets to and from the HomeSpan device. - * This parameter can also be changed at runtime via the [HomeSpan CLI](CLI.md). + * 2 = all status messages plus all HAP communication packets to and from the HomeSpan device + * this parameter can also be changed at runtime via the [HomeSpan CLI](CLI.md) * `void setMaxConnections(uint8_t nCon)` - * Sets the maximum number of HAP Controllers that be simultaneously connected to HomeSpan (default=8). + * sets the maximum number of HAP Controllers that be simultaneously connected to HomeSpan (default=8) -## Creating the HAP Accessory Attributes Database - Primary Classes +## *SpanAccessory()* (class) -The HAP Accessory Attributes Database is constructed by instantiating (using `new`) a combinaton of the following HomeSpan Classes: +Creating an instance of this class add a new HAP Accessory to the HomeSpan HAP Database. + + * every HomeSpan sketch requires at least one Accessory + * there are no arguments or associated methods + * you must call `homeSpan.begin()` before instantiating any Accessories + * example: `new SpanAccessory();` + +## *SpanService()* (base class) + +This is a **base class** from which all HomeSpan Services are derived. To create a new Service, instantiate one of HomeSpan Services defined in the Service namespace -* `SpanAccessory()` - * This creates a new HAP Accessory to hold HAP Services. - * There are no arguments or methods. - * You must call `homeSpan.begin()` before instantiating any Accessories. - * Every HomeSpan sketch requires at least one Accessory. * `SpanService()` * This is the base class for creating new HAP Services. It should