Groups

Get Group State

On a GET of a single group, /groups/10, the Hue API returns:

{
  "name": "Living Room",
  "lights": [
    "1",
    "2",
    "3",
    "4",
    "5",
    "6",
    "7",
    "8"
  ],
  "type": "Room",
  "state": {
    "all_on": false,
    "any_on": false
  },
  "recycle": false,
  "class": "Living room",
  "action": {
    "on": false,
    "bri": 127,
    "hue": 5500,
    "sat": 254,
    "effect": "none",
    "xy": [
      0.6468,
      0.348
    ],
    "ct": 463,
    "alert": "none",
    "colormode": "hs"
  }
}

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

{
  "action": {
    "bri": 127,
    "ct": 0,
    "effect": "none",
    "hue": 0,
    "on": false,
    "sat": 127,
    "xy": [
      0,
      0
    ]
  },
  "devicemembership": [],
  "etag": "a395a7405598df6e0ac929d039e9cc8e",
  "hidden": false,
  "id": "49650",
  "lights": [
    "8",
    "17",
    "11",
    "22",
    "25",
    "26",
    "20",
    "21"
  ],
  "lightsequence": [
    "20",
    "25",
    "26",
    "8",
    "21",
    "22",
    "11",
    "17"
  ],
  "multideviceids": [],
  "name": "Living Room",
  "scenes": [],
  "state": 0
}

Comparison

Attribute	Hue	deCONZ	Remarks
action	Y	Y
action.alert	Y	N	Missing from the deCONZ API.
action.bri	Y	Y
action.colormode	Y		Missing from the deCONZ API.
action.ct	Y	Y
action.effect	Y	Y
action.hue	Y	Y	Different values (see Lights).
action.on	Y	Y
action.sat	Y	Y	Different values (see Lights).
action.xy	Y	Y	Different values (see Lights).
class	Y		Missing from the deCONZ API, but not used by homebridge-hue. Indicates the room type for Room groups, see type.
devicemembership	N	Y	Missing from the Hue API, as it does not support binding switches or sensors to groups.
etag		Y	Missing from the Hue API.
hidden		Y	Missing from the Hue API. Used by the Wireless Light Control web application.
id		Y	Missing from the Hue API. I've been wanting an attribute like this. I could also use it on lights, sensors, and other resources.
lights	Y	Y
lightsequence		Y	Missing from the Hue API. Used by the Wireless Light Control web application.
multideviceids		Y	Missing from the Hue API, which does not create any group resource for the FLS-PP. Currently, homebridge-hue exposes the FLS-PP to HomeKit as a single Light accessory with two LightBulb services. It matches the light resources corresponding to the different endpoints through (the MAC address in) the uniqueid.
name	Y	Y
recycle	Y		Missing from the deCONZ API, but not used by homebridge-hue.
scenes		Y	Missing from the Hue API, which uses a separate /scenes resource. homebridge-hue does not support scenes.
state	Y	Y	Is an object in the Hue API, but a number in the deCONZ API. Has been deprecated in the deCONZ API.
state.all_on	Y		Missing from the deCONZ API.
state.any_on	Y		Missing from the deCONZ API.
type	Y		Missing from the deCONZ API. Indicates the type of group: Lightgroup, Room, Luminaire, or Lightsource. The latter two are used for multisource luminaires, like the Hue Beyond, which contain multiple ZigBee devices (light modules). I don't have any of these, and I don't know of any homebridge-hue user who has one either, so homebridge-hue does not (yet) support these. Room groups are like regular Lightgroup groups, with the additional limitation that a light can belong to only one Room group. The Hue app uses these to create HomeKit rooms and to assign HomeKit light accessories to these.

Get All Groups

On a GET of /groups, the Hue API returns the full state of each group:

{
  "10": {
    "name": "Living Room",
    "lights": [
      "1",
      "2",
      "3",
      "4",
      "5",
      "6",
      "7",
      "8"
    ],
    "type": "Room",
    "state": {
      "all_on": false,
      "any_on": false
    },
    "recycle": false,
    "class": "Living room",
    "action": {
      "on": false,
      "bri": 127,
      "hue": 5500,
      "sat": 254,
      "effect": "none",
      "xy": [
        0.6468,
        0.348
      ],
      "ct": 463,
      "alert": "none",
      "colormode": "hs"
    }
  }
}

Note: I've removed the other groups from the response. Also note that Group 0 (all lights) is missing from the response.

On a GET of /groups, the deCONZ API only returns a partial state of each group:

{
  "49650": {
    "devicemembership": [],
    "etag": "a395a7405598df6e0ac929d039e9cc8e",
    "hidden": false,
    "name": "Living Room"
  }
}

Note: I've removed the other groups from the response. Also note that Group 0 (all lights) is missing from the response.

Comparison

The deCONZ API seems to take a different approach towards polling of groups than the Hue API. The etag attributes only changes when other attributes change, so a simple comparison on etag suffices to check whether a group state has changed. Then, the full groups state can be retrieved using a GET on a single group.
While more efficient on network bandwidth, I doubt whether it's actually more efficient overall than returning the full group states. Also, I don't like the inconsistency with lights or sensors, where the deCONZ API does return the full state. As a compromise, the Get All Groups response could leave out lightsequence, multideviceids, and scenes, similar to the Hue API which leaves out the lightstates on Get All Scenes.