Connected appliances are my thing. I actually wrote a thesis about those suckers. Cool stuff and most likely the way of the future.

That also means that I felt almost obliged to buy the Phillips Hue -lights. They are ordinary light bulbs but you can control them from your phone or via Internet. But really, you could control the lights from any device, program or service that has the ability send HTTP requests.

Hue and Curl work well together

I would like to say, that I like my Phillips Hue -lights. But this is not an endorsement, payed review or anything of like that. Hue is cool but lightbulbs should not cost as much as Hue bulbs cost. Now that said, lets go to the meat of the matter.

HTTP is most commonly used in browsers, or at least it’s one of the more visible uses of the protocol. But browsers are not only programs capable of sending HTTP-requests.

One well known program that is capable of sending HTTP-requests is a command line program Curl. The manual page of curl says that “curl is a tool to transfer data from or to a server, using one of the supported protocols” and that “curl offers a busload of useful tricks like proxy support, user authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer resume, Metalink, and more.” According to Wikipedia, it was first released in 1997.

Phillips Hue -bulbs are controlled by a base station that sends commands to the lightbulbs. App the mobile apps and web apps that control Hue send their commands to the base station using HTTP. The base station provides very nice and clean RESTfull HTTP API. Look those terms up if you don’t what they mean. It’s interesting stuff. In the scope of this article, you don’t have to know what any of that stuff is, so no worries.

If you have not used the base station API directly before you need to know what is the IP-address of the base station. You also need to create a new authorized user on that base station.

So first the IP. If you have for instance the Hue iPhone App you’ll find the IP from your app’s settings. You could also log in to your router and hunt down the IP of the base station.

So now that you have the start your engines and open your command line application of choice now.

Type the following command:

curl -H "Accept: application/json" -X POST --data '{"devicetype":"test user","username":"newdeveloper"}' http://<bridge ip address>/api

It’ll give you an error and say “link button not pressed”. Go ahead and press the button on the base station. This will show the base station that who ever send that previous request has a physical access to the device and might as well give up and let that person control the base station. Now, that you have pressed the button send the previous curl-command again.

curl -H "Accept: application/json" -X POST --data '{"devicetype":"test user","username":"newdeveloper"}' http://<bridge ip address>/api

Now it’ll say “success”.

Note the part of the command that says -X POST. It tells the base station what HTTP verb we are using. Post is generally used when something new is created or posted. When you want to get some existing resource you use GET. If you want to change the state of something existing you will use PUT. Now, if you get tired of some resource waisting space, you can delete it using…wait for it…the DELETE -verb.

There is also the –data option. After it comes single quotes and curly brackets. Inside the brackets is “devicetype”:”test user” and “username”:”newdeveloper”. This style of notation is known as JSON and it’s quite commonly used by web apps to transfer data. The Hue API uses JSON for the same purpose. The JSON data part is where you set the values that you want to create or set in the base station.

So first lets GET some information about our base station.

curl -H "Accept: application/json" http://<bridge ip address>/api/newdeveloper/lights

Now you probably think I forgot the -X GET, but I didn’t. The GET is the norm, so omitting it is ok. For other verbs you need to use the -X option or also know as flag.

You should see the names of your light bulbs and any light bulb groups there are. Make a note of this result.

Lets turn of light bulb #1. Type the following to the terminal:

curl -H "Accept: application/json" -X PUT --data '{"on":false}' http://<bridge ip address>/api/newdeveloper/lights/1/state

Ok, lets turn bulb #1 back on. Type the following to the terminal:

curl -H "Accept: application/json" -X PUT --data '{"on":true}' http://<bridge ip address>/api/newdeveloper/lights/1/state

Note that we only changed the value on from false to true.

Now if you want to turn off or on the whole group of your lights you access the group resource. There should always be group number 0, which means all the lights.

To turn off all the lights, type the command:

curl -H "Accept: application/json" -X PUT --data '{"on":false}' http://<bridge ip address>/api/newdeveloper/groups/0/action

And to turn them all on, use the same command but change the on from false to true, like bellow.

curl -H "Accept: application/json" -X PUT --data '{"on":true}' http://<bridge ip address>/api/newdeveloper/groups/0/action

Make sure you put your quotation marks correctly. If you use double quotes then the JSON propperties need to be in single quotes and vice verse.

Enlighten Me More

I’m not going to go through the whole Hue API because there is a very good documentation on what HTTP verbs to use and what should the JSON-data contain to accomplish what you want. However, the hue developer portal requires registration. The registration is free, so if you are interested at all, I'd encourage you to register. More information at the official Hue API. I hope this post got you started.