Node-hue-api NPM

node-hue-api

An API library for Node.js that interacts with the Philips Hue Bridge to control Lights, schedules, sensors and the various other features of the Hue Bridge.

This library abstracts away the actual Philips Hue Bridge REST API and provides all of the features of the Philips API and a number of useful functions to control/configure its various features.

The library fully supports local network and remote internet access to the Hue Bridge.

Change Log
Installation
v3 API - new API introduced in 3.x versions of the library
Examples
Philips Hue Resources
License

Change Log

For a list of changes, please refer to the change log; Changes

Installation

Node.js using npm:

$ npm install node-hue-api

Node.js using yarn:

$ yarn install node-hue-api

v3 API

The V3 API is written to support JavaScript native Promises, as such you can use stand Promise chaining with then() and catch() or utilize synchronous async and await in your own code base.

Note that there are a number of runnable code samples in the examples/v3 directory of this repository.

Examples

The v3 APIs are documented using example code and links to more complex/complete examples for each API calls, consult the documentation links above.

Alternatively take a look at the examples directory in this repository for complete self contained runnable example code.

Discover and connect to the Hue Bridge for the first time

For getting started interacting with the Hue Bridge, you will need to discover and then connect to the Hue Bridge as an authorized user. To do this you need to either know the IP Address of the Hue Bridge in advance, or use the discovery features to locate it.

Once you know the IP Address of the Bridge, you need to create a user that is authorized to interact with the Hue Bridge, this is typically done by pressing the Link button on the bridge and then attempting to register a new user via code.

Below is example code that can be used to achieve this (using async/await to avoid nested Promises):

const v3 = require('node-hue-api').v3
  , discovery = v3.discovery
  , hueApi = v3.api 
;

const appName = 'node-hue-api';
const deviceName = 'example-code';

async function discoverBridge() {
  const discoveryResults = await discovery.nupnpSearch();

  if (discoveryResults.length === 0) {
    console.error('Failed to resolve any Hue Bridges');
    return null;
  } else {
    // Ignoring that you could have more than one Hue Bridge on a network as this is unlikely in 99.9% of users situations
    return discoveryResults[0].ipaddress;
  }
}

async function discoverAndCreateUser() {
  const ipAddress = await discoverBridge();

  // Create an unauthenticated instance of the Hue API so that we can create a new user
  const unauthenticatedApi = await hueApi.createLocal(ipAddress).connect();
  
  let createdUser;
  try {
    createdUser = await unauthenticatedApi.users.createUser(appName, deviceName);
    console.log('*******************************************************************************\n');
    console.log('User has been created on the Hue Bridge. The following username can be used to\n' +
                'authenticate with the Bridge and provide full local access to the Hue Bridge.\n' +
                'YOU SHOULD TREAT THIS LIKE A PASSWORD\n');
    console.log(`Hue Bridge User: ${createdUser.username}`);
    console.log(`Hue Bridge User Client Key: ${createdUser.clientkey}`);
    console.log('*******************************************************************************\n');

    // Create a new API instance that is authenticated with the new user we created
    const authenticatedApi = await hueApi.createLocal(ipAddress).connect(createdUser.username);

    // Do something with the authenticated user/api
    const bridgeConfig = await authenticatedApi.configuration.get();
    console.log(`Connected to Hue Bridge: ${bridgeConfig.name} :: ${bridgeConfig.ipaddress}`);

  } catch(err) {
    if (err.getHueErrorType() === 101) {
      console.error('The Link button on the bridge was not pressed. Please press the Link button and try again.');
    } else {
      console.error(`Unexpected Error: ${err.message}`);
    }
  }
}

// Invoke the discovery and create user code
discoverAndCreateUser();

The complete code sample above is available from here.

For more details on discovery of Hue Bridges, check out the discovery API and referenced examples along with the users API.

Set a Light State on a Light

Once you have created your user account and know the IP Address of the Hue Bridge you can interact with things on it. To interact with light on the Hue Bridge you can use the following:

const v3 = require('node-hue-api').v3;
const LightState = v3.lightStates.LightState;

const USERNAME = 'your username to authenticating with the bridge'
  // The name of the light we wish to retrieve by name
  , LIGHT_ID = 1
;

v3.discovery.nupnpSearch()
  .then(searchResults => {
    const host = searchResults[0].ipaddress;
    return v3.api.createLocal(host).connect(USERNAME);
  })
  .then(api => {
    // Using a LightState object to build the desired state
    const state = new LightState()
      .on()
      .ct(200)
      .brightness(100)
    ;
    
    return api.lights.setLightState(LIGHT_ID, state);
  })
  .then(result => {
    console.log(`Light state change was successful? ${result}`);
  })
;

For more details on interacting with lights, see the lights API and LightState documentation and examples referenced within.

Using Hue Remote API

This library has support for interacting with the Hue Remote API as well as local network connections.

It is rather involved to set up a remote connection, but not too onerous if you desire such a thing. The complete documentation for doing this is detailed in the Remote API and associated links.

Philips Hue Resources

There are a number of resources where users have detailed documentation on the Philips Hue Bridge;

The Official Phillips Hue Documentation http://www.developers.meethue.com
Hue Hackers Mailing List: https://groups.google.com/forum/#!forum/hue-hackers
StackOverflow: http://stackoverflow.com/questions/tagged/philips-hue

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this library except in compliance with the License.

You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.