Updating docs
This commit is contained in:
parent
3d6ad0a0d8
commit
bca25b6a72
|
|
@ -2,251 +2,39 @@
|
||||||
| ------- | -------------------- | ------------------- |
|
| ------- | -------------------- | ------------------- |
|
||||||
| AccessoryInformation| FirmwareRevision<br>Identity<br>Manufacturer<br>Model<br>Name<br>SerialNumber | HardwareRevision |
|
| AccessoryInformation| FirmwareRevision<br>Identity<br>Manufacturer<br>Model<br>Name<br>SerialNumber | HardwareRevision |
|
||||||
| AirPurifier | Active<br>CurrentAirPurifierState<br>TargetAirPurifierState | Name<br>RotationSpeed<br>SwingMode<br>LockPhysicalControls |
|
| AirPurifier | Active<br>CurrentAirPurifierState<br>TargetAirPurifierState | Name<br>RotationSpeed<br>SwingMode<br>LockPhysicalControls |
|
||||||
| AirQualitySensor
|
| AirQualitySensor | AirQuality | Name<br>OzoneDensity<br>NitrogenDioxideDensity<br>SulphurDioxideDensity<br>PM25Density<br>PM10Density<br>VOCDensity<br>StatusActive<br>StatusFault<br>StatusTampered<br>StatusLowBattery |
|
||||||
REQ(AirQuality);
|
| BatteryService | BatteryLevel<br>ChargingState<br>StatusLowBattery | Name |
|
||||||
OPT(Name);
|
| CarbonDioxideSensor | CarbonDioxideDetected | Name<br>StatusActive<br>StatusFault<br>StatusTampered<br>StatusLowBattery<br>CarbonDioxideLevel<br>CarbonDioxidePeakLevel |
|
||||||
OPT(OzoneDensity);
|
| CarbonMonoxideSensor | CarbonMonoxideDetected | Name<br>StatusActive<br>StatusFault<br>StatusTampered<br>StatusLowBattery<br>CarbonMonoxideLevel<br>CarbonMonoxidePeakLevel |
|
||||||
OPT(NitrogenDioxideDensity);
|
| ContactSensor | ContactSensorState | Name<br>StatusActive<br>StatusFault<br>StatusTampered<br>StatusLowBattery |
|
||||||
OPT(SulphurDioxideDensity);
|
| Door | CurrentPosition | <br>TargetPosition<br>PositionState | Name<br>HoldPosition<br>ObstructionDetected |
|
||||||
OPT(PM25Density);
|
| Doorbell | ProgrammableSwitchEvent | Name<br>Volume<br>Brightness |
|
||||||
OPT(PM10Density);
|
| Fan | Active | Name<br>CurrentFanState<br>TargetFanState<br>RotationDirection<br>RotationSpeed<br>SwingMode<br>LockPhysicalControls |
|
||||||
OPT(VOCDensity);
|
| Faucet | Active | StatusFault<br>Name |
|
||||||
OPT(StatusActive);
|
| FilterMaintenance | FilterChangeIndication | Name<br>FilterLifeLevel<br>ResetFilterIndication |
|
||||||
OPT(StatusFault);
|
| GarageDoorOpener | CurrentDoorState<br>TargetDoorState<br>ObstructionDetected | LockCurrentState<br>LockTargetState<br>Name |
|
||||||
OPT(StatusTampered);
|
| HAPProtocolInformation | Version | |
|
||||||
OPT(StatusLowBattery);
|
| HeaterCooler | Active<br>CurrentTemperature<br>CurrentHeaterCoolerState<br>TargetHeaterCoolerState | Name<br>RotationSpeed<br>TemperatureDisplayUnits<br>SwingMode<br>CoolingThresholdTemperature<br>HeatingThresholdTemperature<br>LockPhysicalControls |
|
||||||
|
| HumidifierDehumidifier | Active<br>CurrentRelativeHumidity<br>CurrentHumidifierDehumidifierState<br>TargetHumidifierDehumidifierState | Name<br>RelativeHumidityDehumidifierThreshold<br>RelativeHumidityHumidifierThreshold<br>RotationSpeed<br>SwingMode<br>WaterLevel<br>LockPhysicalControls |
|
||||||
| BatteryService
|
| HumiditySensor | CurrentRelativeHumidity | Name<br>StatusActive<br>StatusFault<br>StatusTampered<br>StatusLowBattery |
|
||||||
REQ(BatteryLevel);
|
| IrrigationSystem | Active<br>ProgramMode<br>InUse | RemainingDuration<br>Name<br>StatusFault |
|
||||||
REQ(ChargingState);
|
| LeakSensor | LeakDetected | Name<br>StatusActive<br>StatusFault<br>StatusTampered<br>StatusLowBattery |
|
||||||
REQ(StatusLowBattery);
|
| LightBulb | On | Brightness<br>Hue<br>Name<br>Saturation<br>ColorTemperature |
|
||||||
OPT(Name);
|
| LightSensor | CurrentAmbientLightLevel | Name<br>StatusActive<br>StatusFault<br>StatusTampered<br>StatusLowBattery |
|
||||||
| CarbonDioxideSensor
|
| LockMechanism | LockCurrentState<br>LockTargetState | Name |
|
||||||
REQ(CarbonDioxideDetected);
|
| Microphone | Mute | Name<br>Volume |
|
||||||
OPT(Name);
|
| MotionSensor | MotionDetected | Name<br>StatusActive<br>StatusFault<br>StatusTampered<br>StatusLowBattery |
|
||||||
OPT(StatusActive);
|
| OccupancySensor | OccupancyDetected | Name<br>StatusActive<br>StatusFault<br>StatusTampered<br>StatusLowBattery |
|
||||||
OPT(StatusFault);
|
| Outlet | On<br>OutletInUse | Name |
|
||||||
OPT(StatusTampered);
|
| SecuritySystem | SecuritySystemCurrentState<br>SecuritySystemTargetState | Name<br>SecuritySystemAlarmType<br>StatusFault<br>StatusTampered |
|
||||||
OPT(StatusLowBattery);
|
| ServiceLabel | ServiceLabelNamespace | |
|
||||||
OPT(CarbonDioxideLevel);
|
| Slat | CurrentSlatState<br>SlatType | Name<br>SwingMode<br>CurrentTiltAngle<br>TargetTiltAngle |
|
||||||
OPT(CarbonDioxidePeakLevel);
|
| SmokeSensor | SmokeDetected | Name<br>StatusActive<br>StatusFault<br>StatusTampered<br>StatusLowBattery |
|
||||||
| CarbonMonoxideSensor
|
| Speaker | Mute | Name<br>Volume |
|
||||||
REQ(CarbonMonoxideDetected);
|
| StatelessProgrammableSwitch | ProgrammableSwitchEvent | Name<br>ServiceLabelIndex |
|
||||||
OPT(Name);
|
| Switch | On | Name |
|
||||||
OPT(StatusActive);
|
| TemperatureSensor | CurrentTemperature | Name<br>StatusActive<br>StatusFault<br>StatusTampered<br>StatusLowBattery |
|
||||||
OPT(StatusFault);
|
| Thermostat | CurrentHeatingCoolingState<br>TargetHeatingCoolingState<br>CurrentTemperature<br>TargetTemperature<br>TemperatureDisplayUnits | CoolingThresholdTemperature<br>CurrentRelativeHumidity<br>HeatingThresholdTemperature<br>Name<br>TargetRelativeHumidity |
|
||||||
OPT(StatusTampered);
|
| Valve | Active<br>InUse<br>ValveType | SetDuration<br>RemainingDuration<br>IsConfigured<br>ServiceLabelIndex<br>StatusFault<br>Name |
|
||||||
OPT(StatusLowBattery);
|
| Window | CurrentPosition<br>TargetPosition<br>PositionState | Name<br>HoldPosition<br>ObstructionDetected |
|
||||||
OPT(CarbonMonoxideLevel);
|
| WindowCovering | CurrentPosition<br>TargetPosition<br>PositionState | Name<br>HoldPosition<br>CurrentHorizontalTiltAngle<br>TargetHorizontalTiltAngle<br>CurrentVerticalTiltAngle<br>TargetVerticalTiltAngle<br>ObstructionDetected |
|
||||||
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);
|
|
||||||
|
|
|
||||||
|
|
@ -30,32 +30,58 @@
|
||||||
// HomeSpan: A HomeKit implementation for the ESP32 //
|
// 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 //
|
// constructed from basic HomeSpan components //
|
||||||
// //
|
// //
|
||||||
////////////////////////////////////////////////////////////
|
////////////////////////////////////////////////////////////
|
||||||
|
|
||||||
|
|
||||||
#include "HomeSpan.h" // Always start by including the HomeSpan library
|
// WELCOME TO HOMESPAN!
|
||||||
|
|
||||||
void setup() {
|
// 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.
|
||||||
|
|
||||||
Serial.begin(115200); // Start a serial connection - this is needed for you to type in your WiFi credentials
|
// 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.
|
||||||
|
|
||||||
// Begin a HomeSpan Session. Required parameters are Category and Name.
|
// These examples are best understood when reviewed in conjunction with the documentation provided on the HomeSpan GitHub page.
|
||||||
// These are used by HomeKit to configure the icon and name of the device shown when initially pairing, as well
|
// See https://github.com/HomeSpan/HomeSpan for details and references. The examples also make frequent reference to
|
||||||
// as set the icon (but not the name) of defined Accessories in some cases.
|
// Apple's HomeKit Accessory Protocol Specification, known as HAP. You can download this directly from Apple
|
||||||
// There are no other effects. You can even specify a "Lighting" Category for a Faucet with no ill effects (except the icons)
|
// at https://developer.apple.com/support/homekit-accessory-protocol.
|
||||||
// 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.
|
|
||||||
|
|
||||||
homeSpan.begin(Category::Lighting,"HomeSpan LightBulb");
|
// LET'S GET STARTED...
|
||||||
|
|
||||||
// Every HomeKit device consists of one or more Accessories. Each Accessory contains one or more Services.
|
#include "HomeSpan.h" // HomeSpan sketches always begin by including the HomeSpan library
|
||||||
// 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,
|
void setup() { // Your HomeSpan code should be placed within the standard Arduino setup() function
|
||||||
// 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.
|
Serial.begin(115200); // Start a serial connection so you can receive HomeSpan diagnostics and control the device using HomeSpan's Command-Line Interface (CLI)
|
||||||
|
|
||||||
|
// 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's category names are defined in a C++ namespace appropriately called Category, so you'll need to use the prefix Category:: when
|
||||||
|
// specifying categories.
|
||||||
|
|
||||||
|
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
|
// 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,
|
// 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 also requires various informational Services that describe the overall Accessory.
|
||||||
|
|
||||||
// HAP calls the entirety of all Accessories, Services, and Characteristics the "Accessory Attributes Database."
|
// HAP calls the entirety of all Accessories, Services, and Characteristics used in a device the "Accessory Attributes Database" of
|
||||||
// A complete list of HAP Services and Characteristics implemented in HomeSpan can be found in Services.h, which is
|
// that device. A complete list of HomeKit Services can be found in Section 8 of the HAP guide. The subset of those Services that
|
||||||
// based on HAP Section 8 (Services) and HAP Section 9 (Characteristics).
|
// 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
|
// Users construct a HomeKit device's Accessory Attribute Database by instantiating one or more Accessories, each with their own
|
||||||
// SpanServices), and new Characteristics (which point to underlying SpanCharacteristics). The database is assembled in the
|
// HAP Services and HAP Characteristics. To make this as easy as possible, HomeSpan self-registers each object and assembles the database
|
||||||
// order in which components are defined. A new Service will be implemented in the last new Accessory defined, and a new
|
// 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
|
||||||
// Characteristic will be implemented in the last new Service defined. Indention helps convey this structure though is
|
// their underlying HAP codes. HomeSpan takes care of all of this for you.
|
||||||
// of course not required.
|
|
||||||
|
|
||||||
/////////////////////////////////
|
|
||||||
|
|
||||||
// For this example, our Database will comprise a single Accessory containing 3 Services, each with their own required Characteristics
|
// 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
|
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:
|
// 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::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)
|
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
|
// The last required Characteristic for the Accessory Information Service is the special Identify Characteristic. We'll learn more about this
|
||||||
// some implementation code (such as blinking an LED, or flashing the light). HomeSpan defaults to take no action if there is no
|
// Characteristic in later examples. For now, you can just instantiate it without any arguments.
|
||||||
// implementation code, so we can simply create the Identify Characteristic for now and let HomeSpan default to no action.
|
|
||||||
|
|
||||||
new Characteristic::Identify(); // Create the required Identify
|
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.
|
// 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 defined the version number of HAP used by the device.
|
// 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"
|
// HAP Release R2 requires this version to be set to "1.1.0"
|
||||||
|
|
||||||
new Service::HAPProtocolInformation(); // Create the HAP Protcol Information Service
|
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
|
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.
|
// 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 Service::LightBulb(); // Create the Light Bulb Service
|
||||||
new Characteristic::On(); // This Service requires the "On" Characterstic to turn the light on and off
|
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.
|
// 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
|
// 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 HomeKit with an ability to toggle it on and off. In the next
|
// 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.
|
||||||
// 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.
|
|
||||||
|
|
||||||
} // end of setup()
|
} // end of setup()
|
||||||
|
|
||||||
|
|
@ -127,3 +149,7 @@ void loop(){
|
||||||
homeSpan.poll(); // run HomeSpan!
|
homeSpan.poll(); // run HomeSpan!
|
||||||
|
|
||||||
} // end of loop()
|
} // end of loop()
|
||||||
|
|
||||||
|
// Congratulations! You've created your first HomeSpan sketch, ready to be uploaded to your ESP32 board and paired with HomeKit.
|
||||||
|
//
|
||||||
|
//
|
||||||
|
|
|
||||||
|
|
@ -42,9 +42,9 @@ void setup() {
|
||||||
|
|
||||||
// Example 2 expands on Example 1 by implementing two LightBulbs, each as their own Accessory
|
// 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
|
// Here we create the first LightBulb Accessory just as in Example 1
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue