diff --git a/docs/Reference.md b/docs/Reference.md
index bbed105..b011507 100644
--- a/docs/Reference.md
+++ b/docs/Reference.md
@@ -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);`
+
diff --git a/docs/ServiceList.md b/docs/ServiceList.md
index 25c7562..bf4706d 100644
--- a/docs/ServiceList.md
+++ b/docs/ServiceList.md
@@ -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
TargetPosition
PositionState | Name
HoldPosition
ObstructionDetected |
| WindowCovering | CurrentPosition
TargetPosition
PositionState | Name
HoldPosition
CurrentHorizontalTiltAngle
TargetHorizontalTiltAngle
CurrentVerticalTiltAngle
TargetVerticalTiltAngle
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