Jump to content

Recommended Posts

DOF now has support for Philips Hue through PhilipsHueController and AutoConfigurator classes. Massive thanks to arngrim for providing example libraries to start with, and support in DOF Configtool for the Hue, and the I-Pac Ultimate I/O while I'm at it. Please note, this is a fork off the original R3 by lizardking / swisslizard as I've been adding ScheduledSettings, UIO support, tweaks to the I-PAC portion of DOF etc for some time now. Check the link below, and use the latest build if you're feelin' lucky.

Backup your entire DirectOutputFramework-directory before toying with this! I take no responsibility for issues, fire, damages, earthquakes etc.

Swisslizard: huge thanks for putting the project on GitHub. I love my I-PAC Ultimate I/O, and with the sources I was able to add in support for it. That is huge.

The Philips Hue family consists of Zigbee / wireless controlled lights, sensors, remotes etc. using a bridge (the Philips Hue "hub"). The framework supports auto detection and configuration of these units. Philips Hue is made and sold by Philips. The class was based off PacUIO.cs, and implementation makes use of Q42.HueApi. It retains the 3-channel RGB style inputs, but converts that over to a single-channel #rrggbb hex string. Pretty much like normal RGB-bulbs in a pincab. Technically a single bridge can control about 50 lights x3 = 150 input channels (sensors are additionally ~60). Distance is covered either directly, or through ZigBee device-hopping where signal travels along devices to reach the finale device. Each device acts individually, but a LED-strip cannot have its LEDs individually controlled; the entire LED-strip acts like a single RGB device, and will light up with the same color value.

Before DOF can start communicating with the bridge it will need a valid key. To get a key off the bridge the Link-button on the bridge needs to be pressed, and an dof#pincab "user" needs to be registered in the bridge (whitelist) within 30 seconds. This will return a unique key (for instance "2P4R5UT6KAQcpOjFaqwLDrbikEEBsMIHY6z6Gjwg") which can then be used from that point on. The same registration on another bridge, or even the same, will create a new key and is required if you want to crossfire/SLI two hubs for reducing latency per bridge as more bulbs on the same bridge will introduce latency.

To avoid duplicates / spamming the whitelist, and to avoid bugs crashing the bridge, currently this is the suggested approach for getting a key:

Step 1: set static IP to bridge
Get IP of the bridge. Check your phone Hue App -> Settings -> My Bridge -> Network settings. It should default to DHCP. Change this to a static IP, and make note of it, or check your router for IP.

Step 2: whitelist DOF using a browser
Open up the bridge API in a browser using your IP, example (replace IP with your static IP):

In the "CLIP API Debugger" it should say something like URL: "/api/1234/" with GET, PUT, POST, and DELETE-buttons.
Copy&paste the following line into URL-field (not in your browser, but in the CLIP API Debugger):


Copy&paste the following into the Message Body textfield:


Next, walk calmly over to your bridge and press the physical Link button. You now have 30 seconds to hurry back to your browser, and press "POST"-button. Prepare for a second ride.
Eventually you should get a username in the Command Response textbox, for example: "ywCNFGOagGoJYtm16Kq4PS1tkGBAd3bj1ajg7uCk". Make note of this.

If you need more help, or images, see the Philips Hue API getting started tutorial with screenshots and replace the text with your own. The Name can also be adjusted.

Step 3: add IP and key to Cabinet.xml
Open up your Cabinet.xml, and add the following lines in the OutputControllers section, replacing the IP and key with your own:


Step 4: add lights using http://configtool.vpuniverse.com 
A bridge can handle about 50 lights. Each light will multiplex RGB (3 channels) on each send, similar to using RGB-buttons on a PacLed64 or UIO. To match your output channels to a specific light, use your Android / iOS Philips Hue app and decide which light you need to control. Each light should have a number in it, for instance "10. Hue lightstrip 1". That 10-number is the light ID. Mapped to the individual RGB-outputs in DOF Config Tool port assignments this means: ((light ID -1) * 3) + 1 = ((10 - 1) *3) + 1 = 27 +1 = 28, resulting in port 28, 29, 30 (R, G, B).
If your light ID was 3, you'd map it to port 7, 8, 9.
If your light ID was 1, you'd map it to port 1, 2, 3.

If you want to delete the key from your bridge, open up CLIP URL again from the URL below, then enter the API-URL (replace both keys with your own, they're the same used twice), then press DELETE:

Shutdown of lights
DOF will shut down lights that have been affected, not the entire light array like an UIO or Teensy. If you have a house / apartment controlled by the same Hue bridge, it should only power down that one light or LED-strip that was affected when exiting a table. The feature was implemented as I found myself in complete darkness after quitting Attack from Mars way too often.

Latency :angry:
This is where things get complicated, and I try to cheat, trick and compensate for wireless issues. Signal communication is reduced as much as possible. Results will vary greatly. I'll try and detail what is going on, why, and how I tried through testing to compensate for it.

Latency in milliseconds varies depending on wireless distance and signal strength, device-hopping, LED affected (R, G, or B) and brightness. A worst case scenario would be to adjust all RGB-channels, including brightness. A connection takes a few hundred ms (done once at init using BridgeKey and BridgeIP), and color sends per-light about 40-800ms+. Typically about 100ms. The latency becomes the DOF Philips Hue bridge refresh rate. Note that Phlips Hue does support controlling a group of lights at the same time using the same color change (not individiaully controlled); I'm not doing that right now, everything is per-bulb.

The bridge will at worst case queue commands; this introduces more latency and inconsistencies (colors stuck, stuttery fades). To avoid overloading the bridge, DOF will check connection every 3s and use the last known latency as a transition time for the device to smooth out color changes much like TVs introduce frame interpolation from ~film to native panel refresh through synthesized pixel data. Color transition is a Hue API native command, and once set in motion adjust smoothly regardless of latency. The same latency (say 120ms) will become the DOF Hue refresh rate until the next connection check 3 seconds later, at which point the latency might be 300ms.

If latency at any time is below 100ms, this gets reset to 100ms to avoid overloading the bridge. In practice 50ms works, 40 even, for a while. Breathing room and bridge stability has absolute priority. If any color changes occur between refreshes it gets stored locally but not actually sent to the bridge / light until the next color change. This is where colors can get stuck until the next change if latency is also high when that happens.

Compensating for latency
Any off-states in either R, G or B channel uses a fade the amount of current latency. Any on-states from black in either R, G or B is sent instantly without a fade to attempt to have light on as soon as technically possible. Any R, G, B changes not 0 will transition using fade time the amount of current latency. Using Hue color transitions produces smoother pulsating LAUNCH-button for instance, or color changes in general. Without it colors would change inconsistently due to latency changes of 100, 400, 200, 800ms etc while trying to set the color in a varying time span. Using Hue transitions will attempt to smooth out those changes giving the bulbs something to do while DOF is fighting latency.


Practical use
Start with one light. Do some testing and benchmarks, and see how far you can push it.

First thing I did was crossfire / hook up two bridges and 17 devices; RGB, white, ambience, spots, two LED-strips. Then mapped them all to Undercab RGB complex in configtool. It was an interesting experience. 17 devices is 51 ports and about 6000 lumen. One bridge had 16 lights, the other 1 LED-strip. The single LED-strip was close to ~100ms and responded very well to changes, almost hiding latency completely. The other 16 lights were different; Hue will affect one light at a time when controlled individually, and in this case it took about 2 seconds for all lights to light up one by one. For undercab light, it wasn't bad, and the whole apartment flashed vividly, including the bedroom.

I then tried mapping all lights to left (red) and right (blue) flipper. Due to the quick changes, the lights could not keep up. Some commands were ignored as they were issued turn off commands before having a chance to light up.

Splitting the lights between the two bridges would have reduced latency, but the Hue API does have support for groups. This increases latency, but will attempt to sync and set all lights simultaneously instead of gradually for each command. Start with 1, take it from there.

arngrim suggested undercab light. It's a very good match with one of the newer +1000 lumen LED-strips.

Check your DirectOutput.log file for details if nothing works. It should say PhilipsHueController for those specific commands, whether connection was made, whether your IP and key was read of Cabinet.xml, and connection status so you can check your actual latency to the bridge after a game.

Wear and tear
The bulbs are not cheap. They will break a whole lot quicker being controlled like flashers. Use common sense. I take no responsibility for broken hardware, damages, risks, downtime, pissed off better halfs etc.

Example Config.xml attached, with some extra bonuses.



Link to comment
Share on other sites

  • 3 years later...
  • 2 weeks later...

I've got a Hue LED strip I no longer use so I'll follow the steps myself and report back. I have DOF installed for Future PInball at least but don't use it for anything yet. VPX was freezing compiling scripts with the plugin activated so I removed it but I should be able to do something with FP I guess. 

Link to comment
Share on other sites

Partially back from the dead, pincab is doing Netflixduty lately but I did try Attack from Mars (VPX). The Hue lightstrip undercab did light up, though on an older Philips hub. I haven't tried the ginormous apartment-wide 2-hub test again.

Thing is, I'm still using the same software. If I get some time this weekend I'll try and go 6000lumenstyle test again and see if it still works with 3 years of pending Hue Hub updates...

Link to comment
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

  • Create New...