Resource Links

Introduction

A resource link is a type of resource on the Hue bridge or deCONZ gateway. Resource links are maintained using the Hue API or the deCONZ API, through the /resourcelinks endpoint.

As the name suggests, a resource link contains a list of links to other resources. The Hue bridge and deCONZ gateway don't do anything with resource links, but API clients can use these to keep track of what resources belong together, interact with each other. For instance, the Hue app will create a resource link per formula, referring to all the CLIP sensors, rules, groups, scenes, etc., created for that formula.

Use of Resource Links

Homebridge Hue uses resource links for advanced configuration, i.e. configuration per individual resource, rather than per resource type. The configuration per resource type is done in config.json, see Configuration.

Homebridge Hue uses resource links to:

• To specify which resources to expose (blacklist, whitelist);
• To specify how to expose a resource (outlet, switch, valve, venetianblind);
• To combine multiple resources into a single accessory (multiclip, multilight);
• To split multiple resource for the same device into different accessories (splitlight);
• To change the handling of unreachable lights (wallswitch).

Supported Resource Links

Homebridge Hue recognises resource links with a name of "homebridge-hue" and a description specifying the type, see Resource Link Types below. By default, Homebridge Hue recognises resource links from any owner. This means that resource links are shared between all instances of Homebridge Hue connecting to the bridge/gateway, unlike the config.json settings.

To use different resource links for different Homebridge Hue instances, set ownResourcelinks in config.json. With this setting, Homebridge Hue only processes resource links owned by the username used by Homebridge Hue to connect to the bridge/gateway.

Resource Link Types

Homebridge Hue recognises the following types of resource links:

Type	Resources	Description
blacklist	/lights /groups /scenes /sensors /schedules /rules	Blacklist of resources not to expose. Takes precedence over config.json settings. Multiple blacklist resource links can be used; Homebridge Hue combines these into a single blacklist. Note that deCONZ doesn't support /scenes resources.
lightlist	/lights	Workaround for deCONZ issue #2473. Homebridge Hue will delay the startup of Homebridge, until all linked /lights resources are exposed by the API. Multiple lightlist resource links can be used; Homebridge Hue combines these into a single list.
multiclip	/sensors	CLIP sensors to combine into a single accessory. The HomeKit services for the linked CLIP /sensors resources are exposed under a single HomeKit accessory, to mitigate the HomeKit limit of 149 bridged accessories per HomeKit bridge (i.c. Homebridge), or to mimic a physical sensor with multiple resources. Multiple multiclip resource links can be used, each specifying a different accessory.
multilight	/lights	Lights to combine into a single accessory. The HomeKit services for the linked /lights resources are exposed under a single HomeKit accessory, to mitigate the HomeKit limit of 149 bridged accessories per HomeKit bridge (i.c. Homebridge), or to expose a luminary with multiple lightbulbs or spots as single accessory. Multiple multilight resource links can be used, each specifying a different accessory.
outlet	/lights /groups	Groups and lights to expose using an Outlet service instead of Lightbulb. Multiple outlet resource links can be used.
splitlight	/lights	Lights to expose as separate accessory. For wired in-wall switches with multiple gangs controlling lights in different rooms. Multiple splitlight resource links can be used.
switch	/lights	Groups and lights to expose using a Switch service instead of Lightbulb. Multiple switch resource links can be used.
valve	/lights	Lights to expose using a Valve service instead of Lightbulb. Multiple valve resource links can be used.
venetianblind	/lights	Window covering devices to expose as Venetian blinds. For Venetian blinds, lift value 50 is mapped to Position 0 (open), lift values 0 and 100 are mapped to Position 100 (closed). An additional Close Upwards characteristic indicates whether the blind is tilted up (lift < 50) or down (lift > 50).
wallswitch	/lights	Not Recommended Lights that are controlled using a 20th century wall switch. Homebridge Hue will mark the light as off, when the Hue bridge or deCONZ gateway reports it as unreachable. Multiple wallswitch resource links can be used; Homebridge Hue combines these into a single list.
whitelist	/lights /groups /scenes /sensors /schedules /rules	Whitelist of resources to expose. Takes precedence over blacklist resource links and config.json settings. Multiple whitelist resource links can be used; Homebridge Hue combines these into a single whitelist. Note that deCONZ doesn't support /scenes resources. Note that GroupScene scenes are exposed under the associated group and LightScene and v1 scenes under group 0, so make sure the group is exposed.

Maintaining Resource Links

As mentioned in the Introduction, resource links are maintained through the API.

• To get an overview of all resourcelinks, do a GET of /resourcelinks;

• To get a single resourcelink, do a GET of /resourcelinks/id;

• To create a resource link, do a POST to /resourcelinks. If you use the ownResourcelinks setting, make sure to use the Homebridge Hue username when creating the resource link, using ph -u username post /resourcelinks '{body}'.

• To update the linked resources, do a PUT to the /resourcelinks/id resource. Note that you need to specify all resources under links when updating the resource link. You cannot add or remove a single entry from links;

• To delete a resource link, do a DELETE of /resourcelinks/id.

Note that the deCONZ API documentation fails to mention resource links, but they work just like the Hue API.
Note that, unlike the Hue bridge, the deCONZ gateway doesn't update resource links automatically, when a linked resource is deleted.

The ph command-line utility supports maintaining some of the resource links, issue ph -h for details:

• ph lightlist creates or updates a lightest resource link, linking all /lights resources currently exposed;
• ph outlet creates or updates an initial outlet resource link, linking all /lights resource with a type that includes plug.
• ph switch creates or updates a switch resource link, linking all /lights resources with a type that includes on/off.

Note that type is populated from the Zigbee device type, and not all devices identify themselves correctly. You might want to review and update the outlet and switch resource links manually.

If you use the ownResourcelinks setting, make sure to use the Homebridge Hue username when creating the resource link, e.g. ph -u username lightlist.

Examples

Outlet

To create an initial outlet resourcelink:

$ ph outlet -v
ph outlet: /resourcelinks/6: 0 outlets
$ ph get /resourcelinks/6
{
  "classid": 1,
  "description": "outlet",
  "links": [],
  "name": "homebridge-hue",
  "owner": "**********",
  "recycle": false,
  "type": "Link"
}

That didn't list the siren on my Smoke Detector, so let's add that manually:

$ ph put /resourcelinks/6 '{
  "links": [
    "/lights/3"
  ]
}'
{
  "links": [
    "/lights/3"
  ]
}
$ ph get /resourcelinks/6
{
  "classid": 1,
  "description": "outlet",
  "links": [
    "/lights/3"
  ],
  "name": "homebridge-hue",
  "owner": "**********",
  "recycle": false,
  "type": "Link"
}

Note that you need to specify all resources under links when updating the resource link. You cannot add or remove a single entry from links.

Whitelist and Blacklist

If you have a chandelier with three bulbs, you might want to expose this as a group instead of as three individual lights, by creating the following resourcelinks:

$ ph post /resourcelinks '{
  "name": "homebridge-hue",
  "classid": 1,
  "description": "whitelist",
  "links": [
    "/groups/1"
  ],
  "recycle": false
}'
"3"
$ ph get /resourcelinks/3
{
  "classid": 1,
  "description": "whitelist",
  "links": [
    "/groups/1"
  ],
  "name": "homebridge-hue",
  "owner": "**********",
  "recycle": false,
  "type": "Link"
}
$ ph post /resourcelinks '{
  "name": "homebridge-hue",
  "classid": 1,
  "description": "blacklist",
  "links": [
    "/lights/1",
    "/lights/2",
    "/lights/3"
  ],
  "recycle": false
}'
"4"
$ ph get /resourcelinks/4
{
  "classid": 1,
  "description": "blacklist",
  "links": [
    "/lights/1",
    "/lights/2",
    "/lights/3"
  ],
  "name": "homebridge-hue",
  "owner": "**********",
  "recycle": false,
  "type": "Link"
}

Light List

To create a light list:

$ ph lightlist -v
ph lightlist: /resourcelinks/1: 2 lights
$ ph get /resourcelinks/1
{
  "classid": 1,
  "description": "lightlist",
  "links": [
    "/lights/1",
    "/lights/3"
  ],
  "name": "homebridge-hue",
  "owner": "**********",
  "recycle": false,
  "type": "Link"
}