Home

Awesome

Hue Dashboard

What's this?

Hue Dashboard is a web application for comfortably controlling Philips Hue lights from any device with a browser.

What is Hue?

Hue Logo

Hue is Philips' product range of "smart" light bulbs and switches. Hue devices use ZigBee Light Link mesh networking to communicate. Part of the Hue system is a bridge which connects the Hue devices to the network. The bridge offers both an integration into Apple's HomeKit framework and its own REST / HTTP / JSON API. There's a growing number of apps, home automation systems and 3rd party ZigBee devices working with Hue.

Screenshots

Accessing the web interface from an iPhone:

Web Interface Web Interface

And the same on the iPad:

Web Interface

Another view on a Mac desktop browser:

Web Interface

Features

Web Interface

Web Interface

Web Interface

Web Interface

Web Interface

Innr Logo

Web Interface

Web Interface Web Interface

Web Interface

Web Interface

Web Interface

Implementation

Hue Dashboard is implemented in Haskell, talking to the Hue bridge through its REST API using http-conduit. The web interface is done using threepenny-gui and blaze-html. Bootstrap and jQuery are used client-side.

Also see the project page on Blitzcode.net.

Installation

Compiling

This project uses stack, so build with

stack build

and run with

stack exec hue-dashboard

If you've never build a Haskell application before and have nothing prepared on the system, the complete list of steps on OS X would be something like this, assuming you have at least Homebrew and Git setup:

brew install haskell-stack
git clone https://github.com/blitzcode/hue-dashboard.git
cd hue-dashboard
stack setup
stack build
stack exec hue-dashboard

A note for Windows users: It seems like there currently is an issue with dynamic linking. Simply remove the -dynamic flag from ghc-options in hue-dashboard.cabal.

Setup

Like any Hue API application you'll have to authorize access to your bridge by pushlinking. On startup, the program will discover your bridge IP address and prompt you to press the button on your bridge when running the first time. Subsequent runs will restore this and other configuration details from the created config.yaml.

After startup navigate to http://localhost:8001 with your browser to view the dashboard. Be advised that the dashboard might also be visible to others on the network.

There's also a range of command line options to customize behavior:

Usage: hue-dashboard [OPTION...]
  -p PORT     --port=PORT              network port (default: 8001)
              --localhost              only bind to localhost
  -i SECONDS  --poll-interval=SECONDS  bridge poll interval (default: 1)
  -b IP       --bridge-ip=IP           manually specify Hue bridge IP address
  -t LEVEL    --trace-level=LEVEL      execution trace level (default: i)
                                         n = none
                                         e = errors only
                                         w = warnings and errors
                                         i = infos, warnings and errors
              --trace-file=FILE        output file for execution trace (default: none)
              --trace-no-color         no ANSI colors for trace output
  -e          --trace-no-echo          disable echo execution trace to stdout
              --trace-append           append execution trace file instead of overwriting
              --trace-http             trace web server events
  -h          --help                   print usage information

Groups

The groups displayed are based on a prefix word. So 'Kitchen Ceiling' and 'Kitchen Table' will be put into the 'Kitchen' group. You might need to rename your lights to take full advantage of this feature, but the naming convention works well for other reasons (like unique light names for HomeKit) as well. Custom grouping schemes or the build-in groups / rooms of the Hue system are not supported yet.

Compatibility

This program was developed on OS X 10.10 (also tested on Ubuntu 16.04 LTS and Raspbian) with a v2 Hue bridge (the square HomeKit one) and a current (2016) firmware with a selection of original Hue lights / switches and OSRAM LIGHTIFY products. It's of course possible that an older / newer bridge and other 3rd party lights will not work correctly as no testing with them has been performed.

The program traces a lot of information and all errors / warnings to the console, please look for any error messages if things don't work as expected.

Vagrant

One option to get this running quickly is to utilize Vagrant with VirtualBox to setup hue-dashboard with all of its dependencies in an Ubuntu 16.04 Virtual Machine rather then install everything on your Linux/Mac/Windows machine directly.

Install both Vagrant and VirtualBox and then just run vagrant up. The server will come up on the same port 8001 as normal and will be accessible at http://127.0.0.1:8001. There are some instructions inside /Vagrantfile on how to allow other computers to access the virtual machine.

Raspberry Pi

Raspberry Pi

The server for Hue Dashboard needs to live somewhere, and a small ARM machine is an obvious choice if you don't already have a PC running 24/7 in your home. The state of Haskell on ARM is rather unsatisfactory at the moment, so here's a list of steps that worked for me. Hue Dashboard itself has very modest needs, the only real challenge is getting it build. It might be easier to build on an emulator like QEMU or perhaps by renting a cheap ARM VPS with more RAM, but this guide will focus on building on the actual Raspberry Pi.

Update: There's now a Haskell Stack binary for ARM and newer versions of GHC resolve many of the bugs described here. Looks like there is hope that soon deploying Hue Dashboard on ARM will be as straighforward as x86, making many of these steps obsolete

/usr/bin/ld.gold: warning: cannot scan executable section 1 of /home/pi/.cabal/lib/arm-linux-ghc-7.10.3/filelock-0.1.0.1-0GuYZFry5kL0ASYgccAvYE/libHSfilelock-0.1.0.1-0GuYZFry5kL0ASYgccAvYE.a(Flock.o) for Cortex-A8 erratum because it has no mapping symbols.

Looks like a GHC bug, see here and here. To work around this we have to build everything with --disable-library-stripping --disable-executable-stripping and / or set executable-stripping: False + library-stripping: False in Cabal's ~/.cabal/config.

Building stack-1.1.0...
Preprocessing library stack-1.1.0...
[53 of 86] Compiling Stack.Constants  ( src/Stack/Constants.hs, dist/build/Stack/Constants.o )
src/Stack/Constants.hs:291:7:
    cannot find normal object file `dist/build/Stack/Types/PackageName.dyn_o'
    while linking an interpreted expression

Also see this bug report. The workaround is to invoke cabal build with --ghc-options=-dynamic-too.

#!/bin/sh
cd /home/pi/hue-dashboard/
exec .stack-work/dist/arm-linux/Cabal-1.22.5.0/build/hue-dashboard/hue-dashboard 2>&1

TODO

There's a large amount of TODO comments around the code, pointing out potential bugs and limitations, recording my thoughts for future improvements.

Related Projects

If you want to have a very visible alarm telling you when your website or internet connection goes down, please also see my Hue Watchdog project.

Alarm

Abuse those inexpensive Amazon Dash Buttons to control your Hue Lights, please also see my Hue Dash project.

Button

Legal

This program is published under the MIT License.

Author

Developed by Tim C. Schroeder, visit my website to learn more.