Configuration

This page provides an overview of the config.json parameters used by homebridge-hue.

1. Overview

Key	Default	Description
ct	false	Flag to expose colour temperature in Mirek using the Color Temperature characteristic that the v2 (square) Hue bridge uses. When not set, colour temperature is exposed in Kelvin, using the Color Temperature characteristic that Nanoleaf uses.
excludeSensorTypes	[]	An array of sensor types to ignore. The sensor type is the (case sensitive) type attribute of the bridge sensor resource, or "CLIP" as a shortcut for all CLIP sensors. For example, to expose only the Hue motion sensors, Hue taps, and Hue dimmer switches, specify: "excludeSensorTypes": ["CLIP", "Geofence", "Daylight"].
groups	false	Flag whether to expose Hue bridge groups to HomeKit.
group0	false	Flag whether to include group 0 (all lights) when groups are exposed.
heartrate	5	The interval in seconds to poll the Hue bridge. Must be between 1 and 30. Note that this can be changed dynamically per bridge, through the Heartbeat service. I've been using a 2-second heartrate with no issues on my v2 (square) bridge.
host hosts	"" []	The hostname or IP address of the Hue bridge. When set, discovery of bridges is disabled. To specify a single hostname or IP address, use a string, e.g. "host": "192.168.1.10". To specify multiple hostnames and/or IP addresses use an array, e.g. "hosts": ["192.168.1.10", "192.168.1.11"].
lights	false	Flag whether to expose Hue bridge lights to HomeKit.
lowBattery	25	The battery level threshold for StatusLowBattery.
philipsLights	false	Flag whether to include Philips lights when lights are exposed. To expose all lights, set lights as well as philipsLights; to expose only non-Philips lights, only set lights.
name		The prefix homebridge uses for log (debug, error) messages issued by homebridge-hue. Highly recommended to set this to "Hue".
parallelRequests	10 3	The number of ansynchronous requests homebridge-hue sends in parallel to a Hue bridge. Must be between 1 and 30. You might want to decrease this if homebridge-hue reports ECONNRESET errors. The default is 10 for a v2 bridge and 3 for a v1 bridge.
platform		The name of the platform homebridge-hue provides to homebridge. Mandatory, must be set to "Hue".
rules	false	Flag whether to expose Hue bridge rules to HomeKit.
rooms	false	Flag whether to include Room groups when groups are exposed.
schedules	false	Flag whether to expose Hue bridge schedules to HomeKit.
sensors	false	Flag whether to expose Hue bridge sensors to HomeKit.
timeout	5	The timeout in seconds to wait for a response from a Hue bridge (or the Meethue portal or UPnP discovery). Must be between 5 and 30. You might want to increase this if homebridge-hue reports ETIMEDOUT or ESOCKETTIMEDOUT errors.
users	{}	A dictionary containing a key/value-pair per Hue bridge, where the key holds the bridge ID and the value holds the bridge username, effectively a security token to access the bridge. When connecting to a new bridge, homebridge-hue will create the username, and prompt you to edit config.json.
waitTimeResend	300	The time in milliseconds to wait before resending a request after an ECONNRESET error. Must be between 100 and 1000.
waitTimeUpdate	50	The time in milliseconds to wait for a change from HomeKit to another characteristic for the same light or group, before updating the Hue bridge. Must be between 20 and 500. You might want to increase this when homebridge-hue reports hue bridge error 201: parameter, xy, is not modifiable. Device is set to off. on activating a HomeKit scene that turns a light on at a specific colour, colour temperature, and/or brightness.

2. Examples

2.1 Configuration for Square Bridge

The example below is a typical configuration for a v2 (square) bridge, which already exposes the Philips lights to HomeKit. With this configuration, homebridge-hue exposes Hue motion sensors, Hue dimmer switches, Hue taps, and non-Philips lights, using the same Mired ColorTemperature characteristic type as the Hue bridge.

  "platforms": [
    {
      "platform": "Hue",
      "name": "Hue",
      "users": {
        "001788FFFExxxxxx": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "001788FFFEyyyyyy": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
      },
      "sensors": true,
      "excludeSensorTypes": ["Daylight", "CLIP", "Geofence"],
      "lights": true,
      "ct": true
    }
  ]

2.2 Configuration for Round Bridge

The example below is a typical configuration for exposing a v1 (round) bridge, or a v2 (square) bridge where the native HomeKit feature isn't used. With this configuration, homebridge-hue exposes all sensor resources, except those created by the Hue app for Home & Away routines, and all lights, using the Kelvin ColorTemperature characteristic type.

  "platforms": [
    {
      "platform": "Hue",
      "name": "Hue",
      "users": {
        "001788FFFExxxxxx": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "001788FFFEyyyyyy": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
      },
      "sensors": true,
      "excludeSensorTypes": ["CLIPPresence", "Geofence"],
      "lights": true,
      "philipsLights": true
    }
  ]

2.3 Default Configuration

For reference, the example below contains all parameters and their default values. Note that with this configuration, homebridge-hue exposes only the Hue bridge itself.

  "platforms": [
    {
      "platform": "Hue",
      "name": "Hue",
      "host": "",
      "users": {
        "001788FFFExxxxxx": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "001788FFFEyyyyyy": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
      },
      "sensors": false,
      "excludeSensorTypes": [],
      "lowBattery": 25,
      "lights": false,
      "philipsLights": false,
      "ct": false,
      "groups": false,
      "group0": false,
      "rooms": false,
      "schedules": false,
      "rules": false,
      "heartrate": 5,
      "waitTimeUpdate": 20,
      "timeout": 5,
      "parallelRequests": 10,
      "waitTimeResend": 300
    }
  ]