Seich
/
HomeSpan
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
HomeSpan/docs/ServiceList.md

85 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.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 HomeSpan2
    • 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).3

MANDATORY SERVICES

AccessoryInformation (3E)

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

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

LIGHTS, POWER, AND SWITCHES

BatteryService (96)

Defines a standalone Battery Service.

CharacteristicFormatPermsMinMaxConstants/Defaults
BatteryLevel (68) 🔹
  • measured as a percentage
uint8PR+EV0100100
ChargingState (8F) 🔹
  • indicates state of battery charging
uint8PR+EV02
  • NOT_CHARGING (0) ✔️
  • CHARGING (1) 
  • NOT_CHARGEABLE (2) 
StatusLowBattery (79) 🔹
  • indicates state of battery
uint8PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

LightBulb (43)

Defines any type of Light.

CharacteristicFormatPermsMinMaxConstants/Defaults
On (25) 🔹
  • indicates if the Service is active/on
boolPR+PW+EV01
  • OFF (0) ✔️
  • ON (1) 
Brightness (8)
  • measured as a percentage
intPR+PW+EV01000
Hue (13)
  • color (in degrees) from red (0) to green (120) to blue (240) and back to red (360)
floatPR+PW+EV03600
Saturation (2F)
  • color saturation, measured as a percentage
floatPR+PW+EV01000
ColorTemperature (CE)
  • measured in inverse megaKelvin (= 1,000,000 / Kelvin)
uint32PR+PW+EV140500200
ConfiguredName (E3)
  • a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.
stringPW+PR+EV--"unnamed"

Outlet (47)

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

CharacteristicFormatPermsMinMaxConstants/Defaults
On (25) 🔹
  • indicates if the Service is active/on
boolPR+PW+EV01
  • OFF (0) ✔️
  • ON (1) 
OutletInUse (26) 🔹
  • indicates if an appliance or light is plugged into the outlet, regardless of whether on or off
boolPR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

StatelessProgrammableSwitch (89)

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

CharacteristicFormatPermsMinMaxConstants/Defaults
ProgrammableSwitchEvent (73) 🔹
  • specifies type of button press
uint8PR+EV+NV02
  • 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
uint8PR12551

Switch (49)

Defines a generic Switch.

CharacteristicFormatPermsMinMaxConstants/Defaults
On (25) 🔹
  • indicates if the Service is active/on
boolPR+PW+EV01
  • 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.
stringPW+PR+EV--"unnamed"

HEATING, VENTILATION, AND AIR CONDITIONING (HVAC)

AirPurifier (BB)

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

CharacteristicFormatPermsMinMaxConstants/Defaults
Active (B0) 🔹
  • indicates if the Service is active/on
uint8PW+PR+EV01
  • INACTIVE (0) ✔️
  • ACTIVE (1) 
CurrentAirPurifierState (A9) 🔹
  • indicates current state of air purification
uint8PR+EV02
  • INACTIVE (0) 
  • IDLE (1) ✔️
  • PURIFYING (2) 
TargetAirPurifierState (A8) 🔹
  • indicates desired state of air purifier
uint8PW+PR+EV01
  • MANUAL (0) 
  • AUTO (1) ✔️
RotationSpeed (29)
  • measured as a percentage
floatPR+PW+EV01000
SwingMode (B6)
  • indicates whether swing-mode is enabled
uint8PR+EV+PW01
  • SWING_DISABLED (0) ✔️
  • SWING_ENABLED (1) 
LockPhysicalControls (A7)
  • indicates if local control lock is enabled
uint8PW+PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

Fan (B7)

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

CharacteristicFormatPermsMinMaxConstants/Defaults
Active (B0) 🔹
  • indicates if the Service is active/on
uint8PW+PR+EV01
  • INACTIVE (0) ✔️
  • ACTIVE (1) 
CurrentFanState (AF)
  • indicates current state of a fan
uint8PR+EV02
  • INACTIVE (0) 
  • IDLE (1) ✔️
  • BLOWING (2) 
TargetFanState (BF)
  • indicates desired state of fan
uint8PW+PR+EV01
  • MANUAL (0) 
  • AUTO (1) ✔️
RotationDirection (28)
  • indicates the rotation direction of a fan
intPR+PW+EV01
  • CLOCKWISE (0) ✔️
  • COUNTERCLOCKWISE (1) 
RotationSpeed (29)
  • measured as a percentage
floatPR+PW+EV01000
SwingMode (B6)
  • indicates whether swing-mode is enabled
uint8PR+EV+PW01
  • SWING_DISABLED (0) ✔️
  • SWING_ENABLED (1) 
LockPhysicalControls (A7)
  • indicates if local control lock is enabled
uint8PW+PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

FilterMaintenance (BA)

Defines a Filter Maintainence check.

CharacteristicFormatPermsMinMaxConstants/Defaults
FilterChangeIndication (AC) 🔹
  • indicates state of filter
uint8PR+EV01
  • NO_CHANGE_NEEDED (0) ✔️
  • CHANGE_NEEDED (1) 
FilterLifeLevel (AB)
  • measures as a percentage of remaining life
floatPR+EV01000
ResetFilterIndication (AD)
  • triggers and update when the user chooses to reset the FilterChangeIndication from the Home App
uint8PW11
  • 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.
stringPW+PR+EV--"unnamed"

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.

CharacteristicFormatPermsMinMaxConstants/Defaults
Active (B0) 🔹
  • indicates if the Service is active/on
uint8PW+PR+EV01
  • INACTIVE (0) ✔️
  • ACTIVE (1) 
CurrentTemperature (11) 🔹
  • current temperature measured in Celsius
floatPR+EV01000
CurrentHeaterCoolerState (B1) 🔹
  • indicates whether appliance is currently heating, cooling, idle, or off
uint8PR+EV03
  • INACTIVE (0) 
  • IDLE (1) ✔️
  • HEATING (2) 
  • COOLING (3) 
TargetHeaterCoolerState (B2) 🔹
  • indicates desired state of heater/cooler
uint8PW+PR+EV02
  • AUTO (0) ✔️
  • HEAT (1) 
  • COOL (2) 
RotationSpeed (29)
  • measured as a percentage
floatPR+PW+EV01000
TemperatureDisplayUnits (36)
  • indicates the desired units to display the temperature on the device itself (has no effect on Home App)
uint8PW+PR+EV01
  • CELSIUS (0) ✔️
  • FAHRENHEIT (1) 
SwingMode (B6)
  • indicates whether swing-mode is enabled
uint8PR+EV+PW01
  • SWING_DISABLED (0) ✔️
  • SWING_ENABLED (1) 
CoolingThresholdTemperature (D)
  • cooling turns on when temperature (in Celsius) rises above this threshold
floatPR+PW+EV103510
HeatingThresholdTemperature (12)
  • heating turns on when temperature (in Celsius) falls below this threshold
floatPR+PW+EV02516
LockPhysicalControls (A7)
  • indicates if local control lock is enabled
uint8PW+PR+EV01
  • 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.
stringPW+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.

CharacteristicFormatPermsMinMaxConstants/Defaults
Active (B0) 🔹
  • indicates if the Service is active/on
uint8PW+PR+EV01
  • INACTIVE (0) ✔️
  • ACTIVE (1) 
CurrentRelativeHumidity (10) 🔹
  • current humidity measured as a percentage
floatPR+EV01000
CurrentHumidifierDehumidifierState (B3) 🔹
  • indicates current state of humidifier/dehumidifer
uint8PR+EV03
  • INACTIVE (0) 
  • IDLE (1) ✔️
  • HUMIDIFYING (2) 
  • DEHUMIDIFYING (3) 
TargetHumidifierDehumidifierState (B4) 🔹
  • indicates desired state of humidifier/dehumidifier
uint8PW+PR+EV02
  • AUTO (0) ✔️
  • HUMIDIFY (1) 
  • DEHUMIDIFY (2) 
RelativeHumidityDehumidifierThreshold (C9)
  • dehumidfier turns on when humidity rises above this threshold
floatPR+PW+EV010050
RelativeHumidityHumidifierThreshold (CA)
  • humidfier turns on when humidity falls below this threshold
floatPR+PW+EV010050
RotationSpeed (29)
  • measured as a percentage
floatPR+PW+EV01000
SwingMode (B6)
  • indicates whether swing-mode is enabled
uint8PR+EV+PW01
  • SWING_DISABLED (0) ✔️
  • SWING_ENABLED (1) 
WaterLevel (B5)
  • measured as a percentage
floatPR+EV01000
LockPhysicalControls (A7)
  • indicates if local control lock is enabled
uint8PW+PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

Slat (B9)

Defines a motorized ventilation Slat(s).

CharacteristicFormatPermsMinMaxConstants/Defaults
CurrentSlatState (AA) 🔹
  • indicates current state of slats
uint8PR+EV02
  • FIXED (0) ✔️
  • JAMMED (1) 
  • SWINGING (2) 
SlatType (C0) 🔹
  • indicates the direction of a slat or group of slats
uint8PR01
  • HORIZONTAL (0) ✔️
  • VERTICAL (1) 
SwingMode (B6)
  • indicates whether swing-mode is enabled
uint8PR+EV+PW01
  • 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)
intPR+EV-90900
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)
intPW+PR+EV-90900
ConfiguredName (E3)
  • a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.
stringPW+PR+EV--"unnamed"

Thermostat (4A)

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

CharacteristicFormatPermsMinMaxConstants/Defaults
CurrentHeatingCoolingState (F) 🔹
  • indicates whether appliance is currently heating, cooling, or just idle
uint8PR+EV02
  • IDLE (0) ✔️
  • HEATING (1) 
  • COOLING (2) 
TargetHeatingCoolingState (33) 🔹
  • indicates desired state of appliance
uint8PW+PR+EV03
  • OFF (0) ✔️
  • HEAT (1) 
  • COOL (2) 
  • AUTO (3) 
CurrentTemperature (11) 🔹
  • current temperature measured in Celsius
floatPR+EV01000
TargetTemperature (35) 🔹
  • indicates desired temperature measures in Celsius
floatPW+PR+EV103816
TemperatureDisplayUnits (36) 🔹
  • indicates the desired units to display the temperature on the device itself (has no effect on Home App)
uint8PW+PR+EV01
  • CELSIUS (0) ✔️
  • FAHRENHEIT (1) 
CoolingThresholdTemperature (D)
  • cooling turns on when temperature (in Celsius) rises above this threshold
floatPR+PW+EV103510
CurrentRelativeHumidity (10)
  • current humidity measured as a percentage
floatPR+EV01000
HeatingThresholdTemperature (12)
  • heating turns on when temperature (in Celsius) falls below this threshold
floatPR+PW+EV02516
TargetRelativeHumidity (34)
  • indicates desired humidity measured as a percentage
floatPW+PR+EV01000
ConfiguredName (E3)
  • a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.
stringPW+PR+EV--"unnamed"

STANDALONE SENSORS

AirQualitySensor (8D)

Defines an Air Quality Sensor.

CharacteristicFormatPermsMinMaxConstants/Defaults
AirQuality (95) 🔹
  • a subjective description
uint8PR+EV05
  • UNKNOWN (0) ✔️
  • EXCELLENT (1) 
  • GOOD (2) 
  • FAIR (3) 
  • INFERIOR (4) 
  • POOR (5) 
OzoneDensity (C3)
  • measured in µg/m3
floatPR+EV010000
NitrogenDioxideDensity (C4)
  • measured in µg/m3
floatPR+EV010000
SulphurDioxideDensity (C5)
  • measured in µg/m3
floatPR+EV010000
PM25Density (C6)
  • 2.5-micron particulate density, measured in µg/m3
floatPR+EV010000
PM10Density (C7)
  • 10-micron particulate density, measured in µg/m3
floatPR+EV010000
VOCDensity (C8)
  • measured in µg/m3
floatPR+EV010000
StatusActive (75)
  • indicates whether the Service is properly functioning
boolPR+EV01
  • NOT_FUNCTIONING (0) 
  • FUNCTIONING (1) ✔️
StatusFault (77)
  • indicates whether the Service has a fault
uint8PR+EV01
  • NO_FAULT (0) ✔️
  • FAULT (1) 
StatusTampered (7A)
  • indicates whether the Service has been tampered with
uint8PR+EV01
  • NOT_TAMPERED (0) ✔️
  • TAMPERED (1) 
StatusLowBattery (79)
  • indicates state of battery
uint8PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

CarbonDioxideSensor (97)

Defines a Carbon Dioxide Sensor.

CharacteristicFormatPermsMinMaxConstants/Defaults
CarbonDioxideDetected (92) 🔹
  • indicates if abnormal level is detected
uint8PR+EV01
  • NORMAL (0) ✔️
  • ABNORMAL (1) 
CarbonDioxideLevel (93)
  • measured on parts per million (ppm)
floatPR+EV01000000
CarbonDioxidePeakLevel (94)
  • measured in parts per million (ppm)
floatPR+EV01000000
StatusActive (75)
  • indicates whether the Service is properly functioning
boolPR+EV01
  • NOT_FUNCTIONING (0) 
  • FUNCTIONING (1) ✔️
StatusFault (77)
  • indicates whether the Service has a fault
uint8PR+EV01
  • NO_FAULT (0) ✔️
  • FAULT (1) 
StatusTampered (7A)
  • indicates whether the Service has been tampered with
uint8PR+EV01
  • NOT_TAMPERED (0) ✔️
  • TAMPERED (1) 
StatusLowBattery (79)
  • indicates state of battery
uint8PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

CarbonMonoxideSensor (7F)

Defines a Carbon Monoxide Sensor.

CharacteristicFormatPermsMinMaxConstants/Defaults
CarbonMonoxideDetected (69) 🔹
  • indicates if abnormal level is detected
uint8PR+EV01
  • NORMAL (0) ✔️
  • ABNORMAL (1) 
CarbonMonoxideLevel (90)
  • measured in parts per million (ppm)
floatPR+EV01000
CarbonMonoxidePeakLevel (91)
  • measured in parts per million (ppm)
floatPR+EV01000
StatusActive (75)
  • indicates whether the Service is properly functioning
boolPR+EV01
  • NOT_FUNCTIONING (0) 
  • FUNCTIONING (1) ✔️
StatusFault (77)
  • indicates whether the Service has a fault
uint8PR+EV01
  • NO_FAULT (0) ✔️
  • FAULT (1) 
StatusTampered (7A)
  • indicates whether the Service has been tampered with
uint8PR+EV01
  • NOT_TAMPERED (0) ✔️
  • TAMPERED (1) 
StatusLowBattery (79)
  • indicates state of battery
uint8PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

ContactSensor (80)

Defines a Contact Sensor.

CharacteristicFormatPermsMinMaxConstants/Defaults
ContactSensorState (6A) 🔹
  • indictates if contact is detected (i.e. closed)
uint8PR+EV01
  • DETECTED (0) 
  • NOT_DETECTED (1) ✔️
StatusActive (75)
  • indicates whether the Service is properly functioning
boolPR+EV01
  • NOT_FUNCTIONING (0) 
  • FUNCTIONING (1) ✔️
StatusFault (77)
  • indicates whether the Service has a fault
uint8PR+EV01
  • NO_FAULT (0) ✔️
  • FAULT (1) 
StatusTampered (7A)
  • indicates whether the Service has been tampered with
uint8PR+EV01
  • NOT_TAMPERED (0) ✔️
  • TAMPERED (1) 
StatusLowBattery (79)
  • indicates state of battery
uint8PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

HumiditySensor (82)

Defines a Humidity Sensor.

CharacteristicFormatPermsMinMaxConstants/Defaults
CurrentRelativeHumidity (10) 🔹
  • current humidity measured as a percentage
floatPR+EV01000
StatusActive (75)
  • indicates whether the Service is properly functioning
boolPR+EV01
  • NOT_FUNCTIONING (0) 
  • FUNCTIONING (1) ✔️
StatusFault (77)
  • indicates whether the Service has a fault
uint8PR+EV01
  • NO_FAULT (0) ✔️
  • FAULT (1) 
StatusTampered (7A)
  • indicates whether the Service has been tampered with
uint8PR+EV01
  • NOT_TAMPERED (0) ✔️
  • TAMPERED (1) 
StatusLowBattery (79)
  • indicates state of battery
uint8PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

LeakSensor (83)

Defines a Leak Sensor.

CharacteristicFormatPermsMinMaxConstants/Defaults
LeakDetected (70) 🔹
  • indictates if a leak is detected
uint8PR+EV01
  • NOT_DETECTED (0) ✔️
  • DETECTED (1) 
StatusActive (75)
  • indicates whether the Service is properly functioning
boolPR+EV01
  • NOT_FUNCTIONING (0) 
  • FUNCTIONING (1) ✔️
StatusFault (77)
  • indicates whether the Service has a fault
uint8PR+EV01
  • NO_FAULT (0) ✔️
  • FAULT (1) 
StatusTampered (7A)
  • indicates whether the Service has been tampered with
uint8PR+EV01
  • NOT_TAMPERED (0) ✔️
  • TAMPERED (1) 
StatusLowBattery (79)
  • indicates state of battery
uint8PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

LightSensor (84)

Defines a Light Sensor.

CharacteristicFormatPermsMinMaxConstants/Defaults
CurrentAmbientLightLevel (6B) 🔹
  • measured in Lux (lumens/m2
floatPR+EV0.00011000001
StatusActive (75)
  • indicates whether the Service is properly functioning
boolPR+EV01
  • NOT_FUNCTIONING (0) 
  • FUNCTIONING (1) ✔️
StatusFault (77)
  • indicates whether the Service has a fault
uint8PR+EV01
  • NO_FAULT (0) ✔️
  • FAULT (1) 
StatusTampered (7A)
  • indicates whether the Service has been tampered with
uint8PR+EV01
  • NOT_TAMPERED (0) ✔️
  • TAMPERED (1) 
StatusLowBattery (79)
  • indicates state of battery
uint8PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

MotionSensor (85)

Defines a Motion Sensor.

CharacteristicFormatPermsMinMaxConstants/Defaults
MotionDetected (22) 🔹
  • indicates if motion is detected
boolPR+EV01
  • NOT_DETECTED (0) ✔️
  • DETECTED (1) 
StatusActive (75)
  • indicates whether the Service is properly functioning
boolPR+EV01
  • NOT_FUNCTIONING (0) 
  • FUNCTIONING (1) ✔️
StatusFault (77)
  • indicates whether the Service has a fault
uint8PR+EV01
  • NO_FAULT (0) ✔️
  • FAULT (1) 
StatusTampered (7A)
  • indicates whether the Service has been tampered with
uint8PR+EV01
  • NOT_TAMPERED (0) ✔️
  • TAMPERED (1) 
StatusLowBattery (79)
  • indicates state of battery
uint8PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

OccupancySensor (86)

Defines and Occupancy Sensor.

CharacteristicFormatPermsMinMaxConstants/Defaults
OccupancyDetected (71) 🔹
  • indicates if occupanccy is detected
uint8PR+EV01
  • NOT_DETECTED (0) ✔️
  • DETECTED (1) 
StatusActive (75)
  • indicates whether the Service is properly functioning
boolPR+EV01
  • NOT_FUNCTIONING (0) 
  • FUNCTIONING (1) ✔️
StatusFault (77)
  • indicates whether the Service has a fault
uint8PR+EV01
  • NO_FAULT (0) ✔️
  • FAULT (1) 
StatusTampered (7A)
  • indicates whether the Service has been tampered with
uint8PR+EV01
  • NOT_TAMPERED (0) ✔️
  • TAMPERED (1) 
StatusLowBattery (79)
  • indicates state of battery
uint8PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

SmokeSensor (87)

Defines a Smoke Sensor.

CharacteristicFormatPermsMinMaxConstants/Defaults
SmokeDetected (76) 🔹
  • indicates if smoke is detected
uint8PR+EV01
  • NOT_DETECTED (0) ✔️
  • DETECTED (1) 
StatusActive (75)
  • indicates whether the Service is properly functioning
boolPR+EV01
  • NOT_FUNCTIONING (0) 
  • FUNCTIONING (1) ✔️
StatusFault (77)
  • indicates whether the Service has a fault
uint8PR+EV01
  • NO_FAULT (0) ✔️
  • FAULT (1) 
StatusTampered (7A)
  • indicates whether the Service has been tampered with
uint8PR+EV01
  • NOT_TAMPERED (0) ✔️
  • TAMPERED (1) 
StatusLowBattery (79)
  • indicates state of battery
uint8PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

TemperatureSensor (8A)

Defines a Temperature Sensor.

CharacteristicFormatPermsMinMaxConstants/Defaults
CurrentTemperature (11) 🔹
  • current temperature measured in Celsius
floatPR+EV01000
StatusActive (75)
  • indicates whether the Service is properly functioning
boolPR+EV01
  • NOT_FUNCTIONING (0) 
  • FUNCTIONING (1) ✔️
StatusFault (77)
  • indicates whether the Service has a fault
uint8PR+EV01
  • NO_FAULT (0) ✔️
  • FAULT (1) 
StatusTampered (7A)
  • indicates whether the Service has been tampered with
uint8PR+EV01
  • NOT_TAMPERED (0) ✔️
  • TAMPERED (1) 
StatusLowBattery (79)
  • indicates state of battery
uint8PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

DOORS, LOCKS, AND WINDOWS

Door (81)

Defines a motorized Door.

CharacteristicFormatPermsMinMaxConstants/Defaults
CurrentPosition (6D) 🔹
  • current position (as a percentage) from fully closed (0) to full open (100)
uint8PR+EV01000
TargetPosition (7C) 🔹
  • indicates target position (as a percentage) from fully closed (0) to full open (100)
uint8PW+PR+EV01000
ObstructionDetected (24)
  • indicates if obstruction is detected
boolPR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

Doorbell (121)

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

CharacteristicFormatPermsMinMaxConstants/Defaults
ProgrammableSwitchEvent (73) 🔹
  • specifies type of button press
uint8PR+EV+NV02
  • 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.
stringPW+PR+EV--"unnamed"

GarageDoorOpener (41)

Defines a motorized Garage Door Opener.

CharacteristicFormatPermsMinMaxConstants/Defaults
CurrentDoorState (E) 🔹
  • indicates current state of a door
uint8PR+EV04
  • OPEN (0) 
  • CLOSED (1) ✔️
  • OPENING (2) 
  • CLOSING (3) 
  • STOPPED (4) 
TargetDoorState (32) 🔹
  • indicates desired state of door
uint8PW+PR+EV01
  • OPEN (0) 
  • CLOSED (1) ✔️
ObstructionDetected (24) 🔹
  • indicates if obstruction is detected
boolPR+EV01
  • NOT_DETECTED (0) ✔️
  • DETECTED (1) 
LockCurrentState (1D)
  • indicates state of a lock
uint8PR+EV03
  • UNLOCKED (0) ✔️
  • LOCKED (1) 
  • JAMMED (2) 
  • UNKNOWN (3) 
LockTargetState (1E)
  • indicates desired state of lock
uint8PW+PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

LockMechanism (45)

Defines an electronic Lock.

CharacteristicFormatPermsMinMaxConstants/Defaults
LockCurrentState (1D) 🔹
  • indicates state of a lock
uint8PR+EV03
  • UNLOCKED (0) ✔️
  • LOCKED (1) 
  • JAMMED (2) 
  • UNKNOWN (3) 
LockTargetState (1E) 🔹
  • indicates desired state of lock
uint8PW+PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

Window (8B)

Defines a motorized Window.

CharacteristicFormatPermsMinMaxConstants/Defaults
CurrentPosition (6D) 🔹
  • current position (as a percentage) from fully closed (0) to full open (100)
uint8PR+EV01000
TargetPosition (7C) 🔹
  • indicates target position (as a percentage) from fully closed (0) to full open (100)
uint8PW+PR+EV01000
ObstructionDetected (24)
  • indicates if obstruction is detected
boolPR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

WindowCovering (8C)

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

CharacteristicFormatPermsMinMaxConstants/Defaults
TargetPosition (7C) 🔹
  • indicates target position (as a percentage) from fully closed (0) to full open (100)
uint8PW+PR+EV01000
CurrentPosition (6D) 🔹
  • current position (as a percentage) from fully closed (0) to full open (100)
uint8PR+EV01000
CurrentHorizontalTiltAngle (6C)
  • current angle (in degrees) of slats from fully up (-90) to fully open (0) to fully down (90)
intPR+EV-90900
TargetHorizontalTiltAngle (7B)
  • indicates desired angle (in degrees) of slats from fully up (-90) to fully open (0) to fully down (90)
intPW+PR+EV-90900
CurrentVerticalTiltAngle (6E)
  • current angle (in degrees) of slats from fully left (-90) to fully open (0) to fully right (90)
intPR+EV-90900
TargetVerticalTiltAngle (7D)
  • indicates desired angle (in degrees) of slats from fully left (-90) to fully open (0) to fully right (90)
intPW+PR+EV-90900
ObstructionDetected (24)
  • indicates if obstruction is detected
boolPR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

WATER SYSTEMS

Faucet (D7)

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

CharacteristicFormatPermsMinMaxConstants/Defaults
Active (B0) 🔹
  • indicates if the Service is active/on
uint8PW+PR+EV01
  • INACTIVE (0) ✔️
  • ACTIVE (1) 
StatusFault (77)
  • indicates whether the Service has a fault
uint8PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

IrrigationSystem (CF)

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

CharacteristicFormatPermsMinMaxConstants/Defaults
Active (B0) 🔹
  • indicates if the Service is active/on
uint8PW+PR+EV01
  • INACTIVE (0) ✔️
  • ACTIVE (1) 
ProgramMode (D1) 🔹
  • indicates if pre-scheduled program is running
uint8PR+EV02
  • NONE (0) ✔️
  • SCHEDULED (1) 
  • SCHEDULE_OVERRIDEN (2) 
InUse (D2) 🔹
  • if Service is set to active, this indictes whether it is currently in use
uint8PR+EV01
  • NOT_IN_USE (0) ✔️
  • IN_USE (1) 
RemainingDuration (D4)
  • duration (in seconds) remaining for Service to be active/on
uint32PR+EV0360060
StatusFault (77)
  • indicates whether the Service has a fault
uint8PR+EV01
  • 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.
stringPW+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.

CharacteristicFormatPermsMinMaxConstants/Defaults
Active (B0) 🔹
  • indicates if the Service is active/on
uint8PW+PR+EV01
  • INACTIVE (0) ✔️
  • ACTIVE (1) 
InUse (D2) 🔹
  • if Service is set to active, this indictes whether it is currently in use
uint8PR+EV01
  • NOT_IN_USE (0) ✔️
  • IN_USE (1) 
ValveType (D5) 🔹
  • indicates the type of valve
uint8PR+EV03
  • GENERIC (0) ✔️
  • IRRIGATION (1) 
  • SHOWER_HEAD (2) 
  • FAUCET (3) 
SetDuration (D3)
  • specifies the duration (in seconds) for a Service to remain on once activated
uint32PW+PR+EV0360060
RemainingDuration (D4)
  • duration (in seconds) remaining for Service to be active/on
uint32PR+EV0360060
IsConfigured (D6)
  • indicates if a predefined Service has been configured
uint8PR+EV01
  • NOT_CONFIGURED (0) ✔️
  • CONFIGURED (1) 
ServiceLabelIndex (CB)
  • numerical index used to distinguish multiple copies of the same Service within an Accessory
uint8PR12551
StatusFault (77)
  • indicates whether the Service has a fault
uint8PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

SECURITY SYSTEMS

SecuritySystem (7E)

Defines a Security System. Often combined with MotionSensor and ContactSensor Services.

CharacteristicFormatPermsMinMaxConstants/Defaults
SecuritySystemCurrentState (66) 🔹
  • indicates current state of the security system
uint8PR+EV04
  • ARMED_STAY (0) 
  • ARMED_AWAY (1) 
  • ARMED_NIGHT (2) 
  • DISARMED (3) ✔️
  • ALARM_TRIGGERED (4) 
SecuritySystemTargetState (67) 🔹
  • indicates desired state of the security system
uint8PW+PR+EV03
  • ARM_STAY (0) 
  • ARM_AWAY (1) 
  • ARM_NIGHT (2) 
  • DISARM (3) ✔️
SecuritySystemAlarmType (8E)
  • indicates whether alarm was triggered for known reason
uint8PR+EV01
  • KNOWN (0) ✔️
  • UNKNOWN (1) 
StatusFault (77)
  • indicates whether the Service has a fault
uint8PR+EV01
  • NO_FAULT (0) ✔️
  • FAULT (1) 
StatusTampered (7A)
  • indicates whether the Service has been tampered with
uint8PR+EV01
  • 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.
stringPW+PR+EV--"unnamed"

TELEVISIONS

InputSource (D9)

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

CharacteristicFormatPermsMinMaxConstants/Defaults
Identifier (E6) 🔹
  • numerical Identifer of the InputSource.
uint32PR02550
ConfiguredName (E3)
  • a "configurable" Service name - any updates made from within the Home App trigger an update in HomeSpan and vice versa.
stringPW+PR+EV--"unnamed"
IsConfigured (D6)
  • indicates if a predefined Service has been configured
uint8PR+EV01
  • NOT_CONFIGURED (0) ✔️
  • CONFIGURED (1) 
CurrentVisibilityState (135)
  • current visibility of the Service, as selectable on the Settings Page of the Home App
uint8PR+EV01
  • VISIBLE (0) ✔️
  • NOT_VISIBLE (1) 
TargetVisibilityState (134)
  • indicates desired visibility of the Service, as selectable on the Settings Page of the Home App
uint8PW+PR+EV01
  • VISIBLE (0) ✔️
  • NOT_VISIBLE (1) 

Television (D8)

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

CharacteristicFormatPermsMinMaxConstants/Defaults
Active (B0) 🔹
  • indicates if the Service is active/on
uint8PW+PR+EV01
  • INACTIVE (0) ✔️
  • ACTIVE (1) 
ActiveIdentifier (E7)
  • numerical Identifier of the InputSource selected in the Home App.
uint32PW+PR+EV02550
RemoteKey (E1)
  • triggers an update when the corresponding key is pressed in the Remote Control widget on an iPhone
uint8PW415
  • 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
uint8PW00
  • 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.
stringPW+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.

CharacteristicFormatPermsMinMaxConstants/Defaults
VolumeControlType (E9) 🔹
  • indicates the type of volume control
uint8PR+EV03
  • 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
uint8PW01
  • 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.
stringPW+PR+EV--"unnamed"

MISCELLANEOUS

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.

CharacteristicFormatPermsMinMaxConstants/Defaults
ServiceLabelNamespace (CD) 🔹
  • indicates how un-named Services linked together with a ServiceLabel Service should be displayed in the Home App
uint8PR01
  • DOTS (0) 
  • NUMERALS (1) ✔️

↩️ Back to the Welcome page

  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() ↩︎

  3. 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. ↩︎