Things you need to know

Brief notes to help write apps for hue


This is the process where the user presses the button on the bridge (proving he has physical access to the bridge) allowing the user to authenticate themselves.  Normally an app would display a helper image

Heartbeat/Bridge Resources Cache  (for Java/iOS sdk)

In the SDKS the Heartbeat runs at regular intervals in the SDK and at each interval the latest state of the lights, configuration etc, is collected from the bridge and stored in the Bridge Resources cache. This means all fetching of information is retrieved from the cache, not the bridge hence reducing the load on the bridge.

Transition time

When you set the light state, and update color, brightness etc., the light will not respond immediately because by default there is a transition time to the new state of 400 milliseconds. If you want the light to respond quickly to a state change, set the transition time in the light state to zero milliseconds. Read more

Number of commands you can send per second

You can send commands to the lights too fast. If you stay roughly around 10 commands per second to the /lights resource as maximum you should be fine. For /groups commands you should keep to a maximum of 1 per second.

Conflicting parameters

If you try and control multiple conflicting parameters at once e.g. {"ct":250,"xy":[0.5,0.5]} the lights can only physically do one, for this the following simple rule applies: xy beats ct beats hue, sat.

Positioning of lights

All the lights have to be in range. If you can control them from the hue app then you’re fine to play with them via the developer interface. Remember all lights act as a signal repeater, so if you want more range, put a light in between.

Don’t always send ‘ON’

Once you have sent the ‘ON’ attribute to a light, it will stay on. Do not repeatedly send the ‘ON’ command as this will slow the responsiveness of the bridge.

Using RGB colors

The hue API provides three options for setting color:

  • hue and saturation
  • xy in the CIE color space
  • ct the Mired Color temperature

If you would like to use RGB color in your app, you will need to translate to one of these color settings options. Our SDKs provide utility methods to do this or alternatively you can build your own. For more information on this refer to ‘Color gets more complicated’ in ‘Core Concepts’.

RESTful and other tools

There are multiple ways for your app to control the hue system. The hue API is a RESTful interface, which can be accessed by many languages. In addition, we provide SDKs for IOS, OSX, Java multi-platform and Android. Third party developers have created a number of other tools and SDKs for different languages. Refer to hue API documentation, IOS and OSX SDK, Java multi-platform and Android SDK, list of third party SDKs and tools.

Mood, complex mood, simple information, complex information

Everyone can understand that with color changing light you can create mood. With multiple color changing lights you can create subtle mood. What is less obvious is that lights can be used to signal information. One light can be used to signal simple information, and multiple lights can be used to signal complex information. It is also possible to use the changing of lights’ brightness, color, etc., over time to highlight events. A flashing light can of course indicate an event, and a change in brightness or color can indicate loading or emphasis.  

Notification and changing information over time. The various music apps for hue are a good demonstration of how you can use hue light dynamically. In this case they are used to synchronize with music.

The API is local

RESTful interfaces are normally located on the internet. The hue API in the bridge is local. That is to say, it is accessible on your local WiFi network and cannot be accessed directly outside that network. This also makes your hue system secure. The hue bridge, once installed on your network, will have its own IP address set up by your local router. This is the IP address you will use when sending commands to the RESTful API.

UPnP and finding the IP address of the bridge

The hue SDKs provide UPnP tools and UI to help with finding the address of the bridge on the local network. This uses UPnP.  If you don’t use the SDK you will need to find the IP address of the bridge. Here’s how: Getting Started, step 2 and using the hue app.

Remote access to hue (IFTTT)

It is planned that we will have a remote API for accessing hue across the Internet. For now the only option available is to use the IFTTT interface.

The debug tool in the bridge

Every bridge has a debug tool, which you can use directly to send API commands to the bridge and see results. This can be found at http://<bridge ip address>/debug/clip.html.

Using groups API vs lights API

When updating light attributes, unless there are a dozen or more lights it is generally more efficient to use the lights API. With larger numbers of lights, it can be more efficient to access them as a group, using the groups API.

Whitelisting, permission to access the bridge

The bridge secures access from apps by using a whitelist. To add your app to the whitelist you will need to request the bridge to do so and the push linking button must be pressed too. This is a way of securing access to the hue system and preventing apps that haven’t been given permission by push linking.

Hue can do for developers?

Here is a mind map overview

Hue can do for developers