Easy setup for Philips Hue apps

⛔ UNMAINTAINED

This library desperately needs a makeover, but 3rd party apps and integrations became good enough that I no longer see value in maintaining my own tooling.

Because bridge discovery is weird and so is attaining an API token.

It's published on npm.

$ npm install --save hue-connect

Now you can use it in your project. It works with ES Module syntax or plain ol' require.

// ES Modules
import discover from 'hue-connect'

// CommonJS
const discover = require('hue-connect')

The easiest way to use this module is using the hue-register command:

$ hue-register my-app-name > auth.json

Otherwise there's the programmatic approach. There are two functions exported from this module:

• discover(callback)
• Bridge

The main export from hue-connect is a function. Pass it a callback and it'll call it with every bridge it can find.

import discover from 'hue-connect'

const search = discover(bridge => {
  console.log('Found bridge:', bridge)
})

Once you no longer care about finding new bridges (like once you've attained a token), stop the bridge search using the .cancel() method.

const search = discover(bridge => {})

search.cancel()

Note: Bridge discovery works because this other module is amazing.

A bridge is a simple way to get an API token from a hue bridge.

If you know the bridge IP address already, you can skip discovery and create an instance directly.

Bridges are created automatically when using discover().

import { Bridge } from 'hue-connect'

const bridge = new Bridge({
  ip: '192.168.1.42',
})

Attaining an API token is pretty straightforward. Call the .connect method and it returns a promise. If the user pressed the bridge button, you get a token.

bridge.connect({
  appName: 'the-name-of-your-app',
  deviceName: 'the-computer-name-or-whatevs',
})

Note: It wants the app and device name because Hue likes that stuff. If you're just experimenting, you can make something up. But don't tell Hue I said that.

Assuming the user has pressed the button, the promise will resolve with your shiny new API token.

bridge.connect({
  appName: 'illumination',
  deviceName: 'bob',
}).then(token => {
  console.log('Awesome sauce!', token)
})

Otherwise the promise will reject horribly.

bridge.connect({ appName, deviceName }).catch(error => {
  console.log('Oh noes:', error.message)
  console.log('Secret error code:', error.code)
})

All the error codes are in this giant table, but you might need to create a hue account to see 'em. The most common is 101 which means the user is lazy and just hasn't pressed the button.

So you've seen all the docs. Here's an example to tie it all together.

This'll find all the local bridges and ping them once a second until the user presses the bridge button.

const discover = require('hue-connect')

const search = discover(getToken)

async function getToken (bridge) {
  try {
    const token = await bridge.connect({
      appName: 'enlightened',
      deviceName: 'bad-pun-generator',
    })

    console.log('Success!')

    console.log({
      bridge: bridge.ip,
      token: token,
    })

    // Stop searching for new bridges.
    search.cancel()
    process.exit(0)
  } catch (error) {

    // It's some weird error.
    if (error.code !== 101) {
      throw error
    }

    // User hasn't pressed the bridge button.
    // Try again in a second.
    setTimeout(getToken, 1000, bridge)
  }
}