hlapp/node-hue.js

Node.js library for interacting with a Philips Hue bridge

Node Hue Module

This library aims to provide a simple interface to a Philips Hue bridge (http://www.meethue.com/).

A Hue bridge requires your 'app' to register with the bridge. This process involves a user pressing the link button on the hue, and your app making a request to its API to complete the process.

To install

npm install hue.js

To use

var Hue = require('hue.js');

Discover Hue Bridges

Hue.discover(function(stations) {

  console.log(stations);
});

Register your app

var client = Hue.createClient({
  stationIp:station, // 'x.x.x.x', retrieved from the previous step
  appName:appName // Any alpha numeric name for your app
});

client.lights(function(err,lights) {

  if (err && err.type === 1) {
    // App has not been registered

    console.log("Please go and press the link button on your base station(s)");
    client.register(function(err) {

      if (err) {
        // Could not register
      } else {
        // Registered, carry on
      }
    });
  } else {
    console.log(lights);
  }
});

Hue API

Hue.createClient(opts)

opts being stationIp ip address and an appName. Returns a hue client.

Hue.Discover([opts], cb)

Discovers hue bridges on your local network.

opts is optional and may be omitted

• opts.timeout: timeout to use for the UDP broadcast packet, defaults to 3000ms

Client API

client.register(opts,cb)

Attempt to register your app with the base station. opts has 4 optional properties.

• username - the username to register. Default to a md5 hash based upon the value of the appName configured when calling createClient
• deviceType - the device type to register. Defaults to the value of the appName that was set when calling createClient.
• interval - the amount of time to wait in milliseconds before attempting to register again. Defaults to 3000.
• attempts - the number of retry attempts before giving up. This will error out if registration was not successful. Defaults to 0.

client.unregister([username],cb)

Ungregisters (unpair) your app. All future calls will be unauthorised by the base station until your app is reregistered.

With the optional username parameter the username of the application that should be unregistered can be specified. This value defaults to the username of the current application that was determined when calling createClient.

client.config([opts],cb)

Fetch or if opts is specified update, the configuration of this base station. See here for a station's properties.

client.lights(cb)

Fetch the list of the lights associated with this base station

client.light(light,cb)

Fetch the state data about 1 light, light being its index received from client.lights(...)

client.state(light,state,cb)

Update the state of a light, light being its index received from client.lights(...) and state being an object with properties defined here

client.on(light,cb) client.off(light,cb)

Turn on/off that light, light being the index received from the client.lights(...)

client.rgb(light,R,G,B,cb)

Change the RGB colour of the light. Note 0,0,0, is not off.

client.rename(light,name,cb)

Change the light's name to the string name, where light is the index received from client.clients().