Hue - Ruby Library and CLI for Philips Hue #

NOTE: This is a modified fork of birkirb/hue-cli that supports modern Ruby.

WARNING #

All of this is very experimental and could permanently damage your awesome (but ridiculously expensive) lightbulbs. As such, exercise extreme caution.

Installation #

To begin using, install the ruby gem (this requires ruby 3.0+):

$ gem install hue

This will install the hue command.

Usage #

Command Line Interface #

To check the bridge state, simply type:

$ hue

If this is the first time the command is run, it will scan for bridges on the network and attempt to register the application. Follow the on-screen instructions to do so.

Register #

You can also explicitly register the application with:

$ hue register

Bridge state #

Once registered, examine the current state of the bridge:

$ hue
Philips Hue
Button pressed: false
Timestamp: 2013-09-02T17:44:10
Network configuration:
  IP:      196.168.0.1
  Gateway: 196.168.0.255
  Mask:    255.255.255.0
  DHCP:    true
  MAC:     00:00:00:00:00:00
  Proxy:   none:0
Applications:
  073f2ed95fcbbef2532c751dd404cc9d : hue-cli
Lights:
  1. Living Overhead - OFF
  2. Living Cabinet - OFF
  3. Living Corner Lamp - OFF

Lights state #

Examine or operate on all lights #

$ hue lights
1.  Bedroom - Overhead: ON
    Brightness: 254 (100%)
    Color: XY=[0.6736, 0.3221], RGB≈[255, 60, 40]
2.  Living Room - Cabinet: OFF
    Brightness: 142 (56%)
    Color: XY=[0.674, 0.322], RGB≈[255, 60, 40]
3.  Living Room - Overhead: ON
    Brightness: 254 (100%)
    Color: Temperature=2710°K (369 mired), RGB≈[255, 166, 87]

Find new lights #

$ hue lights find

Light state #

Examine the state of a single light:

$ hue light 1

or just:

$ hue 1
1.  Bedroom - Overhead: ON
    Brightness: 254 (100%)
    Color: XY=[0.6736, 0.3221], RGB≈[255, 60, 40]

Change Light state #

Change a single light state with the following (rather self-explanatory) commands:

$ hue 1 on
$ hue 1 off
$ hue 1 flash
$ hue 1 blink
$ hue 1 solid

Brightness #

Brightness can be set with a value (0-255) or percentage (0%-100%):

$ hue 1 brightness 200
$ hue 1 brightness 50%
$ hue 1
Living Overhead: ON
Brightness: 128 (50%)
Color: Temperature=2012°K (497 mired), RGB≈[255, 136, 13]

Color #

The color command takes 1-3 arguments, each interpreted depending on range and value.

Set to 6500 Kelvin:

$ hue 1 color 6500
$ hue 1
Living Overhead: ON
Brightness: 128 (50%)
Color: Temperature=6500°K (153 mired), RGB≈[255, 254, 250]

Set to 240 mired:

$ hue 1 color 240
$ hue 1
Living Overhead: ON
Brightness: 128 (50%)
Color: Temperature=4167°K (240 mired), RGB≈[255, 208, 170]

Set the hue and saturation:

$ hue 1 color 30000 255
$ hue 1
Living Overhead: ON
Brightness: 128 (50%)
Color: Hue=30000, Saturation=255, RGB≈[0, 255, 190]

Set the XY:

$ hue 1 color 0.25 0.25
$ hue 1
Living Overhead: ON
Brightness: 128 (50%)
Color: Hue=30000, Saturation=255, RGB≈[0, 255, 190]

Set all lights #

All the single light state commands can be applied to all lights:

$ hue lights brightness 50%

State aliases #

The following state aliases exist and can be used on all or single lights:

$ hue 1 relax
$ hue lights energize
$ hue 1 reading
$ hue 1 concentrate
$ hue 1 red
$ hue 1 blue
$ hue 1 green
$ hue 1 white
$ hue 1 pink

State Dump #

Dump the current state of the light, this will display the current state as a JSON hash. This can then be pasted into your local (~/.hue-cli/light_alias.yml) or system (/etc/hue/light_alias.yml) alias files.

$ hue 1 dump
$ hue lights dump

Paste into your file like this:

"yellow":
  {
    "on": true,
    "bri": 254,
    "xy": [0.4823, 0.4621],
    "alert": "none",
    "effect": "none",
  }

Ruby Library Usage #

Start by firing up the irb console:

$ irb

>> require 'hue'
=> true

Start by registering your application. Press the button on the bridge and execute:

>> Hue.register_default
=> #<Hue::Bridge:0x8b9d950 @application_id="4aa41fe737808af3559f3d22ca67a0ca", @bridge_uri="http://198.168.1.1/api">

This will create two config files in your ~/.hue-cli directory. One for the bridges discovered on your network and one for the registered application.

You can fetch the default application thus:

>> bridge = Hue.application
=> #<Hue::Bridge:0x8b9d950 @application_id="4aa41fe737808af3559f3d22ca67a0ca", @bridge_uri="http://198.168.1.1/api">

You can see all of the lights attached to your controller by querying the bridge:

>> bridge.lights
=> {"1"=>{"name"=>"Bedroom Overhead"}, "2"=>{"name"=>"Living Overhead"}, "3"=>{"name"=>"Standing Lamp"}, "4"=>{"name"=>"Living Cabinet"}}
>> bridge.light_names
=> "1. Bedroom Overhead\n2. Living Overhead\n3. Standing Lamp\n4. Living Cabinet"

If you know the ID number of a particular lamp, you can access it directly:

>> b = Hue::Bulb.new(bridge, 1)
=> #<Hue::Bulb:0x007fe35a3586b8 @bridge=#<Hue::Bridge:0x007fe35a358690 @id="1">>

# on/off
>> b.on?
=> false

>> b.on
=> true

>> b.on?
=> true

# brightness
>> b.brightness = 128
=> 128

# color
>> b.color = Hue::Colors::ColorTemperature.new(6500)
=> Temperature=6500°K (153 mired)

>> b.color = Hue::Colors::HueSaturation.new(10_000, 255)
=> Hue=10000, Saturation=255

>> b.color = Hue::Colors::XY.new(0.5, 0.5)
=> XY=[0.5, 0.5]

# blinking
>> b.blinking?
=> false

>> b.blink

>> b.blinking?
=> true

>> b.solid

>> b.blinking?
=> false

Development #

Building the gem #

$ rake gem:build

Installing locally #

$ rake gem:install

Running tests #

$ rake spec

License #

This project is open source and available under the MIT License.