I love Hue – A Requirements Specification (Addendum to the Hue Review)

[Update Feb 15, 2014: As time has progressed most of this specification is now redundant. The Hue doesn’t yet manage animations on the Bridge, and I’m not sure it will in the near future, but the rest of it is pretty thorough. I’ll leave this article up for historical purposes, but beware it’s mostly redundant now]

[Update Late 2013: I’ve been poking through the Hue API and it seems a lot of this is possible through the 1.1 version of the API. I will be investigating and seeing if I can make my own controller app]

After writing my extensive Hue review, I couldn’t help but think of what I wanted out of my system, so I came up with this list.

This is a public list of requirements for a useful Hue system. Any developers are welcome to take this list and use it as a feature set checklist for any program they are developing to control the Hue. If you do, and you find this list helpful, it would be nice if you acknowledged my contribution somewhere. Also, if you develop anything that does the majority of these things, please let me know so that I can GIVE YOU MY FUCKING MONEY.


  • Bulb: The core Hue hardware device that comprises an individually configurable lighting unit in the Hue system.
  • Bridge: A basic server for a set of Bulbs, as provided by Philips in the Hue Starter Kit.
  • Master Bridge: The ideal core management server. This is distinct from the provided Starter Kit Bridge, which is fucking useless. Only a single Master Bridge can exist on a network, and it manages configuration for the Bridges. The Master Bridge server is able to provide a list of currently connected ControllersBulbs and Bulb Sets as well as a list of owned Bulbs for a given Bridge. Most Hue systems will only ever have a single Bridge managed by the Master Bridge. Note: the provided Bridge is not capable of this level of configuration management. The Master Bridge is a custom server that sits between the Philips Bridge and a Controller.
  • Bulb Set: A subset of Bulbs connected to a given Bridge. A Bulb Set has a collection of Scenes and always has an active Scene selected, and optionally an active Transition. If a Bulb Set has an active Transition, the Bulb Set’s active Scene will be equal to the Transition’s End Scene and the Bulb Set will have a ‘Transition Start TimeStamp’ equal to the time the Transition was assigned to the Bulb Set.
  • Scene: a configuration object of individual Bulb settings for a given Bulb Set.
  • Off: When relating to Bulb Sets, Off is a Scene belonging to every Bulb Set, where each Bulb is set to brightness 0. This is the default active Scene for each Bulb Set. When relating to individual Bulbs, Off simply means that their brightness is set to 0.
  • On: When relating to Bulb Sets, On is a Scene belonging to every Bulb Set, where each Bulb is set to the default Hue ‘On’ settings (I believe this is full brightness and a warm yellow colour). When relating to individual Bulbs, On means that their brightness and colour is similarly set to the Hue defaults.
  • Transition: A configuration object describing a change from one Scene to another Scene, over a given Duration. The Start or End Scene can be Off. The Duration can be 0.
  • Duration: a specified time period used to manage a Transition.
  • Trigger: A configuration object that describes under what conditions Bulb settings should transition.
  • Controller: An application used to change configuration settings on a given Bridge and to issue commands to that Bridge. If a Controller is location-aware (eg. iPhone), it can be used as a target to create geofencing conditional triggers.

Basic Architecture

  • Configuration and management Information should be stored and managed on the Master Bridge, with the controller apps purely interfacing to the Master Bridge, which in turn controls the Hue bulbs via their respective Bridges.
  • No settings or configuration of ANY type should be stored on the controller apps at all. They are merely a display that shows all connected controller apps the information provided by the Master Bridge about the connected Hue bulbs.
  • Fundamentally, the Master Bridge is a management and translation layer that sits over the top of the Philips Hue API. It manages bulb grouping and transitions, and translates the high level custom commands issued by a Controller into Hue API compatible commands to the respective Bridge.

Core System Management Features

  • Display all bulbs on the network (this is not the same as all bulbs connected to the Bridge, but merely a list of bulbs on your local WiFi network’s IP range). Selecting one of these bulbs gives all information about the bulb, including current settings, owner Bridge, firmware version, and IP.
  • Display all Bridges on the network (selecting a Bridge lists the same kind of information as selecting a bulb, where appropriate)
  • Display all bulbs owned by the selected Bridge
  • Display all bulbs connected to the Bridge (if you’ve read my review, this list is a SUBSET of the owned bulbs list)
  • Change ownership of a selected bulb to a selected Bridge (or simply clear the owner if that’s easier)
  • Select any number of bulbs belonging to a given Bridge and group them into a Bulb Set. Note: It’s perfectly acceptable to limit Bulb Sets to bulbs on a given Bridge. Multi-bridge bulb grouping is expecting a little bit too much.
  • Be able to name and rearrange the Bulb Sets on a given Bridge, and select identifying icons or assign images to the groups that will be displayed as identifiers on any attached controllers.

Core Bulb Configuration Features

  • Create a Scene:
    • Select an existing Bulb Set and configure the individual bulbs in that set to a given colour and brightness.
    • A Preview toggle (default off) allows you to view your edits in real time.
    • Save.
  • Select an existing Scene and edit, as above.
  • Create a Transition:
    • Select a Start Scene and End Scene (the default Start Scene is ‘Current Setting’, or the current state of Bulbs affected by the End Scene. 
    • Select a Duration (this describes how long it takes to transition from Start Scene to End Scene). 
    • Save.
  • Select an existing Transition and edit, as above.

Basic Hue Controlling Commands

  • Activate a Scene. This will set all Bulbs in the Scene’s Bulb Set to the configured values for that Scene.
  • Activate a Transition. This will activate the Transition’s Start Scene (or do nothing if the Start Scene is ‘Current Settings’) and transition its Bulb settings to match the End Scene over the Duration. Note: The Start Scene and End Scene may have different Bulb Sets. The transitioning process will affect the union of all Bulbs in the Start and End Scene Bulb Sets appropriately. This may mean that some Bulbs transition from Off to their final configuration, or vice versa.
  • Deactivate a Bulb Set. This sets the Bulb Set’s active Scene to Off (technically, it creates a temporary Transition with Start Scene ‘Current Settings’, End Scene Off and Duration 0, and assigns it to the Bulb Set).
  • Deactivate all Bulbs. All Bulb Sets for the Controller’s Bridge will be Deactivated.
  • Activate a Bulb Set. This sets the Bulb Set’s active Scene to On (technically, it created a temporary Transition with Start Scene ‘Current Settings’, End Scene On and Duration 0, and assigns it to the Bulb Set).
  • Activate all Bulbs. All Bulb Sets for the Controller’s Bridge will be Activated.
  • Change Brightness for a Bulb Set or Scene. All Bulbs in the selected Bulb Set or selected Scene’s Bulb Set have their Brightness adjusted as indicated.

Note: all these commands are issued to the Bridge by a Controller via the Master Bridge and executed sequentially. A Bulb Set can only have a single active Transition, and a new Transition will overwrite the previous command immediately to ensure responsiveness from the Hue system.


Follow these steps to configure a Trigger object for a Bridge:

  • A Trigger has a Condition and a Start Scene, End Scene and Duration. If a Transition is linked to a Trigger, these last three values are derived from the Transition.
  • Select a Transition or End Scene or Bulb Set.
    • If you selected a Transition, the trigger will have a Start Scene, End Scene and Duration preset from the Transition.
    • If you selected a Bulb Set, select a Scene belonging to that Bulb Set (default On).
    • For the selected Scene, select a Duration (default 0).
    • Unless preset by selecting a Transition, the Start Scene defaults to ‘Current Settings’.
  • Select one of the following conditions:
    • By schedule: Select a Start Time and Frequency to activate the trigger.
    • By locationFrom the list of location-aware Controllers connected to a given Bridge, select a single Controller, a geofencing location, a fence radius, and ‘arriving’ or ‘leaving’. ‘Arriving’ is true when the selected Controller is marked as being outside the geofencing location and subsequently becomes marked as being inside the geofencing location. ‘Leaving’ is true when the selected Controller is marked as being inside the geofencing location and subsequently becomes marked as being outside the geofencing location.

The Master Bridge monitors the condition value of all Triggers on a periodic basis. Whenever a Trigger’s condition becomes True, the Transition associated with that Trigger is activated. If no Transition is associated with that Trigger, a temporary Transition is created from the Start Scene, End Scene and Duration assigned to that Trigger, and is then activated by the Master Bridge.

Some Words

This is a fairly technical, and in places repetitive, list of requirements. I think it’s sufficient to describe a kick-ass management server for Hue, though. Although it doesn’t extend to some of the cool things that can be done with Hue, like colour animations affected by ambient sound input, it certainly describes a fully functional and graceful automated home lighting system.

With this kind of functionality, a home owner can smoothly select and transition lighting for rooms in their home, either on-demand or using conditional triggers. To add remote web triggering functionality some collaboration needs to happen between the Master Bridge and a web triggering service like ‘If This, Then That’. This Hue system will require its own IFTTT channel. The existing IFTTT Hue channel will not be able to support this system as described, because it is not aware of the Master Bridge.

Object Overview

This is a list of objects described in the document above, and some of their properties. It’s just a shortcut to help anyone thinking of implementing this in an OO paradigm. There will undoubtedly be more properties against these classes, but I’m running this off the top of my head.

Master Bridge

  • Collection of Controllers
  • Collection of Bridges


  • Active Bridge
  • Location Aware: Y/N
  • Current Location: Long/Lat Coords (A location aware controller should report its location to the Master Bridge at regular intervals. This will allow the Master Bridge to manage location based triggers as described below).


  • Collection of Owned Bulbs
  • Collection of Connected Bulbs
  • Collection of Bulb Sets

Bulb Set

  • Collection of Bulbs
  • Collection of Scenes
  • Active Scene
  • Active Transition
  • Transition Start Timestamp


  • Current Brightness
  • Current Colour
  • Owning Bridge
  • Owning Bulb Set


  • Bulb Set
  • Collection of Bulb Settings (one for each Bulb in the Bulb Set)

Bulb Setting

  • Bulb
  • Brightness
  • Colour


  • Start Scene (can be null, indicating ‘Current Setting’ of all Bulbs in the ‘Affected Bulbs’ collection
  • End Scene
  • Duration
  • Collection of Affected Bulbs (union of Bulbs in StartScene.BulbSet.Bulbs and EndScene.BulbSet.Bulbs)


  • Condition
  • Transition
  • Start Scene (set from Transition if possible)
  • End Scene (set from Transition if possible)
  • Duration (set from Transition if possible)

Timer Condition

  • Owning Trigger
  • Trigger Time
  • Trigger Frequency/Schedule (eg. first Friday of every Month/every Monday, Tuesday, Friday)
  • Triggered: Y/N (given the current time, am I triggered?)

Geofenced Condition

  • Owning Trigger
  • Owning Controller
  • Geofence Coordinates
  • Geofence Radius
  • Movement: Arriving/Leaving
  • Armed: Y/N (the condition becomes armed based on the owning Controller’s position in relation to the triggering movement. eg. If the trigger is watching for ‘Arriving’, the condition becomes armed if the Controller’s position is ever outside the Geofence and the condition is not already armed. If the trigger is watching for ‘Leaving’, the condition becomes armed if the Controller’s position is ever reported inside the Geofence and the condition is not already armed.)
  • Triggered: Y/N (given the Owning Controller’s current position, am I triggered? eg. If the trigger is watching for ‘Arriving’, the condition becomes triggered if the Controller’s position is inside the geofence and the condition is armed. If the trigger is watching for ‘Leaving’, the condition becomes triggered if the Controller’s position is outside the geofence and the condition is armed.)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.