💡 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