[Back to the Floodgap main page] Return to Floodgap Software

HuePl (HYUU-pull): Control Your hue Lights from the Command Line

Current release: v0.5 (13 January 2016)

[Example image of hue.] The Philips hue wireless lighting system is expensive and, on first impression, wildly gratuitous. But having bought one, I love having a lighting system that is easily remotely controlled with a simple-to-use REST API to adjust their colour and intensity.

However, there aren't many explicit command-line tools for this, so, naturally, I wrote one. Naturally I also wrote it in Perl. This page is primarily intended for people like me who will mostly be controlling their lights through a means like this other than the standard iPhone or Android app, though you can of course do it that way too. You don't even have to install the app to control the lights or set them up; huepl is the only tool I use. Throw it in cron for scheduling, or log in remotely on vacation to turn the lights on for security -- HuePl can do all those things. It's compatible with all of the Philips hue family of lighting, including the BR30 floods, the E26 standard bulbs, and even the Bloom and LightStrips. Here's how.

Initial Setup

In the starter kit are three bulbs and the base station, which Philips calls the "bridge." These three bulbs do not talk to other base stations; you can't buy another starter kit and use those bulbs with this one. Andres Maduro tells me there is an undocumented factory API for bonding bulbs from one bridge to another. I don't support this yet. The IDs range from 1 to 3 and are internal to the bulbs; I didn't even have bulb 1 installed initially, just 2 and 3. There is no way to tell that I know of which ID is which bulb without installing them.

The bulbs contain 2.4GHz 802.15.4 ZigBee transceivers, glue electronics and mixable colour LEDs in a standard E26 fixture. They are rated for 15,000+ hours of illumination and consume 8.5W maximum at their top brightness of 600 lumen (roughly a 50-watt incandescent bulb). There is always a small trickle pull of less than one watt to power the transceiver even if the light is not on.

[Example image of hue.]

Configuring HuePl

HuePl requires Perl 5.8.6+ and cURL 7.16+. It is tested on Mac OS X, NetBSD and AIX, and should work just fine on your choice of Linux and Cygwin. Mac OS X 10.4 and higher contain these tools already, as do most Linux distros. HuePl is distributed under the Floodgap Free Software License.

HuePl needs a key to talk to your base station. That big old button on your base station (don't press it yet) is how you authorize a requesting application (the "link button"). Here's how to set it up:

  1. First, download HuePl (22K) and chmod +x huepl.

  2. Start it with ./huepl or what have you. It will see that there is no HuePl key (normally stored in ~/.hueplkey; you can specify a new path to the key with -keyf=/path/to/key) and start the authentication wizard. (If HuePl can't find cURL, make sure it's in your path, or specify -curl=/path/to/curl to hint it.)

  3. Do not press the link button yet. Enter the IP address or hostname of the base station. If HuePl can't connect, it will fail here.

  4. Otherwise, it will prompt you to press the link button now, and having done so, to press RETURN/ENTER. If this worked, it will assign a hash username to itself and save the IP and hash to ~/.hueplkey. This file can be copied to other systems and is machine-independent. You are now ready to control your lights.

HuePl Commands

HuePl commands look like this:
huepl command arg arg arg...
For example, huepl lights lists the lights your system has installed. Here are the HuePl commands supported in the current version. You can always do a quick huepl help for a refresher.


Lists the configuration settings of the base station and the whitelist of user hashes that may control it. If you add an optional key and value parameter, some of the settings are writeable (most aren't, though), such as huepl config name My Hue base station

Lists the status of the lights known to the base station. The three initial bulbs are always listed, even if you haven't installed them all. Each light has its ID, its on-off state, its brightness, and its colourmode and associated colour parameters. No arguments are specified.

If you save this to a text file, you can feed it back to huepl load to restore a particular state of your lights (read on).

HuePl currently does not support naming bulbs or grouping them. If you set up names or groups in the mobile app, they are not reported here. However, there are ways to address bulbs simultaneously (see below).

Commands the base station to start a scan for new bulbs. The three initial bulbs in the starter pack are always reported, even if they are not installed; this is for adding new, unattached bulbs bought as extras (or for adding Friends of Hue devices to your bridge such as the LightStrips and the Bloom accent light). All powered-on extra bulbs will be added to the base station and assigned IDs. This may take a minute or two, after which a quick huepl lights will show you if they were successfully added. No arguments are specified.

If you lost your keyfile, or somehow deauthorized it, you can restart the authentication sequence manually with huepl rekey. No arguments are specified.

Commanding Individual Lights

Individual bulbs are commanded with a light argument (its ID), like this:
huepl command light arg arg...
By default, changes you make fade in/out.
Turns the light on or off (such as huepl on 2, which turns on bulb 2). If the light is not on, you cannot make any other changes to it. No other arguments are specified.

(All added in 0.4.) Commands a bulb to start or stop blinking, or just blink once. Useful for identifying bulbs, or causing seizures.

bri [brightness]
Specifies the brightness, from 0-255 (such as huepl bri 2 255, which sets the brightness of bulb 2 to 255). Note that 0 is not completely off.

Uses an internal colour preset for the specified bulb (such as huepl red 2, which sets bulb 2 to red). warm is an approximation of an incandescent bulb. The colour fidelity of the bulbs is not perfect and some colours are better saturated than others.

hs [hue] [saturation]
ct [colour temperature]
xy [CIE 1931 x coordinate] [CIE 1931 y coordinate]
rgb [red] [green] [blue]
These four methods allow you to assign a specific hue/colour temperature to your bulb (such as huepl hs 2 47000 255, which sets bulb 2 to a fully-saturated colour of blue).

Colour control with the bulbs is decidedly non-linear. The most precise means of control is with hue and saturation, which range from 0-65535 and 0-255 respectively. The 0 and 65535 extremes are, at full saturation, a deep red; yellow peaks around 16384, green around 25600 and magenta around 57344, as in a typical HSL scheme (which, considering brightness, this is). Even with this, some of the colours are "corrupt" because the LED arrays inside the bulb are not pure R-G-B elements. Blue, for example, appears more as a violet, and green is more of a "lime."

Colour temperature controls the white of the bulb, and sets the colour to white modulo the selected temperature, which is in mireds instead of Kelvin (a mired is 1e6/degrees K, so a 6500 K temperature equals 154, and a 2000 K temperature equals 500; the supported range is 154-500).

RGB control is offered by huepl as a convenience; internally it is converted to HSL by a tuned algorithm using observational data points. RGB values should be expressed as 8-bit quantities (0-255). The RGB output is designed to generate the most accurate colour available at the occasional expense of comparable luminance -- for example, blue appears more dim than red, even at "full" value, because the elements inside are being lit differently to generate the right colour mix -- and low values where the computed brightness comes out as zero will appear dim instead of extinguished, because as you will recall above, setting the brightness of the bulb to 0 does not turn it off. While most primary colours are acceptably rendered, cyan appears off-white; the bulb cannot render it at all (remember that it does not have R-G-B elements). Because RGB necessarily includes brightness information, bulb brightness is also set automatically, meaning there may be a flash of the wrong colour while the bulb receives both commands. (Prior to 0.3, this computation was done using CIE 1931 coordinates [described below]. There is no good reason I know of to use this mode anymore because it inherits all the limitations of that coordinate mapping, but it is still available by passing the option -use_cie.)

CIE 1931 controls are disappointingly imprecise. While the CIE 1931 scheme renders red and purple well, blue tends to appear more white, and overall CIE 1931 gamut mapping onto the LEDs in the hue bulb ranges from merely adequate to totally unsatisfactory. Nevertheless, CIE coordinates are expressed as floating point numbers between 0 and 1.

In general, you should try to use hue and saturation unless you have a specific colour coordinate expressed in another system that you know works correctly, or you are using the bulbs mostly as regular light bulbs (in that case, colour temperature is more appropriate).

Currently, the preset colours and the RGB tuning are designed for the BR30 and E26 bulbs. The Go, Bloom and LightStrip Friends of hue products have slightly different colour gamuts. For example, blue on the Bloom really looks more like a dim cyan, and white tends to be a not-quite-satisfactory mix of all LEDs instead of using a dedicated element like the bulbs. The hue Lux/hue White bulbs don't support any colour options at all!

Commanding Multiple Lights

for ... do
Indicates a command to be applied to multiple light IDs. For example, huepl for 2 3 do on turns bulbs 2 and 3 on; huepl for 1 2 3 do bri 128 sets bulbs 1, 2 and 3 to half brightness. Notice that the light IDs go in the for clause, not to the command, but the command still needs its other arguments (if any).

for ... do stops if the controller raises an error. To ignore the error and continue (though the error is still shown), use for ... try (added in 0.4).

Similarly, to automatically turn the bulb on before sending it commands, use for ... onanddo or for ... onandtry (added in 0.5).

Accepts a filename argument (or - for standard input), from which it loads light states and restores the on-off status, brightness and colour.

This file is in the same format huepl lights generates. Once you have your lights set up the way you want, huepl lights > somefilename, and later to restore them, huepl load somefilename will bring them back to the previous status. Blank lines and lines starting with # are politely ignored.

You can also use huepl load for only a subset of lights: just remove the lines from the file corresponding to the lights you don't want set. You don't have to specify every bulb in the file.



Download current version

The current version is always available from here (22K).


Cameron Kaiser