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