Characteristics

This page provides an overview of the HomeKit characteristic types used by homebridge-hue.

1. Introduction

For each characteristic type, the overview table lists the Hue bridge resource type and attribute type it represents. Characteristic types marked with an asterisk (*) are custom defined by homebridge-hue. Characteristic types marked with a plus (+) are also custom defined, but by some-one else. W(riteable) indicates whether the value of a characteristic of this type can be changed from HomeKit.

2. Overview

Characteristic	W	Resource	Attribute	Notes
Any On*	Y	group	state.any_on action.on	The value is read from state.any_on, changes are written to action.on. See also Power State.
Battery Level	N	sensor	config.battery	In Battery service. See also Status Low Battery.
Brightness	Y	light group	state.bri action.bri
ChargingState	N	sensor	config.battery	In Battery service. Value is Not Chargeable.
Color Temperature	Y	light group	state.ct action.ct	In mired.
Dark*	N	sensor	state.dark
Daylight*	N	sensor	state.daylight	For Daylight sensor, see also Light Level.
Duration*	Y	sensor	config.duration --	When config.duration is not present: Duration (in seconds) for homebridge-hue to report Motion Detected.
Enabled*	Y	sensor schedule rule	config.on status status	See also Status Active.
Heartrate*	Y	--	--	Rate (in seconds) at which homebridge-hue polls the Hue bridge.
Hue	Y	light group	state.xy action.xy	See also Saturation.
Identify	Y	light group sensor	state.alert action.alert config.alert	In Accessory Information service. Write-only.
Input Event	N	config sensor	linkbutton state.buttonevent	Not readable, only for triggers and notifications.
Last Triggered*	N	rule	lasttriggered
Last Updated*	N	config sensor	UTC state.lastupdated
Light Level	N	sensor	state.lightlevel state.daylight	For Daylight sensor, the value is 100,000 during daylight and 0.0001 otherwise.
Link*	Y	config	linkbutton	See also Input Event.
Manufacturer	N	(any)	manufacturername	In Accessory Information service.
Model	N	(any)	modelid type	In Accessory Information service.
Motion Detected	Y	sensor	state.presence	See also Occupancy Detected.
Name	Y	(any)	name
Occupancy Detected	Y	sensor	state.presence	See also Motion Detected.
Power State	Y	light	state.on state.reachable	The value is read from state.on and state.reachable, changes are written to state.on. See also Status Fault.
Power State	Y	group	state.all_on action.on	The value is read from state.all_on, changes are written to action.on. See also Any On.
Power State	Y	sensor	state.flag
Resource*	N	(any)	--	Hue bridge resource.
Saturation	Y	light group	state.xy action.xy	See also Hue.
Sensitivity	N	sensor	config.sensitivity
Serial Number	N	(any)	uniqueid	In Accessory Information service.
Status*	Y	sensor	state.status
Status Active	N	sensor schedule rule	config.on status status	See also Enabled.
Status Fault	N	light sensor	state.reachable config.reachable	Value 0 corresponds to true; value 1 to false.
Status Low Battery	N	sensor	config.battery	In Battery service. See also Battery Level.
Times Triggered*	N	rule	timestriggered
Touchlink*	Y	config	touchlink	Write-only.
Transition Time*	Y	light group	state.transitiontime action.transitiontime	Write-only.
Unique ID+	N	light	uniqueid	Used by v2 Hue bridge.

3. Notes

3.1 Characteristic Type Names

The overview uses the HMCharacteristicType names from the HomeKit API reference. A HomeKit app might display a characteristic using a different (localised) name.
Typically, HAP-NodeJS uses the HMCharacteristicType names. The most notable exceptions are:

• Power State is called On in HAP-NodeJS;
• Input Event is called ProgrammableSwitchEvent in HAP-NodeJS;
• Output State is called ProgrammableSwitchOutputState in HAP-NodeJS.

3.1 Charging State

Charging State is mandatory for a Battery service, so homebridge-hue must provide it, even though the value is always Not Chargeable.

3.2 Duration

homebridge-hue supports Duration in two different ways:

• When config.duration is available, (e.g. for Hue motion sensor connected to the deCONZ gateway), Duration is linked to config.duration. As the sensor (or gateway) has implemented config.duration, homebridge-hue reports Motion Detected as reported by the gateway;
• When config.duration is not available (e.g. for Hue motion sensor connected to the Hue bridge), Duration is handled by homebridge-hue itself. homebridge-hue keeps reporting Motion Detected for Duration seconds after the bridge/gateway reports no more motion.

3.3 Enabled and Status Active

homebridge-hue uses Enabled instead of Power State or Active, to prevent Siri from unintentionally disabling sensors, schedules, or rules. When asked to turn on or off a room or a zone, Siri interacts with the Power State or Active characteristic of every service for every accessory in that room or zone.
Status Active is used in addition to Enabled so Eve shows a warning when the sensor, schedule, or rule is disabled.

3.4 Hue and Saturation

In HomeKit, colour is actually defined by two characteristics, Hue and Saturation. Most HomeKit apps provide a colour picker of some sort, hiding these characteristics. In the Hue bridge, colour is defined by the IEC 1931 colour space xy coordinates. homebridge-hue translates Hue and Saturation into xy and back.

3.5 Input Event

Input Event can neither be written nor read from HomeKit apps. It is used to trigger HomeKit rules and HomeKit apps can receive a notification when the value changes.
The built-in Home app in iOS 10.3 uses this characteristic (and the corresponding Stateless Programmable Switch service) for a programmable switch button. When adding an action to a button, Home creates a hidden rule with a condition based on the Input Event value. Value 0 is used for a Short Press (Hue tap and Hue dimmer switch) and value 2 for a Long Press (Hue dimmer switch only).

3.6 Light Level

Light Level is mandatory for a Light Sensor service, so homebridge-hue must provide it for the Daylight sensor, even though the value is derived from state.daylight, which is already available as Daylight.

3.7 Power State

For lights, by default, Power State is based on state.on. To facilitate the use of traditional wall switches to power off smart lights, homebridge-hue can report Power State as Off, when state.reachable is false, even when state.on is still true. The wallSwitch parameter in config.json enables this behaviour.

For plug-in units, Power State is based only on state.on.

For groups, Power State is based on state.all_on and Any On is based on state.any_on. When changing Power State from HomeKit, homebridge-hue forwards the change to action.on.

3.8 Status Low Battery

The lowBattery setting in config.json specifies the threshold for Status Low Battery.

3.9 Unique ID

The Philips Hue app uses Unique ID when syncing rooms. By including this characteristic for non-Philips lights, the Hue app also syncs the room assignment for these lights.