Skip to content

Latest commit

 

History

History
384 lines (277 loc) · 11.9 KB

readme.md

File metadata and controls

384 lines (277 loc) · 11.9 KB
Raw

💡 philips hue sdk

version downloads size github actions codecov typescript contributing contributors discord

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
💻 📖 ⚠️