Skip to content

Dynamic Configuration

Jump to bottom
Erik Baauw edited this page Mar 8, 2024 · 24 revisions

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.

Configuration API

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:

End Point Method Path
Ping GET /ping
List Gateways GET /gateways
Get Gateway Info GET /gateways/GatewayID
Update Gateway Settings PUT /gateways/GatewayID/settings
List Devices GET /gateways/GatewayID/devices
Get Device Info GET /gateways/GatewayID/devices/DeviceID
Update Device Settings PUT /gateways/GatewayID/devices/DeviceID/settings
List Accessories GET /gateways/GatewayID/accessories
Get Accessory Info GET /gateways/GatewayID/accessories/AccessoryID
Update Accessory Settings PUT /gateways/GatewayID/accessories/AccessoryID /settings

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.

ui Tool

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:

Command Description
ui discover Discover UI servers.
ui get resource Get dynamic settings.
ui put resource body Update dynamic settings.

Ping

Check whether the configuration API can be reached.

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

Example

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

List Gateways

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:

Key Type Description
config object The response of the deCONZ API to an unauthenticated GET of /config.
host string The hostname or hostname and port of the gateway.
id string The ID of the gateway.
Homebridge deCONZ exposes this as the Serial Number of the Gateway accessory.

Example

$ 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 Gateway Info

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

The API responds with a map with the following info:

Key Type Description
host string The hostname or hostname and port of the deCONZ gateway.
id string The ID of the gateway.
Homebridge deCONZ exposes this as the Serial Number of the Gateway accessory.
manufacturer string The manufacturer of the deCONZ gateway, i.e. dresden elektronik.
Homebridge deCONZ exposes this as the Manufacturer of the Gateway accessory.
model string The model of the gateway and coordinator device.
Homebridge deCONZ exposes this as the Model of the Gateway accessory.
name string The name of gateway.
settings object The run-time settings for the gateway.

Settings

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

Key Type Default Description
autoExpose boolean true Automatically expose new Zigbee devices, as they are added to deCONZ.
Expose all Zigbee devices when gateway is first exposed.
brightnessAdjustment integer 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.
expose boolean true Expose gateway.
When set, Homebridge deCONZ connects to the gateway, tries to obtain an API key, and, on success, exposes devices according to the autoExpose settings.
When cleared, Homebridge deCONZ un-exposes all accessories corresponding to devices on the gateway, resets the gateway and device run-time settings to their defaults, deletes the API key, and disconnects from the gateway.
heartrate integer 30 Rate, in seconds, at which Homebridge deCONZ polls the deCONZ gateway.
Between 1 and 60.
logLevel integer 2 Log level for the Gateway accessory.
See Log Messages for details.
periodicEvents boolean true Issue periodic button events on the Stateless Programmable Switch service of the Gateway accessory.
restart boolean false Tell the gateway to shutdown. Typically, it will be restarted when configured to run as service.
search boolean false Tell the gateway to search for new devices. Depending on the autoExpose settings, these might be exposed automatically.
Resets after 120 seconds.
unlock boolean false Tell the gateway to accept requests for an API key from new API clients.
Resets after 60 seconds.

Example

$ 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 Gateway Settings

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.

Example

$ 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 Devices

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:

Key Type Description
expose true Device is exposed by Homebridge deCONZ.
manufacturer string The manufacturer of the device, as reported by the deCONZ API.
model string The model of the device, as reported by the deCONZ API.
name string The name of the device, as set through the deCONZ API.
resources array A list the deCONZ API resources for the device.
type strings The type of device, how it is exposed by the deCONZ API: groups, lights, schedules, or sensors.
zigbee boolean This is a Zigbee device.

Example

$ 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 Device Info

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

The API responds with a map with the following info:

Key Type Description
id string The device ID.
manufacturer string The manufacturer of the device, as reported by the deCONZ API.
model string The model of the device, as reported by the deCONZ API.
name string The name of the device, as set through the deCONZ API.
resources array A list the deCONZ API resources for the device.
settings object The run-time settings for the device.
type strings The type of device, how it is exposed by the deCONZ API: groups, lights, schedules, or sensors.
zigbee boolean This is a Zigbee device.

Settings

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

Key Type Default Description
expose boolean Device is exposed by Homebridge deCONZ.
When set, Homebridge deCONZ creates an accessory for the device.
When cleared, Homebridge deCONZ un-exposes the corresponding accessory and resets the device run-time settings to their defaults.
The default for new devices is determined by the autoExpose gateway run-time setting.

Example

$ 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 Device Settings

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.

Example

$ 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 Accessories

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:

Key Type Description
manufacturer string The manufacturer of the device, as reported by the deCONZ API.
Homebridge deCONZ exposes this as the Manufacturer of the accessory.
model string The model of the device, as reported by the deCONZ API.
Homebridge deCONZ exposes this as the Model of the accessory.
name string The name of the device, as set through the deCONZ API.
Homebridge deCONZ exposes this as the Name of the accessory.
resources array A list the deCONZ API resources for the corresponding device.
settings object The run-time settings for the accessory.
type strings The type of the corresponding device, how it is exposed by the deCONZ API: groups, lights, schedules, or sensors.
zigbee boolean The corresponding device is a Zigbee device.

Example

$ 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 Accessory Info

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

The API responds with a map with the following info:

Key Type Description
id string The accessory ID, which is the device ID of the corresponding device.
Homebridge deCONZ exposes this as the Serial Number of the accessory.
manufacturer string The manufacturer of the device, as reported by the deCONZ API.
Homebridge deCONZ exposes this as the Manufacturer of the accessory.
model string The model of the device, as reported by the deCONZ API.
Homebridge deCONZ exposes this as the Model of the accessory.
name string The name of the device, as set through the deCONZ API.
Homebridge deCONZ exposes this as the Name of the accessory.
resources array A list the deCONZ API resources for the corresponding device.
settings object The run-time settings for the accessory.
type strings The type of the corresponding device, how it is exposed by the deCONZ API: groups, lights, schedules, or sensors.
zigbee boolean The corresponding device is a Zigbee device.

Settings

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

Key Type Default Description
anyOn boolean false For Lightbulb services corresponding to a Zigbee group, On is mapped to state/any_on instead of state/all_on.
expose boolean true Accessory is exposed by Homebridge deCONZ.
When cleared, Homebridge deCONZ un-exposes the accessory, and resets the device run-time settings to their defaults.
exposeEffects boolean true Expose dynamic effects by an additional Lightbulb service per effect.
exposeScenes boolean true Expose scenes by an additional Lightbulb service per scene.
logLevel integer Log level for the accessory, between 0 and 3.
See Log Messages for details.
The default is the logLevel setting of the Gateway accessory.
lowBatteryThreshold integer 20 The threshold for Status Low Battery Status, between 0 and 100.
For battery-powered Zigbee devices.
offset integer 0 The offset, in 0.01°C, for Temperature.
Not yet implemented.
serviceName string The name of the HomeKit service used to expose the device.
Currently, only "Light", "Outlet", "Switch", and "Valve" are supported for lights and groups resources.
venetianBlind boolean false Device is a Venetian Blind.
When set, Close Upwards is added to the Window Covering service, and the device position [100% (open), ..., 50%, ... 0% (closed)] is mapped to [0% (closed down), ..., 100% (open), ..., 0% (closed up)]
wallSwitch boolean false Device is a mains-powered device behind a traditional wall switch, which cuts the power to the device.
When set, On is reported as false, while the gateway reports the device as unreachable.
Note that it is not recommended to cut power to Zigbee devices. It might take a considerable time after cutting power, before the gateway marks the device as unreachable. The gateway might report the device as unreachable even when it is powered.

Example

$ 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

Update Accessory Settings

Example

$ 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
Clone this wiki locally