Pair your Hue bridge

Prerequisites

• A Hue Bridge gen 2 or newer — the square bridge, or the Hue Bridge Pro (2025). Old round bridges do not support the Entertainment streaming API. Bridge Pro needs v1.5.4 or later; see Bridge Pro pairing below.
• Bridge and LumaSync machine on the same local network.
• Bridge firmware up to date (auto-updated by the Hue app — just open it once if you haven’t recently).
• At least one Entertainment Area configured. Haven’t done that? Jump to Entertainment Area first, then come back.
• Physical access to the bridge for a few seconds — pairing requires pressing its link button.

The four steps

LumaSync’s Hue onboarding walks through four named stages. The pairing tracker at the top of the Hue panel shows where you are:

1. Discover — find the bridge on the LAN
2. Pair — press the physical link button to authorize the app
3. Area select — pick an Entertainment Area on the bridge
4. Ready — credentials saved, stream tested, Hue path armed

Step 1 · Discover

Open Settings → Hue → Pair bridge.

From v1.5.0, LumaSync’s primary discovery path is mDNS — it browses _hue._tcp.local. on the LAN through a shared mDNS responder (the same responder that powers WLED discovery). Philips’s public discovery endpoint (https://discovery.meethue.com/) acts as a cloud fallback if mDNS doesn’t resolve. Bridges on the network show up within a couple of seconds.

If the list stays empty:

• Manual IP path: click Enter IP manually, type the bridge’s LAN IP (find it in the Hue app → Settings → My Hue system → your bridge). LumaSync verifies the address by fetching the bridge’s config endpoint before letting you continue. Loopback, multicast, and broadcast addresses are rejected up-front — from v1.5.4 the stream-readiness check applies the same IPv4 guard the rest of the onboarding endpoints already used, so a hand-typed address can never point the readiness probe somewhere off-LAN.
• Discovery blocked: corporate firewalls or guest VLANs often block mDNS and the cloud endpoint. Manual IP still works in that case — you bypass discovery entirely.

Step 2 · Pair

LumaSync hits the bridge’s pairing endpoint once a second. Bridges respond with HUE_PAIRING_PENDING_LINK_BUTTON until the physical link button is pressed, then immediately issue a credential in response to the next request.

What you do:

1. Walk to the bridge.
2. Press the round button on the top.
3. Within 30 seconds, the UI flips to Pairing successful — no extra interaction needed.

Error codes (v1.4+)

From v1.4, the CLIP API’s error.type is split into four distinct codes, each with its own localized message instead of the generic HUE_PAIRING_FAILED:

Code	What it means	What to do
LINK_BUTTON_NOT_PRESSED	The 30-second pairing window elapsed before the button was pressed	Click Try again, press the button faster
DEVICETYPE_INVALID	The bridge rejected the client identity LumaSync sent	Rare — reboot the bridge, then retry
BRIDGE_BUSY	Another app is already mid-pairing with the same bridge	Close the other Hue client (Hue app, Hue Sync Box app)
RATE_LIMITED	Too many pairing attempts in quick succession	Wait 60 seconds, then retry

Retries are free — the bridge has no lockout once the underlying cause is cleared.

Up to v1.5.3, LINK_BUTTON_NOT_PRESSED was rendered on the device card as “Auth error — your credentials have expired”, which pointed at a credential problem that did not exist. From v1.5.4 it lands on the awaiting-link-button state it always should have: press the button and retry.

From v1.5.0, the bridge username and PSK land in your OS keychain — macOS Keychain, Windows Credential Manager, or Linux Secret Service (gnome-keyring / KWallet) — not in the JSON config file. Existing v1.4 installs migrate transparently from the previous plaintext shellStore on first launch of v1.5.0+; the migration is idempotent and downgrade-safe. LumaSync performs no network calls outside your LAN — the Hue bridge’s cloud account is never touched. To invalidate a credential, revoke from the Hue app at any time (Settings → My Hue system → paired apps); the bridge treats LumaSync as a regular third-party client.

Bridge Pro pairing (v1.5.4)

The Hue Bridge Pro serves its local API over HTTPS only — port 80 is closed. LumaSync’s CLIP v1 calls (bridge verification, pairing, credential validation) were hardcoded to plain HTTP up to v1.5.3, so on a Bridge Pro they failed at the transport layer before the bridge ever saw them. Discovery still worked, because it runs over mDNS and the cloud endpoint, which made the failure look like a credential problem rather than an unreachable endpoint.

From v1.5.4 these calls try HTTPS first and fall back to plain HTTP only when the TLS attempt fails at the transport layer. Square gen 2 bridges answer on both ports, so they are unaffected and keep pairing exactly as before — no re-pairing, no configuration change.

If you are on a Bridge Pro and pairing fails with Auth error / Credentials expired, you are on v1.5.3 or earlier. Update from the Download page and pair again.

Step 3 · Area select

LumaSync calls the CLIP v2 Entertainment Configuration endpoint and lists every Entertainment Area on the bridge. Pick one. Each area becomes a distinct LumaSync channel map — switch areas anytime without re-pairing.

If the list is empty (HUE_AREA_LIST_EMPTY), you haven’t created one in the Hue app. Open Hue app → Settings → Entertainment areas → Create. Drop the bulbs you want LumaSync to drive into it, position them on the room diagram, and save. Return to LumaSync and click Refresh list.

Step 4 · Ready

LumaSync runs a readiness check:

• Can it open a DTLS 1.2 PSK session to the bridge on UDP port 2100?
• Do the selected Entertainment Area channels report a valid position?
• Does a tiny test frame round-trip under 50 ms?

If all three pass, the status pill flips to Ready and the Hue target is available as a sink in mode selection.

Re-pairing

The bridge occasionally rotates credentials after firmware updates. LumaSync’s health check detects this and surfaces a Repair Hue credentials banner. Click it and walk back through steps 2–4 — step 1 skips because the IP is already known.

What LumaSync stores

Only what’s needed to stream:

• Bridge username + PSK — in the OS keychain (macOS Keychain / Windows CredMan / Linux Secret Service), retrieved via the keyring Rust crate’s platform abstraction.
• Bridge IP, identifier, selected Entertainment Area UUID, channel position overrides — in ~/.config/lumasync/app.json.

Nothing goes to a cloud. The Hue app’s cloud account is not touched — pairing is LAN-only, and after pairing the bridge is reached only via mDNS or its static LAN IP.

Related

• Entertainment Area — what it is and how to create one
• Hue troubleshooting — when things don’t work