Skip to content

Latest commit

 

History

History
455 lines (404 loc) · 83 KB

ServiceList.md

File metadata and controls

455 lines (404 loc) · 83 KB
Raw

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 display name of the Accessory
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)
  • default display name of this Service
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)
  • default display name of this Service
stringPW+PR+EV--"unnamed"

Outlet (47)

Defines a 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)
  • default display name of this Service
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)
  • default display name of this Service
stringPW+PR+EV--"unnamed"

HEATING, VENTILATION, AND AIR CONDITIONING (HVAC)

AirPurifier (BB)

Defines a basic Air Purifier with an optional fan and swing mode. Optional Linked Services: FilterMaintenance. Combine with an AirSensor Service for automated operations.

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)
  • default display name of this Service
stringPW+PR+EV--"unnamed"

Fan (B7)

Defines a Fan. Combine 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)
  • default display name of this Service
stringPW+PR+EV--"unnamed"

FilterMaintenance (BA)

Defines a Filter Maintainence check. Use only as a Linked Service for the AirPurifier Service.

CharacteristicFormatPermsMinMaxConstants/Defaults
FilterChangeIndication (AC) 🔹
  • indicates state of filter
uint8PR+EV01
  • NO_CHANGE_NEEDED (0) ✔️
  • CHANGE_NEEDED (1) 
FilterLifeLevel (AB)
  • measured as a percentage of remaining life
floatPR+EV0100100
ResetFilterIndication (AD)
  • triggers an update when the user chooses to reset the FilterChangeIndication (only appears in Eve App, not Home App)
uint8PW11
  • RESET_FILTER (1) 
ConfiguredName (E3)
  • default display name of this Service
stringPW+PR+EV--"unnamed"

HeaterCooler (BC)

Defines a standalone Heater, Cooler, or combined Heater/Cooler.

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)
  • default display name of this Service
stringPW+PR+EV--"unnamed"

HumidifierDehumidifier (BD)

Defines a Humidifer, Dehumidifier, or combined Humidifer/Dehumidifier.

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)
  • default display name of this Service
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)
  • default display name of this Service
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)
  • default display name of this Service
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 (only appears in Eve App, not Home App)
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)
  • default display name of this Service
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 (only appears in Eve App, not Home App)
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)
  • default display name of this Service
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 (only appears in Eve App, not Home App)
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)
  • default display name of this Service
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 (only appears in Eve App, not Home App)
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)
  • default display name of this Service
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 (only appears in Eve App, not Home App)
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)
  • default display name of this Service
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 (only appears in Eve App, not Home App)
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)
  • default display name of this Service
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 (only appears in Eve App, not Home App)
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)
  • default display name of this Service
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 (only appears in Eve App, not Home App)
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)
  • default display name of this Service
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 (only appears in Eve App, not Home App)
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)
  • default display name of this Service
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 (only appears in Eve App, not Home App)
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)
  • default display name of this Service
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 (only appears in Eve App, not Home App)
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)
  • default display name of this Service
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)
  • default display name of this Service
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)
  • default display name of this Service
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)
  • default display name of this Service
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)
  • default display name of this Service
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)
  • default display name of this Service
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)
  • default display name of this Service
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 (only appears in Eve App, not Home App)
uint8PR+EV01
  • NO_FAULT (0) ✔️
  • FAULT (1) 
ConfiguredName (E3)
  • default display name of this Service
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 (only appears in Eve App, not Home App)
uint8PR+EV01
  • NO_FAULT (0) ✔️
  • FAULT (1) 
ConfiguredName (E3)
  • default display name of this Service
stringPW+PR+EV--"unnamed"

Valve (D0)

Defines an electronic Valve. Can be used standalone or as a Linked Service for either a Faucet or IrrigationSystem Service.

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 (only appears in Eve App, not Home App)
uint8PR+EV01
  • NO_FAULT (0) ✔️
  • FAULT (1) 
ConfiguredName (E3)
  • default display name of this Service
stringPW+PR+EV--"unnamed"

SECURITY SYSTEMS

SecuritySystem (7E)

Defines a Security System. Often used in combination 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 (only appears in Eve App, not Home App)
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)
  • default display name of this Service
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)
  • default display name of this Service
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
DisplayOrder (136)
  • specifies the order in which the TV inputs are displayed for selection in the Home App
tlv8PR+EV--NULL_TLV
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)
  • default display name of this Service
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)
  • default display name of this Service
stringPW+PR+EV--"unnamed"

MISCELLANEOUS

ServiceLabel (CC)

Defines a naming scheme for un-nameable Services, such as a StatelessProgrammableSwitch, by Linking them to this Service. When used, those other Services must each include a ServiceLabelIndex Characteristic with a unique value.

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

Footnotes

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