ph Tutorial

Homebridge Hue includes the ph command-line utility to interact with the Hue API from the command line. It's used for troubleshooting or for advanced configuration (e.g. creating rules or resource links on the bridge). It can be included in shell scripts, as a backup to re-create your bridge 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.

You'll need to specify to ph where to find the bridge.

Locating a Remote Bridge or Gateway.

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

$ ph discover
{
  "192.x.x.10": {
    "apiversion": "1.61.0",
    "bridgeid": "ECB5FAFFFE0A55DA",
    "datastoreversion": "165",
    "factorynew": false,
    "mac": "ec:b5:fa:0a:55:da",
    "modelid": "BSB002",
    "name": "hue-3",
    "replacesbridgeid": null,
    "starterkitid": "",
    "swversion": "1961135030"
  }
}

In the above example, it finds Hue bridge at 192.x.x.10.

Specifying a Hue Bridge

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

$ ph -H 192.x.x.10 config
{
  "name": "hue-3",
  "datastoreversion": "165",
  "swversion": "1961135030",
  "apiversion": "1.61.0",
  "mac": "ec:b5:fa:0a:55:da",
  "bridgeid": "ECB5FAFFFE0A55DA",
  "factorynew": false,
  "replacesbridgeid": null,
  "modelid": "BSB002",
  "starterkitid": ""
}

Note that config does an unauthenticated request to get the basic configuration of the bridge. This info is also returned by ph discover, checking that the discovered bridge 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 bridge 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. 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 API.

Usage: ph [-hVD] [-H hostname] [-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 the Hue bridge.

  -H hostname, --host=hostname
  Connect to hostname.

  -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.

  eventlog [-hnrs]
  Log events from the Hue API v2 event stream.

  discover [-hS]
  Discover Hue bridges.

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

  description [-hs]
  Retrieve Hue bridge description.

  createuser [-hv]
  Create Hue bridge API username.

  unlock [-hv]
  Unlock Hue bridge so a new API username can be created.

  touchlink [-hv]
  Initiate a touchlink.

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

  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.

For more help, issue: ph command -h

See https://github.com/ebaauw/homebridge-hue for more info.
(homebridge-hue v0.13.69, node v20.10.0)

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

$ ph -H 192.x.x.10 get -h
Command line interface to Philips Hue 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.

See https://github.com/ebaauw/homebridge-hue for more info.
(homebridge-hue v0.13.69, node v20.10.0)