💡 philips hue sdk

Philips Hue SDK for managing smart devices.

📦 Installation

This package is hosted on npm.

npm install @bradgarropy/hue-sdk

🚦 Setup

In order to use the Philips Hue API you must have a Philips Hue Bridge installed. You need the ip address and a user account to send commands to the bridge.

Locate the ip address by navigating to https://discovery.meethue.com in a web browser. This should respond with an array of all discovered bridges on your wifi network, typically there will only be one. You'll see the ip address in the json object which we will call the HUE_BRIDGE_IP.

[
    {
        "id": "001728fdfe70920f",
        "internalipaddress": "192.168.84.129"
    }
]

Then navigate to https://<BRIDGE_IP_ADDRESS>/debug/clip.html. Use the API Debugger to create a new user as follows.

url:    /api
method: POST
body:   {"devicetype": "<USERNAME>"}

You should receive a response with the message "link button not pressed".

Now go press the large button on top of your Philips Hue Bridge, then send the same command again. You should get back a success message with a username property, this will be the HUE_USERNAME.

You can find more information on the Philips Hue Developer Get Started page.

🥑 Usage

Now that all of the setup is done, here's how to send your first command to the bridge. Use the HUE_BRIDGE_IP and the HUE_USERNAME from the Setup section above to initialize a Hue client.

const Hue = require("@bradgarropy/hue-sdk")

const hue = new Hue(process.env.HUE_BRIDGE_IP, process.env.HUE_USERNAME)
const lights = await hue.readLights()

console.log(lights)

📖 API Reference

Hue(ip, username)

Name	Example	Description
ip	"192.168.84.129"	Philips Hue bridge ip.
username	"bradgarropy"	Philips Hue bridge username.

const hue = new Hue("192.168.84.129", "bradgarropy")

hue.readLight(id)

Name	Example	Description
id	"abc123"	Light id.

Get all information for a specific light.

hue.readLight("abc123")

hue.readLights()

Get all information for all lights.

hue.readLights()

hue.updateLight(id, state)

Name	Example	Description
id	"abc123"	Light id.
state	{on: false}	Light state.

Update a light's state.

hue.updateLight("abc123", {on: false})

hue.turnOnLight(id)

Name	Example	Description
id	"abc123"	Light id.

Turn on a specific light.

hue.turnOnLight("abc123")

hue.turnOnLights(ids)

Name	Example	Description
id	["abc123", "def456"]	Array of light ids.

Turn on multiple lights.

hue.turnOnLights(["abc123", "def456"])

hue.turnOnAllLights()

Turn on all lights.

hue.turnOnAllLights()

hue.turnOffLight(id)

Name	Example	Description
id	"abc123"	Light id.

Turn off a specific light.

hue.turnOffLight("abc123")

hue.turnOffLights(ids)

Name	Example	Description
id	["abc123", "def456"]	Array of light ids.

Turn off multiple lights.

hue.turnOffLights(["abc123", "def456"])

hue.turnOffAllLights()

Turn off all lights.

hue.turnOffAllLights()

hue.blinkLight(id, interval, count)

Name	Required	Default	Example	Description
id	true		"abc123"	Light id.
interval	false	500	750	Time (ms) between blinks.
count	false	1	5	Number of blinks.

Blink a specific light.

hue.blinkLight("abc123")
hue.blinkLight("abc123", 750)
hue.blinkLight("abc123", 750, 5)

hue.blinkLights(ids, interval, count)

Name	Required	Default	Example	Description
id	true		["abc123", "def456"]	Array of light ids.
interval	false	500	750	Time (ms) between blinks.
count	false	1	5	Number of blinks.

Blink multiple lights.

hue.blinkLights(["abc123", "def456"])
hue.blinkLights(["abc123", "def456"], 750)
hue.blinkLights(["abc123", "def456"], 750, 5)

hue.setBrightness(id, brightness)

Name	Example	Description
id	"abc123"	Light id.
brightness	128	Brightness level (1-254).

Set the brightness of a specific light.

hue.setBrightness("abc123", 128)

hue.setBrightnesses(ids, brightness)

Name	Example	Description
id	["abc123", "def456"]	Array of light ids.
brightness	128	Brightness level (1-254).

Set the brightness of multiple lights.

hue.setBrightnesses(["abc123", "def456"], 128)

hue.setColor(id, color)

Name	Example	Description
id	"abc123"	Light id.
color	"blue"	Light color.

Set the color of a specific light.

Colors must be chosen from a preset list.

• random
• white
• red
• orange
• yellow
• green
• blue
• purple
• lime
• teal
• pink

hue.setColor("abc123", "blue")

hue.setColors(ids, color)

Name	Example	Description
id	["abc123", "def456"]	Array of light ids.
color	"blue"	Light color.

Set the color of multiple lights.

Colors must be chosen from a preset list.

• random
• white
• red
• orange
• yellow
• green
• blue
• purple
• lime
• teal
• pink

hue.setColors(["abc123", "def123"], "blue")

setRandomColor(id)

Name	Example	Description
id	"abc123"	Light id.

Set a specific light to a random color.

hue.setRandomColor("abc123")

setRandomColors(ids)

Name	Example	Description
id	["abc123", "def456"]	Array of light ids.

Set a multiple lights to a random color.

hue.setRandomColors(["abc123", "def456"])

colorLoopLight(id, duration)

Name	Required	Default	Example	Description
id	true		abc123	Light id.
duration	false	infinity	60000	Duration (ms) of color loop.

Color loop a specific light.

hue.colorLoopLight("abc123")
hue.colorLoopLight("abc123", 60000)

colorLoopLights(ids, duration)

Name	Required	Default	Example	Description
id	true		["abc123", "def456"]	Array of light ids.
duration	false	infinity	60000	Duration (ms) of color loop.

Color loop multiple lights.

hue.colorLoopLights(["abc123", "def456"])
hue.colorLoopLights(["abc123", "def456"], 60000)

❔ Questions

🐛 report bugs by filing issues
📢 provide feedback with issues or on twitter
🙋🏼‍♂️ use my ama or twitter to ask any other questions

✨ Contributors

Brad Garropy 💻 📖 ⚠️ 🚇

willparr 💻 📖 ⚠️