dynamic configuration - ebaauw/homebridge-deconz GitHub Wiki

Homebridge deCONZ can be configured at run-time. For this, Homebridge deCONZ provides a configuration API. This is a REST API, that, for security reasons, is accessible only from the server running Homebridge.

Eventually, Homebridge deCONZ will use the Homebridge Plugin Custom UI Utils to provide a configuration user interface, using the configuration API. For now, Homebridge deCONZ comes with a command-line tool, ui, to interact with the configuration API.

Alternatively, you can use any REST API client, like Postman, or even curl to configure Homebridge deCONZ.

The configuration API of Homebridge deCONZ responds to local http requests to a random port. On startup, Homebridge deCONZ issues a log message with this port:

[deCONZ] ui server: listening on http://127.0.0.1:65376/

The API provides the following end points:

GatewayID is the id of the gateway, as returned by List Gateways. Homebridge deCONZ exposes this as the Serial Number of the Gateway accessory. This is the bridgeid reported by the deCONZ API. Typically, this is the Zigbee mac address of the RaspBee or Conbee.

DeviceID is the id of the device, as returned by List Gateways. For Zigbee devices, this is the Zigbee mac address, reported by the deCONZ API under uniqueid of the corresponding /lights and/or /sensors resources. For virtual devices, this is the Zigbee mac address of the RaspBee or ConBee, suffixed by the resource type and resource ID, e.g. -S1 for /sensors/1 or -G0 for /groups/0.

AccessoryID is the id of the device corresponding to the accessory, as returned by List Accessories. Homebridge deCONZ exposes this as the Serial Number of the accessory.

To interact with the configuration API, Homebridge deCONZ includes the ui command-line tool. Issue ui -h for help.

This tool reads config.json, to find your Homebridge deCONZ instances. Next, it reads cachedAccessories for each instance, to retrieve the port on which the configuration API is listening. Next, it pings the API, to make sure the Homebridge deCONZ instance is running. Finally it issues the API call, as specified by the command-line parameters, and formats the result.

In case ui fails to locate config.json, set the HOMEBRIDGE_DIR environment variable to the Homebridge user directory.

In case you have multiple instances of Homebridge deCONZ (running in separate child bridges), ui will pick the first one listed in config.json. To interact with a different instance, specify that instance's username to ui, using the -U or --username parameter.

In case a Homebridge deCONZ instance exposes multiple deCONZ gateways, ui will pick one at random (the first gateway listed in cachedAccessories). To interact with a specific gateway, specify that gateway's ID, using the -G or --gateway parameter.

ui takes the following commands:

Check whether the configuration API can be reached.

If it can be reached, the API responds with "pong".

$ curl -s http://127.0.0.1:65376/ping | json
"pong"

List the deCONZ gateways known to Homebridge deCONZ.

The API responds with a map of gateways by host. Each gateway is reported using another map, with the following info:

$ ui get /gateways
{
  "pi5": {
    "config": {
      "apiversion": "1.16.0",
      "bridgeid": "00212EFFFF03D4A7",
      "datastoreversion": "93",
      "devicename": "ConBee II",
      "factorynew": false,
      "mac": "dc:a6:32:6f:81:2c",
      "modelid": "deCONZ",
      "name": "pi5",
      "replacesbridgeid": null,
      "starterkitid": "",
      "swversion": "2.22.2"
    },
    "host": "pi5",
    "id": "00212EFFFF03D4A7"
  }
}

This is equivalent to:

$ curl -s http://127.0.0.1:65376/gateways | json

Get the details and current run-time settings of a gateway.

The API responds with a map with the following info:

Homebridge deCONZ provides the following run-time settings per deCONZ gateway:

$ ui get /
{
  "host": "pi5",
  "id": "00212EFFFF03D4A7",
  "manufacturer": "dresden elektronik",
  "model": "deCONZ / ConBee II",
  "name": "pi5",
  "settings": {
    "autoExpose": true,
    "brightnessAdjustment": 100,
    "expose": true,
    "exposeSchedules": false,
    "heartrate": 30,
    "logLevel": 1,
    "periodicEvents": true,
    "restart": false,
    "search": false,
    "unlock": false
  }
}

This is equivalent to:

$ curl -s http://127.0.0.1:65376/gateways/00212EFFFF03D4A7  | json

Update the run-time settings for a gateway.

See Get Gateway Info for the available settings. Multiple settings can be specified in the body; settings not specified are unmodified. The API responds with a map of changed settings. Invalid settings and values cause warning messages in the Homebridge log, but are otherwise ignored.

$ ui put / '{"logLevel": 1}'
{
  "logLevel": 1
}

This is equivalent to:

$ curl -s -X PUT --json '{"logLevel": 1}' http://127.0.0.1:65376/gateways/00212EFFFF03D4A7/settings  | json

Note: not all curl versions implement --json; notably the one one Raspberry Pi OS doesn't. In that case, use -d instead:

$ curl -s -X PUT -d '{"logLevel": 1}' http://127.0.0.1:65376/gateways/00212EFFFF03D4A7/settings  | json

List the supported Zigbee and virtual devices on a gateway.

The API responds with a map of devices by device ID. Each device is reported using another map, with the following info:

$ ui get /devices
{
  "001788010B1CFF75": {
    "expose": true,
    "manufacturer": "Signify Netherlands B.V.",
    "model": "LCA006",
    "name": "Hue Gamut-C",
    "resources": [
      "/lights/6"
    ],
    "type": "lights",
    "zigbee": true
  },
  "001788010BD108D7": {
    "expose": true,
    "manufacturer": "Signify Netherlands B.V.",
    "model": "SML004",
    "name": "Hue outdoor motion sensor 2022",
    "resources": [
      "/sensors/31",
      "/sensors/32",
      "/sensors/33"
    ],
    "type": "sensors",
    "zigbee": true
  },
  "00212EFFFF03D4A7-G0": {
    "expose": false,
    "manufacturer": "dresden elektronik",
    "model": "LightGroup",
    "name": "All",
    "resources": [
      "/groups/0"
    ],
    "type": "groups",
    "zigbee": false
  },
  "00212EFFFF03D4A7-S1": {
    "expose": false,
    "manufacturer": "dresden elektronik",
    "model": "Daylight",
    "name": "Daylight",
    "resources": [
      "/sensors/1"
    ],
    "type": "sensors",
    "zigbee": false
  }
}

This is equivalent to:

$ curl -s http://127.0.0.1:65376/gateways/00212EFFFF03D4A7/devices  | json

Get the details and current run-time settings of a device.

The API responds with a map with the following info:

Homebridge deCONZ provides the following run-time settings per device:

$ ui get /devices/001788010BD108D7
{
  "id": "001788010BD108D7",
  "manufacturer": "Signify Netherlands B.V.",
  "model": "SML004",
  "name": "Hue outdoor motion sensor 2022",
  "resources": [
    "/sensors/49",
    "/sensors/50",
    "/sensors/51"
  ],
  "settings": {
    "expose": true
  },
  "type": "sensors",
  "zigbee": true
}

This is equivalent to:

$ curl -s http://127.0.0.1:65376/gateways/00212EFFFF03D4A7/devices/001788010BD108D7  | json

Update the run-time settings for a device.

See Get Device Info for the available settings. Multiple settings can be specified in the body; settings not specified are unmodified. The API responds with a map of changed settings. Invalid settings and values cause warning messages in the Homebridge log, but are otherwise ignored.

$ ui put /devices/001788010BD108D7 '{"expose": true}'
{
  "expose": true
}

This is equivalent to:

$ curl -s -X PUT --json '{"expose": true}' http://127.0.0.1:65376/gateways/00212EFFFF03D4A7/devices/001788010BD108D7/settings  | json

List the accessories exposed by Homebridge deCONZ, corresponding to devices on a gateway.

The API responds with a map of accessories by accessory ID. Each accessory is reported using another map, with the following info:

$ ui get /accessories
{
  "001788010B1CFF75": {
    "manufacturer": "Signify Netherlands B.V.",
    "model": "LCA006",
    "name": "Hue Gamut-C",
    "resources": [
      "/lights/6"
    ],
    "type": "lights",
    "zigbee": true
  },
  "001788010BD108D7": {
    "manufacturer": "Signify Netherlands B.V.",
    "model": "SML004",
    "name": "Hue outdoor motion sensor 2022",
    "resources": [
      "/sensors/31",
      "/sensors/32",
      "/sensors/33"
    ],
    "type": "sensors",
    "zigbee": true
  }
}

This is equivalent to:

$ curl -s http://127.0.0.1:65376/gateways/00212EFFFF03D4A7/accessories  | json

Get the details and current run-time settings of an accessory.

The API responds with a map with the following info:

Homebridge deCONZ provides the following run-time settings per accessory:

$ ui get /accessories/001788010BD108D7
{
  "id": "001788010BD108D7",
  "manufacturer": "Signify Netherlands B.V.",
  "model": "SML004",
  "name": "Hue outdoor motion sensor 2022",
  "resources": [
    "/sensors/31",
    "/sensors/32",
    "/sensors/33"
  ],
  "settings": {
    "expose": true,
    "logLevel": 1,
    "lowBatteryThreshold": 20
  },
  "type": "sensors",
  "zigbee": true
}

This is equivalent to:

$ curl -s http://127.0.0.1:65376/gateways/00212EFFFF03D4A7/accessories/001788010BD108D7  | json

$ ui put /accessories/001788010BD108D7 '{"logLevel": 1}'
{
  "logLevel": 1
}

This is equivalent to:

$ curl -s -X PUT --json '{"logLevel": 1}' http://127.0.0.1:65376/gateways/00212EFFFF03D4A7/accessories/001788010BD108D7/settings  | json