diff --git a/docs/NameSpaces.md b/docs/NameSpaces.md
index 4eed5d8..0e54f44 100644
--- a/docs/NameSpaces.md
+++ b/docs/NameSpaces.md
@@ -2,251 +2,39 @@
| ------- | -------------------- | ------------------- |
| AccessoryInformation| FirmwareRevision
Identity
Manufacturer
Model
Name
SerialNumber | HardwareRevision |
| AirPurifier | Active
CurrentAirPurifierState
TargetAirPurifierState | Name
RotationSpeed
SwingMode
LockPhysicalControls |
-| AirQualitySensor
- REQ(AirQuality);
- OPT(Name);
- OPT(OzoneDensity);
- OPT(NitrogenDioxideDensity);
- OPT(SulphurDioxideDensity);
- OPT(PM25Density);
- OPT(PM10Density);
- OPT(VOCDensity);
- OPT(StatusActive);
- OPT(StatusFault);
- OPT(StatusTampered);
- OPT(StatusLowBattery);
-
-| BatteryService
- REQ(BatteryLevel);
- REQ(ChargingState);
- REQ(StatusLowBattery);
- OPT(Name);
-| CarbonDioxideSensor
- REQ(CarbonDioxideDetected);
- OPT(Name);
- OPT(StatusActive);
- OPT(StatusFault);
- OPT(StatusTampered);
- OPT(StatusLowBattery);
- OPT(CarbonDioxideLevel);
- OPT(CarbonDioxidePeakLevel);
-| CarbonMonoxideSensor
- REQ(CarbonMonoxideDetected);
- OPT(Name);
- OPT(StatusActive);
- OPT(StatusFault);
- OPT(StatusTampered);
- OPT(StatusLowBattery);
- OPT(CarbonMonoxideLevel);
- OPT(CarbonMonoxidePeakLevel);
-| ContactSensor
- REQ(ContactSensorState);
- OPT(Name);
- OPT(StatusActive);
- OPT(StatusFault);
- OPT(StatusTampered);
- OPT(StatusLowBattery);
-| Door
- REQ(CurrentPosition);
- REQ(TargetPosition);
- REQ(PositionState);
- OPT(Name);
- OPT(HoldPosition);
- OPT(ObstructionDetected);
-| Doorbell
- REQ(ProgrammableSwitchEvent);
- OPT(Name);
- OPT(Volume);
- OPT(Brightness);
-| Fan
- REQ(Active);
- OPT(Name);
- OPT(CurrentFanState);
- OPT(TargetFanState);
- OPT(RotationDirection);
- OPT(RotationSpeed);
- OPT(SwingMode);
- OPT(LockPhysicalControls);
-| Faucet
- REQ(Active);
- OPT(StatusFault);
- OPT(Name);
-| FilterMaintenance
- REQ(FilterChangeIndication);
- OPT(Name);
- OPT(FilterLifeLevel);
- OPT(ResetFilterIndication);
-| GarageDoorOpener
- REQ(CurrentDoorState);
- REQ(TargetDoorState);
- REQ(ObstructionDetected);
- OPT(LockCurrentState);
- OPT(LockTargetState);
- OPT(Name);
-| HAPProtocolInformation
- REQ(Version);
-| HeaterCooler
- REQ(Active);
- REQ(CurrentTemperature);
- REQ(CurrentHeaterCoolerState);
- REQ(TargetHeaterCoolerState);
- OPT(Name);
- OPT(RotationSpeed);
- OPT(TemperatureDisplayUnits);
- OPT(SwingMode);
- OPT(CoolingThresholdTemperature);
- OPT(HeatingThresholdTemperature);
- OPT(LockPhysicalControls);
-| HumidifierDehumidifier
- REQ(Active);
- REQ(CurrentRelativeHumidity);
- REQ(CurrentHumidifierDehumidifierState);
- REQ(TargetHumidifierDehumidifierState);
- OPT(Name);
- OPT(RelativeHumidityDehumidifierThreshold);
- OPT(RelativeHumidityHumidifierThreshold);
- OPT(RotationSpeed);
- OPT(SwingMode);
- OPT(WaterLevel);
- OPT(LockPhysicalControls);
-| HumiditySensor
- REQ(CurrentRelativeHumidity);
- OPT(Name);
- OPT(StatusActive);
- OPT(StatusFault);
- OPT(StatusTampered);
- OPT(StatusLowBattery);
-| IrrigationSystem
- REQ(Active);
- REQ(ProgramMode);
- REQ(InUse);
- OPT(RemainingDuration);
- OPT(Name);
- OPT(StatusFault);
-| LeakSensor
- REQ(LeakDetected);
- OPT(Name);
- OPT(StatusActive);
- OPT(StatusFault);
- OPT(StatusTampered);
- OPT(StatusLowBattery);
-| LightBulb
- REQ(On);
- OPT(Brightness);
- OPT(Hue);
- OPT(Name);
- OPT(Saturation);
- OPT(ColorTemperature);
-| LightSensor
- REQ(CurrentAmbientLightLevel);
- OPT(Name);
- OPT(StatusActive);
- OPT(StatusFault);
- OPT(StatusTampered);
- OPT(StatusLowBattery);
-| LockMechanism
- REQ(LockCurrentState);
- REQ(LockTargetState);
- OPT(Name);
-| Microphone
- REQ(Mute);
- OPT(Name);
- OPT(Volume);
-| MotionSensor
- REQ(MotionDetected);
- OPT(Name);
- OPT(StatusActive);
- OPT(StatusFault);
- OPT(StatusTampered);
- OPT(StatusLowBattery);
-| OccupancySensor
- REQ(OccupancyDetected);
- OPT(Name);
- OPT(StatusActive);
- OPT(StatusFault);
- OPT(StatusTampered);
- OPT(StatusLowBattery);
-| Outlet
- REQ(On);
- REQ(OutletInUse);
- OPT(Name);
-| SecuritySystem
- REQ(SecuritySystemCurrentState);
- REQ(SecuritySystemTargetState);
- OPT(Name);
- OPT(SecuritySystemAlarmType);
- OPT(StatusFault);
- OPT(StatusTampered);
-| ServiceLabel
- REQ(ServiceLabelNamespace);
-| Slat
- REQ(CurrentSlatState);
- REQ(SlatType);
- OPT(Name);
- OPT(SwingMode);
- OPT(CurrentTiltAngle);
- OPT(TargetTiltAngle);
-| SmokeSensor
- REQ(SmokeDetected);
- OPT(Name);
- OPT(StatusActive);
- OPT(StatusFault);
- OPT(StatusTampered);
- OPT(StatusLowBattery);
-| Speaker
- REQ(Mute);
- OPT(Name);
- OPT(Volume);
-| StatelessProgrammableSwitch
- REQ(ProgrammableSwitchEvent);
- OPT(Name);
- OPT(ServiceLabelIndex);
-| Switch
- REQ(On);
- OPT(Name);
-| TemperatureSensor
- REQ(CurrentTemperature);
- OPT(Name);
- OPT(StatusActive);
- OPT(StatusFault);
- OPT(StatusTampered);
- OPT(StatusLowBattery);
-| Thermostat
- REQ(CurrentHeatingCoolingState);
- REQ(TargetHeatingCoolingState);
- REQ(CurrentTemperature);
- REQ(TargetTemperature);
- REQ(TemperatureDisplayUnits);
- OPT(CoolingThresholdTemperature);
- OPT(CurrentRelativeHumidity);
- OPT(HeatingThresholdTemperature);
- OPT(Name);
- OPT(TargetRelativeHumidity);
-| Valve
- REQ(Active);
- REQ(InUse);
- REQ(ValveType);
- OPT(SetDuration);
- OPT(RemainingDuration);
- OPT(IsConfigured);
- OPT(ServiceLabelIndex);
- OPT(StatusFault);
- OPT(Name);
-| Window
- REQ(CurrentPosition);
- REQ(TargetPosition);
- REQ(PositionState);
- OPT(Name);
- OPT(HoldPosition);
- OPT(ObstructionDetected);
-| WindowCovering
- REQ(CurrentPosition);
- REQ(TargetPosition);
- REQ(PositionState);
- OPT(Name);
- OPT(HoldPosition);
- OPT(CurrentHorizontalTiltAngle);
- OPT(TargetHorizontalTiltAngle);
- OPT(CurrentVerticalTiltAngle);
- OPT(TargetVerticalTiltAngle);
- OPT(ObstructionDetected);
+| AirQualitySensor | AirQuality | Name
OzoneDensity
NitrogenDioxideDensity
SulphurDioxideDensity
PM25Density
PM10Density
VOCDensity
StatusActive
StatusFault
StatusTampered
StatusLowBattery |
+| BatteryService | BatteryLevel
ChargingState
StatusLowBattery | Name |
+| CarbonDioxideSensor | CarbonDioxideDetected | Name
StatusActive
StatusFault
StatusTampered
StatusLowBattery
CarbonDioxideLevel
CarbonDioxidePeakLevel |
+| CarbonMonoxideSensor | CarbonMonoxideDetected | Name
StatusActive
StatusFault
StatusTampered
StatusLowBattery
CarbonMonoxideLevel
CarbonMonoxidePeakLevel |
+| ContactSensor | ContactSensorState | Name
StatusActive
StatusFault
StatusTampered
StatusLowBattery |
+| Door | CurrentPosition |
TargetPosition
PositionState | Name
HoldPosition
ObstructionDetected |
+| Doorbell | ProgrammableSwitchEvent | Name
Volume
Brightness |
+| Fan | Active | Name
CurrentFanState
TargetFanState
RotationDirection
RotationSpeed
SwingMode
LockPhysicalControls |
+| Faucet | Active | StatusFault
Name |
+| FilterMaintenance | FilterChangeIndication | Name
FilterLifeLevel
ResetFilterIndication |
+| GarageDoorOpener | CurrentDoorState
TargetDoorState
ObstructionDetected | LockCurrentState
LockTargetState
Name |
+| HAPProtocolInformation | Version | |
+| HeaterCooler | Active
CurrentTemperature
CurrentHeaterCoolerState
TargetHeaterCoolerState | Name
RotationSpeed
TemperatureDisplayUnits
SwingMode
CoolingThresholdTemperature
HeatingThresholdTemperature
LockPhysicalControls |
+| HumidifierDehumidifier | Active
CurrentRelativeHumidity
CurrentHumidifierDehumidifierState
TargetHumidifierDehumidifierState | Name
RelativeHumidityDehumidifierThreshold
RelativeHumidityHumidifierThreshold
RotationSpeed
SwingMode
WaterLevel
LockPhysicalControls |
+| HumiditySensor | CurrentRelativeHumidity | Name
StatusActive
StatusFault
StatusTampered
StatusLowBattery |
+| IrrigationSystem | Active
ProgramMode
InUse | RemainingDuration
Name
StatusFault |
+| LeakSensor | LeakDetected | Name
StatusActive
StatusFault
StatusTampered
StatusLowBattery |
+| LightBulb | On | Brightness
Hue
Name
Saturation
ColorTemperature |
+| LightSensor | CurrentAmbientLightLevel | Name
StatusActive
StatusFault
StatusTampered
StatusLowBattery |
+| LockMechanism | LockCurrentState
LockTargetState | Name |
+| Microphone | Mute | Name
Volume |
+| MotionSensor | MotionDetected | Name
StatusActive
StatusFault
StatusTampered
StatusLowBattery |
+| OccupancySensor | OccupancyDetected | Name
StatusActive
StatusFault
StatusTampered
StatusLowBattery |
+| Outlet | On
OutletInUse | Name |
+| SecuritySystem | SecuritySystemCurrentState
SecuritySystemTargetState | Name
SecuritySystemAlarmType
StatusFault
StatusTampered |
+| ServiceLabel | ServiceLabelNamespace | |
+| Slat | CurrentSlatState
SlatType | Name
SwingMode
CurrentTiltAngle
TargetTiltAngle |
+| SmokeSensor | SmokeDetected | Name
StatusActive
StatusFault
StatusTampered
StatusLowBattery |
+| Speaker | Mute | Name
Volume |
+| StatelessProgrammableSwitch | ProgrammableSwitchEvent | Name
ServiceLabelIndex |
+| Switch | On | Name |
+| TemperatureSensor | CurrentTemperature | Name
StatusActive
StatusFault
StatusTampered
StatusLowBattery |
+| Thermostat | CurrentHeatingCoolingState
TargetHeatingCoolingState
CurrentTemperature
TargetTemperature
TemperatureDisplayUnits | CoolingThresholdTemperature
CurrentRelativeHumidity
HeatingThresholdTemperature
Name
TargetRelativeHumidity |
+| Valve | Active
InUse
ValveType | SetDuration
RemainingDuration
IsConfigured
ServiceLabelIndex
StatusFault
Name |
+| Window | CurrentPosition
TargetPosition
PositionState | Name
HoldPosition
ObstructionDetected |
+| WindowCovering | CurrentPosition
TargetPosition
PositionState | Name
HoldPosition
CurrentHorizontalTiltAngle
TargetHorizontalTiltAngle
CurrentVerticalTiltAngle
TargetVerticalTiltAngle
ObstructionDetected |
diff --git a/examples/01-SimpleLightBulb/01-SimpleLightBulb.ino b/examples/01-SimpleLightBulb/01-SimpleLightBulb.ino
index bc691a2..446d105 100644
--- a/examples/01-SimpleLightBulb/01-SimpleLightBulb.ino
+++ b/examples/01-SimpleLightBulb/01-SimpleLightBulb.ino
@@ -30,32 +30,58 @@
// HomeSpan: A HomeKit implementation for the ESP32 //
// ------------------------------------------------ //
// //
-// Example 1: A non-functioning on/off light bulb //
+// Example 1: A non-functioning on/off light control //
// constructed from basic HomeSpan components //
// //
////////////////////////////////////////////////////////////
-#include "HomeSpan.h" // Always start by including the HomeSpan library
+ // WELCOME TO HOMESPAN!
+
+ // This first example introduces the HomeSpan library and demonstrates how to implement a simple HomeKit on/off light control
+ // using a combination of HomeSpan Accessory, Service, and Characteristic objects. Once this sketch has been uploaded
+ // to your HomeSpan device and the device is paired to your home, a new "lightbulb" tile will appear in the Home App of your iPhone,
+ // iPad, or Mac.
+
+ // Though the tile will be fully operational (i.e. you can change the status of the lightbulb from "on" or "off"), we won't yet connect
+ // an actual light or LED to the HomeSpan device, so nothing real will light up. Instead, in this and the next few examples, we'll focus
+ // on learning about the different ways HomeKit controls can be configured. Starting in Example 5, we'll connect an LED to the device
+ // and introduce the methods you'll need to implement to actually turn the LED on and off from your Home App.
-void setup() {
+ // These examples are best understood when reviewed in conjunction with the documentation provided on the HomeSpan GitHub page.
+ // See https://github.com/HomeSpan/HomeSpan for details and references. The examples also make frequent reference to
+ // Apple's HomeKit Accessory Protocol Specification, known as HAP. You can download this directly from Apple
+ // at https://developer.apple.com/support/homekit-accessory-protocol.
+
+ // LET'S GET STARTED...
+
+#include "HomeSpan.h" // HomeSpan sketches always begin by including the HomeSpan library
+
+void setup() { // Your HomeSpan code should be placed within the standard Arduino setup() function
- Serial.begin(115200); // Start a serial connection - this is needed for you to type in your WiFi credentials
+ Serial.begin(115200); // Start a serial connection so you can receive HomeSpan diagnostics and control the device using HomeSpan's Command-Line Interface (CLI)
- // Begin a HomeSpan Session. Required parameters are Category and Name.
- // These are used by HomeKit to configure the icon and name of the device shown when initially pairing, as well
- // as set the icon (but not the name) of defined Accessories in some cases.
- // There are no other effects. You can even specify a "Lighting" Category for a Faucet with no ill effects (except the icons)
- // A complete list of Categories can be found in Settings.h, which is based on Section 13 of Apple's
- // HomeKit Accessory Protocol (HAP) Specifications Document.
+ // The HomeSpan library creates a global object named "homeSpan" that encapsulates all HomeSpan functionality.
+ // The begin() method is used to initialize HomeSpan and start all HomeSpan processes.
+
+ // Required parameters are Category and Name, which are used by HomeKit to configure the icon and name of the device shown in your Home App
+ // when initially pairing your device. A list of all defined categories can be found at https://github.com/HomeSpan/HomeSpan/docs/Categories.md
+ // and match those specified by Apple in Section 13 of the HAP guide (which of course you have downloaded as recommended above!).
- homeSpan.begin(Category::Lighting,"HomeSpan LightBulb");
+ // HomeSpan's category names are defined in a C++ namespace appropriately called Category, so you'll need to use the prefix Category:: when
+ // specifying categories.
- // Every HomeKit device consists of one or more Accessories. Each Accessory contains one or more Services.
- // Every Service contains one or more Characteristics. HAP defines all allowable Services and Characteristics,
- // including those that are required and those that are optional. An Accessory is typically a complete appliance,
- // such as a table lamp or ceiling fan. Services are the main components of the appliance - a ceiling fan Accessory will
- // typically have a fan Service and a light bulb Service. Characteristics define how each Service operates.
+ homeSpan.begin(Category::Lighting,"HomeSpan LightBulb"); // initializes a HomeSpan device named "HomeSpan Lightbulb" with Category set to Lighting
+
+ // Next, some general information about Apple HomeKit before we proceed...
+
+ // Every HomeKit device consists of one or more Accessories. Each Accessory contains one or more Services, and
+ // every Service contains one or more Characteristics. HAP defines all allowable Services and specifies which Characteristics
+ // are required or optional for each Service.
+
+ // An Accessory is typically a complete appliance, such as a table lamp or ceiling fan. Services are the main components of the
+ // appliance - a ceiling fan Accessory will typically have a fan Service and a light bulb Service. Characteristics define
+ // how each Service operates.
// Some Characteristics are read-only and describe the name or properties of a Service. Other Characteristics
// can be both written and read by HomeKit - these are the interesting ones since they enable actions to occur,
@@ -63,23 +89,22 @@ void setup() {
// HAP also requires various informational Services that describe the overall Accessory.
- // HAP calls the entirety of all Accessories, Services, and Characteristics the "Accessory Attributes Database."
- // A complete list of HAP Services and Characteristics implemented in HomeSpan can be found in Services.h, which is
- // based on HAP Section 8 (Services) and HAP Section 9 (Characteristics).
+ // HAP calls the entirety of all Accessories, Services, and Characteristics used in a device the "Accessory Attributes Database" of
+ // that device. A complete list of HomeKit Services can be found in Section 8 of the HAP guide. The subset of those Services that
+ // have been implemented in HomeSpan can be found at https://github.com/HomeSpan/HomeSpan/docs/ServiceList.md. and are defined in the
+ // Services namespace. A complete list of all HomeKit Characteristics used by these Services can be found in Section 9 of the HAP guide,
+ // and are defined by HomeSpan in the Characteristics namespace.
- // Users construct the Accessories database in HomeSpan by using a combination of new SpanAccessory, new Services (which point to underlying
- // SpanServices), and new Characteristics (which point to underlying SpanCharacteristics). The database is assembled in the
- // order in which components are defined. A new Service will be implemented in the last new Accessory defined, and a new
- // Characteristic will be implemented in the last new Service defined. Indention helps convey this structure though is
- // of course not required.
-
- /////////////////////////////////
+ // Users construct a HomeKit device's Accessory Attribute Database by instantiating one or more Accessories, each with their own
+ // HAP Services and HAP Characteristics. To make this as easy as possible, HomeSpan self-registers each object and assembles the database
+ // in the order in which you instantiate the objects. You do not need to create variables for any of the objects nor know anything about
+ // their underlying HAP codes. HomeSpan takes care of all of this for you.
// For this example, our Database will comprise a single Accessory containing 3 Services, each with their own required Characteristics
- new SpanAccessory(); // Begin by creating a new Accessory using SpanAccessory(), which takes no arguments
+ new SpanAccessory(); // Begin by creating a new Accessory using SpanAccessory(), which takes no arguments
- new Service::AccessoryInformation(); // HAP requires every Accessory to implement an AccessoryInformation Service, which has 6 required Characteristics
+ new Service::AccessoryInformation(); // HAP requires every Accessory to implement an AccessoryInformation Service, which has 6 required Characteristics:
new Characteristic::Name("My Table Lamp"); // Name of the Accessory, which shows up on the HomeKit "tiles", and should be unique across Accessories
// The next 4 Characteristics serve no function except for being displayed in HomeKit's setting panel for each Accessory. They are nevertheless required by HAP:
@@ -89,30 +114,27 @@ void setup() {
new Characteristic::Model("120-Volt Lamp"); // Model of the Accessory (arbitrary text string, and can be the same for every Accessory)
new Characteristic::FirmwareRevision("0.9"); // Firmware of the Accessory (arbitrary text string, and can be the same for every Accessory)
- // The last required Characteristic for the Accessory Information Service allows the user to identify the Characteristic and requires
- // some implementation code (such as blinking an LED, or flashing the light). HomeSpan defaults to take no action if there is no
- // implementation code, so we can simply create the Identify Characteristic for now and let HomeSpan default to no action.
+ // The last required Characteristic for the Accessory Information Service is the special Identify Characteristic. We'll learn more about this
+ // Characteristic in later examples. For now, you can just instantiate it without any arguments.
new Characteristic::Identify(); // Create the required Identify
- // HAP requires every Accessory (with the exception of those in Bridges) to implement the HAP Protocol Information Service.
- // This Serrvice supports a single required Characteristic that defined the version number of HAP used by the device.
+ // HAP also requires every Accessory (with the exception of those in Bridges, as we will see later) to implement the HAP Protocol Information Service.
+ // This Serrvice supports a single required Characteristic that defines the version number of HAP used by the device.
// HAP Release R2 requires this version to be set to "1.1.0"
new Service::HAPProtocolInformation(); // Create the HAP Protcol Information Service
new Characteristic::Version("1.1.0"); // Set the Version Characteristicto "1.1.0" as required by HAP
- // Now that the required "informational" Services have been defined, we can finally create the Light Bulb Service
+ // Now that the required "informational" Services have been defined, we can finally create our Light Bulb Service
// NOTE: The order of the Services is not important - we could have created the LightBulb first.
new Service::LightBulb(); // Create the Light Bulb Service
new Characteristic::On(); // This Service requires the "On" Characterstic to turn the light on and off
// That's all that's needed to define a database from scratch, including all required HAP elements, to control a single lightbulb.
- // Of course the database itself does not contain any code to implement the actual operation of the light - there is nothing to
- // turn on and off. But you'll still see a Light Bulb tile show up in HomeKit with an ability to toggle it on and off. In the next
- // example we will add the code that turns on and off an LED. For now, upload this sketch to your ESP32, pair with HomeKit, and
- // verify everything works.
+ // Of course this sketch does not yet contain any code to implement the actual operation of the light - there is nothing to
+ // turn on and off. But you'll still see a Light Bulb tile show up in your Home App with an ability to toggle it on and off.
} // end of setup()
@@ -127,3 +149,7 @@ void loop(){
homeSpan.poll(); // run HomeSpan!
} // end of loop()
+
+// Congratulations! You've created your first HomeSpan sketch, ready to be uploaded to your ESP32 board and paired with HomeKit.
+//
+//
diff --git a/examples/02-TwoSimpleLightBulbs/02-TwoSimpleLightBulbs.ino b/examples/02-TwoSimpleLightBulbs/02-TwoSimpleLightBulbs.ino
index 3aa8577..dece10a 100644
--- a/examples/02-TwoSimpleLightBulbs/02-TwoSimpleLightBulbs.ino
+++ b/examples/02-TwoSimpleLightBulbs/02-TwoSimpleLightBulbs.ino
@@ -42,9 +42,9 @@ void setup() {
// Example 2 expands on Example 1 by implementing two LightBulbs, each as their own Accessory
- Serial.begin(115200); // Start a serial connection - this is needed for you to type in your WiFi credentials
+ Serial.begin(115200);
- homeSpan.begin(Category::Lighting,"HomeSpan LightBulbs"); // Begin a HomeSpan Session - note the name is now "HomeSpan LightBulbs"
+ homeSpan.begin(Category::Lighting,"HomeSpan LightBulbs"); // initialize HomeSpan - note the name is now "HomeSpan LightBulbs"
// Here we create the first LightBulb Accessory just as in Example 1