Lights

Get Light State

On a GET of a single light, /lights/1, the Hue API returns:

{
  "state": {
    "on": true,
    "bri": 254,
    "hue": 13195,
    "sat": 210,
    "effect": "none",
    "xy": [
      0.5106,
      0.415
    ],
    "ct": 463,
    "alert": "none",
    "colormode": "xy",
    "reachable": true
  },
  "type": "Extended color light",
  "name": "Living Room 1",
  "modelid": "LCT003",
  "manufacturername": "Philips",
  "uniqueid": "00:17:88:01:00:xx:xx:xx-0b",
  "swversion": "5.50.1.19085"
}

On a GET of the same light, the deCONZ REST API returns:

{
  "etag": "5cb86e5afc7077abed02ff18eca41d2f",
  "hascolor": true,
  "manufacturer": "Philips",
  "modelid": "LCT003",
  "name": "Living Room 1",
  "pointsymbol": {},
  "state": {
    "alert": "none",
    "bri": 254,
    "colormode": "xy",
    "ct": 463,
    "effect": "none",
    "hue": 13158,
    "on": true,
    "reachable": true,
    "sat": 210,
    "xy": [
      0.512615,
      0.416627
    ]
  },
  "swversion": "5.50.1.19085",
  "type": "Extended color light",
  "uniqueid": "00:17:88:01:00:xx:xx:xx-0b"
}

Comparison

Attribute	Hue	deCONZ	Remarks
etag		Y	Missing from the Hue API.
hascolor		Y	Missing from the Hue API. Seems redundant - could be derived from type.
manufacturer	N	Y
manudacturername	Y	N
modelid	Y	Y
name	Y	Y
pointsymbol		Y	Has been removed from Hue API.
state	Y	Y
state.alert	Y	Y
state.bri	Y	Y
state.colormode	Y	Y
state.ct	Y	Y
state.effect	Y	Y
state.hue	Y	Y	Values differ, see below.
state.on	Y	Y
state.reachable	Y	Y
state.sat	Y	Y	Values differ, see below.
state.xy	Y	Y	Values differ, see below. The Hue API limits the values to four decimals, the deCONZ API uses six decimals.
swversion	Y	Y
type	Y	Y
uniqueid	Y	Y

Notes

The deCONZ API returns the attributes in alphabetical order of key; the Hue API returns the attributes in a pre-defined logical (?) order. This is not an issue from an API perspective, as the order of keys within an JSON object doesn't matter.

Both the Hue API and the deCONZ API seem to base state.ct on the Color temparature attribute (0x0007) in the Color control cluster (0x0300). The value of this attribute is used directly, without any conversions.

The Hue API seems to base state.hue on the Enhanced current hue attribute (0x4000) in the Color Control cluster. The value of this attribute is used directly, without any conversions. The deCONZ API reports a slightly different value, which doesn't seem to be based on the Current hue attribute (0x0000) either.

The Hue bridge seems to base state.sat on the Current saturation attribute (0x0002) in the Color control cluster (0x0300). The value of this attribute is used directly, without any conversions. Sometimes the deCONZ API reports a slightly different value.

The Hue API seems to base state.xy[0] on the Current x attribute (0x0003) and state.xy[1] on the Current y attribute (0x0004) in the Color control cluster (0x0300). The attributes are u16; the API values are float, which are derived by dividing the attribute values by 65536. The deCONZ API reports slightly different values.

Philips Hue lights don't support attribute reporting. It seems the Hue bridge polls the lights for their state. The time between polls seems to increase with the number of lights connected to the bridge. I suspect that's why Philips recommend no more that 50 lights, even though technically they can accommodate 64 lights. Changes to the light state through the Hue API are not visible in deCONZ, until I manually read the cluster attributes from the deCONZ GUI. Changes from the deCONZ API are not visible in the Hue bridge for some time, until the bridge polls the light.

When setting a light to an unsupported colour (e.g "xy": [0, 0]), its attributes immediately contain the actual values (corresponding to [0.167, 0.04] - I'm testing on a Gamut B light). It takes the Hue bridge a while before it reports these values.

Get All Lights

Both the Hue API and the deCONZ API report the same attributes per light as when getting a single light resource. The Hue API returns the lights in numerical order; the deCONZ API returns the lights in alphabetical order (see issue #22). Again, from an API perspective this doesn't matter, as JSON doesn't define any order of keys within an object.