light

Last updated on May 25, 2023

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.

Function	Mandatory?	Description
light_brightness		Device brightness
light_colour		Device colour
light_colour_temp		Device colour temperature
light_mode		Device operation mode: colour 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": [
        "online",
        "on_off",
        "light_mode",
        "light_brightness",
        "light_colour",
        "light_colour_temp",
        "sleep_timer"
    ],
    "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",
        "Smart lamp"
    ],
    "home": "My home",
    "room": "Living room",
    "groups": [
        "Overhead light",
        "Alcove"
    ],
    "model_id": "QWERTY123",
    "hw_version": "3.2",
    "sw_version": "5.7",
    "partner_meta": {
        "internal-id": 1234,
        "specificity": "microchip 2A"
    },
},