Lights¶

Monitor and control single lights.

Get all lights ¶

GET /api/<apikey>/lights

Returns a list of all lights.

Parameters¶

None

Response¶


HTTP/1.1 200 OK


{
    "1": {
        "etag": "026bcfe544ad76c7534e5ca8ed39047c",
        "hascolor": true,
        "manufacturername": "dresden elektronik",
        "modelid": "FLS-PP3",
        "name": "Light 1",
        "pointsymbol": {},
        "state": {
            "alert": "none",
            "bri": 111,
            "colormode": "ct",
            "ct": 307,
            "effect": "none",
            "hue": 7998,
            "on": false,
            "reachable": true,
            "sat": 172,
            "xy": [ 0.421253, 0.39921 ]
        },
        "swversion": "020C.201000A0",
        "type": "Extended color light",
        "uniqueid": "00:21:2E:FF:FF:00:73:9F-0A"
    },

    "2": {
        "etag": "026bcfe544ad76c7534e5ca8ed39047c",
        "hascolor": false,
        "manufacturername": "dresden elektronik",
        "modelid": "FLS-PP3 White",
        "name": "Light 2",
        "pointsymbol": {},
        "state": {
            "alert": "none",
            "bri": 1,
            "effect": "none",
            "on": false,
            "reachable": true
        },
        "swversion": "020C.201000A0",
        "type": "Dimmable light",
        "uniqueid": "00:21:2E:FF:FF:00:73:9F-0B"
    }
}

Response fields¶

The whole light object as descripted in Get light state.

Possible errors¶

403 Forbidden

Get light state ¶

GET /api/<apikey>/lights/<id>

Returns the full state of a light.

Parameters¶

None

Response¶


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


{
        "etag": "026bcfe544ad76c7534e5ca8ed39047c",
        "hascolor": true,
        "manufacturername": "dresden elektronik",
        "modelid": "FLS-PP3",
        "name": "Light 1",
        "pointsymbol": {},
        "state": {
            "alert": "none",
            "bri": 111,
            "colormode": "ct",
            "ct": 307,
            "effect": "none",
            "hue": 7998,
            "on": false,
            "reachable": true,
            "sat": 172,
            "xy": [ 0.421253, 0.39921 ]
        },
        "swversion": "020C.201000A0",
        "type": "Extended color light",
        "uniqueid": "00:21:2E:FF:FF:00:73:9F-0A"
    }

Response fields¶

Field	Type	Description
colorcapabilities	Number	The color capabilities as reported by the light.
ctmax	Number	The maximum mired color temperature value a device supports.
ctmin	Number	The minimum mired color temperature value a device supports.
lastannounced	String	Last time the device announced itself to the network.
lastseen	String	Last time the device has transmitted any data.
etag	String	HTTP etag which changes on any action to the light.
hascolor	bool	Indicates if the light can change color. Deprecated - use state instead: if light has no color colormode, hue and xy will not be shown.
manufacturername	String	The manufacturer name of the light device.
name	String	Name of a light.
modelid	String	An identifier unique to the product.
pointsymbol	Object	Not used in the current version.
powerup	Number	SETTABLE. Brightness to set after power on (limited to DE devices).
swversion	String	Firmware version.
type	String	Human readable type of the light.
state	Object	The current state of the light.
state.on	Bool	true if the light is on.
state.bri	Number (0–255)	Brightness of the light. Depending on the light type 0 might not mean visible "off" but minimum brightness.
state.effect	String	Run special effect (if supported). See the device documentation for all possible values.
state.hue	Number (0–65535)	Color hue of the light. The hue parameter in the HSV color model is between 0°–360° and is mapped to 0–65535 to get 16-bit resolution.
state.sat	Number (0–255)	Color saturation of the light. There 0 means no color at all and 255 is the greatest saturation of the color.
state.ct	Number (ctmin–ctmax)	Mired color temperature of the light. Where Mired is 1000000 / color temperature (in kelvins).
state.xy	Array	CIE xy color space coordinates as array [x, y] of real values (0–1).
state.alert	String	Temporary alert effect. "none" — light is not performing an alert "select" — light is blinking a short time "lselect" — light is blinking a longer time
state.colormode	String	The current color mode of the light: "hs" — hue and saturation "xy" — CIE xy values "ct" — color temperature
state.effect	String	Effect of the light: "none" — no effect "colorloop" — cycle through hue values 0–360
state.speed	Number (0–6)	SETTABLE. Sets the speed of fans/ventilators.
state.reachable	Bool	true if the light is reachable and accepts commands.
uniqueid	String	The unique id of the light. It consists of the MAC address of the light followed by a dash and an unique endpoint identifier in the range 01 to FF.

Possible errors¶

304 Not Modified

403 Forbidden

404 Not Found

Set light state ¶

PUT /api/<apikey>/lights/<id>/state

Sets the state of a light.

Parameters¶

Field	Type	Description	Required
alert	String	Trigger a temporary alert effect: "none" — light is not performing an alert "select" — light is blinking a short time "lselect" — light is blinking a longer time	optional
bri	Number (0–255)	Set the brightness of the light. Depending on the light type 0 might not mean visible "off" but minimum brightness. If the light is off and the value is greater 0 a on=true shall also be provided.	optional
colorloopspeed	Number (1–255)	Specifies the speed of a colorloop (default: 15). 1 = very fast 255 = very slow This parameter only has an effect when it is called together with effect colorloop.	optional
ct	Number (ctmin–ctmax)	Set the Mired color temperature of the light. Where Mired is 1000000 / color temperature (in kelvins).	optional
effect	String	Trigger an effect of the light: "none" — no effect "colorloop" — the light will cycle continously through all colors with the speed specified by colorloopspeed	optional
hue	Number (0–65535)	Set the color hue of the light. The hue parameter in the HSV color model is between 0°–360° and is mapped to 0–65535 to get 16-bit resolution.	optional
on	Bool	Set to true to turn the light on, false to turn it off.	optional
sat	Number (0–255)	Set the color saturation of the light. There 0 means no color at all and 255 is the greatest saturation of the color.	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
xy	Array	Set the CIE xy color space coordinates as array [x, y] of real values (0–1).	optional

Window covering parameters¶

For historic reasons window covering devices are currently exposed under the lights endpoint.

For lights with type:

"Window covering controller"
"Window covering device"

Field	Type	Description	Required
open	Bool	Set to true to lift the shutter to 0 %, false to lift it to 100 %.	optional
stop	Bool	Stops the current action.	optional
lift	Number String	Supported range is 0–100 or special value "stop". `lift` is best understood as “percentage closed”. So for any lift value below 100 %, open is true. 0–99 — `open` is true 100 — `open` is false "stop" — Stops the lift action	optional
tilt	Number	Sets the tilt angle of the shutter (0–100 %).	optional
Deprecated
bri	Number String	(deprecated by "lift") 0–255 or "stop" where `lift` = bri * 100 / 254.	optional
bri_inc	Number	(deprecated by "stop") Only supported value is 0 meaning stop.	optional
on	Bool	(deprecated by "open") true when lift > 0	optional
sat	Number	(deprecated by "tilt") 0–255 where `tilt` = sat * 100 / 254.	optional

Example request data¶

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

Response¶


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


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

Possible errors¶

400 Bad Request

403 Forbidden

404 Not Found

Set light attributes ¶

PUT /api/<apikey>/lights/<id>

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

Parameters¶

Field	Type	Description	Required
name	String (0–32)	Set the name of the light.	required

Example request data¶

{ "name": "Living Room 1" }

Response¶


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


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

Possible errors¶

400 Bad Request

403 Forbidden

404 Not Found

Delete light ¶

DELETE /api/<apikey>/lights/<id>

Removes the light from the gateway. It will not be shown in any REST-API call. Also deletes all groups and scenes on the light device.

Parameters¶

Field	Type	Description	Required
reset	Bool	If true sends a network leave command to the light device (may not supported by each manufacturer).	optional

Response¶


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


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

Possible errors¶

400 Bad Request

404 Not Found

Remove from all groups ¶

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

Remove the light from all groups it is a member of.

Response¶


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


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

Possible errors¶

404 Not Found

Remove from all scenes ¶

DELETE /api/<apikey>/lights/<id>/scenes

Remove the light from all scenes it is a member of.

Response¶


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


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

Possible errors¶

404 Not Found