diff --git a/docs/ServiceList.md b/docs/ServiceList.md deleted file mode 100644 index 1416fd6..0000000 --- a/docs/ServiceList.md +++ /dev/null @@ -1,204 +0,0 @@ -# HomeSpan Services and Characteristics - -HomeSpan implements all HAP-R2 Services and Characteristics except for those that involve video or audio streaming, Apple TV, or advanced lock management (i.e. all HAP Services except those that require Characteristics with a TLV8 data type). - -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, 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](#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: - -```C++ -new Service::LightBulb(); // instantiate a Light Bulb Service - new Characteristic:On(); // instantiate the required On Characteristic without setting initial value - new Characteristic::Brightness(50); // instantiate an optional Brightness Characteristic and set initial value to 50% - new Characteristic::Name("Living Room Lamp"); // instantiate an optional Name Characteristic for this Service, and set to "Living Room Lamp" -``` - -Please see Sections 8 and 9 of HAP-R2 for a complete description of all HAP Services and Characteristics. Note that HomeSpan's Service and Characteristic Classes already contain all the required HAP fields, such as the UUID, Format, and Permissions, so you don't need to specify any of these parameters. - -Additionally, when first starting up, HomeSpan begins by validating the device's configuration to ensure each Service you instantiate includes all required Characteristics, but does not include any Characteristics that are neither required nor optional. If any errors are found, HomeSpan reports them to the Arduino Serial Monitor. - -### Service List - -|Service|Required Characteristics|Optional Characteristics| -|-|-|-| -|AccessoryInformation|Identify|FirmwareRevision
Manufacturer
Model
Name
SerialNumber
HardwareRevision
AccessoryFlags| -|AirPurifier|Active
CurrentAirPurifierState
TargetAirPurifierState|Name
RotationSpeed
SwingMode
LockPhysicalControls| -|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| -|InputSource|Identifier|ConfiguredName
IsConfigured
CurrentVisibilityState
TargetVisibilityState| -|IrrigationSystem|Active
ProgramMode
InUse|RemainingDuration
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| -|Television|Active|ConfiguredName
ActiveIdentifier
RemoteKey
PowerModeSelection| -|TelevisionSpeaker|VolumeControlType
VolumeSelector| -|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|TargetPosition
CurrentPosition
PositionState|Name
HoldPosition
CurrentHorizontalTiltAngle
TargetHorizontalTiltAngle
CurrentVerticalTiltAngle
TargetVerticalTiltAngle
ObstructionDetected| - -### Characteristic Types and Defaults - -|Characteristic|Type|Default|Range| -|-|-|-|-| -AccessoryFlags|uint32_t|1|[1,1]| -Active|uint8_t|0|[0,1]| -ActiveIdentifier|uint32_t|0|[0,255]| -AirQuality|uint8_t|0|[0,5]| -BatteryLevel|uint8_t|0|[0,100]| -Brightness|int|0|[0,100]| -CarbonMonoxideLevel|double|0|[0,100]| -CarbonMonoxidePeakLevel|double|0|[0,100]| -CarbonMonoxideDetected|uint8_t|0|[0,1]| -CarbonDioxideLevel|double|0|[0,100000]| -CarbonDioxidePeakLevel|double|0|[0,100000]| -CarbonDioxideDetected|uint8_t|0|[0,1]| -ChargingState|uint8_t|0|[0,2]| -ClosedCaptions|uint8_t|0|[0,1]| -CoolingThresholdTemperature|double|10|[10,35]| -ColorTemperature|uint32_t|200|[140,500]| -ContactSensorState|uint8_t|1|[0,1]| -ConfiguredName|char \*|"unnamed"||| -CurrentAmbientLightLevel|double|1|[0.0001,100000]| -CurrentHorizontalTiltAngle|int|0|[-90,90]| -CurrentAirPurifierState|uint8_t|1|[0,2]| -CurrentSlatState|uint8_t|0|[0,2]| -CurrentPosition|uint8_t|0|[0,100]| -CurrentVerticalTiltAngle|int|0|[-90,90]| -CurrentVisibilityState|uint8_t|0|[0,1]| -CurrentHumidifierDehumidifierState|uint8_t|1|[0,3]| -CurrentDoorState|uint8_t|1|[0,4]| -CurrentFanState|uint8_t|1|[0,2]| -CurrentHeatingCoolingState|uint8_t|0|[0,2]| -CurrentHeaterCoolerState|uint8_t|1|[0,3]| -CurrentMediaState|uint8_t|0|[0,5]| -CurrentRelativeHumidity|double|0|[0,100]| -CurrentTemperature|double|0|[0,100]| -CurrentTiltAngle|int|0|[-90,90]| -FilterLifeLevel|double|0|[0,100]| -FilterChangeIndication|uint8_t|0|[0,1]| -FirmwareRevision|char \*|"1.0.0"||| -HardwareRevision|char \*|"1.0.0"||| -HeatingThresholdTemperature|double|16|[0,25]| -HoldPosition|boolean|false|[0,1]| -Hue|double|0|[0,360]| -Identify|boolean|false|[0,1]| -Identifier|uint32_t|0|[0,255]| -InputDeviceType|uint8_t|0|[0,6]| -InputSourceType|uint8_t|0|[0,10]| -InUse|uint8_t|0|[0,1]| -IsConfigured|uint8_t|0|[0,1]| -LeakDetected|uint8_t|0|[0,1]| -LockCurrentState|uint8_t|0|[0,3]| -LockPhysicalControls|uint8_t|0|[0,1]| -LockTargetState|uint8_t|0|[0,1]| -Manufacturer|char \*|"HomeSpan"||| -Model|char \*|"HomeSpan-ESP32"||| -MotionDetected|boolean|false|[0,1]| -Mute|boolean|false|[0,1]| -Name|char \*|"unnamed"||| -NitrogenDioxideDensity|double|0|[0,1000]| -ObstructionDetected|boolean|false|[0,1]| -PM25Density|double|0|[0,1000]| -OccupancyDetected|uint8_t|0|[0,1]| -OutletInUse|boolean|false|[0,1]| -On|boolean|false|[0,1]| -OzoneDensity|double|0|[0,1000]| -PictureMode|uint8_t|0|[0,13]| -PM10Density|double|0|[0,1000]| -PositionState|uint8_t|2|[0,2]| -PowerModeSelection|uint8_t|0|[0,1]| -ProgramMode|uint8_t|0|[0,2]| -ProgrammableSwitchEvent|uint8_t|0|[0,2]| -RelativeHumidityDehumidifierThreshold|double|50|[0,100]| -RelativeHumidityHumidifierThreshold|double|50|[0,100]| -RemainingDuration|uint32_t|60|[0,3600]| -RemoteKey|uint8_t|0|[0,16]| -ResetFilterIndication|uint8_t|0|[1,1]| -RotationDirection|int|0|[0,1]| -RotationSpeed|double|0|[0,100]| -Saturation|double|0|[0,100]| -SecuritySystemAlarmType|uint8_t|0|[0,1]| -SecuritySystemCurrentState|uint8_t|3|[0,4]| -SecuritySystemTargetState|uint8_t|3|[0,3]| -SerialNumber|char \*|"HS-12345"||| -ServiceLabelIndex|uint8_t|1|[1,255]| -ServiceLabelNamespace|uint8_t|1|[0,1]| -SlatType|uint8_t|0|[0,1]| -SleepDiscoveryMode|uint8_t|0|[0,1]| -SmokeDetected|uint8_t|0|[0,1]| -StatusActive|boolean|true|[0,1]| -StatusFault|uint8_t|0|[0,1]| -StatusJammed|uint8_t|0|[0,1]| -StatusLowBattery|uint8_t|0|[0,1]| -StatusTampered|uint8_t|0|[0,1]| -SulphurDioxideDensity|double|0|[0,1000]| -SwingMode|uint8_t|0|[0,1]| -TargetAirPurifierState|uint8_t|1|[0,1]| -TargetFanState|uint8_t|1|[0,1]| -TargetTiltAngle|int|0|[-90,90]| -TargetHeaterCoolerState|uint8_t|0|[0,2]| -SetDuration|uint32_t|60|[0,3600]| -TargetHorizontalTiltAngle|int|0|[-90,90]| -TargetHumidifierDehumidifierState|uint8_t|0|[0,2]| -TargetPosition|uint8_t|0|[0,100]| -TargetDoorState|uint8_t|1|[0,1]| -TargetHeatingCoolingState|uint8_t|0|[0,3]| -TargetMediaState|uint8_t|0|[0,2]| -TargetRelativeHumidity|double|0|[0,100]| -TargetTemperature|double|16|[10,38]| -TargetVisibilityState|uint8_t|0|[0,1]| -TemperatureDisplayUnits|uint8_t|0|[0,1]| -TargetVerticalTiltAngle|int|0|[-90,90]| -ValveType|uint8_t|0|[0,3]| -Version|char \*|"1.0.0"||| -VOCDensity|double|0|[0,1000]| -Volume|uint8_t|0|[0,100]| -VolumeControlType|uint8_t|0|[0,3]| -VolumeSelector|uint8_t|0|[0,1]| -WaterLevel|double|0|[0,100]| - -### HAP Format Codes (HAP-R2 Table 6-5) - -|HAP-R2 Format Code|HomeSpan C++ Type| -|------------------|-----------------| -|BOOL|boolean| -|UINT8|uint8_t| -|UINT16|uint16_t| -|UINT32|uint32_t| -|UINT64|uint64_t| -|INT|int| -|FLOAT|double| -|STRING|char \*| -|TLV8|(not implemented)| -|DATA|uint8_t *| - ---- - -[↩️](../README.md) Back to the Welcome page diff --git a/docs/ServiceListHead.md b/docs/ServiceListHead.md new file mode 100644 index 0000000..9c2b182 --- /dev/null +++ b/docs/ServiceListHead.md @@ -0,0 +1,27 @@ +# HomeSpan Services and Characteristics + +Below is a list of all Services supported by HomeSpan, along with a brief description of each Service. Click on the arrow next to the description of any Service to see a list of all Characteristics supported by the Service, as well as a description of each Characteristic.[^1] + +A blue diamond (🔹) next to a Characteristic means it is **required** for that Service, otherwise it is optional. Information included for each Characteristic is as follows: + +* **Format** - the native format of the Characteristic's value. Note that *string* means a standard C-string (i.e. char \*) +* **Perms**, where + * PR = Paired Read. This means HomeKit can read the value from HomeSpan[^2] + * PW = Paired Write. This means HomeKit can write the value to HomeSpan, which triggers a call to `update()` + * EV = Event Notification. This means HomeSpan can push notifications of value changes to HomeKit using `setVal()` +* **Min** / **Max** - the default minimum and maximum values allowed in HomeKit. For applicable numerical Characteristics, you can change the allowed minimum and maximum values using `setRange()` +* **Constants/Defaults** + * for enumerated Characteristics, a list of all allowed values in the form of pre-defined constant expressions and their equivalent numeric values. A check mark next to a constant indicates that it is the default value. If your Accessory does not support certain states of a Characteristic, you can change the allowed values using `setValidValues()` + * for all other Characteristics, the actual default value that is used if you do not specify one when instantiating the Characteristic + + [^1]: The hexidecimal numbers in parentheses next to each Service and Characteristic represent the short-form of the Apple's UUID for that Service or Characteristic. These are provided for informational purposes only (you do not need to use them, or even know about them, to create HomeSpan sketches) + + [^2]: Though rarely needed, you can change the permissions of a Characteristic using `setPerms()`, `addPerms()`, and `removePerms()` + +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, 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`. + +The pre-defined constant expressions for enumerated Characteristics are in namespaces that match the name of the Characteristic. For example, to set the *Air Quality* Characteristic of an *Air Quality Sensor* Service, you could use `setVal(AirQuality::GOOD)` or, equivalently, `setVal(2)`[^3] + +--- + +[↩️](../README.md) Back to the Welcome page diff --git a/src/src.ino b/src/src.ino index 0a87165..ee6162a 100644 --- a/src/src.ino +++ b/src/src.ino @@ -33,34 +33,60 @@ void setup() { Serial.begin(115200); - homeSpan.setLogLevel(1).setStatusPin(13); - pinMode(21,OUTPUT); - homeSpan.setControlPin(21,SpanToggle::TRIGGER_ON_HIGH ); - homeSpan.setControlPin(21,PushButton::TRIGGER_ON_HIGH ); - homeSpan.enableWebLog(50,"pool.ntp.org","UTC"); + homeSpan.setLogLevel(2); - homeSpan.begin(Category::Lighting,"HomeSpan Max"); + homeSpan.begin(Category::Lighting,"HomeSpan Test"); + + new SpanAccessory(); // start with Bridge Accessory + new Service::AccessoryInformation(); + new Characteristic::Identify(); + +// First dual-light/dual-switch Accessory new SpanAccessory(); new Service::AccessoryInformation(); - new Characteristic::Identify(); + new Characteristic::Identify(); + new Characteristic::Name("Access-1"); // the AccessoryInformation Service seems to require Name(), and will ignore ConfiguredName() - for(int i=0;i