Philips delivers promised dev docs for colorful Hue LED lights

Hacker-friendly SDK & API are free for use, can make Hue lights way more awesome.

We reviewed the Hue LED-powered lightbulbs late last year, and the programmable lights have since become a major part of my life. I wake up with their help in the morning and go to bed with their help in the evening, and the 11 bulbs I've got throughout my home change colors as the day advances—from morning gold to daytime bright to evening dim, and finally to nighttime blues.

Philips Hue light shifting colors

They do this, though, without the help of the official app, which can best be characterized as "cute but ultimately useless." Enterprising Hue users discovered ways into the Hue system's RESTful API some time ago, and the only way to finely control Hue lights is with cron-triggered (or Task Scheduler-triggered) scripts speaking JSON directly to the system. Less-savvy Hue users like my poor parents are stuck manually resetting timers and schedules every night on the official app, which is, frankly, ridiculous.

Since the system's release, Philips has promised that the API and SDK for the lights would be made available for royalty-free use, and that has finally happened. Developers.meethue.com is live as of early this morning, though before you're able to see anything you must agree to Philips conditions of use. Most of the terms are reasonable and they for the most part eschew lawyer language, but a few are worth taking note of:

You may not distribute the documentation shown on developers.meethue.com except by links to the site itself or, if you use another method, these conditions of use must be attached.

...

We want all your apps to work with our API to form a rich ecosystem of interoperable applications, so it is a condition of access to our API documentation that you do not use it to develop or distribute any bridges or devices which interpret the Hue API.

It may happen that working on an app suggests an idea to you for an improvement in the API. If you suggest any improvements to us and we adopt them, they become part of the platform used by everyone, and belong to Philips, you will make no claims in this respect.

...

We want you and others to enjoy Hue. So please don’t make any applications that are obscene, not compliant with laws and regulations, offensive or discriminatory or that infringe someone else’s rights.

Though the API documentation presented and the linked SDK and iOS SDK on Github are nominally free and open, Philips does want to maintain some control over the code. Duplicating or forking doesn't appear to be allowed, with improvements to the SDK or API becoming the property of Philips if they're actually folded into the official system.

Still, though, it's friendlier intellectual property behavior from a multinational corporation than we're used to seeing. Rather than attempting to monetize app development for the Hue lights and charging a developer fee for entry, Philips has tossed the community the keys and told developers to get busy coding. A quick rundown of the API reveals that early explorers like Ross McKillop and others at the unofficial Hue community forums have done a pretty good job at exploring the API's nooks and crannies. The docs shine light for the first time on an area that has been relatively impenetrable: how to accurately set a Hue lamp's color.

The CIE colorspace, with the Hue lights operating area demarcated by the green triangle.

Philips

The color of a Hue LED light is set by picking a position in the CIE 1931 color space, and there are several methods for doing this: setting an X/Y value within the allowed space (denoted by the green triangle in the picture above), or choosing a point along the black curved line specified in values of "reciprocal megakelvin," or calling out pure hue and saturation numbers.

Divining exactly where and what these values should be and how they interact have proven difficult for the community. In fact, prior to the API's release, the best way to get a Hue lamp to programmatically change to a specific color was to manually set it to approximate the color you want in the official app, then query the light for its status and write down the values it reported. Thankfully, as developers wrap their heads around the color space implementation described in the docs, this should no longer be necessary.

Notable among the things announced today is an iOS SDK for the Hue system, to assist in making Hue lights addressable through iOS applications. Though there is an Android Hue app on the Google Play store, no Android app-specific SDK has yet been released. However, the API's documentation and the fact that the API is RESTful—that is, it's mostly stateless and interaction occurs by sending chunks of JSON over HTTP—means that the barrier to entry for coding Hue-friendly Android apps is pretty low.

Bring on the apps

I'm most excited about there being more (and better) applications for providing fine control over the lights. The official app has massive failings, some of which are baffling: the inability to set repeatable schedules for lights is the most egregious oversight (the Philips team has been promising a fix for this since November 2012, but users are still waiting). It's also nearly impossible to set the color and brightness on single lights with anything close to precision, and setting the levels on groups of lights is so annoyingly difficult that the capability might as well not exist. Since about day two with the lights, I've been relying on a (poorly coded) web interface that I (badly) hacked together for all of my interaction with the lights. I don't think I've fired up the iOS app once this year, and it's totally unsuitable for all but the most casual user.

Now that the official documentation is out there, I have high hopes that the community will begin to deliver polished Hue control applications, for both the desktop and for smartphones. It won't take much to eclipse the limited functionality of the official app, the skew of which toward using photographs and "scenes" to awkwardly configure lights is befuddling. The official app is in fact so awful that that my parents, for whom I bought a Hue set and several add-on bulbs for Christmas and who are both very smart people, have abandoned all pretense at actually using it to customize their lights (though my dad is forced, every single night, to re-enable the "wake up" event in the app so that the lights turn on the morning—what the hell was Philips thinking when they gave users the ability to set light-based alarms, but required those alarms to be re-enabled after every single use?). Third-party relief from the official app's failings is long overdue.

Listing image by Lee Hutchinson

Lee Hutchinson
Lee is the Senior Technology Editor at Ars and oversees gadget, automotive, IT, and culture content. He also knows stuff about enterprise storage, security, and manned space flight. Lee is based in Houston, TX. Emaillee.hutchinson@arstechnica.com//Twitter@Lee_Ars

The day I wake up and realize that a simple light "became a major part of my life", I know I will have to change something...

Something can be a feature of a major part of your (waking, indoors) life without it being on your mind or a very high *life* priority. Dropbox is a major part of my environment that makes my life easier, but I don't think about it all day long.

Frankly, one of the largest improvements in my QOL of late has been a dawn simulator alarm clock I purchased two years ago.Don't dismiss the impact of subtle environmental changes, in something as ubiquitous as lighting!

Sorry, but calling any gadget "a major part of ones life" is beyond me, unless maybe when you invented it. On your deathbed, would you reminisce about the Hue?

I'll elaborate, then, because you seem to be having trouble. The Hue lights have replaced my alarm clock--the ones in our bedroom fade in at 6:45 and wake my wife & me up. At the same time, the living room and kitchen and and hallway and office lights also come on, dimly, so that when I stumble out of the bedroom the house isn't pitch black (because of the abomination that is DST).

After I make my coffee, I sit down in the office here and start getting ready to write insightful and informative articles. Over the next hour, the light level slowly increases and at about 8, the four hue lights in the office here shift to white and the rest of the lights go out, since I tend to spend most of my day here.

As the time nears 17:00, the lights begin to soften and shift from a white task-lighting to a warmer color, which is a great way to pull me out of a writing trance without an annoying alarm or popup. The lights in the rest of the house come on at about that time, so that when my wife gets home from work we don't have to run around flipping on lights.

At 21:00, the office lights dim to a really cool blue, which is another reminder that it's night and I should start thinking about bed. The lights in the rest of the house dim.

The bedroom light shuts off at 22:00, and by that point we're usually brushing our teeth or whatever and we've got other lights in there turned on. We go to sleep between 22-23:00. At 23:59, the rest of the lights in the house all turn off.

The schedule is different on weekends so that we can sleep in and stay up later, but it follows roughly the same pattern.

So while I'm not taking the lights for long walks on the beach or spending quality time with them, they are definitely a major part of my life. Because I work from home, I'm using them all day, every day, and the ability to slap some automation on them has massively increased their usefulness. I would very, very much miss them if they stopped working tomorrow.

Does that answer your question, or do you want to get into a protracted semantic debate about the meaning and applicability of the word "major"?

Sorry, but calling any gadget "a major part of ones life" is beyond me, unless maybe when you invented it. On your deathbed, would you reminisce about the Hue?

I have to disagree. Computers sure have been a major part of my life and they'll continue to be that until the day I die. Why? Well, computers have shaped who I am quite profoundly, giving me access to swathes of information I wouldn't otherwise have, allowing me to interact with people I would never have met, enabling me to research and learn, giving me a way to relax when I need it and even shaping as outlets for creativity and flow of thought. And you know, computers are gadgets.

I love this product and I think having an SDK is awesome, but I am a little disturbed by the extreme faith Philips is putting in the community to fix their horrible UI. I wrote to them about how terrible the official app is and they wrote back saying not to worry, community will fix everything. That may be, but the official app is part of the user's first experience with the product- why do they not care that it sucks? They have this great product that is so hard to use. It's like Philips is run by geeks who can't market anything. It would be a shame If that causes them to fail because their tech is awesome.

This is just another product slated for the clearance bin, and rather soon. How it was even mentioned on Ars is beyond me.

If you haven't tried it and don't want to hear from those who have, leave. This product has some imperfections, but Philips is clearly trying to keep lighting moving forward and deserves some attention for their efforts. One day, I think all lights will have the features the Hue has- color adjustment and programmability.

Sorry, but calling any gadget "a major part of ones life" is beyond me, unless maybe when you invented it. On your deathbed, would you reminisce about the Hue?

... And you know, computers are gadgets.

They are? Let me enlighten you "A gadget is a small[1] tool such as a machine that has a particular function, but is often thought of as a novelty. Gadgets are sometimes referred to as gizmos." (Wikipedia)

You fail by your own definition then. Computers are small and they are tools. To some, they are a novelty with only one particular function. Most people see them as more than that. Similarly, the Hue is far more than a novelty with one function to anyone who had actually used one.

At 21:00, the office lights dim to a really cool blue, which is another reminder that it's night and I should start thinking about bed.

Just a quick tip on that... I was listening to a story about one of the "mars travel" tests where a bunch of folks are locked up and then subjected to "mars time" to see what happens. One of the sleep scientists noted that Circadian rhythms are influenced (in a "hey, wake up it's daytime" way) more by blue or daylight wavelengths than the warm end of the spectrum. So you may actually be confusing your brain a bit by shifting to a cooler temperature at night (in the experiments, they peaked the blue hues during the day and moved to warmer lighting at night).

You see, life, in my opinion, shouldn't be about those things. Gadgets can be cool and fun and interesting, but a major part of ones life? ...seriously?

Ah, gotcha. So everyone should conform to your world view and anything that anyone else finds changes their life, or makes their life easier, that you find irrelevant or inconsequential is stupid and worthy of ridicule.

I didn't have any problem at all.. I just thought it was funny how you called a gadget a "major part of your life". When I wake up, I just flip a switch and call it a day. I don't need any apps, API's, schedules and alarms to worry about, etc. etc. You see, life, in my opinion, shouldn't be about those things. Gadgets can be cool and fun and interesting, but a major part of ones life? ...seriously?

'Gadgets' are a major part of your life, you just aren't self-aware enough to acknowledge it I guess. Would your life be disrupted if you no longer had a cell phone? Tablet? Laptop? Alarm clock? Vacuum cleaner? Or maybe the older gadgets like hammers, screws, locks? Not to mention all the gadgets we have at the hospital that will add years to your life. Fact is, gadgets have been a major part of people's lives since the dawn of our species- in fact, more than anything else they define us and have elevated us to the place of privilege we enjoy in the web of life. I think you need to take an honest look around yourself.

Frankly, one of the largest improvements in my QOL of late has been a dawn simulator alarm clock I purchased two years ago.

Is it really, though? I've tried the whole wake-up light thing as well, and like others, found that it did absolutely nothing for me. Which, really, I should have figured before buying one because when I sleep with the curtains open I don't wake when the sun is up either. I wake up before sunrise, at sunrise, well after sunrise, at whichever time my body feels like waking up, with no apparent cue from the sunlight in my bedroom.

I have to wonder if this whole "wake up by gradually turning on a light" thing really works, or if the positive stories I'm hearing about them are just people who really want them to work because they've bought into something and don't want to admit to themselves it was, perhaps, a waste.

In the early days of personal computers, a friend programmed an Altair to control the lights in his house and flush his toilet. This was a big part of his life for awhile, but he didn't move the setup to his next house, and he flushes the same way as the rest of us now.

This is a major problem, because the CIE color space is a theoretical one, ie. it's not meant to be used to define colors, a la RGB or HSB. Whether intentional or not, Philips is not really providing any kind of color API here, and is in fact forcing third-party developers to hack something that was never intended for such a purpose.

In the early days of personal computers, a friend programmed an Altair to control the lights in his house and flush his toilet. This was a big part of his life for awhile, but he didn't move the setup to his next house, and he flushes the same way as the rest of us now.

The Hue is unlikely to suffer from that problem, because the large, immobile computer is no longer required and there is some flexibility to make the UI more compelling. They already have a phone app, and I expect to see voice, smart watch, motion activated, etc. If you could control the light from anywhere, just by speaking as they do on Star Trek TNG, do you really think you'd prefer a switch? Add in the ability to control color and set timers, and we should be well ahead of Star Trek within a couple years.

I really have to look into the SDK. Have held off on spending the money on the Hue lights so far as I thought that the interface was simply not mature enough - and Lee's account of his parents experience with it fully confirm my opinion...The killer app for me would be linking the light control with an external mic so that a soft red night light comes on when the baby needs attention. Unfortunately, I have to hope for some people with more time for coding to come up with it - job and newborn don't leave enough time for extra projects right now...

Frankly, one of the largest improvements in my QOL of late has been a dawn simulator alarm clock I purchased two years ago.

Is it really, though? I've tried the whole wake-up light thing as well, and like others, found that it did absolutely nothing for me. Which, really, I should have figured before buying one because when I sleep with the curtains open I don't wake when the sun is up either. I wake up before sunrise, at sunrise, well after sunrise, at whichever time my body feels like waking up, with no apparent cue from the sunlight in my bedroom.

I have to wonder if this whole "wake up by gradually turning on a light" thing really works, or if the positive stories I'm hearing about them are just people who really want them to work because they've bought into something and don't want to admit to themselves it was, perhaps, a waste.

Your expectations may have been too high. It isn't going to make you feel like you've had a full night sleep and slept in until 10 if you haven't. If you get 4 hours of sleep, you will still be hurting the next day. Nor does everyone wake up to light alone. However, if you set it far enough back from when you wake up (mine starts coming on nearly an hour before I get up), it has been shown to increase the amount of cortisol in your body quite a bit. You won't feel light headed the first time you stand up, you will have less tendency to fall back asleep, and of course your eyes won't hurt when you turn the lights on.

This may not be the night and day life changer some people say, but I find it helps noticeably. This probably varies from person to person a bit. That said, it certainly does have some evidence behind it- both NASA and Boeing use lighting to put the travellers in their vehicles to sleep and wake them back up.

This kind of thing might become appealing to me if a company like Nest were to take a crack at it with their semi-AI kind of approach. If the light is thinking and learning and trying its best, ok, I'd give it a shot.

But as this article describes it this sounds like yet one more chore to add to my day. Sometimes manual control isn't all it's cracked up to be.

At 21:00, the office lights dim to a really cool blue, which is another reminder that it's night and I should start thinking about bed.

Just a quick tip on that... I was listening to a story about one of the "mars travel" tests where a bunch of folks are locked up and then subjected to "mars time" to see what happens. One of the sleep scientists noted that Circadian rhythms are influenced (in a "hey, wake up it's daytime" way) more by blue or daylight wavelengths than the warm end of the spectrum. So you may actually be confusing your brain a bit by shifting to a cooler temperature at night (in the experiments, they peaked the blue hues during the day and moved to warmer lighting at night).

Yea, that's pretty much what I've read about it, it's pretty much about the fact that in the morning the color temperature is higher (bluer) than in the afternoon.

I wonder how hard it would be to link the control of these LEDlights to a computer running F-Lux, so that its managing your screen _and_ ambient light levels.

F-lux has saved me (and a lot of the users wherever I work), a crap ton of eyestrain, cluster headaches, blurred vision and as a result less sick time :- So much so that its become a recommended application on an organisational level.

Hell a little work, you could 'check in' to work areas/rooms/your home via your phone and it will adjust lighting colours/levels to your presets, - a teeny tiney step from star trek voice command.....

This is a major problem, because the CIE color space is a theoretical one, ie. it's not meant to be used to define colors, a la RGB or HSB. Whether intentional or not, Philips is not really providing any kind of color API here, and is in fact forcing third-party developers to hack something that was never intended for such a purpose.

Are you sure? I'd think that it's a sensible compromise, since it skips at least one color profile tranformation.

One may do direct RGB-RGB conversions but, AFAIK, every engine always goes to CIE first, then to the desired model/profile.

Frankly, one of the largest improvements in my QOL of late has been a dawn simulator alarm clock I purchased two years ago.

Is it really, though? I've tried the whole wake-up light thing as well, and like others, found that it did absolutely nothing for me. Which, really, I should have figured before buying one because when I sleep with the curtains open I don't wake when the sun is up either. I wake up before sunrise, at sunrise, well after sunrise, at whichever time my body feels like waking up, with no apparent cue from the sunlight in my bedroom.

I have to wonder if this whole "wake up by gradually turning on a light" thing really works, or if the positive stories I'm hearing about them are just people who really want them to work because they've bought into something and don't want to admit to themselves it was, perhaps, a waste.

Your expectations may have been too high. It isn't going to make you feel like you've had a full night sleep and slept in until 10 if you haven't. If you get 4 hours of sleep, you will still be hurting the next day. Nor does everyone way up to light alone. However, if you set it far enough back from when you wake up (mine starts coming on nearly an hour before I get up), it has been shown to increase the amount of cortisol in your body quite a bit. You won't feel light headed the first time you stand up, you will have less tendency to fall back asleep, and of course your eyes won't hurt when you turn the lights on.

Well, obviously I wasn't expecting it to wake me up bright and fresh after 4 hours of sleep. Like I said, I find that it doesn't have any influence whatsoever on when I wake up: my body wakes up when it feels like it (i.e. not after four hours of sleep).

The cortisol thing is interesting, and it no doubt has been shown to raise cortisol levels, but again, I have to ask: why doesn't the same thing happen with the sunlight, then? Even if I wake up (after a good night's sleep) and the sun is already up for an hour or so, I'm still groggy, lightheaded, and prone to fall asleep again. Shouldn't the sun have raised my cortisol levels as well? Or does the whole cortisol thing perhaps not matter as much as advertised?

I don't know. I still don't see how a device that simulates the sun is supposed to help me if the sun itself has no apparent effect whatsoever on my ability to get up in the morning.

This is probably in violation of somebody's terms of service somewhere, but back when these came out, I took a weekend and wrote a Python API for controlling Hue lamps. It abstracts the raw JSON away from the programmer, so turning a lamp on is as simple as saying

lamp.on = True

It works great for me. I wake up to a 45-minute sunrise simulation every morning.

it'd be great if somebody interfaces this with sleep monitoring alarm that's dime a dozen these days, granted, a paid app would have a pretty limited user base to sell to, so there's pretty low motivation to develop for the system, Phillips should encourage the community with rewards or something to kickstart the ecosystem

Frankly, one of the largest improvements in my QOL of late has been a dawn simulator alarm clock I purchased two years ago.

Is it really, though? I've tried the whole wake-up light thing as well, and like others, found that it did absolutely nothing for me. Which, really, I should have figured before buying one because when I sleep with the curtains open I don't wake when the sun is up either. I wake up before sunrise, at sunrise, well after sunrise, at whichever time my body feels like waking up, with no apparent cue from the sunlight in my bedroom.

I have to wonder if this whole "wake up by gradually turning on a light" thing really works, or if the positive stories I'm hearing about them are just people who really want them to work because they've bought into something and don't want to admit to themselves it was, perhaps, a waste.

I've been waking up to lights and an alarm for about 10 years. As long as I'm already starting to wake up, the lights are pleasant, gentle cue that the alarm will soon chime. However if I'm "passed out" I won't even notice them. I enjoy the lights gradually dimming to help me fall asleep about as much or more than helping me wake up.

I think if you actually wanted the lights to wake you out of sleep, you'd need a lot of really bright ones pointed right at your face. I like to bury myself in blankets and pillows so I'm pretty good at hiding from the light if I so choose.

The cortisol thing is interesting, and it no doubt has been shown to raise cortisol levels, but again, I have to ask: why doesn't the same thing happen with the sunlight, then? Even if I wake up (after a good night's sleep) and the sun is already up for an hour or so, I'm still groggy, lightheaded, and prone to fall asleep again. Shouldn't the sun have raised my cortisol levels as well? Or does the whole cortisol thing perhaps not matter as much as advertised?

I don't know. I still don't see how a device that simulates the sun is supposed to help me if the sun itself has no apparent effect whatsoever on my ability to get up in the morning.

If you really don't notice a difference between getting up before dawn and getting up after sunrise then I'm not surprised you don't notice a difference with wakeup lighting. As you say, the effect should be the same. There are a few possibilities here-

- you are naturally insensitive to the effect- your sleep environment has too much stray light in it for the effect to happen- the effect is enhanced by the placebo effect which was nullified by your lack of faith

It could be any combination of the above as well. That said, even if the effect were entirely placebo, which seems unlikely based on hormone cycle studies that have shown a clear physiological response (melatonin production as the lights dim and cortisol as the lights come back on), it can still have a meaningful effect on people's quality of life making the product worth it.

I want this system, likereallybad, but Hutchinson's first article convinced me to wait for better control. One of the main draws for this setup is the "alarm clock" capability. Waking up is just so much easier with ample light, and a gradually brightening room sounds like morning bliss. But having to 'set the alarm' every night is ridiculous.

The other major issue with the control.. err.. issue is the ability of others in the house to use the system. This system is a no-go in our house until all users can adjust the settings without pulling their hair out. I'm generally okay with frustration; my wife is not.

jamesmckenzie wrote:

I didn't have any problem at all.. I just thought it was funny how you called a gadget a "major part of your life". When I wake up, I just flip a switch and call it a day. I don't need any apps, API's, schedules and alarms to worry about, etc. etc. You see, life, in my opinion, shouldn't be about those things. Gadgets can be cool and fun and interesting, but a major part of ones life? ...seriously?