Skip to content

Resourcelinks

Jump to bottom
Erik Baauw edited this page Sep 4, 2024 · 11 revisions

Introduction

A resource link is a type of resource on the deCONZ gateway. Resource links are maintained using the deCONZ REST API, through the /resourcelinks endpoint (which, unfortunately is still missing from the documentation).

As the name suggests, a resource link contains a list of links to other resources. The deCONZ gateway 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.

Use of Resource Links

Homebridge deCONZ uses resource links for advanced configuration, i.e. configuration per individual resource of a device, rather than per device. The configuration per device is done through Dynamic Configuration. Resource links take precedence over dynamic configuration, changing the way dynamic configuration sees the devices exposed by deCONZ.

Homebridge deCONZ uses resource links to:

  • To specify which resources not to expose (blacklist);
  • To split off certain resources for a device into a different accessory (splitdevice).

Supported Resource Links

Homebridge deCONZ recognises resource links with a name of "homebridge-deconz" and a description specifying the type, see Resource Link Types below. Homebridge deCONZ recognises resource links from any owner. This means that resource links are shared between all instances of Homebridge deCONZ connecting to the bridge/gateway, unlike the dynamic configuration.

Resource Link Types

Homebridge Hue recognises the following types of resource links:

Type Resources Description
blacklist /lights
/sensors
 Blacklist of resources not to expose.
Multiple blacklist resource links can be used; Homebridge deCONZ combines these into a single blacklist.
splitdevice /lights
/sensors 		Resources to expose as separate accessory.
For wired in-wall switches with multiple gangs controlling lights in different rooms, or for multi-zone presence sensors with zones in different rooms.
Multiple splitdevice resource links can be used.

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.
  • 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.

Examples

For this example, I'll be using a MZCozy ZG-005-RF relay with four outputs, which deCONZ exposes as four /lights resources:

$ deconz get /lights
{
  "8": {
    "config": {
      "groups": [],
      "on": {
        "startup": "previous"
      }
    },
    "etag": "cd0767cf690ba47ef5732ea697af3c08",
    "hascolor": false,
    "lastannounced": null,
    "lastseen": "2024-09-04T08:06Z",
    "manufacturername": "_TZ3000_u3oupgdy",
    "modelid": "TS0004",
    "name": "MHCozy",
    "productid": "ZG-005-RF",
    "state": {
      "on": false,
      "reachable": false
    },
    "swversion": "1.1.0",
    "type": "On/Off output",
    "uniqueid": "a4:c1:38:22:67:96:ec:15-01"
  },
  "20": {
    "config": {
      "groups": [],
      "on": {
        "startup": "previous"
      }
    },
    "etag": "b82428f8098e810f314351f736e1ebca",
    "hascolor": false,
    "lastannounced": null,
    "lastseen": "2024-09-04T08:06Z",
    "manufacturername": "_TZ3000_u3oupgdy",
    "modelid": "TS0004",
    "name": "MHCozy",
    "productid": "ZG-005-RF",
    "state": {
      "on": false,
      "reachable": false
    },
    "swversion": "1.1.0",
    "type": "On/Off output",
    "uniqueid": "a4:c1:38:22:67:96:ec:15-02"
  },
  "21": {
    "config": {
      "groups": [],
      "on": {
        "startup": "previous"
      }
    },
    "etag": "b82428f8098e810f314351f736e1ebca",
    "hascolor": false,
    "lastannounced": null,
    "lastseen": "2024-09-04T08:06Z",
    "manufacturername": "_TZ3000_u3oupgdy",
    "modelid": "TS0004",
    "name": "MHCozy",
    "productid": "ZG-005-RF",
    "state": {
      "on": false,
      "reachable": false
    },
    "swversion": "1.1.0",
    "type": "On/Off output",
    "uniqueid": "a4:c1:38:22:67:96:ec:15-03"
  },
  "22": {
    "config": {
      "groups": [],
      "on": {
        "startup": "previous"
      }
    },
    "etag": "b82428f8098e810f314351f736e1ebca",
    "hascolor": false,
    "lastannounced": null,
    "lastseen": "2024-09-04T08:06Z",
    "manufacturername": "_TZ3000_u3oupgdy",
    "modelid": "TS0004",
    "name": "MHCozy",
    "productid": "ZG-005-RF",
    "state": {
      "on": false,
      "reachable": false
    },
    "swversion": "1.1.0",
    "type": "On/Off output",
    "uniqueid": "a4:c1:38:22:67:96:ec:15-04"
  }
}

Normally Homebridge deCONZ sees this as a single device.

$ ui get /devices/a4:c1:38:22:67:96:ec:15
{
  "id": "A4C138226796EC15",
  "manufacturer": "_TZ3000_u3oupgdy",
  "model": "TS0004",
  "name": "MHCozy",
  "resources": [
    "/lights/8",
    "/lights/20",
    "/lights/21",
    "/lights/22"
  ],
  "settings": {
    "expose": true
  },
  "type": "lights",
  "zigbee": true
}

This device is exposed to HomeKit as a single accessory with four Outlet services:

$ ui get /accessories/a4:c1:38:22:67:96:ec:15
{
  "id": "A4C138226796EC15",
  "manufacturer": "_TZ3000_u3oupgdy",
  "model": "TS0004",
  "name": "MHCozy",
  "resources": [
    "/lights/8",
    "/lights/20",
    "/lights/21",
    "/lights/22"
  ],
  "settings": {
    "expose": true,
    "logLevel": 1,
    "serviceName": "Outlet",
    "wallSwitch": false
  },
  "type": "lights",
  "zigbee": true
}

Blacklist

Suppose I'm only using the first two outputs of the MHCozy. Consequently, I want to suppress the Outlet services for the unused outputs. To do this, let's create the following resourcelink:

$ deconz post /resourcelinks '{
  "name": "homebridge-deconz",
  "classid": 1,
  "description": "blacklist",
  "links": [
    "/lights/21",
    "/lights/22"
  ],
  "recycle": false
}'
"2"
$ deconz get /resourcelinks/2
{
  "classid": 1,
  "description": "blacklist",
  "links": [
    "/lights/21",
    "/lights/22"
  ],
  "name": "homebridge-deconz",
  "owner": "0FF58F7C06",
  "recycle": false,
  "type": "Link"
}

After this, Homebridge deCONZ simply ignores the two resources, seeing a device with only two resources.

$ ui get /devices/a4:c1:38:22:67:96:ec:15
{
  "id": "A4C138226796EC15",
  "manufacturer": "_TZ3000_u3oupgdy",
  "model": "TS0004",
  "name": "MHCozy",
  "resources": [
    "/lights/8",
    "/lights/20"
  ],
  "settings": {
    "expose": true
  },
  "type": "lights",
  "zigbee": true
}

This device is exposed as a single accessory, now with only two Outlet services:

$ ui get /accessories/a4:c1:38:22:67:96:ec:15
{
  "id": "A4C138226796EC15",
  "manufacturer": "_TZ3000_u3oupgdy",
  "model": "TS0004",
  "name": "MHCozy",
  "resources": [
    "/lights/8",
    "/lights/20"
  ],
  "settings": {
    "expose": true,
    "logLevel": 1,
    "serviceName": "Outlet",
    "wallSwitch": false
  },
  "type": "lights",
  "zigbee": true
}

Split Device

Now suppose the first two outputs are wired to dumb lights, but these lights are in different rooms. Because HomeKit sees only a single accessory, both Outlet services are in one and the same room. To change this, let's split off the resource corresponding to the second output, using a splitdevice resource link:

$ deconz post /resourcelinks '{
  "name": "homebridge-deconz",
  "classid": 1,
  "description": "splitdevice",
  "links": [
    "/lights/20"
  ],
  "recycle": false
}'
"4"
$ deconz get /resourcelinks/4
{
  "classid": 1,
  "description": "splitdevice",
  "links": [
    "/lights/20"
  ],
  "name": "homebridge-deconz",
  "owner": "0FF58F7C06",
  "recycle": false,
  "type": "Link"
}

Now, Homebridge deCONZ sees two devices, each with one resource.

$ ui get /devices/a4:c1:38:22:67:96:ec:15
{
  "id": "A4C138226796EC15",
  "manufacturer": "_TZ3000_u3oupgdy",
  "model": "TS0004",
  "name": "MHCozy",
  "resources": [
    "/lights/8"
  ],
  "settings": {
    "expose": true
  },
  "type": "lights",
  "zigbee": true
}
$ ui get /devices/a4:c1:38:22:67:96:ec:15-02
{
  "id": "A4C138226796EC15-02",
  "manufacturer": "_TZ3000_u3oupgdy",
  "model": "TS0004",
  "name": "MHCozy",
  "resources": [
    "/lights/20"
  ],
  "settings": {
    "expose": true
  },
  "type": "lights",
  "zigbee": true
}

Note that the ID of the device corresponding to the split off resource.

Both devices are exposed as separate HomeKit accessories:

$ ui get /accessories/a4:c1:38:22:67:96:ec:15
{
  "id": "A4C138226796EC15",
  "manufacturer": "_TZ3000_u3oupgdy",
  "model": "TS0004",
  "name": "MHCozy",
  "resources": [
    "/lights/8"
  ],
  "settings": {
    "expose": true,
    "logLevel": 1,
    "serviceName": "Outlet",
    "wallSwitch": false
  },
  "type": "lights",
  "zigbee": true
}
$ ui get /accessories/a4:c1:38:22:67:96:ec:15-02
{
  "id": "A4C138226796EC15-02",
  "manufacturer": "_TZ3000_u3oupgdy",
  "model": "TS0004",
  "name": "MHCozy",
  "resources": [
    "/lights/20"
  ],
  "settings": {
    "expose": true,
    "logLevel": 1,
    "serviceName": "Outlet",
    "wallSwitch": false
  },
  "type": "lights",
  "zigbee": true
}
Clone this wiki locally