Configuration

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

Note that these parameters allow configuration of Homebridge Hue at the level of resource type. For advanced configuration, per individual resource, Homebridge Hue makes use of resource links.

1. Overview

Key	Default	Description
anyOn	true	Expose a group's state.any_on as a separate (custom) AnyOn characteristic. In this case, the On characteristic maps to state.all_on. Set to false to suppress AnyOn and map On to state.any_on.
brightnessAdjustment	100	For adaptive lighting: the adjustment factor to apply to a light's brightness, before computing the colour temperature. Must be between 10% and 100%. For instance, with a factor of 50% and a brightness of 80%, the colour temperature for 40% brightness will be used.
configuredName	false	Expose a Configured Name characteristic on services for /lights and /sensors resources. Do not set this on new installations of Homebridge Hue. Only set this when you've upgraded from any version between v0.12.2 and v0.12.12, and are no longer able to change the service name in HomeKit. See #861.
effects	true	Expose additional Switch services to activate special effects of Tint by Mueller Light bulbs and LIDL Xmas light strip, and additional Lightbulb services for the effect colours of the LIDL Xmas light strip.
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"].
forceEveWeather	false	Expose temperature/humidity sensors like an Eve Weather, by exposing a dummy pressure sensor.
forceHttp	false	Connect to the v2 (square) Hue bridge (and to the NPM registry) over plain http instead of over https.
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 rate, in seconds, at which 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.
hosts	[]	An array of hostnames or IP addresses (optionally with ports) of the Hue bridges/deCONZ gateways. When non-empty, discovery of bridges is disabled. To specify a single hostname or IP address, use an array with a single string entry, e.g. "hosts": ["127.0.0.1"]. To specify multiple hostnames and/or IP addresses, separate the entries by commas, e.g. "hosts": ["192.168.1.10", "192.168.1.11"] or "hosts": ["192.168.1.10", "192.168.1.11:8080"].
hueDimmerRepeat	false	Flag whether to enable repeat mode for the Hue dimmer switch (Dim Up and Dim Down buttons) and for the Hue smart button. When enabled, while the button is pressed, homebridge-hue continuously fires Single Press events, instead of a single Long Press event.
hueMotionTemperatureHistory	false	Flag whether to expose the ZLLTemperature/ZHATemperature sensor resource for the Hue motion sensor as a separate HomeKit accessory, to enable temperature history in Eve, next to the motion history. nativeHomeKitSensors needs to be false for the history to work.
homebridgeDeconz		The ID of the migration resource link maintained by Homebridge deCONZ. When set, Homebridge Hue blacklists the resources exposed by Homebridge deCONZ.
homebridgeHue2		The ID of the migration resource link maintained by Homebridge Hue2. When set, Homebridge Hue blacklists resources exposed by Homebridge Hue2.
lights	false	Flag whether to expose Hue bridge lights to HomeKit.
linkButton		Flag whether to expose the link button on the Hue bridge. By default, the link button is exposed for the gen-1 (round) Hue bridge, and for the gen-2 (square) Hue bridge with old firmware (API version < 1.31.0).
lowBattery	25	The battery level threshold for Status Low Battery.
name		The prefix homebridge uses for log (debug, error) messages issued by homebridge-hue. Highly recommended to set this to "Hue".
nativeHomeKitLights	true	Indicates that you use the native HomeKit feature of the v2 (square) Hue bridge to expose lights. With this setting, homebridge-hue does not expose Philips Hue lights, connected to a v2 (square) Hue bridge.
nativeHomeKitSensors	true	Indicates that you use the native HomeKit feature of the v2 (square) Hue bridge to expose sensors. With this setting, homebridge-hue doesn’t expose Philips Hue motion sensors, dimmer switches, and tab switches, connected to a v2 (square) Hue bridge.
noDeconz	false	Do not discover deCONZ gateways.
noResponse	false	Report unreachable lights as No Response in HomeKit.
ownResourceLinks	false	Only consider resourcelinks created by the API key (username) used by Homebridge Hue itself.
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".
resetTimeout	500	The time, in milliseconds, after which pulse-like controls (e.g. for recalling a scene) reset.
resource	true	Flag whether to expose Resource characteristic. Set to false, to reduce the memory footprint of the accessories exposed by homebridge-hue.
rooms	false	Flag whether to include Room groups when groups are exposed.
rules	false	Flag whether to expose Hue bridge rules to HomeKit.
scenes	false	Flag whether to expose Hue bridge scenes to HomeKit. Note that GroupScene scenes are exposed under their corresponding group, and LightScene and v1 scenes under group 0, so make sure the group is exposed.
scenesAsSwitch	false	Flag whether to expose scenes as standard Switch services, so they'll be visible in Apple's Home app. Note that with this setting, Siri will activate all scenes when you turn on the room.
schedules	false	Flag whether to expose Hue bridge schedules to HomeKit.
sensors	false	Flag whether to expose Hue bridge sensors to HomeKit.
stealth	false	Stealth mode: don't make any calls to the Internet. Don't contact the MeetHue nor Phoscon portals; only use local discovery. Don't check for the latest version with the NPM registry.
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 (in uppercase) and the value holds the bridge username (case sensitive), effectively a security token to access the bridge. When connecting to a new bridge, homebridge-hue will create the username, and prompt to edit config.json.
waitTimePut	50	The time, in milliseconds, to wait after sending a PUT request to a light, before sending the next PUT request.
waitTimePutGroup	1000	The time, in milliseconds, to wait after sending a PUT request to a group, before sending the next PUT request.
waitTimeResend	300	The time, in milliseconds, to wait before resending a request after an ECONNRESET error. Must be between 100 and 1000.
waitTimeUpdate	20	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.
wallSwitch	false	Flag whether you use traditional wall switches to power off your lights. When set, attempt to match the wall switch actions and report a light's Power State as Off, while its state.reachable attribute is false. Note however, that the state.reachable attribute does not reflect accurately whether a light is currently reachable, let alone whether it's currently connected to power. Also note that, when exposing (Philips) lights to HomeKit, the v2 (square) Hue bridge behaves like the homebridge-hue default. You might not want to set wallSwitch when using the Hue bridge to expose lights to HomeKit.

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 non-Philips lights.

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

2.2 Configuration for Round Bridge

The example below is a typical configuration for exposing a v1 (round) bridge or deCONZ gateway. With this configuration, homebridge-hue exposes all light and sensor resources, except those created by the Hue app for Home & Away routines, and all lights.

  "platforms": [
    {
      "platform": "Hue",
      "users": {
        "001788FFFExxxxxx": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "001788FFFEyyyyyy": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
      },
      "sensors": true,
      "nativeHomeKitSensors": false,
      "excludeSensorTypes": ["CLIPPresence", "Geofence"],
      "lights": true,
      "nativeHomeKitLights": false,
      "wallSwitch": true
    }
  ]

To expose all lights and sensors on a v2 Hue bridge, add "nativeHomeKit": false

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",
      "hosts": [],
      "users": {
        "001788FFFExxxxxx": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "001788FFFEyyyyyy": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
      },
      "sensors": false,
      "nativeHomeKitSensors": true,
      "excludeSensorTypes": [],
      "lowBattery": 25,
      "lights": false,
      "nativeHomeKitLights": true,
      "brightnessAdjustment": 100,
      "wallSwitch": false,
      "groups": false,
      "group0": false,
      "rooms": false,
      "schedules": false,
      "rules": false,
      "heartrate": 5,
      "timeout": 5,
      "resource": true,
      "parallelRequests": 10,
      "waitTimeResend": 300,
      "waitTimeUpdate": 20
    }
  ]