Elixir Hue SDK 💡

An unofficial Elixir SDK for the Philips Hue personal wireless lightning system.

Build with Finch, Jason, Mdns, and NimbleOptions.

Features

HueSDK ships with the following features:

• Automatic discovery of the Hue Bridge device on local networks
• Complete support of the latest Hue Bridge JSON REST API
• SSL support for requests made to the Hue Bridge device

Automatic Bridge Discovery

HueSDK supports automatic bridge discovery via the following protocols:

• N-UPnP
• mDNS
• Manual IP

If you have already connected your Hue Bridge device to the internet and registered online with Philips, then N-UPnP will be the fastest and most reliable way to discover your device.

If you do not wish to connect your Hue Bridge device to the internet or register it with Philips, then mDNS can be used to discover your device.

If neither of those protocols work, you can manually enter the IP address of your Hue Bridge device via the Manual IP protocol. Consult your home router to identify the device's IP address.

REST API

HueSDK supports the following resources:

• Lights
• Groups
• Schedules
• Scenes
• Sensors
• Rules
• Configuration
• Resourcelinks
• Capabilities

Currently, this library provides a simple Elixir wrapper over the Hue Bridge REST API. Please refer to the official documentation for detailed information on interacting with lights, groups, schedules, etc.

High-level Elixir APIs may be added in future versions. If you have any you would like implemented, please open an issue or pull-request!

Installation

Add the Hue SDK to your mix.exs and run mix deps.get:

def deps do
  [
    {:hue_sdk, "~> 0.1.0"}
  ]
end

Add any optional configuration to your config/*.exs files:

use Config

# disabling SSL
config :hue_sdk, ssl: false

# specifying a custom N-UPnP host
config :hue_sdk, portal_host: "mycustomproxy.com"

Usage

Automatically discover your Hue Bridge device available on your local network:

{:nupnp, [bridge]} = HueSDK.Discovery.discover(HueSDK.Discovery.NUPNP)

Press the link button on your Hue Bridge device and authenticate a new user:

bridge = HueSDK.Bridge.authenticate(bridge, "connorlay#huesdk")

Make requests to the Hue Bridge REST API:

HueSDK.API.Lights.get_all_lights(bridge)

{:ok,
 %{
   "1" => %{
     "capabilities" => %{
       "certified" => true,
       "control" => %{
         "colorgamut" => [[0.6915, 0.3083], [0.17, 0.7], [0.1532, 0.0475]],
         "colorgamuttype" => "C",
         "ct" => %{"max" => 500, "min" => 153},
         "maxlumen" => 800,
         "mindimlevel" => 200
       },
       "streaming" => %{"proxy" => true, "renderer" => true}
     },
     "config" => %{
       "archetype" => "classicbulb",
       "direction" => "omnidirectional",
       "function" => "mixed",
       "startup" => %{"configured" => true, "mode" => "safety"}
     },
     "manufacturername" => "Signify Netherlands B.V.",
     "modelid" => "LCA003",
     "name" => "Floor Lamp",
     "productid" => "Philips-LCA003-1-A19ECLv6",
     "productname" => "Hue color Lamp",
     "state" => %{
       "alert" => "select",
       "bri" => 145,
       "colormode" => "xy",
       "ct" => 443,
       "effect" => "none",
       "hue" => 7675,
       "mode" => "homeautomation",
       "on" => false,
       "reachable" => true,
       "sat" => 199,
       "xy" => [0.5016, 0.4151]
     },
     "swconfigid" => "598716A0",
     "swupdate" => %{
       "lastinstall" => "2021-01-27T22:48:41",
       "state" => "noupdates"
     },
     "swversion" => "1.76.6",
     "type" => "Extended color light",
     "uniqueid" => "00:17:88:01:09:4c:a7:29-0b"
   },
   # ...
  }
}

Additional Resources

• The Hue Developers forum.
• The Hue API documentation.

Acknowledgments

To the authors of Huex and Yet Another Hue API, which served as inspiration for HueSDK.

To the maintainers of Finch, Jason, Mdns, and NimbleOptions for their ongoing efforts.

To Philips and Signify for creating the Hue Lighting system and opening the REST API for developers.