![[Back to the Floodgap main page]](/pix/hosted.gif "[Back to the Floodgap main page]")
Return to Floodgap Software
![[Example image of hue.]](scene.jpg "Result of huepl for 2 3 do on;huepl red 2;huepl blue 3")
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.
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.
Once your DHCP setup is ready, connect the base station to Ethernet and plug it in. It will get its DHCP address and then immediately try to phone home to the Philips meethue site. It does not have to phone home to function with huepl, but it does if you intend to use the mobile apps. My base station sits on a secured internal network, and it has never connected to Philips; all control is through huepl.
![[Example image of hue.]](scene2.jpg "Result of huepl for 2 3 do on;huepl for 2 3 do warm")
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:
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.
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).
huepl command light arg arg...By default, changes you make fade in/out.
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!
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).
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 state. 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.
Your PATH under cron or your webserver may be very different from your shell's. Either correct this in your crontab, or pass -curl=/path/to/curl to HuePl, e.g., huepl -curl=/path/to/curl for 2 3 do on
If HuePl can't find your key, it will start the interactive wizard, which depending on I/O may not generate any output to cron or your browser other than sitting there taking up CPU.
If you run your webserver, gopher server or crond as a different (non-root) user, your keyfile may need to be copied somewhere and chowned to that user, or you may need to relax the chmod on your home directory and/or ~/.hueplkey. The correct choice for security will depend on how your host is set up.
It is also possible that your environment may not have HOME, causing HuePl to fall back on /.hueplkey (note no ~). If this is fine, do nothing. If this is not fine, use -keyf=/path/to/key to be explicit.
For example, the key portions of my "on" script for my gopher server look like this:
$ENV{'LIBPATH'} = "/opt/lib:/usr/local/lib";
exec("/home/censored/bin/huepl",
"-keyf=/home/censored/.hueplkey",
"-curl=/usr/local/bin/curl",
"-verbose",
"load",
"/home/censored/huepl/warm");
The LIBPATH is because my cURL is dynamically linked in
a weird place. As written, this will call huepl, force the
locations of the key and cURL, and then load from my directory of
HuePl saved states.