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

FieldTypeDescription
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

FieldTypeDescriptionRequired
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"
FieldTypeDescriptionRequired
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

FieldTypeDescriptionRequired
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

FieldTypeDescriptionRequired
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