deconz Command‐Line Utility - ebaauw/homebridge-deconz GitHub Wiki

Homebridge deCONZ includes the deconz command-line utility to interact with deCONZ API from the command line. It's used for troubleshooting or for advanced configuration (e.g. creating rules or resource links on the gateway). It can be included in shell scripts, as a backup to re-create your gateway configuration (see e.g. ph.sh).

Initial Setup

When Homebridge deCONZ was installed through the Homebridge UI, or through sudo npm -g i homebridge-deconz, npm should have installed deconz. If not, you might need to run npx deconz.

By default, deconz tries to connect to the deCONZ gateway running at port 80 of the local host. If you're not running deCONZ locally, deconz will report an error, and you'll need to specify to deconz where to find the gateway.

$ deconz config
deconz: localhost: request 1: GET /config
deconz: warning: localhost: request 1: connect ECONNREFUSED 127.0.0.1:80
deconz: fatal: localhost: deCONZ gateway not found

Locating a Remote Gateway.

To find the IP addresses (and ports) of the gateway(s) on your local network, use deconz discover:

$ deconz discover
{
  "192.x.x.103": {
    "apiversion": "1.16.0",
    "bridgeid": "00212EFFFF061EE9",
    "datastoreversion": "93",
    "devicename": "RaspBee II",
    "factorynew": false,
    "mac": "dc:a6:32:4b:e1:1e",
    "modelid": "deCONZ",
    "name": "pi3",
    "replacesbridgeid": null,
    "starterkitid": "",
    "swversion": "2.17.1"
  },
  "192.x.x105": {
    "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.17.1"
  }
}

In the above example, it finds two deCONZ gateways: at 192.x.x.103 and at 192.x.x.105. Both are running at (default) port 80.

Specifying a Remote Gateway

Now, we can specify the location of the server using the -H option:

$ deconz -H 192.x.x.105 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.17.1"
}

Note that config does an unauthenticated request to get the basic configuration of the gateway. This info is also returned by deconz discover, checking that the discovered gateway is indeed reachable.

Alternatively, you can set the DECONZ_HOST environment variable, so you don't have to specify -H with each call:

$ export DECONZ_HOST=192.x.x.105
$ deconz 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.17.1"
}

Obtaining an API key

To do anything useful, you need to obtain an API key (sometimes called username) from the gateway. Note that deconz uses its own API keys, independent from those used by Homebridge deCONZ. To request a new API key, run deconz getApiKey:

$ deconz getApiKey
deconz getApiKey: request 1: POST / {"devicetype":"deconz#macmini"}
deconz getApiKey: error: request 1: api error 101: link button not pressed

That didn't work. Since deconz is running from another host, the gateway wants confirmation that it's OK to give out a new API key. This is done through Phoscon: in the Advanced tab under the Gateway Settings, press Authenticate app. Do so, and issue another deconz getApiKey:

$ deconz getApiKey
"9BB041006D"

deconz returns the created API key. It also stores the API key in ~/.deconz, so you don't have to specify it for further requests

Help

Run deconz -h to see the commands and options deconz supports:

$ deconz -h
Command line interface to deCONZ gateway.

Usage: deconz [-hVDp] [-H hostname[:port]] [-K api key] [-t timeout] command [argument ...]

Parameters:
  -h, --help
  Print this help and exit.

  -V, --version
  Print version and exit.

  -D, --debug
  Print debug messages for communication with the gateway.

  -p, --phoscon
  Imitate the Phoscon app.

  -H hostname[:port], --host=hostname[:port]
  Connect to hostname:80 or hostname:port instead of the default localhost:80.
  The hostname and port can also be specified by setting DECONZ_HOST.

  -K API key, --apiKey=API key
  Use API key instead of the API key saved in ~/.deconz.
  The API key can also be specified by setting DECONZ_API_KEY.

  -t timeout, --timeout=timeout
  Set timeout to timeout seconds instead of default 5.

Commands:
  get [-hsnjuatlkv] [path]
  Retrieve path from gateway.

  put [-hv] resource [body]
  Update resource on gateway with body.

  post [-hv] resource [body]
  Create resource on gateway with body.

  delete [-hv] resource [body]
  Delete resource from gateway with body.

  eventlog [-hnrs]
  Log web socket notifications by the gateway.

  discover [-hS]
  Discover gateways.

  config [-hs]
  Retrieve gateway configuration (unauthenticated).

  description [-hs]
  Retrieve gateway description.

  getApiKey [-hv]
  Obtain an API key for the gateway.

  unlock [-hv]
  Unlock the gateway so new clients can obtain an API key.

  search [-hv]
  Initiate a seach for new devices.

  probe [-hv] [-t timeout] light
  Probe light for supported colour (temperature) range.

  restart [-hv]
  Restart the gateway.

For more help, issue: deconz command -h

See https://github.com/ebaauw/homebridge-deconz for more info.
(homebridge-deconz v0.0.17, node v16.16.0)

To see the options for a particular command, run deconz command -h, e.g:

$ deconz get -h
Command line interface to deCONZ gateway.

Usage: deconz get [-hsnjuatlkv] [path]

Retrieve path from gateway.

Parameters:
  -h, --help
  Print this help and exit.

  -s, --sortKeys
  Sort object key/value pairs alphabetically on key.

  -n, -noWhiteSpace
  Do not include spaces nor newlines in the output.

  -j, --jsonArray
  Output a JSON array of objects for each key/value pair.
  Each object contains two key/value pairs: key "keys" with an array
  of keys as value and key "value" with the value as value.

  -u, --joinKeys
  Output JSON array of objects for each key/value pair.
  Each object contains one key/value pair: the path (concatenated
  keys separated by '/') as key and the value as value.

  -a, --ascii
  Output path:value in plain text instead of JSON.

  -t, --topOnly
  Limit output to top-level key/values.

  -l, --leavesOnly
  Limit output to leaf (non-array, non-object) key/values.

  -k, --keysOnly
  Limit output to keys. With -u, output a JSON array of paths.

  -v, --valuesOnly
  Limit output to values. With -u, output a JSON array of values.

  path
  Path to retrieve from the gateway.

See https://github.com/ebaauw/homebridge-deconz for more info.
(homebridge-deconz v0.0.17, node v16.16.0)