Groups
With the groups endpoint groups can be added, modified and deleted. Groups are useful to control many lights at once and provide the base to use scenes. A Group can represent a room or any other type of grouping.
Create group
POST /api/<apikey>/groups
Creates a new empty group.
Parameters
| Name | Type | Description | Required |
|---|---|---|---|
| name | String | Provides details about the scanning progress | Required |
| type | String | Type of a group
|
Optional |
| class1 | String | Category of the group when the type is Room, default is Other | Optional |
- The class is one of the following Room types:
Other, Living room, Kitchen, Dining, Bedroom, Kids bedroom, Bathroom, Nursery, Recreation, Office, Gym, Hallway, Toilet, Front door, Garage, Terrace, Garden, Driveway, Carport.
Example request data
{ "name": "Garage" }Response
[ { "success": { "id": "3" } } ]The returned id can be used in various group REST-API
requests.
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
Get all groups
GET /api/<apikey>/groups
Returns a list of all groups known to the gateway.
Response
{
"1": {
"action": {
"bri": 80,
"colormode": "ct",
"ct": 300,
"effect": "none",
"hue": 26544,
"on": true,
"sat": 30,
"scene": "1",
"xy": [ 0.6, 0.34 ]
},
"class": "Kitchen",
"etag": "686b7c265be9db2ba32820bb4268c102",
"id": "1",
"lights": [ "3", "7" ],
"name": "Kitchen",
"scenes": [
{
"id": "1",
"lightcount": 2,
"name": "Dinner",
"transitiontime": 10
},
{
"id": "2",
"lightcount": 2,
"name": "Breakfast",
"transitiontime": 10
}
],
"state": {
"all_on": false,
"any_on": true
},
"type": "Room"
},
"2": {
"action": {
"bri": 20,
"colormode": "hs",
"ct": 489,
"effect": "none",
"hue": 23199,
"on": false,
"sat": 15,
"scene": null,
"xy": [ 0.4, 0.71 ]
},
"class": "Other",
"etag": "686b7c265be9db2ba32820bb4268c102",
"id": "127",
"lights": [ "6" ],
"name": "Hallway",
"scenes": [
{
"id": "1",
"lightcount": 1,
"name": "Entry",
"transitiontime": 10
}
],
"state": {
"all_on": false,
"any_on": false
},
"type": "LightGroup"
}
}Each group in the response object is referenced by its
id as key. The group object format is described in detail
in Get group attributes.
Possible errors
Get group attributes
GET /api/<apikey>/groups/<id>
Returns all attributes and the full state of a group.
Response
{
"action": {
"bri": 80,
"colormode": "ct",
"ct": 300,
"effect": "none",
"hue": 26544,
"on": true,
"sat": 30,
"scene": "1",
"xy": [ 0.6, 0.34 ]
},
"class": "Kitchen",
"etag": "686b7c265be9db2ba32820bb4268c102",
"id": "1",
"lights": [ "3", "7" ],
"name": "Kitchen",
"scenes": [
{
"id": "1",
"lightcount": 2,
"name": "Dinner",
"transitiontime": 10
},
{
"id": "2",
"lightcount": 2,
"name": "Breakfast",
"transitiontime": 10
}
],
"state": {
"all_on": false,
"any_on": true
},
"type": "Room"
}Response fields
| Name | Type | Description |
|---|---|---|
| action | Object | The last action which was send to the group. Note: The action doesn’t necessarily reflect the current state of the group. |
| name | String | Name of the group as shown in the app |
| etag | String | The Etag of the group to track changes |
| type | String | Type of a group
|
| class | String | Category of the group if it is of Room type
|
| lights | Array | Idenditifers of the lights which are memebers of the group |
| state | Object | The state of the group |
| scenes | Array | Each scene of the group as object |
Possible errors
Set group attributes
PUT /api/<apikey>/groups/<id>
Sets attributes of a group which are not related to the group state.
Parameters
| Name | Type | Description |
|---|---|---|
| name | String 1–32 | Name of the group as shown in the app |
| lights | Array | Idenditifers of the member lights of the group |
| class1 | String 1–32 | Category of the group if it is of Room type |
- The class is one of the following Room types:
Other, Living room, Kitchen, Dining, Bedroom, Kids bedroom, Bathroom, Nursery, Recreation, Office, Gym, Hallway, Toilet, Front door, Garage, Terrace, Garden, Driveway, Carport.
Example request data
{
"name": "Living Room",
"lights": [ "1", "4" ],
"class": "Living room"
}Response
[
{ "success": { "/groups/1/name": "Living Room" } },
{ "success": { "/groups/1/lights": [ "1", "4" ] } },
{ "success": { "/groups/1/class": "Living room" } }
]Possible errors
Send group action
PUT /api/<apikey>/groups/<id>/action
Sends state related commands to all lights of a group.
Parameters
| Name | Type | Description |
|---|---|---|
| on | Bool | Turn lights on or off |
| bri | Number 0–255 | Brightness of lights, in order to turn lights on/off, the
on attribute should be provided as well. |
| hue | Number 0–65535 | Color hue, the parameter is in HSV color model in range 0°–360° mapped to 0–65535 for 16-bit resolution. |
| sat | Number 0–255 | Color saturation, where 0 means no color at all and 255 is maximum saturation. |
| ct | Number 0–1000 | Mired color temperature (Mired = 1.000.000 / Kelvin) |
| xy | Array [0–1, 0–1] | CIE xy color space coordinates as array of two real values |
| alert | String | Trigger temporary alert effect
|
| effect | String | Trigger light effect
|
| colorloopspeed | Numer 1–255 | Specifies the speed of a colorloop, must be combined with
|
| transitiontime | Number | Transitiontime to new state in 1/10 seconds |
Example request data
{
"on": true,
"bri": 180,
"hue": 43680,
"sat": 255,
"transitiontime": 10
}Response
[
{ "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
Delete group
DELETE /api/<apikey>/groups/<id>
Deletes a group and all scenes which are related to that group.
Response
[ { "success": { "id": "1" } } ]