WLED cannot connect with Hue Pro Bridge (Sync Interface)

[DataFran]

What happened?

I recently upgraded to a Hue Pro Bridge, and when attempting to sync WLED to a Hue light I get a "Hue Status: Inactive" message.

To Reproduce Bug

In sync settings, add the bridge pro IP address, light number, etc. press the touchlink button and click "save".

Expected Behavior

Syncing between WLED and a given hue bulb

Install Method

Binary from WLED.me

What version of WLED?

WLED 15.3

Which microcontroller/board are you seeing the problem on?

ESP32

Relevant log/trace output

Anything else?

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[softhack007]

@coderabbitai please research the web for documentation of the API provided by Philips Hue Pro bridge, and compare to Hue bridge V1 API implemented in wled00/hue.cpp. Are there differences that explain why the user cannot connect to HUE Pro, while it seemed to work with a normal HUE bridge?

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Read the wled00/hue.cpp file to understand the current Hue API implementation
cat wled00/hue.cpp

Length of output: 5021

---

🌐 Web query:

Philips Hue Pro bridge API documentation differences from V1

💡 Result:

Key Hue Bridge API v2 (CLIP v2) differences vs API v1 (CLIP v1)—as you’ll see in the docs and on the wire:

• Base URL / routing

  • v1: endpoints are under /api/<username>/… (the “username” is created by link-button pairing). [1]
  • v2: endpoints are under /clip/v2/resource/… (for example /clip/v2/resource/bridge). [2]

• Auth / credentials placement

  • v1: the credential is embedded in the URL path (/api/<username>/…). [1]
  • v2: you send the credential as an HTTP header: hue-application-key: <key> (created via the same link-button flow, but then used as a header). [2][3]

• Resource model + identifiers

  • v1: resources are mostly numeric IDs per collection (e.g., /lights/1). (Implied by the v1 URL structure in the official get-started examples.) [1]
  • v2: resources are typed and use UUIDs (e.g., …/light/<uuid>), and commonly include id_v1 back-references like "/lights/6" to help migration. [2][4]

• Response shape

  • v1: returns “raw-ish” JSON objects/lists per endpoint (no standard data wrapper in the basic examples). [1]
  • v2: responses are typically wrapped in { "errors": [...], "data": [...] }. [2][4]

• Events / push updates

  • v1: largely polling-based for state changes (many integrations historically poll).
  • v2: adds Server-Sent Events (SSE) for proactive state change events (faster status updates). [5][6]

• Feature availability (why v2 matters)

  • Newer capabilities (e.g., dynamic scenes, gradient/segment entertainment, and eventing) are called out by Signify as part of the “new Hue API” direction, with new features landing on v2. [5][6]

• Transport / discovery changes called out in the v2-era docs

  • HTTPS-only direction: Signify notes v2 doesn’t support HTTP (and broader removal of HTTP support is being rolled out). [5][7]
  • Discovery: UPnP is deprecated; mDNS and discovery.meethue.com are the recommended approaches. [5]

• Hue Bridge Pro compatibility note (practical impact)

  • Some users report Bridge Pro breaks legacy integrations that rely on the v1 API (e.g., Ambilight+Hue setups), implying a v2-only (or at least v1-incompatible) environment for those integrations. Treat this as ecosystem evidence rather than formal API spec. [8]

Sources:
[1] Philips Hue Developer Program – “Get Started” (v1 examples showing /api/<username>/…) https://developers.meethue.com/develop/get-started-2/
[2] OpenHue API docs (v2 endpoints, header, UUID resources, {errors,data} response) https://www.openhue.io/api/openhue-api/bridge
[3] GitHub – create-hue-application-key (explains hue-application-key header usage) https://github.com/parasaurolophus/create-hue-application-key
[4] GitHub – hue-v2-api (example v2 payload with id_v1) https://github.com/niomwungeri-fabrice/hue-v2-api
[5] Philips Hue Developer Program – “New Hue API” announcement (v2 features, eventing, HTTPS-only note, discovery deprecation) https://developers.meethue.com/new-hue-api/
[6] openHAB Hue binding docs (notes v2 features like SSE and that new features are on v2) https://www.openhab.org/addons/bindings/hue/
[7] Philips Hue Developer Program homepage news excerpt (states deprecation of HTTP support) https://developers.meethue.com/
[8] Reddit thread reporting Bridge Pro omits v1 API / breaks Ambilight+Hue (ecosystem evidence) https://www.reddit.com/r/Hue/comments/1q6na0f/bridge_v2_flux_strip/

---

🌐 Web query:

Philips Hue Bridge Pro V1 API backward compatibility support

💡 Result:

Philips Hue Bridge Pro is not fully backward-compatible with the legacy Hue “API v1” ecosystem in practice:

• HTTP is not supported on Bridge Pro (HTTPS-only): Signify has been moving the local Hue API to TLS-only access, and the V2 API does not support HTTP (and V1 HTTP is slated to be blocked as well). Any “v1 API” integration that assumes http://bridge-ip/… will fail on Bridge Pro unless updated to HTTPS and/or the newer API. [1]
• Many integrations must migrate to the Hue API V2: App developers have explicitly reported that their integrations broke because they used the legacy v1 API and need to be rewritten for the v2 API to work with Bridge Pro. [2]
• Real-world symptom (example): Ambilight+Hue on older Philips TVs: Reports show Ambilight+Hue can’t find/work with Bridge Pro, with likely causes including the HTTPS requirement and device identification differences; the common workaround is to keep an older Bridge (v2) for that integration. [3]

Bottom line: If you rely on “API v1” (especially over plain HTTP), assume you need to update to Hue API v2 + HTTPS (or keep a Hue Bridge v2 alongside the Bridge Pro for legacy integrations). [1][3]

Sources:
[1] Philips Hue Developer Program – “New Hue API” (V2 API, HTTP→HTTPS notes) https://developers.meethue.com/new-hue-api/
[2] Sleep Cycle integration discussion (developer comment: legacy v1 API must be rewritten to v2 for Bridge Pro) https://www.reddit.com/r/sleepcycle/comments/1ovj3d4/hue_bridge_pro_and_hue_integration_broken/
[3] Hueblog – “Ambilight+Hue does not work with the Hue Bridge Pro” (HTTPS requirement noted) https://hueblog.com/2025/09/15/ambilighthue-does-not-work-with-the-hue-bridge-pro/

---

@softhack007, I've researched the Hue Bridge Pro API and compared it with WLED's implementation. Here are the critical differences that explain the connection failure:

Key Incompatibilities:

1. Transport Protocol (Primary Blocker)

• WLED (hue.cpp): Uses plain HTTP on port 80

  hueClient->connect(hueIP, 80);

• Hue Bridge Pro: Requires HTTPS-only, HTTP is not supported

2. API Endpoints

• WLED (V1 API):

  req += F("GET /api/");
  req += hueApiKey;
  req += F("/lights/");
  req += String(huePollLightId);

  Path structure: /api/<username>/lights/<id>

• Hue Bridge Pro (V2 API): Uses /clip/v2/resource/light/<uuid>

3. Authentication Method

• WLED (V1): Embeds API key in URL path (/api/<apikey>/...)
• Hue Bridge Pro (V2): Requires HTTP header: hue-application-key: <key>

4. Resource Identifiers

• WLED: Uses numeric light IDs (e.g., huePollLightId as integer)
• Hue Bridge Pro: Uses UUIDs for resources

5. Response Format

• WLED expects: Direct JSON objects/arrays from V1 API
• Hue Bridge Pro: Returns wrapped responses: { "errors": [...], "data": [...] }

Why Normal Hue Bridge Works:

The standard Hue Bridge (V2) still supports the legacy V1 API over HTTP, maintaining backward compatibility with existing integrations.

Why Hue Bridge Pro Doesn't Work:

Bridge Pro is not backward-compatible with V1 API. According to developer reports, integrations using the legacy V1 API must be completely rewritten for V2. This is similar to issues reported with Philips Ambilight+Hue setups that also can't connect to Bridge Pro.

Required Changes for Bridge Pro Support:

To support Hue Bridge Pro, WLED would need:

1. ✅ HTTPS/TLS support (replace AsyncClient with secure client)
2. ✅ V2 API endpoint implementation (/clip/v2/resource/...)
3. ✅ Header-based authentication (hue-application-key)
4. ✅ UUID-based resource addressing
5. ✅ V2 response parsing (handle errors/data wrapper)
6. Optional: SSE (Server-Sent Events) for real-time updates instead of polling

This is a significant architectural change, essentially requiring a complete rewrite of the Hue sync functionality.

Citations: [1], [2], [3]

[softhack007]

@DataFran sorry but the AI summary sounds like bad news to me.

If the Bridge Pro requires HTTPS and/or a new protocol, it might take long before WLED could support it. There were several attempts already to switch from HTTP to HTTPS, but they all ended with "you need an ESP32 with at least 8MB flash", so the standard esp32 4MB model seems too small for https and WLED and a filesystem with lots of presets and other files.

Additionally, integrating the new V2 API would need a complete re-write of hue.cpp, plus moving all hue communication buffers from stack to heap because JSON responses will not fit into 1KB buffers we use atm (a "killer" for 8266 hue support).

Other HUE related issues for reference:

• Hue Integration causes intermittent resets #2495
• Implement diyHue #40
• Hue sync makes WLED unstable #3083
• Possible to support Philips Wiz lights? #2111

[DataFran]

Bummer!
I was able to recreate much of my functionality via the WLED Homebridge plugin and automations, but I do regret upgrading to the Pro bridge, as it seems they've locked the system down considerably.

[softhack007]

If you still have the older HUE bridge, it might be possible to run them in both?

I've seen posts hinting at "using the non-pro bridge for integrations, and running the pro bridge in parallel".

[DataFran]

If folks have figured out how to do that, I'm all ears. I can't figure out how to add specific lights to the old bridge once the app is set up with an account/the new bridge.
The solution I think you're suggesting would be to add the lights I want to sync to specifically to the old bridge, and use them as normal. I did try that, but found it wasn't possible to define which bridge lights get added to.

[softhack007]

well I only did a quick research, so I can't give you much.

• search the internet for "HUE bridge PRO breaks existing integrations" or "HUE bridge PRO and non-pro in parallel".
• some sites say you should create two separate accounts, and use two instances of the HUE app (not user-friendly, but might work). Its important to keep the new bridge switched off when connecting lights to the old bridge.
• Multi-Bridge setups are possible, but not sure this solves the protocol problem
  • https://hueblog.com/2024/11/27/philips-hue-unlocks-multi-bridge-support/
  • https://www.androidauthority.com/philips-hue-multi-bridge-support-3504439/

[Jason2866]

Its dead Jim.

[netmindz]

Has a quick go at trying to vibe code a new usermod to handle V2

#5423