Getting Started

1. Bridges

The homebridge-hue plugin tries to discover any Hue bridge on your network by querying the Meethue portal. Alternatively, the hostname(s) or IP address(es) of the Hue bridge(s) can be specified in config.json. Both v2 (square) as well as v1 (round) Hue bridges are supported.

As the Philips Hue API does not support notifications of changes to the Hue bridge state, homebridge-hue polls each Hue bridge for its state at a regular interval, the heartrate. For each Hue bridge attribute changed, homebridge-hue updates the corresponding HomeKit characteristic. HomeKit (through homebridge) does notify homebridge-hue of any changes to HomeKit characteristic values. For each change, homebridge-hue updates the corresponding Hue bridge attribute.

For each bridge, homebridge-hue creates a HomeKit accessory, with a custom service, Heartbeat. This service contains two custom characteristics: Heartrate to control the heartrate, and LastUpdated that shows the time of the last homebridge-hue refreshed the bridge state. Note that Apple's Home app doesn't support custom services, nor any custom characteristic, so you need to use another HomeKit app for that, see 10. Caveats below.

Each supported Hue bridge resource is mapped to a corresponding HomeKit accessory, with appropriate service(s) to match the resource type (sensors, lights, groups), or to an additional service for the Hue bridge accessory (schedules, rules). Each supported Hue bridge resource attribute is then mapped to a corresponding HomeKit characteristic.

1.1 Bridge Configuration

By default, homebridge-hue exposes all bridges it discovers. This discovery is disabled when the bridge hostname(s) or IP address(es) is specified in config.json.

The polling interval can be set through heartrate in config.json. It can also be changed dynamically through the Heartrate characteristic of the bridge Heartbeat service.

config.json contains a key/value-pair for the username per bridge. When homebridge-hue finds a new bridge, it prompts to press the link button on the bridge. It then creates a bridge username, and prompts to edit config.json, providing the key/value-pair.

2. Sensors

For each Hue bridge sensor, homebridge-hue creates a HomeKit accessory with the appropriate services and characteristics.

2.1 Hue Motion Sensor

The Hue bridge actually uses three sensors per Hue Motion Sensor. For each of these, homebridge-hue creates a separate HomeKit service:

1. For the ZLLPresence bridge sensor, a Motion Sensor service is created, with a Motion Detected characteristic;

• For the ZLLLightLevel bridge sensor, a Light Sensor service is created, with characteristics Light Level, Dark, and Daylight. Note that Dark and Daylight are custom characteristic types, which might not be supported by all HomeKit apps;
• The ZLLTemperature bridge sensor is exposed as a Temperature Sensor service, with a Current Temperature characteristic.

As of v0.3, homebridge-hue creates a single accessory combining these three services.

Note that homebridge-hue does not support setting the thresholds for Dark and Daylight; the tolddark and tholdoffset attributes in the ZLLLightLevel bridge sensor config are not exposed. Also homebridge-hue does not yet support setting the sensitivity of the ZLLPresence sensor.

2.2 Hue Tap and Hue Dimmer Switch

The Hue bridge uses a ZGPSwitch sensor per Hue tap and a ZLLSwitch sensor per Hue dimmer switch. For each of these, homebridge-hue creates a separate HomeKit accessory with the following services:

1. Four Stateless Programmable Switch services, one for each button, with an Input Event characteristic. As of iOS 10.3, Apple's Home app treats this as a four-button programmable switch. For the Hue dimmer, Button 1 is mapped to On, button 2 to Dim Up, button 3 to Dim Down, and button 4 to Off. The Hue tap supports Single Press per button, the hue dimmer switch Single Press (for press) and Long Press (for hold);
2. One custom service, for the sensor status characteristics, see 2.5 below.

2.3 Daylight Sensor

The built-in Daylight sensor is exposed a as an accessory with a Light Sensor service and a custom Daylight characteristic. The mandatory Ambient Light Level characteristic is set to 100,000 lux during daylight and to 0.0001 lux otherwise. Apple's Home app supports triggers on sunrise and sunset, but HomeKit only supports these as conditions. The Daylight characteristic might come in handy if you want to trigger automation on sunrise or sunset from other HomeKit apps.

2.4 CLIP Sensors

Unlike the Hue motion sensor, Hue tap, Hue Dimmer switch, and the built-in Daylight sensor, CLIP sensors are more like Hue bridge variables than actual sensors. Their values can be set and used from the Hue bridge API as well as in Hue bridge rules. This makes these sensors extremely useful in home automation scenarios.

Homebridge-hue supports the following CLIP sensors:

Sensor Type	Service	Characteristic	Notes
CLIPGenericFlag	Switch	Power+	Typically used as virtual switch, see the home automation example below.
CLIPGenericStatus	(custom)	Status+*	Typically used to keep state in conjunction with Hue bridge rules, see home automation example below. Note that Status is a custom characteristic type, which might not be supported by all HomeKit apps.
CLIPPresence Geofence	MotionSensor	MotionDetected	The Philips Hue app uses these extensively for Home & Away routines.
CLIPTemperature	TemperatureSensor	CurrentTemperature	See virtual weather station example below.
CLIPHumidity	HumiditySensor	CurrentRelativeHumidity	See virtual weather station example below.
CLIPPressure	PressureSensor*	AirPressure*	See virtual weather station example below.
CLIPOpenClose	ContactSensor	ContactSensorState
CLIPLightLevel	LightSensor	LightLevel
CLIPSwitch	--	--	Not supported.

* Custom service / characteristic
+ These characteristics can be updated from HomeKit, the other characteristics are read-only.

2.4.1 Home Automation

To turn on the lights and music when entering a room, and to turn them off again when leaving, I use the following setup:

1. A CLIPGenericFlag sensor acts as virtual master switch for the room;

• An elaborate set of manually-created Hue bridge rules control this virtual master switch from the Hue motion sensors in the room and in the adjacent rooms. The state for these rules is maintained in a CLIPGenericStatus sensor. The room only turns off when some-one actually leaves the room, not when we're just sitting still in front of the TV;
• A second set of manually-created Hue bridge rules control the same virtual master switch from a Hue dimmer switch, providing a manual override;
• The virtual master switch is exposed to HomeKit, so it's controlled directly from Siri, and from widgets on our Apple watches and iPhones;
• A third set of manually-created Hue bridge rules control the lights in the room, based on the virtual master switch, the time of day, and the ambient light level (from the Hue motion sensor);
• A set of HomeKit triggers control the Sonos speakers in the room, based on the virtual master switch and the state of the Sonos speakers in the other rooms. The Sonos speakers are exposed to HomeKit using my other homebridge plugin, homebridge-zp;
• Another set of HomeKit triggers control a fan, based on the master switch and the room temperature (from the Hue motion sensor). The fan is made smart through an Eve Energy plug by Elgato, which has native HomeKit support.

2.4.2 Virtual Weather Station

A simpler example is my virtual weather station. A small cron job retrieves the local temperature and humidity from Weather Underground using curl and stores these values in a CLIPTemperature and a CLIPHumidity sensor on the Hue bridge, again using curl. These sensors are then exposed to HomeKit.

2.5 Sensor Status

For each sensor, homebridge-hue creates the following additional characteristics:

• LastUpdated for the sensor's state attribute lastupdated. Note that this is a customer characteristic type, which might not be supported by all HomeKit apps;
• Enabled for the sensor's config attribute on, which allows you to enable or disable the sensor from HomeKit. To make sure Siri won't unintentionally disable a sensor, homebridge-hue uses a custom characteristic, instead of Active;
• Status Active, also for the sensor's config attribute on. Elgato's Eve shows a nice warning sign next to the service when it's inactive.
• Status Fault for a Zigbee sensor's config attribute reachable. Elgato's Eve shows a nice warning sign next to the service when it's reporting a fault.

To provide these characteristic for programmable switches (Hue dimmer switches and Hue tap switches), an additional custom service is added to the accessory. Under iOS 10.3, Apple's Home app happily ignores this service, so you only see the programmable switch. Conversely, Elgato's Eve app hides the StatelessProgrammableSwitch services (or rather the ProgrammableSwitchEvent characteristic), showing only the custom service in the Rooms view. It does show the ProgrammableSwitchEvent when creating triggers for rules in the Scenes view.

For battery operated Zigbee sensors (the Hue motion sensor and the Hue dimmer switch), homebridge-hue exposes a BatteryService service with characteristics BatteryLevel, StatusLowBattery, and ChargingState. BatteryLevel is mapped to the sensor's config attribute battery. StatusLowBattery is set when the battery level is below 25%. The mandatory ChargingState characteristic is set to Not Chargeable. Note that Apple's Home app only shows this service as of iOS 10.3.

2.6 Sensor Configuration

By default homebridge-hue does not expose sensors. You want to change this in config.json, so the sensors can be used as triggers and/or conditions in HomeKit rules. When you disable CLIP sensors in config.json, homebridge-hue exposes only Hue Motions sensors, Hue Dimmer switches, Hue Tap switches, and the built-in Daylight sensor.

3. Lights

A Hue bridge light is exposed as a HomeKit accessory with a Lightbulb service, with characteristics for Power, Brightness, Hue, Saturation, and Color Temperature, depending on the light's features. Both Philips as well as non-Philips lights are supported. Note that Color Temperature is a custom characteristic type, which might not be supported by all HomeKit apps. It holds the light's colour temperature in Kelvin, from 2000 to 6536.

Additionally, a characteristic for Status Fault is provided. It is set when the Hue bridge reports the light as unreachable. Note that Apple's Home app doesn't support this optional characteristic for a Lightbulb. Elgato's Eve shows a nice warning sign next to the service when it's reporting a fault.

Note that an On/Off plug-in unit, is exposed as an accessory with a Switch service, with only one characteristic for Power. To treat it as a light, set its Type to Light in your HomeKit app.

3.1 Color Temperature

Note that the v2 (square) Hue bridge also exposes a custom characteristic for colour temperature as well, but with some limitations:

• It only exposes colour temperature for Color Temperature Lights, not for Extended Color Lights;
• This Color Temperature characteristic holds the value in Mired (from 153 to 500) instead of in Kelvin. Note that Elgato's Eve app actually converts this value into Kelvin.

By setting ct in config.json, homebridge-hue exposes colour temperature using the same characteristic type as the Hue bridge.

3.2 Light Configuration

By default homebridge-hue does not expose any lights. You might want to change this in config.json to expose only non-Philips lights, if you already expose the Philips lights from your v2 (square) Hue Bridge. You might want to change this to expose all lights, if you have a v1 (round) bridge, or if you want to use the Color Temperature characteristic for Philips Extended color lights.

3.3 Rooms

From the Philips Hue app, you can synchronise the Room groups on the Hue bridge with HomeKit rooms, under Settings, HomeKit & Siri, Rooms. The app then re-assigns the HomeKit accessories for the lights to the HomeKit rooms, matching the Hue bridge Room groups. This works for (Philips) lights exposed by the Hue bridge as well as for (non-Philips) lights exposed by homebridge-hue.

4. Groups

A Hue bridge group is exposed as a HomeKit accessory with Lightbulb service and appropriate characteristics, just as a light. A group containing only On/Off plug-in units is exposed through a Switch service.

In addition to the characteristics uses for lights, an additional characteristic AnyOn is provided.

4.1 Group Configuration

By default, homebridge-hue does not expose groups. You might want to change this in config.json if you want to use Hue group commands from HomeKit scenes. As polling the state for group 0 (all lights) requires an additional bridge request, this group can be disabled in config.json. Note that groups of type Room are ignored by default. You can change this by in config.json.

5. Schedules

A Hue bridge schedule is exposed as an additional custom service to the bridge accessory. This service contains a single Enabled characteristic, mapped to the schedule's enabled attribute, which allows you to enable or disable the schedule from HomeKit. To make sure Siri won't unintentionally disable a schedule, homebridge-hue uses a custom characteristic, instead of Power or Active.

By default, homebridge-hue does not expose schedules. You might want to change this in config.json, to enable or disable schedules from HomeKit.

6. Rules

A Hue bridge rule is exposed as an additional custom service to the bridge accessory. This service contains the follwing custom characteristics:

• Enabled, mapped to the rule's enabled attribute, which allows you to enable or disable the rule from HomeKit. To make sure Siri won't unintentionally disable a rule, homebridge-hue uses a custom characteristic, instead of Power or Active;
• LastUpdated, mapped to the rule's lasttriggered attribute;
• TimesTriggered, mapped to the rule's timestriggered attribute.

By default, homebridge-hue does not expose rules. You probably don't want to, but you can change this in config.json. I only use this feature occasionally, when debugging the Hue bridge configuration. It allows monitoring when bridge rules are triggered and enabling or disabling bridge rules from HomeKit.

Note that HomeKit only supports up to 99 services per accessory, so only the first 98 rules are exposed. Or fewer, when you also expose schedules.