Resource Links

Introduction

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

As the name suggests, a resource link contains a list of links to other resources. The Hue bridge doesn'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.
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 HomeKit Position 100% (open); values 0 and 100 are mapped to 0% (closed). An additional Close Upwards characteristic indicates whether the blind is tilted up (lift < 50) or down (lift > 50). Multiple venetianblind resource links can be used.
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.

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

• 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"
}