Skip to content

ph Tutorial

Erik Baauw edited this page May 26, 2021 · 6 revisions

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

Initial Setup

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

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

$ ph config
ph: localhost: request 1: GET /config
ph: warning: localhost: request 1: 127.0.0.1:80: cannot connect: ECONNREFUSED
ph: error: localhost: not a Hue bridge nor deCONZ gateway

Locating a Remote Bridge or Gateway.

To find the IP addresses (and ports) of the bridges and/or gateways on your local network, use ph discover:

$ ph discover
{
  "192.x.x.10": {
    "apiversion": "1.44.0",
    "bridgeid": "ECB5FAFFFE0A55DA",
    "datastoreversion": "103",
    "factorynew": false,
    "mac": "ec:b5:fa:0a:55:da",
    "modelid": "BSB002",
    "name": "hue-3",
    "replacesbridgeid": null,
    "starterkitid": "",
    "swversion": "1945091050"
  },
  "192.x.x.101": {
    "apiversion": "1.16.0",
    "bridgeid": "00212EFFFF05BBDB",
    "datastoreversion": "93",
    "devicename": "RaspBee II",
    "factorynew": false,
    "mac": "dc:a6:32:e0:1a:6a",
    "modelid": "deCONZ",
    "name": "pi1",
    "replacesbridgeid": null,
    "starterkitid": "",
    "swversion": "2.11.5"
  }
}

In the above example, it finds Hue bridge at 192.x.x.10 and a deCONZ gateway at 192.x.x.101. Both are running at (default) port 80.

Specifying a Remote Bridge or Gateway

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

$ ph -H 192.x.x.101 config
{
  "apiversion": "1.16.0",
  "bridgeid": "00212EFFFF05BBDB",
  "datastoreversion": "93",
  "devicename": "RaspBee II",
  "factorynew": false,
  "mac": "dc:a6:32:e0:1a:6a",
  "modelid": "deCONZ",
  "name": "pi1",
  "replacesbridgeid": null,
  "starterkitid": "",
  "swversion": "2.11.5"
}

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

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

$ export PH_HOST=192.x.x.101
$ ph config
{
  "apiversion": "1.16.0",
  "bridgeid": "00212EFFFF05BBDB",
  "datastoreversion": "93",
  "devicename": "RaspBee II",
  "factorynew": false,
  "mac": "dc:a6:32:e0:1a:6a",
  "modelid": "deCONZ",
  "name": "pi1",
  "replacesbridgeid": null,
  "starterkitid": "",
  "swversion": "2.11.5"
}

Obtaining an API key

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

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

That didn't work, as the API server wants confirmation that it's OK to give out a new API key. For the Hue bridge, this is done by pressing the link button on the Hue bridge. For deCONZ, this is done through Phoscon. In the Advanced tab under the Gateway Settings, press _Authenticate app. Do so, and issue another ph createuser:

$ ph createuser
"9BB041006D"

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

Help

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

$ ph -h
Command line interface to Philips Hue or deCONZ API.

Usage: ph [-hVDp] [-H hostname[:port]] [-u username] [-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 Hue bridge / deCONZ gateway.

  -p, --phoscon
  Imitate the Phoscon app.  Only works for deCONZ.

  -H hostname[:port], --host=hostname[:port]
  Connect to hostname:80 or hostname:port instead of the default localhost:80.

  -u username, --username=username
  Use username instead of the username saved in ~/.ph.

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

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

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

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

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

  discover [-hv] [-t timeout]
  Discover bridges/gateways.

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

  description [-hs]
  Retrieve bridge/gateway description.

  createuser [-hv]
  Create bridge/gateway API username.

  unlock [-hv]
  Unlock bridge/gateway so new API username can be created.

  touchlink [-hv]
  Initiate a touchlink.

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

  lightlist [-hv]
  Create/update lightlist resourcelink.

  outlet [-hv]
  Create/update outlet resourcelink.

  switch [-hv]
  Create/update switch resourcelink.

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

  restart [-hv]
  Restart Hue bridge or deCONZ gateway.

For more help, issue: ph command -h

See https://github.com/ebaauw/homebridge-hue for more info.
(homebridge-hue v0.13.11, node v14.17.0)

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

$ ph get -h
Command line interface to Philips Hue or deCONZ API.

Usage: ph get [-hsnjuatlkv] [path]

Retrieve path from bridge/gateway.

Parameters:
  -h          Print this help and exit.
  -s          Sort object key/value pairs alphabetically on key.
  -n          Do not include spaces nor newlines in output.
  -j          Output 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          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          Output path:value in plain text instead of JSON.
  -t          Limit output to top-level key/values.
  -l          Limit output to leaf (non-array, non-object) key/values.
  -k          Limit output to keys. With -u output JSON array of paths.
  -v          Limit output to values. With -u output JSON array of values.
  path        Path to retrieve from the Hue bridge / deCONZ gateway.

See https://github.com/ebaauw/homebridge-hue for more info.
(homebridge-hue v0.13.11, node v14.17.0)
Clone this wiki locally