Skip to content

A command line management interface to Philips hue

Notifications You must be signed in to change notification settings

bahamas10/hueadm

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

25 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

hueadm - Phillips Hue Admin CLI Utility

A command line management interface to phillips hue

Installation

First, install Node.js, then:

npm install -g hueadm

...and the executable will be installed globally as hueadm

Getting Started

Setup

Find a bridge

To get started you must find the IP address of the Hue bridge you would like to manage. If you know the IP address or the hostname of the bridge you would like to manage you can skip this step.

$ hueadm search
IP
10.0.1.80

On my network 10.0.1.80 is the IP of the bridge I'll be controlling.

Register a user

Now that we have the IP of the bridge we want to control, we can now create a new account for the hueadm tool to use.

$ hueadm -H 10.0.1.80 register dave
sending request... press the link button on the hue bridge

Now, go to the bridge and press the physical button on it to complete the registration - you'll see a message like this:

$ hueadm -H 10.0.1.80 register dave
sending request... press the link button on the hue bridge
-
    success: {username: f28jfl3gtltQw4r4gKLEtVFsfJcBGE87A1RaAXgt}

That very long string is the username we'll be using for all requests going forward. Using the lights subcommand we can get a list of all lights on the bridge to verify the new user account is working.

$ hueadm -H 10.0.1.80 -U f28jfl3gtltQw4r4gKLEtVFsfJcBGE87A1RaAXgt lights
ID  NAME                       STATUS  BRIGHTNESS  REACHABLE
1   Nightstand                 on      254         true
2   Garage Right               on      254         false
3   Garage Left                on      254         false
4   Pool House                 on      254         true
5   Garage Side Door           on      254         true
6   Garage Back                on      254         true
7   Front Door                 on      254         true
8   Screen Room Right          on      254         true
12  Couch                      on      254         true
13  Street Left                on      254         false
14  Pool House Back            on      254         true
15  Test Light 1               on      254         true
16  Driveway                   on      254         false
20  Inside Garage Front Left   off     250         false
21  Inside Garage Front Right  off     250         true
22  Inside Garage Back Right   off     250         false
23  Inside Garage Back Left    off     2           false
24  Screen Room Left           on      254         false
25  Inside Screen Room Left    on      254         true
26  Courtyard Back             on      254         false
27  Front Yard                 on      254         false
28  Hue color light 1          on      254         false

Create a config

Instead of passing -H and -U for every request, we can create a config file for hueadm to use if those arguments are not specified.

$ vim ~/.hueadm.json
$ cat ~/.hueadm.json
{
    "user": "f28jfl3gtltQw4r4gKLEtVFsfJcBGE87A1RaAXgt",
    "host": "10.0.1.80"
}

Lights

Get light information

Now, we can run the same command like:

$ hueadm lights
ID  NAME                       STATUS  BRIGHTNESS  REACHABLE
1   Nightstand                 on      254         true
2   Garage Right               on      254         false
... snipped ...

To get information about a specific light:

$ hueadm light 15
state:
    on: true
    bri: 254
    hue: 14988
    sat: 141
    effect: none
    xy: [0.4575, 0.4101]
    ct: 366
    alert: select
    colormode: xy
    reachable: true
type: 'Extended color light'
name: 'Test Light 1'
modelid: LCT001
manufacturername: Philips
uniqueid: 'removed'
swversion: 5.50.1.19085

Lights can also be identified by name, as long as the name is unique:

$ hueadm light "Test Light 1"
[same output as above]

All subcommands allow for -j or --json to be specified to force the output to be JSON.

$ hueadm light -j 15
{
  "state": {
    "on": true,
    "bri": 254,
    "hue": 14988,
    "sat": 141,
    "effect": "none",
    "xy": [
      0.4575,
      0.4101
    ],
    "ct": 366,
    "alert": "select",
    "colormode": "xy",
    "reachable": true
  },
  "type": "Extended color light",
  "name": "Test Light 1",
  "modelid": "LCT001",
  "manufacturername": "Philips",
  "uniqueid": "removed",
  "swversion": "5.50.1.19085"
}

Setting light state

Using the same light subcommand, the state can be set. There are a lot of different ways to change the state of the lights.

  • on: turn the light on
  • off: turn the light off
  • clear: clear any and all effects on a light
  • reset: clear any and all effects on a light and set it to the "default" color (as if it just turned on)
  • select: flash the light once
  • lselect: flash the light for 15 seconds (can be cancelled with reset)
  • colorloop: enable the color loop effect
  • [-+=]<num>: set brightness, ie: =50, -20, +40, all values out of 254
  • [-+=]<num>%: set brightness, ie: =50%, -20%, +40%, all values out of 100
  • -: read state JSON object from stdin
  • [0-9]+K: set the light to a color based on Kelvin. ie. 2700K, 5000k, etc.
  • <colorname>: set the light to a color name (using CSS color names). ie. blue, red, magenta
  • #012345: set the light to any hex string (# is optional)

Turn a light on or off

$ hueadm light 15 off
-
    success: {/lights/15/state/on: false}
$ hueadm light "Test Light 1" on
-
    success: {/lights/15/state/on: true}

Again, -j works here too

$ hueadm light 15 -j off
[
  {
    "success": {
      "/lights/15/state/on": false
    }
  }
]

Set a light to green (this will turn it on if it was previously off)

$ hueadm light 15 green
-
    success: {/lights/15/state/on: true}
-
    success: {/lights/15/state/hue: 21845}
-
    success: {/lights/15/state/sat: 254}
-
    success: {/lights/15/state/bri: 64}

Any extra arguments will be processed as key=value pairs, and added to the request sent to the bridge. This way, it is possible to set multiple attributes of a light in a single command.

Set the light to green with the brightness set to max.

$ hueadm light 15 green bri=255
-
    success: {/lights/15/state/on: true}
-
    success: {/lights/15/state/hue: 21845}
-
    success: {/lights/15/state/sat: 254}
-
    success: {/lights/15/state/bri: 254}

Change the light to red and take 5 seconds for the transition to happen. transitiontime is given in 100's of milliseconds, so 50 is 5 seconds.

$ hueadm light 15 red bri=127 transitiontime=50
-
    success: {/lights/15/state/transitiontime: 50}
-
    success: {/lights/15/state/on: true}
-
    success: {/lights/15/state/hue: 0}
-
    success: {/lights/15/state/sat: 254}
-
    success: {/lights/15/state/bri: 127}

Read light state from stdin as JSON.

$ echo '{"on": true}' | hueadm light 15 -
-
    success: {/lights/15/state/on: true}

Set the light color using a hex string

$ hueadm light 15 '#00ff00'
-
    success: {/lights/15/state/on: true}
-
    success: {/lights/15/state/hue: 21845}
-
    success: {/lights/15/state/sat: 254}
-
    success: {/lights/15/state/bri: 127}

Set the light to a standard "Warm White" color (similar to an incandescent bulb)

$ hueadm light 15 2700k
-
    success: {/lights/15/state/on: true}
-
    success: {/lights/15/state/ct: 370}

Enable the color loop effect

$ hueadm light 15 colorloop
-
    success: {/lights/15/state/on: true}
-
    success: {/lights/15/state/effect: colorloop}

Clear the color loop (and any other) effect

$ hueadm light 15 reset
-
    success: {/lights/15/state/on: true}
-
    success: {/lights/15/state/alert: none}
-
    success: {/lights/15/state/effect: none}

Modify a light

Using the lights subcommand, it is also possible to filter for a specific ID to get a short synopsis of the light state.

$ hueadm lights id=15
ID  NAME          STATUS  BRIGHTNESS  REACHABLE
15  Test Light 1  on      127         true

Rename the light to foobar

$ hueadm rename-light 15 'foobar'
-
    success: {/lights/15/name: foobar}

$ hueadm lights id=15
ID  NAME    STATUS  BRIGHTNESS  REACHABLE
15  foobar  on      127         true

Groups

List light groups

In order to control more than 1 light at a time, a group of lights must be created. The group can then be controlled the same way a single light is controlled using hueadm.

To list all groups

$ hueadm groups
ID  NAME           TYPE  LIGHTS
3   Garage Inside  Room  20,21,22,23
4   Outside        Room  2,3,4,5,6,7,8,13,14,15,16,24,25,26,27

Even though it doesn't show it, group 0 always exists on the bridge and contains every light known. This group is special and cannot be deleted.

Create a light group

To create a light group

$ hueadm create-group name='Test Group' lights=1,2,3,4
-
    success: {id: '1'}

The group has been created with the id 1, we can see it with

$ hueadm group 1
name: 'Test Group'
lights:
    - '1'
    - '2'
    - '3'
    - '4'
type: LightGroup
state:
    all_on: true
    any_on: true
    recycle: false
action:
    on: true
    bri: 254
    hue: 14988
    sat: 141
    effect: none
    xy: [0.4575, 0.4101]
    ct: 365
    alert: select
    colormode: xy

You may also specify a group using its name

$ hueadm group 'Test Group'
name: 'Test Group'
lights:
    - '1'
    - '2'
    - '3'
    - '4'
type: LightGroup
state:
    all_on: true
    any_on: true
    recycle: false
action:
    on: true
    bri: 254
    hue: 14988
    sat: 141
    effect: none
    xy: [0.4575, 0.4101]
    ct: 365
    alert: select
    colormode: xy

Or in a simpler way with

$ hueadm groups id=1
ID  NAME        TYPE        LIGHTS
1   Test Group  LightGroup  1,2,3,4

Modify a group

Any property of the group can be modified with modify-group

To rename a group

$ hueadm modify-group 1 name='Foo Group'
-
    success: {/groups/1/name: 'Foo Group'}

$ hueadm groups id=1
ID  NAME       TYPE        LIGHTS
1   Foo Group  LightGroup  1,2,3,4

To change the lights in a group

$ hueadm modify-group 1 lights=5,6,7,8
-
    success: {/groups/1/lights: ['5', '6', '7', '8']}

$ hueadm groups id=1
ID  NAME       TYPE        LIGHTS
1   Foo Group  LightGroup  5,6,7,8

Set a group state

All state modifications to a single light can be used to modify a group as well

Kelvin

$ hueadm group 1 2700k
-
    success: {/groups/1/action/on: true}
-
    success: {/groups/1/action/ct: 370}

Color and brightness

$ hueadm group 1 red bri=255
-
    success: {/groups/1/action/on: true}
-
    success: {/groups/1/action/bri: 254}
-
    success: {/groups/1/action/hue: 0}
-
    success: {/groups/1/action/sat: 254}

Clear all effects

$ hueadm group 1 reset
-
    success: {/groups/1/action/on: true}
-
    success: {/groups/1/action/alert: none}
-
    success: {/groups/1/action/effect: none}

Groups also support recalling/loading of scenes. Either using

$ hueadm group 1 scene=<sceneID>
-
    success: {/groups/1/action/scene: <sceneID>}

or

$ hueadm recall-scene <sceneID> Garage
-
    success: {/groups/1/action/scene: <sceneID>}

Delete a group

To delete the group run

$ hueadm delete-group 1
-
    success: '/groups/1 deleted'

Users

List users

To list all users on a bridge (I've modified some IDs for privacy reasons)

$ hueadm users
ID                                        NAME               CREATION  LASTUSE
1                                         node-hue-cli       3y        1s
2                                         hue-cli#dave       2d        11h
3                                         hue_ios_app#black  1d        21h
4                                         gohue#papertigers  1w        1w
f28jfl3gtltQw4r4gKLEtVFsfJcBGE87A1RaAXgt  hueadm#dave        11h       1s

See a specific user

To see our current username we can do

$ hueadm users id=f28jfl3gtltQw4r4gKLEtVFsfJcBGE87A1RaAXgt
ID                                        NAME         CREATION  LASTUSE
f28jfl3gtltQw4r4gKLEtVFsfJcBGE87A1RaAXgt  hueadm#dave  11h       2s

Or

$ hueadm user f28jfl3gtltQw4r4gKLEtVFsfJcBGE87A1RaAXgt
'last use date': '2017-09-04T16:56:26'
'create date': '2017-09-04T05:51:40'
name: 'hueadm#dave'

Delete a user

To delete our user

$ hueadm delete-user f28jfl3gtltQw4r4gKLEtVFsfJcBGE87A1RaAXgt
-
    success: '/config/whitelist/f28jfl3gtltQw4r4gKLEtVFsfJcBGE87A1RaAXgt deleted'

NOTE: If you do this, you will need to register a new username

Misc.

Config

To get the full bridge config, use:

$ hueadm config
name: 'Philips hue'
zigbeechannel: 20
... snipped ...

Raw request

To make a raw request to the bridge, use the request subcommand. This will automatically prepend /api/<username> to the endpoint given.

$ hueadm request /lights/15
state:
    on: true
    bri: 100
    hue: 14884
    sat: 144
    effect: none
    xy: [0.4597, 0.4103]
    ct: 370
    alert: none
    colormode: ct
    reachable: true
type: 'Extended color light'
name: foobar
modelid: LCT001
manufacturername: Philips
uniqueid: 'removed'
swversion: 5.50.1.19085

Give body as CLI args

$ hueadm request -j -X PUT /lights/15/state on=true bri=255
[
  {
    "success": {
      "/lights/15/state/on": true
    }
  },
  {
    "success": {
      "/lights/15/state/bri": 254
    }
  }
]

Give body as JSON

$ echo '{"on":true,"bri":255}' | hueadm request -j -X PUT /lights/15/state -
[
  {
    "success": {
      "/lights/15/state/on": true
    }
  },
  {
    "success": {
      "/lights/15/state/bri": 254
    }
  }
]

Usage

$ hueadm -h
A command line management interface to phillips hue

Usage:
    hueadm [OPTIONS] COMMAND [ARGS...]
    hueadm help COMMAND

Options:
    -c CONFIG, --config=CONFIG  config file - defaults to ~/.hueadm.json.
    -d, --debug                 enable debug logging.
    -H HOST, --host=HOST        host address of the hue bridge.
    -h, --help                  print this help message and exit.
    -U USER, --user=USER        username associated with the hue bridge.
    -u, --updates               check npm for available updates.
    -v, --version               print the version number and exit.

Commands:
  General:
    discover (search)  Search for Hue bridges

  Lights:
    lights          List all lights
    light           Show/set a light
    search-lights   Search for new lights
    new-lights      Show new lights
    rename-light    Rename a light
    delete-light    Delete a light

  Groups:
    groups          List all light groups
    group           Show/set a light group
    create-group    Create a light group
    modify-group    Modify a light group
    delete-group    Delete a light group

  Schedules:
    schedules       List all schedules
    schedule        Show a schedule
    create-schedule  Create a schedule
    modify-schedule  Modify a schedule
    delete-schedule  Delete a schedule

  Scenes:
    scenes          List all scenes
    scene           Show a scene
    create-scene    Create a scene
    modify-scene    Modify a scene
    delete-scene    Delete a scene
    recall-scene    Recalls a scene on a group

  Sensors:
    sensors         List all sensors
    sensor          Show a sensor
    create-sensor   Create a sensor
    rename-sensor   Rename a sensor
    delete-sensor   Delete a sensor

  Rules:
    rules           List all rules
    rule            Show a rule
    create-rule     Create a rule
    modify-rule     Modify a rule
    delete-rule     Delete a rule

  Users:
    users           List all users
    user            Show a user
    create-user (register)  Create/register a new user
    delete-user     Delete a user

  Other Commands:
    config          Show the hue bridge config
    full-state      Show the hue bridge fullstate
    request         Make a raw HTTP request

  Generic Commands:
    help (?)        Help on a specific sub-command.

License

MIT

About

A command line management interface to Philips hue

Resources

Stars

Watchers

Forks

Packages

No packages published