Groups

Groups are useful to control many lights at once and provide the base to use scenes.

Create group 

POST /api/<apikey>/groups

Creates a new empty group.

Parameters

FieldTypeDescriptionRequired
name String The name of the new group required

Example request data

{ "name": "Garage" }

Response


HTTP/1.1 200 OK


[ { "success": { "id": "3" } } ]

Response fields

FieldTypeDescription
id String The unique identifier of the group.

Note

Creating a group with a name which already exists will not create a new group or fail. Such a call does only return the id of the existing group.

Possible errors

400 Bad Request

403 Forbidden


Get all groups 

GET /api/<apikey>/groups

Returns a list of all groups.

Parameters

None

Response


HTTP/1.1 200 OK


{
    "1": {
        "devicemembership": [],
        "etag": "ab5272cfe11339202929259af22252ae",
        "hidden" : false,
        "name": "Living Room"
    },
    "2": {
        "devicemembership": ["3"],
        "etag": "030cf8c1c0025420f3a0659afab251f5",
        "hidden" : false,
        "name": "Kitchen"
    }
}

Response fields

FieldTypeDescription
devicemembership Array If this group was created by a device (switch or sensor) this list contains the device ids.
name String Name of a group.
etag String HTTP etag which changes on any action to the group.
hidden Bool Indicates if this group is hidden.

Possible errors

403 Forbidden


Get group attributes 

GET /api/<apikey>/groups/<id>

Returns the full state of a group.

Parameters

None

Response


HTTP/1.1 200 OK
ETag: "0b32030b31ef30a4446c9adff6a6f9e5"


{
    "action": {
        "bri": 0,
        "ct": 500,
        "effect": "none",
        "hue": 0,
        "on": false,
        "sat": 0,
        "xy": [ 0, 0 ]
    },
    "devicemembership": [],
    "etag": "0b32030b31ef30a4446c9adff6a6f9e5",
    "hidden": false,
    "id": "32772",
    "lights": [ "3","42","43" ],
    "lightsequence": [ "42","43","3" ],
    "multideviceids": ["2"],
    "name": "Livingroom",
    "scenes": [
        { "id": "1", "name": "warmlight" }
    ],
    "state": 0
}

Response fields

FieldTypeDescription
action Object The last action which was send to the group.
action.on Bool true if the group was turned on.
action.bri Number (0–255) Brightness of the group. Depending on the lights 0 might not mean visible "off" but minimum brightness.
action.hue Number (0–65535) The hue parameter in the HSV color model is between 0°–360° and is mapped to 0–65535 to get 16-bit resolution.
action.sat Number (0–255) Color saturation there 0 means no color at all and 255 is the greatest saturation of the color.
action.ct Number (153–500) Mired color temperature. (2000K–6500K)
action.xy Array CIE xy color space coordinates as array [x, y] of real values (0–1).
action.effect String Dynamic effect:
  • none - no effect
  • colorloop
devicemembership Array A list of device ids (sensors) if this group was created by a device.
etag String HTTP etag which changes on any action to the group.
hidden Bool Indicates the hidden status of the group. Has no effect at the gateway but apps can uses this to hide groups.
id String The id of the group.
lights Array A list of all light ids of this group. Sequence is defined by the gateway.
lightsequence Array A list of light ids of this group that can be sorted by the user. Need not to contain all light ids of this group.
mulitdeviceids Array A list of light ids of this group that are subsequent ids from multidvices with multiple endpoints like the FLS-PP.
name String Name of the group.
scenes Array A list of scenes of the group.
state Number Deprecated - will be removed in future.

Possible errors

304 Not Modified

403 Forbidden

404 Not Found


Set group attributes 

PUT /api/<apikey>/groups/<id>

Sets attributes of a group which are not related to its state.

Parameters

FieldTypeDescriptionRequired
name String (0–32) The name of the group optional
lights Array IDs of the lights which are members of the group. optional
hidden Bool Indicates the hidden status of the group. Has no effect at the gateway but apps can uses this to hide groups. optional
lightsequence Array Specify a sorted list of light ids that can be used in apps. optional
mulitdeviceids Array Append the subsequential light ids of multidevices like the FLS-PP if the app should handle that light differently. optional

Example request data

{
    "name": "Living Room",
    "lights": [ "1", "4" ]
}

Response


HTTP/1.1 200 OK
ETag: "000bf36b51ef3324446c98hdf6a6ace6"


[
    { "success": { "/groups/1/name": "Living Room" } },
    { "success": { "/groups/1/lights": [ "1", "4" ] } }
]

Note

In order to add or remove lights to the group the lights must be powered on.

Possible errors

400 Bad Request

403 Forbidden

404 Not Found

503 Service Unavailable


Set group state 

PUT /api/<apikey>/groups/<id>/action

Sets the state of a group.

Parameters

FieldTypeDescriptionRequired
on Bool Set to true to turn the lights on, false to turn them off. optional
toggle Bool Set to true toggles the lights of that group from on to off or vice versa, false has no effect. **Notice:** This setting supersedes the `on` parameter! optional
bri Number (0–255) Set the brightness of the group. Depending on the lights 0 might not mean visible "off" but minimum brightness. If the lights are off and the value is greater 0 a on=true shall also be provided. optional
hue Number (0–65535) Set the color hue of the group. The hue parameter in the HSV color model is between 0°–360° and is mapped to 0–65535 to get 16-bit resolution. optional
sat Number (0–255) Set the color saturation of the group. There 0 means no color at all and 255 is the highest saturation of the color. optional
ct Number (153–500) Set the Mired color temperature of the group. (2000K–6500K) optional
xy Array Set the CIE xy color space coordinates as array [x, y] of real values (0–1). optional
alert String Trigger a temporary alert effect:
  • none - lights are not performing an alert
  • select - lights are blinking a short time
  • lselect - lights are blinking a longer time
optional
effect String Trigger an effect of the group:
  • none - no effect
  • colorloop - the lights of the group will cycle continously through all colors with the speed specified by colorloopspeed
optional
colorloopspeed Number (1–255) Specifies the speed of a colorloop. 1 = very fast, 255 = very slow (default: 15). This parameter only has an effect when it is called together with effect colorloop. optional
transitiontime Number Transition time in 1/10 seconds between two states. Note that not all states support a transition time. For example, a transition time when setting
on
will be ignored as the Zigbee On and Off commands do not support transition times. In general, light attributes that support a range of values support transition times, while boolean values do not.
optional

Example request data

{
  "on": true,
  "bri": 180,
  "hue": 43680,
  "sat": 255,
  "transitiontime": 10
}

Response


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


[
    { "success": { "/groups/1/action/on": true   }},
    { "success": { "/groups/1/action/bri": 180   }},
    { "success": { "/groups/1/action/hue": 43680 }},
    { "success": { "/groups/1/action/sat": 255   }}
]

Possible errors

400 Bad Request

403 Forbidden

404 Not Found

503 Service Unavailable


Delete group 

DELETE /api/<apikey>/groups/<id>

Deletes a group.

Parameters

None

Response


HTTP/1.1 200 OK


[ { "success": { "id": "1" } } ]

Note

In order to delete the group and therefore remove all lights from the group the lights must be powered on.

Possible errors

403 Forbidden

404 Not Found

503 Service Unavailable