Lights - dresden-elektronik/deconz-rest-plugin GitHub Wiki

This page documents the differences between the Hue API and the deCONZ API for the /lights resource.

Get Light State

Extended Colour Light

On a GET of an Extended color light, the Hue API returns (my formatting and sorting):

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

On a GET of the same light, the deCONZ REST API returns (my formatting):

{
  "etag": "1e6fe902a4aa8c0bbd2ef8528f654532",
  "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": false,
    "reachable": true,
    "sat": 210,
    "xy": [
      0.512615,
      0.416627
    ]
  },
  "swversion": "5.50.1.19085",
  "type": "Extended color light",
  "uniqueid": "00:17:88:01:00:f0:71:18-0b"
}

Color Light

On a GET of a Color light, the Hue API returns (my formatting and sorting):

{
  "manufacturername": "Philips",
  "modelid": "LLC011",
  "name": "Living Room Left",
  "state": {
    "alert": "none",
    "bri": 127,
    "colormode": "hs",
    "effect": "none",
    "hue": 5500,
    "on": true,
    "reachable": true,
    "sat": 254,
    "xy": [
      0.6468,
      0.348
    ]
  },
  "swversion": "5.23.1.13452",
  "type": "Color light",
  "uniqueid": "00:17:88:01:00:xx:xx:xx-0b"
}

On a GET of the same light, the deCONZ REST API returns (my formatting):

{
  "etag": "87bdc7362238192c26d5a9ad861f0690",
  "hascolor": true,
  "manufacturer": "Philips",
  "modelid": "LLC011",
  "name": "Living Room Left",
  "pointsymbol": {},
  "state": {
    "alert": "none",
    "bri": 127,
    "colormode": "hs",
    "ct": 0,
    "effect": "none",
    "hue": 5418,
    "on": true,
    "reachable": true,
    "sat": 254,
    "xy": [
      0.649321,
      0.349362
    ]
  },
  "swversion": "5.23.1.13452",
  "type": "Color light",
  "uniqueid": "00:17:88:01:00:xx:xx:xx-0b"
}

Color Temperature Light

On a GET of a Color temperature light, the Hue API returns (my formatting and sorting):

{
  "manufacturername": "Philips",
  "modelid": "LTW013",
  "name": "Bathroom 1",
  "productid": "Philips-LTW013-1-GU10CTv1",
  "state": {
    "alert": "none",
    "bri": 254,
    "colormode": "ct",
    "ct": 451,
    "on": true,
    "reachable": true
  },
  "swconfigid": "B7A3ED0F",
  "swversion": "1.15.2_r19181",
  "type": "Color temperature light",
  "uniqueid": "00:17:88:01:02:xx:xx:xx-0b"
}

On a GET of the same light, the deCONZ REST API returns (my formatting):

{
  "etag": "58ac074dcec2585f4255c9f65b32ab0c",
  "hascolor": true,
  "manufacturer": "Philips",
  "modelid": "LTW013",
  "name": "Bathroom 1",
  "pointsymbol": {},
  "state": {
    "alert": "none",
    "bri": 254,
    "colormode": "ct",
    "ct": 451,
    "effect": "none",
    "hue": 0,
    "on": true,
    "reachable": true,
    "sat": 0,
    "xy": [
      0.505231,
      0.416842
    ]
  },
  "swversion": "1.15.2_r19181",
  "type": "Color temperature light",
  "uniqueid": "00:17:88:01:02:xx:xx:xx-0b"
}

Dimmable Light

On a GET of a Dimmable light, the Hue API returns (my formatting and sorting):

{
  "manufacturername": "Philips",
  "modelid": "LWB006",
  "name": "Entrance 1",
  "state": {
    "alert": "select",
    "bri": 254,
    "on": true,
    "reachable": true
  },
  "swversion": "5.38.2.19136",
  "type": "Dimmable light",
  "uniqueid": "00:17:88:01:10:xx:xx:xx-0b"
}

On a GET of the same light, the deCONZ REST API returns (my formatting):

{
  "etag": "a5376897e04934cc2011dd1704b36474",
  "hascolor": false,
  "manufacturer": "Philips",
  "modelid": "LWB006",
  "name": "Entrance 1",
  "pointsymbol": {},
  "state": {
    "alert": "none",
    "bri": 254,
    "effect": "none",
    "on": true,
    "reachable": true
  },
  "swversion": "5.38.2.19136",
  "type": "Dimmable light",
  "uniqueid": "00:17:88:01:10:xx:xx:xx-0b"
}

On/off plugin unit

On a GET of an On/off plug-in unit, the Hue API returns (my formatting and sorting):

{
  "manufacturername": "OSRAM",
  "modelid": "Plug - LIGHTIFY",
  "name": "Living Room Fan",
  "state": {
    "alert": "none",
    "on": true,
    "reachable": true
  },
  "swversion": "V1.03.21",
  "type": "On/Off plug-in unit",
  "uniqueid": "84:18:26:00:00:xx:xx:xx-03"
}

On a GET of the same light, the deCONZ REST API returns (my formatting):

{
  "etag": "3baff0625dbf27d3256fa801432c1710",
  "hascolor": false,
  "manufacturer": "OSRAM",
  "modelid": "Plug - LIGHTIFY",
  "name": "Living Room Fan",
  "pointsymbol": {},
  "state": {
    "alert": "none",
    "bri": 255,
    "effect": "none",
    "on": true,
    "reachable": true
  },
  "swversion": "V1.03.21",
  "type": "On/Off plug-in unit",
  "uniqueid": "84:18:26:00:00:xx:xx:xx-03"
}

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`		Y	Is `manufacturername` in the Hue API.
`manufacturername`	Y		Is `manufacturer` in the deCONZ API.
`modelid`	Y	Y
`name`	Y	Y
`pointsymbol`		Y	Has been removed from Hue API.
`productid`	Y		Missing from the deCONZ API. The Hue API only shows this (undocumented!) attribute for some lights, like the GU10 White Ambiance (model `LWT013`) lights.
`state`	Y	Y
`state.alert`	Y	Y
`state.bri`	Y	Y*	Functionality differs, see below. The deCONZ API also shows `bri` for an On/off plugin unit.
`state.colormode`	Y	Y
`state.ct`	Y	Y*	The deCONZ API also shows this attribute for Color Lights.
`state.effect`	Y	Y*	The deCONZ API also shows this attribute for a Dimmable light and for an On/off plugin unit.
`state.hue`	Y	Y*	Values differ, see below. The deCONZ API also shows this attribute for Color Temperature Lights.
`state.on`	Y	Y
`state.reachable`	Y	Y
`state.sat`	Y	Y*	Values differ, see below. The deCONZ API also shows `state.sat` for Color Temperature Lights.
`state.xy`	Y	Y*	Values differ, see below. The Hue API limits the values to four decimals, the deCONZ API uses six decimals. The deCONZ API also shows this attribute for Color Temperature Lights.
`swversion`	Y	Y
`swconfigid`	Y		Missing from the deCONZ API. The Hue API only shows this (undocumented!) attribute for some lights, like the GU10 White Ambiance (model `LWT013`) lights.
`type`	Y	Y
`uniqueid`	Y	Y

Notes

Brightness

On a PUT {"bri": 0} to a light state, the Hue API turns down the light to minimum brightness, but the deCONZ API turns off the light. When subsequently trying to set {"bri": 254}, deCONZ throws an error 201, parameter, /lights/xx/bri, is not modifiable. Device is set to off.

The Hue API only shows state.bri for lights that actually support dimming. The deCONZ API also shows state.bri for On/off plugin units.

Colour Temperature

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 only shows state.ct for lights that actually support colour temperature. The deCONZ API also shows state.ct for Color Lights.

Colour

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 API 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.

The Hue API only shows state.hue, state.sat, and state.xy for lights that actually support colour. The deCONZ API also shows these attributes for Color temperature lights.

The Hue API only shows state.effect for lights that actually support colour. The deCONZ API shows state.effect for any light or plug-in unit.

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.