Device light | Documentation for developers
Skip to main content


Last updated on November 25, 2022

An illumination device that can be managed. Examples:

  • Electric bulb
  • Night light

Available device functions

The device can have all the functions listed below or some of them. E.g. if the smart lamp cannot change the colour temperature, there is no need in including the light_colour_temp function in its model description.

Some functions are mandatory, and all lamps must have them.

light_brightnessDevice brightness
light_colourDevice color
light_colour_tempDevice color temperature
light_modeDevice operation mode: color or white
on_off✔︎Turning the device on and off remotely
online✔︎Device availability: offline or online

Lamp model description example

The model shall be described in accordance with the model structure. The example describes a lamp that can be switched on/off remotely, supports both the white light mode and the colour mode, can change its light intensity, colour and colour temperature. The lamp has a time-out timer.

Besides, a dependency between the light_colour and light_mode functions is described for the model: the strip light colour may only be changed if switched to the colour mode.

Allowed values for the light_brightness functions have also been changed: it is indicated that devices of this model can change the brightness from 10 to 900 at an interval of 1.

"id": "QWERTY123",
"manufacturer": "Xiaqara",
"model": "SM0123456789",
"hw_version": "3.2",
"sw_version": "5.7",
"description": "Xiaqara smart lamp",
"category": "light",
"features": [
"dependencies": {
"light_colour": {
"key": "light_mode",
"value": [
"type": "ENUM",
"enum_value": "colour"
"allowed_values": {
"light_brightness": {
"type": "INTEGER",
"integer_values": {
"min": "10",
"max": "900",
"step": "1"

User's lamp description example

The device shall be describe in accordance with the device structure. The example contains no lamp model description as we believe that models are described independently and the model ID will be enough (in this case, QWERTY124).

"id": "ABCD_003",
"name": "My lamp",
"default_name": "Smart lamp",
"nicknames": ["LED lamp", "Intelligent lamp"],
"home": "My home",
"room": "Living room",
"groups": ["Overhead light", "Niches"],
"model_id": "QWERTY123",
"hw_version": "3.2",
"sw_version": "5.7"