HomeSpan/docs/ServiceList.md

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 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:

new Service::LightBulb();                         // instantiate a Light Bulb Service
  new Characteristics: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 Section 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 and halts the program.

Service List

Service	Required Characteristics	Optional Characteristics
AccessoryInformation	FirmwareRevision Identity Manufacturer Model Name SerialNumber	HardwareRevision
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
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