Hue hub notes 
|∞| Doc: hue-notes.htm
Changed: 2025sep21 02:48

Hue hub notes

Developer API at developers.meethue.com.

The IP address of the bridge (hub) needs to be known. Once known, a few documents are available from "http://[ip-address]".

# internal CLI

Modify settings with the document "/debug/clip.html" available on the hub. Or use the custom interface: hue-api.html.

Must have an authorized name. Create one by pushing the button on the Hub and then within 30 seconds use GET and the URL: /api A name will be returned and added to the whitelist. Maximum 100 whitelist entries. Most recent name: E7ZOr8Qmch1cKrrMQ0lKa1iS9Sk2OIyKEnwyCJse

In general, "GET" is for getting current info about a resource, "DELETE" is for deleting a resource, "POST" is for adding a new resource, and "PUT" is for modifying a resource.

# configuration info

A basic bridge configuration is avaliable with only: /api/config More is available with an authorized name: /api/[name]/config

Can be modified with PUT. The "name" property is 4–16 characters. Notably, the "UTC" property is modifiable only when without an internet connection.

The full state of the hub reveals the collections of lights, groups, configuration, schedules, scenes, sensors, rules, and resourcelinks. It is retrieved with GET and only: /api/[name]/

# updates

Check configuration with GET and URL: /api/[name]/config

Check for updates with PUT and same URL, with body: {"swupdate":{"checkforupdate":true}}

Review the "swupdate" attribute for available updates (at this moment CIfq0F: API 1.16.0, SW 01041302). The property "updatestate" should be 2. (0 means no update, 1 means downloading.) Set, t.i. PUT, "updatestate" to 3 to install update.
Message: {"swupdate":{"updatestate":3}}

Reset with PUT the "notify" property after reviewing:
Message: {"swupdate":{"notify":false}}

After an update review changes to documentation and revise these notes. NOTE: Updated to API 1.16 on CFlv. That's the final API update available for Gen 1 hub. However, the lightbulbs have occasional updates.

# lights

Search for new lights with POST and the URL: /api/[name]/lights
Message: none.
Any lights found are automatically added. Get a list of all lights added with GET and same URL. Get a list of only the new lights found from last search with GET and the URL: /api/[name]/lights/new

Maximum 50 lights.

# scenes

A scene is created from the current state of lights. Therefore, set the lights for a scene to their desired states, then list the lights to be remembered by the scene. The "recycle" resource is also required for creation. Optional transition time is tenths of seconds, from 0 to 65535: 10 = 1 second. The scene's transition time overrides the transition time set with "group/#/action", even when the scene is without a transition time. So the scene's transtition time is the only way to have a trasition for it.

Add a scene with POST and the URL: /api/[name]/scenes
Message: {"name":"","lights":["1","3"],"recycle":false}
Message: {"name":"","lights":["1","3"],"transitiontime":10,"recycle":false}

Edit name or lights of scene id with PUT and URL: /api/[name]/scenes/[scene-id]
Message: {"name":""}

Update states of lights or transition time with "storelightstate" attribute:
Message: {"storelightstate":true,"transitiontime":10}

Maximum 200 scenes, or 2048 light states. A lamp can have 50 scenes.

# groups

Add groups with POST.
URL: /api/[name]/groups
Message: {"name":"" ,"lights":["1","2","3"] ,"type":"LightGroup"}

Edit groups by id with PUT.
URL, f.e. for group 1: /api/[name]/groups/1

Maximum 64 groups.

# set light states

Set states for lights by either light or group. There is also a "scene" property for applying a scene to a light or group of lights, if the light is listed in that scene. Other lights in the scene are ignored.

By light with PUT.
URL: /api/[name]/lights/2/state
Message: {"on":true}

By group with PUT.
URL: /api/[name]/groups/1/action
Message: {"on":false}

A yellow based light is at "ct":300. Pure color for any hue is at "sat":254, and white is "sat":0. Three types of setting color: xy > ct > hs.

The "effect" resource: "colorloop", "none". Loops through the colors until set to "none". The "alert" resource: "select", "lselect", "none". The light or lights do one smooth transition from the current state to a higher brightness in the current color to a lower brightness in the current color and back to the original state. For the "lselect" value it will continue for 15 seconds or until set to "none". The value itself is the last value it had.

# sensors

List all known sensors with GET.
URL: /api/[name]/sensors

Search for new sensors with POST.
URL: /api/[name]/sensors
Message: none.

For the Hue tap press and hold (≈10s) one of the buttons during the sensor scan. Button events are, 1–4: 34, 16, 17, 18.

Get a list of only the new sensors found from last search with GET.
URL: /api/[name]/sensors/new

Create new sensors with POST.
URL: /api/[name]/sensors
Message: {"name": "" ,"type": "CLIPGenericStatus" ,"modelid": " none " ,"manufacturername": " name " ,"swversion": "1" ,"uniqueid": ""}

One approach for using created sensors is to set the "status" property of the sensor within rules to track when a set of changes are applied, such as with a number: {"status":2}. Useful for multiple states, like dimming levels. For on/off with the same button, just use two rules that check the "on" property of a light, or the "any_on" property of a group.

Configure daylight sensor (id=1) with longitude and latitude values. Writable, but non-retrievable. Attribute "configured" indicates whether location is configured.
URL: /api/[name]/sensors/1/config
Message: {"long":"000.0000W","lat":"000.0000N"}

Maximum 64 sensors, within which 50 can be ZigBee sensors.

# rules

Add rules with POST and the URL: /api/[name]/rules
Message: {"name":"" ,"conditions":[{"address":"/sensors/1/state/daylight","operator":"eq","value":"true"}] ,"actions":[{"address":"/groups/0/action","method":"PUT","body":{"scene":"[scene-id]"}}]} Transition time can be set, but transition time within a scene overrides (even when absent).
Message: {"name":"" ,"conditions":[{"address":"/sensors/1/state/daylight","operator":"eq","value":"true"}] ,"actions":[{"address":"/groups/1/action","method":"PUT","body":{"on":true}}]} Edit with PUT. Address limited to 32 chars, value to 64 chars, and body to 90 chars. A rule is limited to 8 conditions and 8 actions. Maximum 100 rules, or 400 conditions and 400 actions. Operators include: eq for integer or boolean; gt, lt for integer; stable and "not stable" for boolean or timestamp (not current time) but does not trigger. dx (value) or ddx (delayed value) for boolean or timestamp, only one per rule; in or "not in" for time intervals (use /), only one in, many "not in", not both; Format for time is with schedules notes. Actions can set transition time as either a light state or a group action. Deleting sensors will disable rules that relied upon them, making "status" as "resourcedeleted". Must update rules then set their "status" to "enabled".

# schedules

Add schedules with POST.
URL: /api/[name]/schedules
Message: {"name":"" ,"command":{"address":"/api/[name]/groups/1/action","method":"PUT","body":{"on":true}} ,"localtime":""}

Edit schedule id with PUT.
URL: /api/[name]/schedules/[schedule-id]
Message: {"status":"disabled"}

Address limited to 64 chars, body to 90 chars.

Maximum 100 schedules.

localtime

The localtime attribute is very flexible. [Brackets aren't necessary.] Optional randomizing +/- value denoted with "A" and time less than 12 hours.

Absolute time:
[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]A[hh]:[mm]:[ss]

Time interval:
T[hh]:[mm]:[ss]/T[hh]:[mm]:[ss]

Recurring time, with bbb a bit mask for 0MTWTFSS, f.e. Tuesday is 32, all week is 127:
W[bbb]/T[hh]:[mm]:[ss]A[hh]:[mm]:[ss]
The "autodelete" resource is inapplicable for recurring times, causes error.

Recurring time interval (max 23 hours):
W[bbb]/T[hh]:[mm]:[ss]/T[hh]:[mm]:[ss]

Timer:
PT[hh]:[mm]:[ss]A[hh]:[mm]:[ss]

Recurring timer, with optional nn (01..99) for limit of occurrences:
R[nn]/PT[hh]:[mm]:[ss]A[hh]:[mm]:[ss]

sharing.htm