Philips Hue: "Just Press the Link Button"

in Philips Hue, Solved, Bug, Debugging, Mitmproxy, iOS

A while ago I decided to upgrade my power level (read: laziness level) by getting myself some of those awesome Philips Hue lights. The concept is equally amazing: You plug in some Hue bulbs, connect something called a Hue Bridge to your network, download the app and you're good to go. Or so they say.

Unfortunately for me, things did not go as smoothly. Setup was straight forward and everything connected as it should, but the moment I had to 'Link' my phone to the Hue Bridge, it simply didn't do anything. It showed a draining progress bar (indicating a timeframe to press the Link button on top of the Bridge), and automatically dismissed the wizard afterwards as if I didn't finish the process in time.

Not willing to give up, the first thing I did was try again and mash the button rapidly during the actual process. Of course, this didn't make any difference, so I decided to check the internet. As expected, there were a wide variety of people with similar symptoms:

While these are obviously only a few examples, hours of searching and attempting things didn't seem to bring me any closer to the solution. If anything, the longer I searched, the more it seemed like the system wasn't compatible with my Network due to my Airport Time Capsule router not supporting UPNP.

At a certain stage, I decided searching wasn't getting me anywhere, so I manually started debugging things by swapping each of the machine's cogs one by one, followed by checking the result within the app. Here's what I tried:

  • Switched the LAN-cable between my network and the Hue Bridge
  • Reconfigured the network
  • Dusted off and tried an old router I still had laying around.
  • Made sure everything was running the latest software version (obviously)
  • Checked the MeetHue nUPNP page, which reported the bridge being visible on my network
  • Manually enter the IP Address of the Bridge into the app (on the 'Help' page)
  • Did (multiple) Factory Resets and reinstalls of the app.

Nothing seemed to help. Nothing. Even a completely different network didn't work.
Something must be broken, but what?!

At this point, I had finally given up, and decided to look at the App Store reviews. Perhaps it's a bug introduced into the latest software version? This is when the Philips Hue Gen. 1 app caught my eye. I didn't expect it to do anything, as I own a Generation 2 device (and bulbs), but since I had tried just about everything by now, I decided to download it and give it a shot..

Instantaneously, it sprang to life. What the actual fuck is going on here.

At this point, I had come to a simple conclusion, one I could have (and probably should have) figured out way earlier: The current generation app is broken.

While the Gen. 1 app worked, I had mixed feelings about this. For starters, I clearly didn't have a circular Gen.1 Bridge device, and more or less every part of the app was begging me to upgrade to the new app, ironically promising me an improved experience that will work with the hardware I already own.

So, I created a Philips Lighting support ticket, and went on with my day.

Philips Lighting Support.

A day or so after creating the Support ticket, a (friendly) customer service rep. called Dennis contacted me. He asked me some of the basic things I'd also ask my grandma if she'd be calling with computer problems: "Are all indicator lights lit?", "Is your iPhone connected to the same WiFi network?", "Is your Router on a 2.4GHz or 5GHz band, or perhaps both?" (Well, okay, maybe I wouldn't ask my grandma that last one).

After answering all of his questions and supplying him with info he'd probably be asking next (to cut the crap and move on to the actual problem), one of his colleagues contacted me and asked me to do a factory reset, because he wanted to be sure it wasn't a software-related issue. Obviously I had already done this, so a swift reply was sent.

At this point I guess Philips was also out of ideas, because it took them almost a week to reply to me. Not just that, but once they did, the only thing they asked me to do was a series of power cycles. This (of course) didn't solve the problem either, after which I gave up with support, and decided on simply getting a proper third party app to use (I chose iConnectHue).

A second attempt

A few months go by, and yesterday I'm talking to a colleague of mine which just the other day had bought an iPhone. Somehow, we ended up discussing Philips Hue, at which point I brought up how impossibly broken the official app is. Somewhat surprised, he told me that setup worked instantaneously for him, and he even showed me the app working on his phone. "Never had a single issue with it", he said.

Because it was a Friday, and because I kind of wanted it to just work on my phone as well, I decided to give it another shot. This time, though, I wasn't going to leave it to chance: I grabbed MitmProxy from the toolshed once again, and configured my iPhone to pipe all network traffic through it.

Seconds in, I saw the following:

To a certain extent, this surprised me. I expected it to scan for bridges on multiple IP-Addresses, but what I saw here is that it was successfully connecting to my Bridge, followed by repetitive requests that eventually stopped due to the Link button timeout.

So, obviously, I decided to take a better look at one of those requests.

Alright, so far so good: According to the Official Hue API docs, it tries to create an API user and expects a API token in return (something that's only allowed when clicking the Link button). From thereon forward, this API token is used to communicate with the Hue Bridge, and is stored somewhere in the app on your phone, after which setup is complete.

But then why did it keep sending the same type of request?!

"body contains invalid json".

On first sight, this does not make any sense, as my colleague's phone was set up properly using the same app just a few days ago, and I've tested the API today and know with certainty that it works. Besides, the only thing it's really sending is the name of my iPhone so it ca—OH!

Let me take a step back there: In my case, my iPhone's name is デッカー・クラウディオのiPhone (Claudio Dekker's iPhone, written in Katakana, a Japanese character set). As it turns out, the official Philips Hue app doesn't properly escape iPhone Device Names with "foreign" characters in them. This causes the underlying software to crash and return an error message: body contains invalid json.

At this stage, though, the app isn't really expecting any error, so it simply re-sends the request again, and again, and again, until at some point either the setup succeeds, or time runs out and you're returned to the "main" screen, seemingly as-if you've never clicked the "Link" button.

Working around the issue

Since the App 'trades' the device name for an API token (which it uses from thereon forward), the issue seems to be limited to only the initial set-up screen.

As such, on my iPhone, I went to Settings -> General -> About -> Name and changed my iPhone's name from デッカー・クラウディオのiPhone to TestHueiPhoneFix (something with regular 'Latin' / 'Roman' characters) and gave it another shot. Straight away, I saw the following in mitmproxy:


When I looked away from my Macbook screen back to my iPhone, the app was already configured and I could finally use it. I switched back my iPhone's name to what it was before (デッカー・クラウディオのiPhone), and even after killing and cold-booting the app, it was still working as expected.


January 28th, 2017 - Bug discovered and Reported with Philips Support (NL)
January 30th, 2017 - Issue forwarded to Philips Lighting Developers

(Note to developers: If you have further updates and support didn't forward my email address, just send a response to blog at