Philips Hue Bridge

The Philips Hue driver controls Hue lights, rooms, and zones through the local CLIP v2 REST API on the Hue Bridge V2 (square model). All traffic stays on the LAN — no cloud account required for control.

Status

Pairing, on/off, dimming, scene recall, and polling are implemented against the published Hue developer documentation. Color and color-temperature setpoints are best-effort and may need per-light gamut tuning. Push updates via the bridge event stream are not yet implemented; state is polled on a configurable interval (default 5 s).

Prerequisites

• Philips Hue Bridge V2 (square footprint). The round V1 bridge is not supported by CLIP v2.
• Bridge firmware 1948086000 or newer.
• Bridge and the GEM controller on the same LAN (the bridge advertises mDNS as _hue._tcp).
• Physical access to the bridge to press the link button during pairing.

Setup

1. Find the bridge IP. Use one of:
   • The Hue app: Settings > My Hue System > Bridge.
   • https://discovery.meethue.com (returns bridges visible from your public IP).
   • Your router's DHCP table (look for "Philips Hue").
2. Create a device in System > Devices with driver philips_hue. Set the ip attribute. Leave application_key blank.
3. Press and release the round button on top of the Hue Bridge.
4. Within ~30 seconds, run the pair_bridge command from the Script Console:

   await gem.command({device: <device_id>, action: 'pair_bridge'});

   On success, the returned application key is stored encrypted as the application_key attribute and the driver re-connects automatically.
5. Run get_lights to enumerate lights:

   await gem.command({device: <device_id>, action: 'get_lights'});

   Each entry has an id (UUID resource id) and metadata.name. The id is what you use as the GEM zone address.
6. Create a zone per light in System > Zones. Set address to the light's id (UUID). For a Hue room or zone group, prefix the address with group: (e.g. group:1a2b3c4d-…).

Attribute reference

Device attributes

Attribute	Type	Required	Description
ip	string	yes	LAN IP of the bridge.
application_key	string (secure)	for control	Bearer token returned by pair_bridge. Sent as hue-application-key header.
port	int	no	HTTPS port. Default 443.
status_interval	int	no	Poll interval in milliseconds. Default 5000.
devicetype	string	no	Identifier sent during pairing. Shown in the Hue app as the application name. Default gem-controller#default.

Zone address format

Address pattern	Targets
<uuid>	A single Hue light (CLIP v2 light resource).
group:<uuid>	A Hue room or zone group (CLIP v2 grouped_light resource).

The UUID comes from the id field in get_lights / get_groups output — not the legacy id_v1 numeric id.

Commands

Command	Args	Description
on	address	Turn light/group on.
off	address	Turn light/group off.
set_level	address, level (0-100)	Set brightness. Implicitly turns on at level > 0.
set_color	address, hue (0-360), saturation (0-100)	Set xy color. Lights without color capability ignore.
set_color_temp	address, mirek (153-500)	Set color temperature. Lights without ct capability ignore.
recall_scene	scene_id	Activate a Hue scene by its rid.
get_lights	—	List all lights on the bridge.
get_groups	—	List rooms and zone groups (grouped_light resources).
get_scenes	—	List scenes.
get_bridge	—	Bridge metadata (model, swversion, etc.).
pair_bridge	—	Mint a new application key. Press the link button first.

State polling

On every poll cycle, the driver fetches /clip/v2/resource/light and updates each mapped GEM zone:

GEM zone attribute	Source on Hue light
state	on.on → 'on' or 'off'
level	dimming.brightness (0-100, rounded to int)

Group polling (writes to zones with group: addresses) is on the roadmap but not yet implemented.

Known limitations

• No event-stream subscription yet. State changes from physical Hue dimmers or third-party apps are picked up on the next poll, not pushed in real time. The bridge supports server-sent events at /eventstream/clip/v2; adding it is a follow-up.
• Color conversion is approximate. set_color converts HSV → sRGB → CIE xy without per-light gamut clamping. Wide-gamut lights (Hue Color) reproduce slightly differently than narrow-gamut models.
• Group polling not yet writing back. group: addresses can be controlled but their reported state is not yet read back into zone attributes.
• CLIP v1 not used. Older bridges (round V1) are not supported by this driver.

Troubleshooting

Symptom	Check
pair_bridge returns "link button not pressed"	Press the round button on top of the bridge, then call pair_bridge within ~30 seconds.
401 unauthorized on every request	The application_key is missing or has been revoked from the Hue app. Run pair_bridge again to mint a new one.
Connection refused / TLS error	Verify port 443 is reachable from GEM to the bridge. The bridge serves a self-signed cert which the driver tolerates, but corporate firewalls that MITM-strip TLS will break the connection.
Zone state never updates	Confirm the zone address is the resource id (UUID) from get_lights, not the legacy numeric id_v1 or the human-readable name.
Brightness changes don't take effect	The bridge requires on:true to also be set when ramping up from off. The driver does this automatically — if it's still failing, run get_lights and verify the light is reachable (status: 'connected').
pair_bridge succeeds but driver still shows disconnected	Check the device log for the follow-up connect cycle. The driver re-connects automatically after pairing; if it doesn't, toggle the device disabled/enabled.

Related

• Devices
• Zones
• Macros — script gem.command(...) calls against Hue lights.