Groups¶

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

A “All” group is generated by the REST API by default and add all light in it. This group is avaliable at “/api//groups/0” but his ID is not always “0”; In that case the group is also avaliable at “/api//groups/65520”.

Create group ¶

POST /api/<apikey>/groups

Creates a new empty group.

Parameters¶

Field	Type	Description	Required
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¶

Field	Type	Description
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.

Note

The “All” group (id=0) with all devices is not returned in this list.

Parameters¶

None

Response¶


HTTP/1.1 200 OK


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

Response fields¶

The whole group object as descripted in Get group attributes.

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": {
        "all_on": false,
        "any_on": false
    }
}

Response fields¶

Field	Type	Description
action	Object	The last action which was send to the group.
action.on	Bool	true if the group was turned on.
action.alert	String	Temporary alert effect. "none" — group's lights is not performing an alert "select" — group's lights is blinking a short time "lselect" — group's lights is blinking a longer time
action.bri	Number (0–255)	Brightness of the group. Depending on the lights 0 might not mean visible "off" but minimum brightness.
action.colormode	String	The current color mode of the group's lights: "hs" — hue and saturation "xy" — CIE xy values "ct" — color temperature
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
action.scene	String \| null	Last scene called
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.
multideviceids	Array	A list of light ids of this group that are subsequent ids from multidevices with multiple endpoints like the FLS-PP.
name	String	Name of the group.
scenes	Array	A list of scenes of the group.
state	Object	The state of the group.
state.all_on	Bool	true if all lights of the group are on.
state.any_on	Bool	true if any light of the group is on.
type	String	The type of the group. LightGroup by default LightGroup Luminaire Lightsource Room
class	String	The class of the group, only for "Room" groups. Attic Balcony Barbecue Bathroom Bedroom Carport Closet Computer Dining Downstairs Driveway Front door Garage Garden Guest room Gym Hallway Home Kids bedroom Kitchen Laundry room Living room Lounge Man cave Music Nursery Office Other Pool Porch Reading Recreation Staircase Storage Studio TV Terrace Toilet Top floor Upstairs

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¶

Field	Type	Description	Required
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
multideviceids	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¶

Field	Type	Description	Required
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