Lights

Monitor and control single lights.

Get all lights

GET /api/<apikey>/lights

Returns an object of all lights, when no lights are registered an empty object {} will be returned.

Response

{
    "1": {
        "etag": "026bcfe544ad76c7534e5ca8ed39047c",
        "manufacturer": "dresden elektronik",
        "modelid": "FLS-PP3",
        "name": "Light 1",
        "ctmin": 153,
        "ctmax": 500,
        "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",
        "manufacturer": "dresden elektronik",
        "modelid": "FLS-PP3 White",
        "name": "Light 2",
        "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"
    }
}

Each light is included as key-value pair, where the key is the light id and the value is the light object as descripted in Get light state.

Possible errors

403 Forbidden

Get light

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

Returns the full state of a light.

Response

{
    "etag": "026bcfe544ad76c7534e5ca8ed39047c",
    "manufacturer": "dresden elektronik",
    "modelid": "FLS-PP3",
    "name": "Light 1",
    "ctmin": 153,
    "ctmax": 500,
    "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"
}

Top level attributes

Name Type Description
etag String read-only HTTP etag which changes on any action to the light
manufacturer String read-only Manufacturer of the light
name String Name given by the user in the app
modelid String read-only An identifier unique to the product
swversion String read-only Current firmware version of the light
type String read-only Type of the light
state Object Current state of the light
uniqueid String read-only A unique identifier for the light
ctmin Number read-only Included for lights supporting color temperature
ctmax Number read-only Included for lights supporting color temperature

State attributes

Supported state attributes for lights are listed in the light types table.

Name Type Description
on Bool True if the light is on
bri Number 0–255 Brightness of the light, where 0 means visual minimum brightness
hue Number 0–65535 Color hue between 0°–360° mapped to 0–65535
sat Number 0-255 Saturation of the current color
ct Number ctmin–ctmax Mired color temperature (1.000.000 / temperature in Kelvin)
xy Array [0–1, 0–1] CIE xy color space coordinates as array of two real values
alert String

Puts the light into identify mode for a few seconds

  • none — light is not performing an alert
  • select — light is blinking a short time
  • lselect — light is blinking a longer time
colormode String read-only

Current color mode of the light

  • ct — color temperature
  • xy — CIE 1931 xy
  • hs — hue saturation
effect String

Start/stop a visual effect like colorloop

  • none — no effect is active
  • colorloop — colorloop cycles through hue range
reachable Bool read-only True if the light is reachable and accepts commands

Light types

There are various types of lights and smart plugs. Each type only supports specific state attributes related to the lights capabilities.

Type Supported state attributes
On/Off output on, alert
On/Off light on, alert
Smart plug on, alert
Level controllable output on, bri, alert
On/Off plug-in unit on, alert
Dimmable plug-in unit on, bri, alert
Dimmable light on, bri, alert
Color light on, bri, colormode, hue, sat, alert
Color dimmable light on, bri, colormode, hue, sat, alert
Color temperature light on, bri, colormode, ct, alert
Extended color light on, bri, colormode, hue, sat, ct, xy, alert, effect

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

Name Type Description
on Bool True turns the light on, false turns it off
bri Number 0–255 Set brightness of the light, where 0 means visual minimum brightness. Note: only the on attribute can turn the light on or off.
transitiontime Number 0–65535 Time to fade to the new state in 1/10 seconds (default 4)
hue Number 0–65535 Color hue between 0°–360° mapped to 0–65535
sat Number 0-255 Saturation of the color
ct Number ctmin–ctmax Mired color temperature
xy Array [0–1, 0–1] CIE xy color space coordinates as array of two real values
alert String

Puts the light into identify mode for a few seconds

  • none — stops light performing an alert
  • select — let light is blinking a short time
  • lselect — let light is blinking a longer time
effect String

Start/stop a visual effect like colorloop

  • none — stops active effect
  • colorloop — starts colorloop which cycles through hue range
bri_inc1 Number -254–254 Increments or decrements the current brightness
ct_inc2 Number -65534–65534 Increments or decrements the current color temperature
  1. The bri_inc changes the brighness relative to its current value. 0 will stop any ongoing brightness transition. The parameter will be ignored if bri parameter is also provided.
  2. The ct_inc changes the color temperature relative to its current value. 0 will stop any ongoing color temperature transition. The parameter will be ignored if ct parameter is also provided.

Example request data

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

Response

[
    { "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>

Set top level attributes of a light which are not related to its state.

Parameters

Name Type Description
name String 0–32 Name of the light as shown in the app

Example request data

{ "name": "Living Room 1" }

Response

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

Possible errors

400 Bad Request

403 Forbidden

404 Not Found

Search new lights

POST /api/<apikey>/lights

Starts a search for new lights. Lights need to be in factory new state in order to join.

Response

[{
    "success": {
        "/lights": "Searching for new devices",
        "/lights/duration": 60
    }
}]

Possible errors

503 Service Unavailable

Get new lights

GET /api/<apikey>/lights/new

Displays the result of the last light search.

Response

{
    "5": { "name": "Light 5" },
    "6": { "name": "Light 6" },
    "lastscan": "2018-08-15T09:41:04"
}

Response fields

Name Type Description
lastscan String read-only

Provides details about the scanning progress

  • none — no light scan was started yet
  • active — a light scan is in progress
  • timestamp — the last light scan time as ISO 8601

If new lights are found they are listed with their id as key holding an object with the lights name attribute.

Possible errors

503 Service Unavailable

Delete light

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

Removes the light from the gateway and optionally resets it.

Parameters

Name Type Description
reset Bool optional If true the light will be removed from the ZigBee network (default false)

Response

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

Possible errors

400 Bad Request

404 Not Found

Remove all groups

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

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

Response

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

Possible errors

404 Not Found

Remove all scenes

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

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

Response

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

Possible errors

404 Not Found