Skip to content →

Philips Hue Control

Philips’ Hue lighting system allows you to control the lighting in your home from a mobile app, or from any application you write yourself that can connect to the internet. The center of the system is the Hue hub, an Ethernet-connected device that communicates with compatible lamps through the ZigBee HA radio protocol. Philips makes a range of Hue-compatible lamps, and the GE Link lamps also work with the Hue system. Each Hue hub is its own HTTP web server, and can be controlled using the Hue REST API. There are libraries to control the Hue available in many programming languages. The tutorials here are all in client-side JavaScript using P5.js, or server-side using node.js, or micrcontroller-based for Arduino.

For a detailed introduction to the Hue, se the hue-control repository. The notes below are a summary of some of the finer points from that repository

Connecting To the Network

All the Hue hubs ITP owns should be on the network, but if not, check with Marlon Evans.

To find the Hue’s MAC address, look on the bottom. If it’s a Hue Hub 1, there should be a three-byte address like so:  aa:bb:cc:dd:ee:ff. If it’s a Hue Hub 2, there will be a six-character address like this: 1A2B3C. The hub’s MAC address will be that number preceded by 00:17:88, e.g. 00:17:88:1A:2B:3C.

If you’re on the same subnet as the hue (in other words, you’re on the wired ethernet subnet, not the wireless subnets), you can use the command line to discover it. Send a broadcast ping to the subnet,  like so:

Then use arp to find it. You know it will start with 0:17:88, so you can do this:

You should get a result like this:

Details found at these links:

Connecting to the hub

Once you’ve got the hub’s address, you need to create a user on the hub. Go to http://<hub’s address>/debug/clip.html. Philips’ Getting Started With the Hue API guide will explain how, and help you get going.

To set up a new user, press the hub button, then immediately send the following using the debug interface:

  • URL: /api
  • Method: POST
  • Body: {“devicetype”:”your_netid”}

You should get a reply including a new user ID like so:

That’s the username you’ll need from now on. It will be associated with your netID in the hub.

Control of the Hue Hub

Here is a repository of examples on controlling the Hue Hub from node.js or client-side JavaScript. Start with the client example, it’s the simplest to understand, especially if you don’t know node.js. You can just open the index.html file in a browser locally and it’ll run.

Adding Hue Bulbs

If you’ve got a new Hue bulb, just give it power and do a search for new bulbs from the debug tool as described in the Getting Started with the API guide. Here’s the command for the debug interface:

  • Url: /api/<your username>/lights
  • Method: POST
  • Body: empty

You should get a reply like this:

If your (not so new) bulb won’t show up in the new lamp search, it may have been previously claimed by another hub. You can “steal” it back by using the debug tool. Place your lamp within 30cm of the hub, power it, and  and enter the following:

  • Url: /api/<your username>/config
  • Method: PUT
  • Body: {“touchlink”:true}

Adding GE Link Bulbs

GE Link bulbs can be added to a Hue hub. To do so, first put the bulb in a working socket and turn it on. Then turn it on and off again every three seconds until it blinks once. This should take about five on-off cycles. When the bulb blinks, run the new light discovery routine on the hub, and the hub should discover and claim the bulb.

Command Line Control

Since the Hue is controlled entirely by HTTP requests, you can use the command line tool curl to control it. For example:

To get a list of all the lights:

To search for new lights:

To list discovered lights:

To “steal” a light for your hub:

To turn a light on:

Arduino Control of Hue Lights

The MKR1000 and MKR1010 Arduino models can control the Hue hub via HTTP requests as well. There are some Arduino Hue examples, with notes, in the repository of examples as well.

Compatibility Guide

iConnecthue has a good guide to compatible third party products.