Step 1: find the bridge
Check your router's DHCP list or Home Assistant's discovered integrations, and give the bridge a DHCP reservation. A cloud lookup page also exists (discovery.meethue.com), which lists bridges seen from your public IP, but it needs internet and is not needed if you know the IP.
Step 2: get an application key
Press the round link button on the bridge, then send the request shortly afterwards (the link button only stays active briefly). The bridge uses HTTPS with a certificate issued by Signify, so curl will complain. For a quick test on your own LAN you can add -k to skip verification (not for anything permanent):
Code: Select all
curl -k -X POST https://BRIDGE_IP/api -H "Content-Type: application/json" -d '{"devicetype":"jsh#test","generateclientkey":true}'Step 3: read resources
The v2 API sends the key in a hue-application-key header and lives under /clip/v2/resource. The spec lists resource types including light, grouped_light, scene, smart_scene, room, zone, device, motion, temperature and button:
Code: Select all
curl -k -H "hue-application-key: YOUR_KEY" https://BRIDGE_IP/clip/v2/resource/lightStep 4: control one light
The spec's example for updating a light is a PUT with an on object:
Code: Select all
curl -k -X PUT -H "hue-application-key: YOUR_KEY" -H "Content-Type: application/json" -d '{"on":{"on":true}}' https://BRIDGE_IP/clip/v2/resource/light/LIGHT_IDLimits: this is a request/response API suited to occasional control. For fast continuous effects such as syncing lights to video or music, Hue has a separate Entertainment API, and you should not hammer the normal one. Also, the spec lists status code 429 (too many requests), which means you are going too fast.
Step 5: Home Assistant
Home Assistant normally discovers the bridge. Otherwise go to Settings > Devices and services > Add integration > Philips Hue and follow the prompts, pressing the link button when asked. Useful notes from the HA docs:
- Rooms and zones become grouped light entities that are disabled by default. Enable the ones you want.
- Hue scenes are imported as scene entities, and V2 bridges get a Scene dropdown per room or zone. Create and edit scenes in the Hue app.
- Hue remotes such as the dimmer switch are stateless and fire hue_event events. You can watch them under Settings > Tools > Events (the docs say button events are rate-limited to one per second).
- There is a Philips Hue activate scene action with extra options such as dynamic mode and brightness.
The OpenHue project publishes an OpenAPI spec and a command line tool (openhue-cli) built on it, useful if you prefer a ready-made CLI to raw curl. Check its README for installation and current version.
Safety
Treat the application key as a secret, do not post it in forums or paste it into untrusted scripts, and if it leaks, look for a way to remove the app authorisation in the Hue app or bridge settings (I have not checked the exact steps). Keep the bridge on a trusted network and do not port-forward it.
Links
- OpenHue API specification
- openhue-cli
- Home Assistant Hue integration
- Hue developer portal (free login needed for the official docs)