deconz Command‐Line Utility
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).
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
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.
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"
}
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
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)