Hue Light Choreographer

Drive Philips Hue lights through the bridge's own REST API. One curl pattern, four resource types: lights, groups, scenes, and schedules.

When to Use

• User says "turn off the living room lights" or "dim the bedroom to 20%"
• User wants a warm sunset scene or a specific RGB color on a bulb
• User wants a routine like "bright at 7am, dim at 11pm" via the bridge schedule
• User wants to know what lights/groups/scenes exist on the network

Do not use for: Zigbee-level automation or scenes that need motion sensors outside Hue — keep to the bridge API. Also avoid for non-Hue Zigbee bulbs that the bridge cannot see.

Procedure

1. Find the bridge on the LAN (or ask the user for its IP):

curl -s https://discovery.meethue.com/ | jq -r '.[0].internalipaddress'

2. Mint an API key. Press the physical link button on the bridge, then within 30 seconds:

curl -s -X POST http://BRIDGE_IP/api \
  -H 'Content-Type: application/json' \
  -d '{"devicetype":"seoproagent#desktop"}'
# -> [{"success":{"username":"ABC123..."}}] ; save the username as HUE_USER

3. Enumerate resources:

export HUE=http://BRIDGE_IP/api/$HUE_USER
curl -s $HUE/lights | jq -r 'to_entries[] | "\(.key) \(.value.name) on=\(.value.state.on)"'
curl -s $HUE/groups | jq -r 'to_entries[] | "\(.key) \(.value.name)"'
curl -s $HUE/scenes | jq -r 'to_entries[] | "\(.key) \(.value.name)"'

4. Set a bulb state (on, brightness, color). Brightness is 0–254; hue 0–65535; sat 0–254; ct in mireds (153 warm … 500 cool):

curl -s -X PUT $HUE/lights/3/state \
  -H 'Content-Type: application/json' \
  -d '{"on":true,"bri":200,"sat":0,"ct":350}'

5. Command a whole room/group — same payload, group scope:

curl -s -X PUT $HUE/groups/2/action \
  -H 'Content-Type: application/json' -d '{"on":true,"bri":80}'

6. Recall a saved scene and put the room back to normal later:

curl -s -X PUT $HUE/groups/2/action \
  -H 'Content-Type: application/json' -d '{"scene":"SCENE_ID"}'

7. Schedule a routine — create a timer that fires a group action at a clock time (RCTime format "PT07:00:00"):

curl -s -X POST $HUE/schedules \
  -H 'Content-Type: application/json' \
  -d '{"name":"morning-bright","localtime":"PT07:00:00","description":"wakeup","command":{"address":"/api/'$HUE_USER'/groups/2/action","method":"PUT","body":{"on":true,"bri":254}},"status":"enabled"}'

Reference

| Endpoint | Method | Purpose | |---|---|---| | /lights | GET | list bulbs | | /lights/{id}/state | PUT | single bulb control | | /groups | GET | room/zone list | | /groups/{id}/action | PUT | whole-room control | | /scenes | GET | list scenes | | /schedules | POST | timed routines |

| Field | Range | Meaning | |---|---|---| | bri | 0–254 | brightness | | hue | 0–65535 | color wheel position | | sat | 0–254 | color saturation | | ct | 153–500 | color temperature (mireds) | | `transitionti