Hue Dashboard is a web application for comfortably controlling Philips Hue lights from any device with a browser.
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.
Accessing the web interface from an iPhone:
And the same on the iPad:
Another view on a Mac desktop browser:
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.
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
.
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
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.
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.
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.
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
2016-03-18-raspbian-jessie-lite.img
as the OS image, download from here or current version here. See this guide for how to write the SD card. You want at least a 16GB card, Haskell builds are largeraspberrypi
, user pi
password raspberry
. So ssh pi@raspberrypi
should work. If the host can't be found, check the DNS settings or just use the IP your router assignedsudo apt-get update
tar xf archive.tar
) and do the whole ./configure
/ make install
danceghc --version
sudo apt install libgmp-dev
ghci
should work, test thatapt
. It doesn't actually work, just produces executables that fail with a cryptic error. We need a version with a few bugfixes included, 3.5.2
. Download the bindist from the official LLVM download page (direct download link).rsync
it over /usr/local
so it's installed in the path. Verify with opt --version
sudo apt install git
and then git clone https://github.com/haskell/cabal.git
cabal-install
directory contains bootstrap.sh
for building Cabal without Cabal. It only works for releases though, so check out v1.22.8.0
/ 1352025e823536ac8c29a823a1ad33adccc86a04
firstEXTRA_CONFIGURE_OPTS="" ./bootstrap.sh
so it doesn't do a profile build as well~/.cabal/bin
directory, the script should tell you. Might also want to do a cabal update
and add the bin directory to your path, i.e. PATH="$HOME/.cabal/bin/:$PATH"
cabal install stack
is unlikely to work. We especially don't want to do it this way as any error discards the progress made and we have to start over. Start with cabal unpack stack
(v1.1.0 was used here)/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
.
cabal install --dependencies-only
-j1
) and passing heap options to GHC (--ghc-option=+RTS --ghc-option=-M500m --ghc-option=-RTS
). It's best to babysit the build a bit, monitor with a tool like htop
and restart / tweak options once it hits the 100MB swap file and everything grinds to a halt. But it should work, with a bit of patience.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
.
cabal install
to put Stack in the Cabal bin directory / pathgit clone https://github.com/blitzcode/hue-dashboard.git
. This guide was written when 164729ef0d28e749ccbfd135f0e3ea5ced8ca8f1
was the current revision, but it's probably best to try HEAD
stack build
should work. No special options required. Hue Dashboard itself builds relatively quickly, but the dependencies will require the same careful tweaking and babysitting as with building Stackstack exec hue-dashboard
that everything worksrun
script for the daemon might be easiest:
#!/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
sudo svc -u /service/hue-dashboard/
etc. always works. I can only conjecture that Hue Dashboard is being run before the network is fully initialized. Adding a sleep 5
at the beginning seems to fix this reliablyThere's a large amount of TODO
comments around the code, pointing out potential bugs and limitations, recording my thoughts for future improvements.
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.
Abuse those inexpensive Amazon Dash Buttons to control your Hue Lights, please also see my Hue Dash project.
This program is published under the MIT License.
Developed by Tim C. Schroeder, visit my website to learn more.