86 KiB

Raw Blame History

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.¹

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

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(Characteristic::AirQuality::GOOD) or, equivalently, setVal(2).³

👉 For a fully-expanded list of all Services and Characteristics (suitable for searching), click HERE instead.

Currently-Supported Services and Characteristics

AccessoryInformation (3E)

Required Identification Information. For each Accessory in a HomeSpan device this must be included as the first Service.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
Identify (14) 🔹 triggers an update when HomeKit wants HomeSpan to run its identification routine for an Accessory	bool	PW	1	1	RUN_ID (1)
Name (23) default name of a Service used only during initial pairing	string	PR	-	-	"unnamed"
FirmwareRevision (52) must be in form x[.y[.z]] - informational only	string	PR+EV	-	-	"1.0.0"
Manufacturer (20) any string - informational only	string	PR	-	-	"HomeSpan"
Model (21) any string - informational only	string	PR	-	-	"HomeSpan-ESP32"
SerialNumber (30) any string - informational only	string	PR	-	-	"HS-12345"
HardwareRevision (53) must be in form x[.y[.z]] - informational only	string	PR	-	-	"1.0.0"

AirPurifier (BB)

Defines a basic Air Purifier with an optional fan. Optional Linked Services: FilterMaintenance, AirQualitySensor, Fan, and Slat

Characteristic	Format	Perms	Min	Max	Constants/Defaults
Active (B0) 🔹 indicates if the Service is active/on	uint8	PW+PR+EV	0	1	INACTIVE (0) ✔️ ACTIVE (1)
CurrentAirPurifierState (A9) 🔹 indicates current state of air purification	uint8	PR+EV	0	2	INACTIVE (0) IDLE (1) ✔️ PURIFYING (2)
TargetAirPurifierState (A8) 🔹 indicates desired state of air purifier	uint8	PW+PR+EV	0	1	MANUAL (0) AUTO (1) ✔️
RotationSpeed (29) measured as a percentage	float	PR+PW+EV	0	100	0
SwingMode (B6) indicates whether swing-mode is enabled	uint8	PR+EV+PW	0	1	SWING_DISABLED (0) ✔️ SWING_ENABLED (1)
LockPhysicalControls (A7) indicates if local control lock is enabled	uint8	PW+PR+EV	0	1	CONTROL_LOCK_DISABLED (0) ✔️ CONTROL_LOCK_ENABLED (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

AirQualitySensor (8D)

Defines an Air Quality Sensor.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
AirQuality (95) 🔹 a subjective description	uint8	PR+EV	0	5	UNKNOWN (0) ✔️ EXCELLENT (1) GOOD (2) FAIR (3) INFERIOR (4) POOR (5)
OzoneDensity (C3) measured in µg/m³	float	PR+EV	0	1000	0
NitrogenDioxideDensity (C4) measured in µg/m³	float	PR+EV	0	1000	0
SulphurDioxideDensity (C5) measured in µg/m³	float	PR+EV	0	1000	0
PM25Density (C6) 2.5-micron particulate density, measured in µg/m³	float	PR+EV	0	1000	0
PM10Density (C7) 10-micron particulate density, measured in µg/m³	float	PR+EV	0	1000	0
VOCDensity (C8) measured in µg/m³	float	PR+EV	0	1000	0
StatusActive (75) indicates whether the Service is properly functioning	bool	PR+EV	0	1	NOT_FUNCTIONING (0) FUNCTIONING (1) ✔️
StatusFault (77) indicates whether the Service has a fault	uint8	PR+EV	0	1	NO_FAULT (0) ✔️ FAULT (1)
StatusTampered (7A) indicates whether the Service has been tampered with	uint8	PR+EV	0	1	NOT_TAMPERED (0) ✔️ TAMPERED (1)
StatusLowBattery (79) indicates state of battery	uint8	PR+EV	0	1	NOT_LOW_BATTERY (0) ✔️ LOW_BATTERY (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

BatteryService (96)

Defines a standalone Battery Service.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
BatteryLevel (68) 🔹 measured as a percentage	uint8	PR+EV	0	100	100
ChargingState (8F) 🔹 indicates state of battery charging	uint8	PR+EV	0	2	NOT_CHARGING (0) ✔️ CHARGING (1) NOT_CHARGEABLE (2)
StatusLowBattery (79) 🔹 indicates state of battery	uint8	PR+EV	0	1	NOT_LOW_BATTERY (0) ✔️ LOW_BATTERY (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

CarbonDioxideSensor (97)

Defines a Carbon Dioxide Sensor.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
CarbonDioxideDetected (92) 🔹 indicates if abnormal level is detected	uint8	PR+EV	0	1	NORMAL (0) ✔️ ABNORMAL (1)
CarbonDioxideLevel (93) measured on parts per million (ppm)	float	PR+EV	0	100000	0
CarbonDioxidePeakLevel (94) measured in parts per million (ppm)	float	PR+EV	0	100000	0
StatusActive (75) indicates whether the Service is properly functioning	bool	PR+EV	0	1	NOT_FUNCTIONING (0) FUNCTIONING (1) ✔️
StatusFault (77) indicates whether the Service has a fault	uint8	PR+EV	0	1	NO_FAULT (0) ✔️ FAULT (1)
StatusTampered (7A) indicates whether the Service has been tampered with	uint8	PR+EV	0	1	NOT_TAMPERED (0) ✔️ TAMPERED (1)
StatusLowBattery (79) indicates state of battery	uint8	PR+EV	0	1	NOT_LOW_BATTERY (0) ✔️ LOW_BATTERY (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

CarbonMonoxideSensor (7F)

Defines a Carbon Monoxide Sensor.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
CarbonMonoxideDetected (69) 🔹 indicates if abnormal level is detected	uint8	PR+EV	0	1	NORMAL (0) ✔️ ABNORMAL (1)
CarbonMonoxideLevel (90) measured in parts per million (ppm)	float	PR+EV	0	100	0
CarbonMonoxidePeakLevel (91) measured in parts per million (ppm)	float	PR+EV	0	100	0
StatusActive (75) indicates whether the Service is properly functioning	bool	PR+EV	0	1	NOT_FUNCTIONING (0) FUNCTIONING (1) ✔️
StatusFault (77) indicates whether the Service has a fault	uint8	PR+EV	0	1	NO_FAULT (0) ✔️ FAULT (1)
StatusTampered (7A) indicates whether the Service has been tampered with	uint8	PR+EV	0	1	NOT_TAMPERED (0) ✔️ TAMPERED (1)
StatusLowBattery (79) indicates state of battery	uint8	PR+EV	0	1	NOT_LOW_BATTERY (0) ✔️ LOW_BATTERY (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

ContactSensor (80)

Defines a Contact Sensor.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
ContactSensorState (6A) 🔹 indictates if contact is detected (i.e. closed)	uint8	PR+EV	0	1	DETECTED (0) NOT_DETECTED (1) ✔️
StatusActive (75) indicates whether the Service is properly functioning	bool	PR+EV	0	1	NOT_FUNCTIONING (0) FUNCTIONING (1) ✔️
StatusFault (77) indicates whether the Service has a fault	uint8	PR+EV	0	1	NO_FAULT (0) ✔️ FAULT (1)
StatusTampered (7A) indicates whether the Service has been tampered with	uint8	PR+EV	0	1	NOT_TAMPERED (0) ✔️ TAMPERED (1)
StatusLowBattery (79) indicates state of battery	uint8	PR+EV	0	1	NOT_LOW_BATTERY (0) ✔️ LOW_BATTERY (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

Door (81)

Defines a motorized Door.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
CurrentPosition (6D) 🔹 current position (as a percentage) from fully closed (0) to full open (100)	uint8	PR+EV	0	100	0
TargetPosition (7C) 🔹 indicates target position (as a percentage) from fully closed (0) to full open (100)	uint8	PW+PR+EV	0	100	0
ObstructionDetected (24) indicates if obstruction is detected	bool	PR+EV	0	1	NOT_DETECTED (0) ✔️ DETECTED (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

Doorbell (121)

Defines a Doorbell. Can be used on a standalone basis or in conjunction with a LockMechanism Service.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
ProgrammableSwitchEvent (73) 🔹 specifies type of button press	uint8	PR+EV+NV	0	2	SINGLE_PRESS (0) ✔️ DOUBLE_PRESS (1) LONG_PRESS (2)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

Fan (B7)

Defines a Fan. Can be used in conjunction with a LightBulb Service to create a Lighted Ceiling Fan.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
Active (B0) 🔹 indicates if the Service is active/on	uint8	PW+PR+EV	0	1	INACTIVE (0) ✔️ ACTIVE (1)
CurrentFanState (AF) indicates current state of a fan	uint8	PR+EV	0	2	INACTIVE (0) IDLE (1) ✔️ BLOWING (2)
TargetFanState (BF) indicates desired state of fan	uint8	PW+PR+EV	0	1	MANUAL (0) AUTO (1) ✔️
RotationDirection (28) indicates the rotation direction of a fan	int	PR+PW+EV	0	1	CLOCKWISE (0) ✔️ COUNTERCLOCKWISE (1)
RotationSpeed (29) measured as a percentage	float	PR+PW+EV	0	100	0
SwingMode (B6) indicates whether swing-mode is enabled	uint8	PR+EV+PW	0	1	SWING_DISABLED (0) ✔️ SWING_ENABLED (1)
LockPhysicalControls (A7) indicates if local control lock is enabled	uint8	PW+PR+EV	0	1	CONTROL_LOCK_DISABLED (0) ✔️ CONTROL_LOCK_ENABLED (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

Faucet (D7)

Defines the master control for a multi-Valve appliance. Linked Services: Valve (at least one required), and HeaterCooler (optional).

Characteristic	Format	Perms	Min	Max	Constants/Defaults
Active (B0) 🔹 indicates if the Service is active/on	uint8	PW+PR+EV	0	1	INACTIVE (0) ✔️ ACTIVE (1)
StatusFault (77) indicates whether the Service has a fault	uint8	PR+EV	0	1	NO_FAULT (0) ✔️ FAULT (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

FilterMaintenance (BA)

Defines a Filter Maintainence check.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
FilterChangeIndication (AC) 🔹 indicates state of filter	uint8	PR+EV	0	1	NO_CHANGE_NEEDED (0) ✔️ CHANGE_NEEDED (1)
FilterLifeLevel (AB) measures as a percentage of remaining life	float	PR+EV	0	100	0
ResetFilterIndication (AD) triggers and update when the user chooses to reset the FilterChangeIndication from the Home App	uint8	PW	1	1	RESET_FILTER (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

GarageDoorOpener (41)

Defines a motorized Garage Door Opener.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
CurrentDoorState (E) 🔹 indicates current state of a door	uint8	PR+EV	0	4	OPEN (0) CLOSED (1) ✔️ OPENING (2) CLOSING (3) STOPPED (4)
TargetDoorState (32) 🔹 indicates desired state of door	uint8	PW+PR+EV	0	1	OPEN (0) CLOSED (1) ✔️
ObstructionDetected (24) 🔹 indicates if obstruction is detected	bool	PR+EV	0	1	NOT_DETECTED (0) ✔️ DETECTED (1)
LockCurrentState (1D) indicates state of a lock	uint8	PR+EV	0	3	UNLOCKED (0) ✔️ LOCKED (1) JAMMED (2) UNKNOWN (3)
LockTargetState (1E) indicates desired state of lock	uint8	PW+PR+EV	0	1	UNLOCK (0) ✔️ LOCK (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"
Version (37) 🔹 unused	string	PR	-	-	"1.0.0"

HeaterCooler (BC)

Defines a standalone Heater, Cooler, or combined Heater/Cooler. Can be used with a separate Fan Service and/or Slat Service to extend functionality.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
Active (B0) 🔹 indicates if the Service is active/on	uint8	PW+PR+EV	0	1	INACTIVE (0) ✔️ ACTIVE (1)
CurrentTemperature (11) 🔹 current temperature measured in Celsius	float	PR+EV	0	100	0
CurrentHeaterCoolerState (B1) 🔹 indicates whether appliance is currently heating, cooling, idle, or off	uint8	PR+EV	0	3	INACTIVE (0) IDLE (1) ✔️ HEATING (2) COOLING (3)
TargetHeaterCoolerState (B2) 🔹 indicates desired state of heater/cooler	uint8	PW+PR+EV	0	2	AUTO (0) ✔️ HEAT (1) COOL (2)
RotationSpeed (29) measured as a percentage	float	PR+PW+EV	0	100	0
TemperatureDisplayUnits (36) indicates the desired units to display the temperature on the device itself (has no effect on Home App)	uint8	PW+PR+EV	0	1	CELSIUS (0) ✔️ FAHRENHEIT (1)
SwingMode (B6) indicates whether swing-mode is enabled	uint8	PR+EV+PW	0	1	SWING_DISABLED (0) ✔️ SWING_ENABLED (1)
CoolingThresholdTemperature (D) cooling turns on when temperature (in Celsius) rises above this threshold	float	PR+PW+EV	10	35	10
HeatingThresholdTemperature (12) heating turns on when temperature (in Celsius) falls below this threshold	float	PR+PW+EV	0	25	16
LockPhysicalControls (A7) indicates if local control lock is enabled	uint8	PW+PR+EV	0	1	CONTROL_LOCK_DISABLED (0) ✔️ CONTROL_LOCK_ENABLED (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

HumidifierDehumidifier (BD)

Defines a Humidifer, Dehumidifier, or combined Humidifer/Dehumidifier. Can be used with a separate Fan Service and/or Slat Service to extend functionality.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
Active (B0) 🔹 indicates if the Service is active/on	uint8	PW+PR+EV	0	1	INACTIVE (0) ✔️ ACTIVE (1)
CurrentRelativeHumidity (10) 🔹 current humidity measured as a percentage	float	PR+EV	0	100	0
CurrentHumidifierDehumidifierState (B3) 🔹 indicates current state of humidifier/dehumidifer	uint8	PR+EV	0	3	INACTIVE (0) IDLE (1) ✔️ HUMIDIFYING (2) DEHUMIDIFYING (3)
TargetHumidifierDehumidifierState (B4) 🔹 indicates desired state of humidifier/dehumidifier	uint8	PW+PR+EV	0	2	AUTO (0) ✔️ HUMIDIFY (1) DEHUMIDIFY (2)
RelativeHumidityDehumidifierThreshold (C9) dehumidfier turns on when humidity rises above this threshold	float	PR+PW+EV	0	100	50
RelativeHumidityHumidifierThreshold (CA) humidfier turns on when humidity falls below this threshold	float	PR+PW+EV	0	100	50
RotationSpeed (29) measured as a percentage	float	PR+PW+EV	0	100	0
SwingMode (B6) indicates whether swing-mode is enabled	uint8	PR+EV+PW	0	1	SWING_DISABLED (0) ✔️ SWING_ENABLED (1)
WaterLevel (B5) measured as a percentage	float	PR+EV	0	100	0
LockPhysicalControls (A7) indicates if local control lock is enabled	uint8	PW+PR+EV	0	1	CONTROL_LOCK_DISABLED (0) ✔️ CONTROL_LOCK_ENABLED (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

HumiditySensor (82)

Defines a Humidity Sensor.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
CurrentRelativeHumidity (10) 🔹 current humidity measured as a percentage	float	PR+EV	0	100	0
StatusActive (75) indicates whether the Service is properly functioning	bool	PR+EV	0	1	NOT_FUNCTIONING (0) FUNCTIONING (1) ✔️
StatusFault (77) indicates whether the Service has a fault	uint8	PR+EV	0	1	NO_FAULT (0) ✔️ FAULT (1)
StatusTampered (7A) indicates whether the Service has been tampered with	uint8	PR+EV	0	1	NOT_TAMPERED (0) ✔️ TAMPERED (1)
StatusLowBattery (79) indicates state of battery	uint8	PR+EV	0	1	NOT_LOW_BATTERY (0) ✔️ LOW_BATTERY (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

InputSource (D9)

Defines an Input Source for a TV. Use only as a Linked Service for the Television Service.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
Identifier (E6) 🔹 numerical Identifer of the InputSource.	uint32	PR	0	255	0
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"
IsConfigured (D6) indicates if a predefined Service has been configured	uint8	PR+EV	0	1	NOT_CONFIGURED (0) ✔️ CONFIGURED (1)
CurrentVisibilityState (135) current visibility of the Service, as selectable on the Settings Page of the Home App	uint8	PR+EV	0	1	VISIBLE (0) ✔️ NOT_VISIBLE (1)
TargetVisibilityState (134) indicates desired visibility of the Service, as selectable on the Settings Page of the Home App	uint8	PW+PR+EV	0	1	VISIBLE (0) ✔️ NOT_VISIBLE (1)

IrrigationSystem (CF)

Defines an Irrigation System. Linked Services: Valve Service (at least one required).

Characteristic	Format	Perms	Min	Max	Constants/Defaults
Active (B0) 🔹 indicates if the Service is active/on	uint8	PW+PR+EV	0	1	INACTIVE (0) ✔️ ACTIVE (1)
ProgramMode (D1) 🔹 indicates if pre-scheduled program is running	uint8	PR+EV	0	2	NONE (0) ✔️ SCHEDULED (1) SCHEDULE_OVERRIDEN (2)
InUse (D2) 🔹 if Service is set to active, this indictes whether it is currently in use	uint8	PR+EV	0	1	NOT_IN_USE (0) ✔️ IN_USE (1)
RemainingDuration (D4) duration (in seconds) remaining for Service to be active/on	uint32	PR+EV	0	3600	60
StatusFault (77) indicates whether the Service has a fault	uint8	PR+EV	0	1	NO_FAULT (0) ✔️ FAULT (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

LeakSensor (83)

Defines a Leak Sensor.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
LeakDetected (70) 🔹 indictates if a leak is detected	uint8	PR+EV	0	1	NOT_DETECTED (0) ✔️ DETECTED (1)
StatusActive (75) indicates whether the Service is properly functioning	bool	PR+EV	0	1	NOT_FUNCTIONING (0) FUNCTIONING (1) ✔️
StatusFault (77) indicates whether the Service has a fault	uint8	PR+EV	0	1	NO_FAULT (0) ✔️ FAULT (1)
StatusTampered (7A) indicates whether the Service has been tampered with	uint8	PR+EV	0	1	NOT_TAMPERED (0) ✔️ TAMPERED (1)
StatusLowBattery (79) indicates state of battery	uint8	PR+EV	0	1	NOT_LOW_BATTERY (0) ✔️ LOW_BATTERY (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

LightBulb (43)

Defines any type of Light.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
On (25) 🔹 indicates if the Service is active/on	bool	PR+PW+EV	0	1	OFF (0) ✔️ ON (1)
Brightness (8) measured as a percentage	int	PR+PW+EV	0	100	0
Hue (13) color (in degrees) from red (0) to green (120) to blue (240) and back to red (360)	float	PR+PW+EV	0	360	0
Saturation (2F) color saturation, measured as a percentage	float	PR+PW+EV	0	100	0
ColorTemperature (CE) measured in inverse megaKelvin (= 1,000,000 / Kelvin)	uint32	PR+PW+EV	140	500	200
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

LightSensor (84)

Defines a Light Sensor.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
CurrentAmbientLightLevel (6B) 🔹 measured in Lux (lumens/m²	float	PR+EV	0.0001	100000	1
StatusActive (75) indicates whether the Service is properly functioning	bool	PR+EV	0	1	NOT_FUNCTIONING (0) FUNCTIONING (1) ✔️
StatusFault (77) indicates whether the Service has a fault	uint8	PR+EV	0	1	NO_FAULT (0) ✔️ FAULT (1)
StatusTampered (7A) indicates whether the Service has been tampered with	uint8	PR+EV	0	1	NOT_TAMPERED (0) ✔️ TAMPERED (1)
StatusLowBattery (79) indicates state of battery	uint8	PR+EV	0	1	NOT_LOW_BATTERY (0) ✔️ LOW_BATTERY (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

LockMechanism (45)

Defines an electronic Lock.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
LockCurrentState (1D) 🔹 indicates state of a lock	uint8	PR+EV	0	3	UNLOCKED (0) ✔️ LOCKED (1) JAMMED (2) UNKNOWN (3)
LockTargetState (1E) 🔹 indicates desired state of lock	uint8	PW+PR+EV	0	1	UNLOCK (0) ✔️ LOCK (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"
Mute (11A) 🔹 not used	bool	PW+PR+EV	0	1	OFF (0) ✔️ ON (1)
Volume (119) unused	uint8	PW+PR+EV	0	100	0
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

MotionSensor (85)

Defines a Motion Sensor.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
MotionDetected (22) 🔹 indicates if motion is detected	bool	PR+EV	0	1	NOT_DETECTED (0) ✔️ DETECTED (1)
StatusActive (75) indicates whether the Service is properly functioning	bool	PR+EV	0	1	NOT_FUNCTIONING (0) FUNCTIONING (1) ✔️
StatusFault (77) indicates whether the Service has a fault	uint8	PR+EV	0	1	NO_FAULT (0) ✔️ FAULT (1)
StatusTampered (7A) indicates whether the Service has been tampered with	uint8	PR+EV	0	1	NOT_TAMPERED (0) ✔️ TAMPERED (1)
StatusLowBattery (79) indicates state of battery	uint8	PR+EV	0	1	NOT_LOW_BATTERY (0) ✔️ LOW_BATTERY (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

OccupancySensor (86)

Defines and Occupancy Sensor.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
OccupancyDetected (71) 🔹 indicates if occupanccy is detected	uint8	PR+EV	0	1	NOT_DETECTED (0) ✔️ DETECTED (1)
StatusActive (75) indicates whether the Service is properly functioning	bool	PR+EV	0	1	NOT_FUNCTIONING (0) FUNCTIONING (1) ✔️
StatusFault (77) indicates whether the Service has a fault	uint8	PR+EV	0	1	NO_FAULT (0) ✔️ FAULT (1)
StatusTampered (7A) indicates whether the Service has been tampered with	uint8	PR+EV	0	1	NOT_TAMPERED (0) ✔️ TAMPERED (1)
StatusLowBattery (79) indicates state of battery	uint8	PR+EV	0	1	NOT_LOW_BATTERY (0) ✔️ LOW_BATTERY (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

Outlet (47)

Defines an controllable Outlet used to power any light or appliance.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
On (25) 🔹 indicates if the Service is active/on	bool	PR+PW+EV	0	1	OFF (0) ✔️ ON (1)
OutletInUse (26) 🔹 indicates if an appliance or light is plugged into the outlet, regardless of whether on or off	bool	PR+EV	0	1	NOT_IN_USE (0) ✔️ IN_USE (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

SecuritySystem (7E)

Defines a Security System.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
SecuritySystemCurrentState (66) 🔹 indicates current state of the security system	uint8	PR+EV	0	4	ARMED_STAY (0) ARMED_AWAY (1) ARMED_NIGHT (2) DISARMED (3) ✔️ ALARM_TRIGGERED (4)
SecuritySystemTargetState (67) 🔹 indicates desired state of the security system	uint8	PW+PR+EV	0	3	ARM_STAY (0) ARM_AWAY (1) ARM_NIGHT (2) DISARM (3) ✔️
SecuritySystemAlarmType (8E) indicates whether alarm was triggered for known reason	uint8	PR+EV	0	1	KNOWN (0) ✔️ UNKNOWN (1)
StatusFault (77) indicates whether the Service has a fault	uint8	PR+EV	0	1	NO_FAULT (0) ✔️ FAULT (1)
StatusTampered (7A) indicates whether the Service has been tampered with	uint8	PR+EV	0	1	NOT_TAMPERED (0) ✔️ TAMPERED (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

ServiceLabel (CC)

Groups together un-named (or un-nameable) Services by Linking them to this Service. When used, those other Services must each include a ServiceLabelIndex Characteristic with a unique value. Rarely needed.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
ServiceLabelNamespace (CD) 🔹 indicates how un-named Services linked together with a ServiceLabel Service should be displayed in the Home App	uint8	PR	0	1	DOTS (0) NUMERALS (1) ✔️

Slat (B9)

Defines a motorized ventilation Slat(s).

Characteristic	Format	Perms	Min	Max	Constants/Defaults
CurrentSlatState (AA) 🔹 indicates current state of slats	uint8	PR+EV	0	2	FIXED (0) ✔️ JAMMED (1) SWINGING (2)
SlatType (C0) 🔹 indicates the direction of a slat or group of slats	uint8	PR	0	1	HORIZONTAL (0) ✔️ VERTICAL (1)
SwingMode (B6) indicates whether swing-mode is enabled	uint8	PR+EV+PW	0	1	SWING_DISABLED (0) ✔️ SWING_ENABLED (1)
CurrentTiltAngle (C1) current angle (in degrees) of slats from fully up or left (-90) to fully open (0) to fully down or right (90)	int	PR+EV	-90	90	0
TargetTiltAngle (C2) indicated desired angle (in degrees) of slats from fully up or left (-90) to fully open (0) to fully down or right (90)	int	PW+PR+EV	-90	90	0
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

SmokeSensor (87)

Defines a Smoke Sensor.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
SmokeDetected (76) 🔹 indicates if smoke is detected	uint8	PR+EV	0	1	NOT_DETECTED (0) ✔️ DETECTED (1)
StatusActive (75) indicates whether the Service is properly functioning	bool	PR+EV	0	1	NOT_FUNCTIONING (0) FUNCTIONING (1) ✔️
StatusFault (77) indicates whether the Service has a fault	uint8	PR+EV	0	1	NO_FAULT (0) ✔️ FAULT (1)
StatusTampered (7A) indicates whether the Service has been tampered with	uint8	PR+EV	0	1	NOT_TAMPERED (0) ✔️ TAMPERED (1)
StatusLowBattery (79) indicates state of battery	uint8	PR+EV	0	1	NOT_LOW_BATTERY (0) ✔️ LOW_BATTERY (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"
Mute (11A) 🔹 not used	bool	PW+PR+EV	0	1	OFF (0) ✔️ ON (1)
Volume (119) unused	uint8	PW+PR+EV	0	100	0
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

StatelessProgrammableSwitch (89)

Defines a "Stateless" Programmable Switch that can be used to trigger actions in the Home App.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
ProgrammableSwitchEvent (73) 🔹 specifies type of button press	uint8	PR+EV+NV	0	2	SINGLE_PRESS (0) ✔️ DOUBLE_PRESS (1) LONG_PRESS (2)
ServiceLabelIndex (CB) numerical index used to distinguish multiple copies of the same Service within an Accessory	uint8	PR	1	255	1

Switch (49)

Defines a generic Switch.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
On (25) 🔹 indicates if the Service is active/on	bool	PR+PW+EV	0	1	OFF (0) ✔️ ON (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

Television (D8)

Defines a TV. Optional Linked Services: InputSource and TelevisionSpeaker.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
Active (B0) 🔹 indicates if the Service is active/on	uint8	PW+PR+EV	0	1	INACTIVE (0) ✔️ ACTIVE (1)
ActiveIdentifier (E7) numerical Identifier of the InputSource selected in the Home App.	uint32	PW+PR+EV	0	255	0
RemoteKey (E1) triggers an update when the corresponding key is pressed in the Remote Control widget on an iPhone	uint8	PW	4	15	UP (4) DOWN (5) LEFT (6) RIGHT (7) CENTER (8) BACK (9) PLAY_PAUSE (11) INFO (15)
PowerModeSelection (DF) when defined, creates a "View TV Settings" button in the Home App that triggers an update to this Characteristic when pressed	uint8	PW	0	0	VIEW_SETTINGS (0)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

TelevisionSpeaker (113)

Defines a Television Speaker that can be controlled via the Remote Control widget on an iPhone. Use only as a Linked Service for the Television Service.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
VolumeControlType (E9) 🔹 indicates the type of volume control	uint8	PR+EV	0	3	NONE (0) RELATIVE (1) RELATIVE_CURRENT (2) ABSOLUTE (3) ✔️
VolumeSelector (EA) 🔹 triggered by presses to the iPhone's volume up/down buttons when TV is selected in the Remote Control widget	uint8	PW	0	1	VOLUME_UP (0) VOLUME_DOWN (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

TemperatureSensor (8A)

Defines a Temperature Sensor.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
CurrentTemperature (11) 🔹 current temperature measured in Celsius	float	PR+EV	0	100	0
StatusActive (75) indicates whether the Service is properly functioning	bool	PR+EV	0	1	NOT_FUNCTIONING (0) FUNCTIONING (1) ✔️
StatusFault (77) indicates whether the Service has a fault	uint8	PR+EV	0	1	NO_FAULT (0) ✔️ FAULT (1)
StatusTampered (7A) indicates whether the Service has been tampered with	uint8	PR+EV	0	1	NOT_TAMPERED (0) ✔️ TAMPERED (1)
StatusLowBattery (79) indicates state of battery	uint8	PR+EV	0	1	NOT_LOW_BATTERY (0) ✔️ LOW_BATTERY (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

Thermostat (4A)

Defines a Thermostat used to control a furnace, air conditioner, or both.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
CurrentHeatingCoolingState (F) 🔹 indicates whether appliance is currently heating, cooling, or just idle	uint8	PR+EV	0	2	IDLE (0) ✔️ HEATING (1) COOLING (2)
TargetHeatingCoolingState (33) 🔹 indicates desired state of appliance	uint8	PW+PR+EV	0	3	OFF (0) ✔️ HEAT (1) COOL (2) AUTO (3)
CurrentTemperature (11) 🔹 current temperature measured in Celsius	float	PR+EV	0	100	0
TargetTemperature (35) 🔹 indicates desired temperature measures in Celsius	float	PW+PR+EV	10	38	16
TemperatureDisplayUnits (36) 🔹 indicates the desired units to display the temperature on the device itself (has no effect on Home App)	uint8	PW+PR+EV	0	1	CELSIUS (0) ✔️ FAHRENHEIT (1)
CoolingThresholdTemperature (D) cooling turns on when temperature (in Celsius) rises above this threshold	float	PR+PW+EV	10	35	10
CurrentRelativeHumidity (10) current humidity measured as a percentage	float	PR+EV	0	100	0
HeatingThresholdTemperature (12) heating turns on when temperature (in Celsius) falls below this threshold	float	PR+PW+EV	0	25	16
TargetRelativeHumidity (34) indicates desired humidity measured as a percentage	float	PW+PR+EV	0	100	0
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

Valve (D0)

Defines an electronic Valve. Can be used standalone or as a Linked Service in conjunction with the Faucet and IrrigationSystem Services.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
Active (B0) 🔹 indicates if the Service is active/on	uint8	PW+PR+EV	0	1	INACTIVE (0) ✔️ ACTIVE (1)
InUse (D2) 🔹 if Service is set to active, this indictes whether it is currently in use	uint8	PR+EV	0	1	NOT_IN_USE (0) ✔️ IN_USE (1)
ValveType (D5) 🔹 indicates the type of valve	uint8	PR+EV	0	3	GENERIC (0) ✔️ IRRIGATION (1) SHOWER_HEAD (2) FAUCET (3)
SetDuration (D3) specifies the duration (in seconds) for a Service to remain on once activated	uint32	PW+PR+EV	0	3600	60
RemainingDuration (D4) duration (in seconds) remaining for Service to be active/on	uint32	PR+EV	0	3600	60
IsConfigured (D6) indicates if a predefined Service has been configured	uint8	PR+EV	0	1	NOT_CONFIGURED (0) ✔️ CONFIGURED (1)
ServiceLabelIndex (CB) numerical index used to distinguish multiple copies of the same Service within an Accessory	uint8	PR	1	255	1
StatusFault (77) indicates whether the Service has a fault	uint8	PR+EV	0	1	NO_FAULT (0) ✔️ FAULT (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

Window (8B)

Defines a motorized Window.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
CurrentPosition (6D) 🔹 current position (as a percentage) from fully closed (0) to full open (100)	uint8	PR+EV	0	100	0
TargetPosition (7C) 🔹 indicates target position (as a percentage) from fully closed (0) to full open (100)	uint8	PW+PR+EV	0	100	0
ObstructionDetected (24) indicates if obstruction is detected	bool	PR+EV	0	1	NOT_DETECTED (0) ✔️ DETECTED (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

WindowCovering (8C)

Defines a motorized Window Shade, Screen, Awning, etc.

Characteristic	Format	Perms	Min	Max	Constants/Defaults
TargetPosition (7C) 🔹 indicates target position (as a percentage) from fully closed (0) to full open (100)	uint8	PW+PR+EV	0	100	0
CurrentPosition (6D) 🔹 current position (as a percentage) from fully closed (0) to full open (100)	uint8	PR+EV	0	100	0
CurrentHorizontalTiltAngle (6C) current angle (in degrees) of slats from fully up (-90) to fully open (0) to fully down (90)	int	PR+EV	-90	90	0
TargetHorizontalTiltAngle (7B) indicates desired angle (in degrees) of slats from fully up (-90) to fully open (0) to fully down (90)	int	PW+PR+EV	-90	90	0
CurrentVerticalTiltAngle (6E) current angle (in degrees) of slats from fully left (-90) to fully open (0) to fully right (90)	int	PR+EV	-90	90	0
TargetVerticalTiltAngle (7D) indicates desired angle (in degrees) of slats from fully left (-90) to fully open (0) to fully right (90)	int	PW+PR+EV	-90	90	0
ObstructionDetected (24) indicates if obstruction is detected	bool	PR+EV	0	1	NOT_DETECTED (0) ✔️ DETECTED (1)
ConfiguredName (E3) a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.	string	PW+PR+EV	-	-	"unnamed"

↩️ Back to the Welcome page

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) ↩︎
Though rarely needed, you can change the permissions of a Characteristic using setPerms(), addPerms(), and removePerms() ↩︎
Note that a Characteristic's pre-defined constants are inherited by objects that you create from that Characteristic. This means that if you create a pointer to the AirQuality Characteristic using Characteristic::AirQuality *air = new Characteristic::AirQuality; then later in your code you can either say
air->setVal(Characteristic::AirQuality::GOOD) or air->GOOD. Both will work, but the latter is much easier to type. ↩︎

86 KiB Raw Blame History