Merge branch 'master' of https://github.com/HomeSpan/HomeSpan
This commit is contained in:
Gregg
commit
c742e86849
|
|
@ -1,3 +1,100 @@
|
|||
# HomeSpan Library Reference
|
||||
|
||||
*(coming soon)*
|
||||
The HomeSpan Library is invoked by including *HomeSpan.h* in your Arduino sketch as follows:
|
||||
|
||||
```C++
|
||||
#include "HomeSpan.h"
|
||||
```
|
||||
|
||||
## *homeSpan*
|
||||
|
||||
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"
|
||||
* 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
|
||||
|
||||
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)
|
||||
|
||||
* `void setStatusPin(uint8_t pin)`
|
||||
* 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")
|
||||
|
||||
* `void setApPassword(char *pwd)`
|
||||
* 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)
|
||||
|
||||
* `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)
|
||||
|
||||
* `void setLogLevel(uint8_t level)`
|
||||
* 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)
|
||||
|
||||
* `void setMaxConnections(uint8_t nCon)`
|
||||
* sets the maximum number of HAP Controllers that be simultaneously connected to HomeSpan (default=8)
|
||||
|
||||
## *SpanAccessory()*
|
||||
|
||||
Creating an instance of this **class** adds 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()*
|
||||
|
||||
This is a **base class** from which all HomeSpan Services are derived, and should **not** be directly instantiated. Rather, to create a new Service instantiate one of the HomeSpan Services defined in the [Service](ServiceList.md) namespace. No arguments are needed.
|
||||
|
||||
* instantiated Services are added to the HomeSpan HAP Database and associated with the last Accessory instantiated
|
||||
* instantiating a Service without first instantiating an Accessory throws an error during initialization
|
||||
* example: `new Service::MotionSensor();`
|
||||
|
||||
The following methods are supported:
|
||||
|
||||
* `SpanService *setPrimary()`
|
||||
* specifies that this is the primary Service for the Accessory. Returns a pointer to the Service itself so that the method can be chained during instantiation. Example: `new Service::Fan->setPrimary();`
|
||||
* `SpanService *setHidden()`
|
||||
* specifies that this is hidden Service for the Accessory. Returns a pointer to the Service itself so that the method can be chained during instantiation.
|
||||
* `virtual boolean update()`
|
||||
* HomeSpan calls this method upon receiving a request from a HomeKit Controller to update one or more Characteristics associated with the Service. Users should override this method with code that implements that requested updates and returns *true* or *false* if the update succeeds or fails
|
||||
* `virtual void loop()`
|
||||
* HomeSpan calls this method every time `homeSpan.poll()` is executed. Users should override this method with code that monitors for state changes in Characteristics that require HomeKit Controllers to be notified.
|
||||
* `virtual void button(int pin, int pressType)`
|
||||
* HomeSpan calls this method whenever a SpanButton() object associated with the Service is triggered. Users should override this method with code that implements any actions to be taken in response to the SpanButton() trigger
|
||||
* *pin* - the ESP32 pin associated with the SpanButton() object
|
||||
* *pressType* -
|
||||
* 0=single press (SpanButton::SINGLE)
|
||||
* 1=double press (SpanButton::DOUBLE)
|
||||
* 2=long press (SpanButton::LONG)
|
||||
|
||||
## *SpanCharacteristic()*
|
||||
|
||||
This is a **base class** from which all HomeSpan Characteristics are derived, and should **not** be directly instantiated. Rather, to create a new Characteristic instantiate one of the HomeSpan Characteristics defined in the [Characteristic](ServiceList.md) namespace.
|
||||
|
||||
* 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.
|
||||
* example: `new Characteristic::Brightness(50);`
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ HomeSpan implements all [HAP-R2](https://developer.apple.com/support/homekit-acc
|
|||
|
||||
HomeSpan Services and Characteristics are implemented as C++ Classes with names that exactly match the spelling and capitalization specified by Apple in Sections 8 and 9 of [HAP-R2](https://developer.apple.com/support/homekit-accessory-protocol/), but without any spaces. HomeSpan Services are defined in HomeSpan's `Service` namespace. HomeSpan Characteristics are defined in HomeSpan's `Characteristic` namespace. For example, HomeSpan defines the *Carbon Dioxide Sensor* Service (HAP Service 8.7) as `Service::CarbonDioxideSensor`, and the *Carbon Dioxide Detected* Characteristic (HAP Characteristic 9.16) as `Characteristic::CarbonDioxideDetected`.
|
||||
|
||||
HomeSpan Services and Characteristics are instantiated with a C++ `new` command. Services do not take any arguments, whereas Characteristics take a single, optional argument that is used to initialize the value of the Characteristic at startup. If this argument is not specified, HomeSpan will apply a reasonable default value based on the Characteristic's type and allowed range.
|
||||
HomeSpan Services and Characteristics are instantiated with a C++ `new` command. Services do not take any arguments, whereas Characteristics take a single, optional argument that is used to initialize the value of the Characteristic at startup. If this argument is not specified, HomeSpan will apply a reasonable [default value](#characteristic-types-and-defaults) based on the Characteristic's type and allowed range.
|
||||
|
||||
A list of all HomeSpan Services is provided in the table below. For each Service the table also indicates which Characteristics are required and which are optional. For example, a dimmable light bulb could be configured in HomeSpan as such:
|
||||
|
||||
|
|
@ -62,6 +62,110 @@ Additionally, when first starting up, HomeSpan begins by validating the device's
|
|||
| Window | CurrentPosition<br>TargetPosition<br>PositionState | Name<br>HoldPosition<br>ObstructionDetected |
|
||||
| WindowCovering | CurrentPosition<br>TargetPosition<br>PositionState | Name<br>HoldPosition<br>CurrentHorizontalTiltAngle<br>TargetHorizontalTiltAngle<br>CurrentVerticalTiltAngle<br>TargetVerticalTiltAngle<br>ObstructionDetected |
|
||||
|
||||
|
||||
### Characteristic Types and Defaults
|
||||
|
||||
|Characteristic|Type|Default
|
||||
|---|---|---|
|
||||
|Active|uint8_t|0|
|
||||
|AirQuality|uint8_t|0|
|
||||
|BatteryLevel|uint8_t|0|
|
||||
|Brightness|int|0|
|
||||
|CarbonMonoxideLevel|double|0|
|
||||
|CarbonMonoxidePeakLevel|double|0|
|
||||
|CarbonMonoxideDetected|uint8_t|0|
|
||||
|CarbonDioxideLevel|double|0|
|
||||
|CarbonDioxidePeakLevel|double|0|
|
||||
|CarbonDioxideDetected|uint8_t|0|
|
||||
|ChargingState|uint8_t|0|
|
||||
|CoolingThresholdTemperature|double|10|
|
||||
|ColorTemperature|uint32_t|50|
|
||||
|ContactSensorState|uint8_t|1|
|
||||
|CurrentAmbientLightLevel|double|1|
|
||||
|CurrentHorizontalTiltAngle|int|0|
|
||||
|CurrentAirPurifierState|uint8_t|1|
|
||||
|CurrentSlatState|uint8_t|0|
|
||||
|CurrentPosition|uint8_t|0|
|
||||
|CurrentVerticalTiltAngle|int|0|
|
||||
|CurrentHumidifierDehumidifierState|uint8_t|1|
|
||||
|CurrentDoorState|uint8_t|1|
|
||||
|CurrentFanState|uint8_t|1|
|
||||
|CurrentHeatingCoolingState|uint8_t|0|
|
||||
|CurrentHeaterCoolerState|uint8_t|1|
|
||||
|CurrentRelativeHumidity|double|0|
|
||||
|CurrentTemperature|double|0|
|
||||
|CurrentTiltAngle|int|0|
|
||||
|FilterLifeLevel|double|0|
|
||||
|FilterChangeIndication|uint8_t|0|
|
||||
|FirmwareRevision|char \*|"1.0.0"|
|
||||
|HardwareRevision|char \*|"1.0.0"|
|
||||
|HeatingThresholdTemperature|double|16|
|
||||
|HoldPosition|boolean|false|
|
||||
|Hue|double|0|
|
||||
|Identify|boolean|false|
|
||||
|InUse|uint8_t|0|
|
||||
|IsConfigured|uint8_t|0|
|
||||
|LeakDetected|uint8_t|0|
|
||||
|LockCurrentState|uint8_t|0|
|
||||
|LockPhysicalControls|uint8_t|0|
|
||||
|LockTargetState|uint8_t|0|
|
||||
|Manufacturer|char \*|"HomeSpan"|
|
||||
|Model|char \*|"HomeSpan-ESP32"|
|
||||
|MotionDetected|boolean|false|
|
||||
|Mute|boolean|false|
|
||||
|Name|char \*|"unnamed"|
|
||||
|NitrogenDioxideDensity|double|0|
|
||||
|ObstructionDetected|boolean|false|
|
||||
|PM25Density|double|0|
|
||||
|OccupancyDetected|uint8_t|0|
|
||||
|OutletInUse|boolean|false|
|
||||
|On|boolean|false|
|
||||
|OzoneDensity|double|0|
|
||||
|PM10Density|double|0|
|
||||
|PositionState|uint8_t|2|
|
||||
|ProgramMode|uint8_t|0|
|
||||
|ProgrammableSwitchEvent|uint8_t|0|
|
||||
|RelativeHumidityDehumidifierThreshold|double|50|
|
||||
|RelativeHumidityHumidifierThreshold|double|50|
|
||||
|RemainingDuration|uint32_t|60|
|
||||
|ResetFilterIndication|uint8_t|0|
|
||||
|RotationDirection|int|0|
|
||||
|RotationSpeed|double|0|
|
||||
|Saturation|double|0|
|
||||
|SecuritySystemAlarmType|uint8_t|0|
|
||||
|SecuritySystemCurrentState|uint8_t|3|
|
||||
|SecuritySystemTargetState|uint8_t|3|
|
||||
|SerialNumber|char \*|"HS-12345"|
|
||||
|ServiceLabelIndex|uint8_t|1|
|
||||
|ServiceLabelNamespace|uint8_t|1|
|
||||
|SlatType|uint8_t|0|
|
||||
|SmokeDetected|uint8_t|0|
|
||||
|StatusActive|boolean|true|
|
||||
|StatusFault|uint8_t|0|
|
||||
|StatusJammed|uint8_t|0|
|
||||
|StatusLowBattery|uint8_t|0|
|
||||
|StatusTampered|uint8_t|0|
|
||||
|SulphurDioxideDensity|double|0|
|
||||
|SwingMode|uint8_t|0|
|
||||
|TargetAirPurifierState|uint8_t|1|
|
||||
|TargetFanState|uint8_t|1|
|
||||
|TargetTiltAngle|int|0|
|
||||
|SetDuration|uint32_t|60|
|
||||
|TargetHorizontalTiltAngle|int|0|
|
||||
|TargetHumidifierDehumidifierState|uint8_t|0|
|
||||
|TargetPosition|uint8_t|0|
|
||||
|TargetDoorState|uint8_t|1|
|
||||
|TargetHeatingCoolingState|uint8_t|0|
|
||||
|TargetRelativeHumidity|double|0|
|
||||
|TargetTemperature|double|16|
|
||||
|TemperatureDisplayUnits|uint8_t|0|
|
||||
|TargetVerticalTiltAngle|int|0|
|
||||
|ValveType|uint8_t|0|
|
||||
|Version|char \*|"1.0.0"|
|
||||
|VOCDensity|double|0|
|
||||
|Volume|uint8_t|0|
|
||||
|WaterLevel|double|0|
|
||||
|
||||
---
|
||||
|
||||
[↩️](README.md) Back to the Welcome page
|
||||
|
|
|
|||
Loading…
Reference in New Issue