Color_setting

devices.capabilities.color_setting

Color control for device lighting elements. The device may have one or more of the following functions:

Changing the color of its lighting elements to any color from the HSV or RGB model.
Changing the color temperature of its lighting elements.
Playing back different visual effects.

Examples of such devices (you can also review the page with the description of the devices.types.light device type):

Color light bulb.
A regular white light bulb with the capability to change the temperature of its white color.
An electric kettle with color-changing LED lights.

Common voice commands

Yasmina, turn on red light.
Yasmina, make the light warmer.
Yasmina, set the light bulb to green light.
Yasmina, change the light to party mode.

Description of capability

The structure is used in the response to the Information about user devices operation.

Capability parameters

Parameter Type Description Required

type String Type of capability. Yes

retrievable

If it's possible to request the state of this device capability. Acceptable values:

true: A state request is available for the capability. Default value.
false: A state request is not available for the capability.

reportable

Indicates that the notification service reports the capability state change. Acceptable values:

true: Notification is enabled. The manufacturer notifies Yango Smart Home of every change in the capability state.
false: Notification is disabled. The manufacturer doesn't notify Yango Smart Home of the capability state change. Default value.

parameters Object parameters object. The object must contain at least one parameter. Yes

parameters object

color_model

Custom change of the color of device lighting elements. Acceptable values:

hsv: Change color according to the HSV model.
rgb: Change color according to the RGB model. The value must be in the 24-bit format (TrueColor).

Yes, if the temperature_k and color_scene parameters are omitted

temperature_k

Change in color temperature in kelvins. The range is specified in the additional min and max fields. The default range is 2000—9000K.

The value will be converted to a color from the palette below.

Restriction.

If the device supports a single temperature mode, select the closest value from the table and pass it.

If you pass a value or range of values outside of the table, the user is offered the default color (white with the temperature of 4500 K).

Color palette


Color	Temperature, K	Default value
Fire white	1500	No
Soft white	2700	No
Warm white	3400	No
White	4500	Default value
Daylight white	5600	No
Cold white	6500	No
Mist white	7500	No
Sky white	9000	No


Color	Temperature, K	Default value
Fire white	1500	No
Soft white	2700	No
Warm white	3400	No
White	4500	Default value
Daylight white	5600	No
Cold white	6500	No
Mist white	7500	No
Sky white	9000	No

Yes, if the color_model and color_scene parameters are omitted

color_scene

Changing the operating mode of the device's lighting elements according to the preset lighting themes and scenarios.

Yes, if the color_model and temperature_k parameters are omitted

temperature_k object

min Integer The minimum acceptable color temperature in kelvins. No

max Integer The maximum color temperature in kelvins. No

The color_scene object

scenes Array of scene objects An array of scene objects that describe lighting themes and scenarios. Minimum number of elements in the array: 1. Yes

The scene object included in the scenes array

Lighting scenario ID. You can find the acceptable values in the list below.

Lighting themes and scenarios


Theme (scenario)	Name
`alarm`	Alarm
`candle`	Candle
`dinner`	Dinner
`fantasy`	Fantasy
`garland`	Garland
`jungle`	Jungle
`movie`	Movie
`neon`	Neon
`night`	Night
`ocean`	Ocean
`party`	Party
`reading`	Reading
`rest`	Rest
`romance`	Romance
`siren`	Siren
`sunrise`	Sunrise
`sunset`	Sunset


Theme (scenario)	Name
`alarm`	Alarm
`candle`	Candle
`dinner`	Dinner
`fantasy`	Fantasy
`garland`	Garland
`jungle`	Jungle
`movie`	Movie
`neon`	Neon
`night`	Night
`ocean`	Ocean
`party`	Party
`reading`	Reading
`rest`	Rest
`romance`	Romance
`siren`	Siren
`sunrise`	Sunrise
`sunset`	Sunset

Yes

Parameter Type Description Required

type String Type of capability. Yes

retrievable

If it's possible to request the state of this device capability. Acceptable values:

true: A state request is available for the capability. Default value.
false: A state request is not available for the capability.

reportable

Indicates that the notification service reports the capability state change. Acceptable values:

true: Notification is enabled. The manufacturer notifies Yango Smart Home of every change in the capability state.
false: Notification is disabled. The manufacturer doesn't notify Yango Smart Home of the capability state change. Default value.

parameters Object parameters object. The object must contain at least one parameter. Yes

parameters object

color_model

Custom change of the color of device lighting elements. Acceptable values:

hsv: Change color according to the HSV model.
rgb: Change color according to the RGB model. The value must be in the 24-bit format (TrueColor).

Yes, if the temperature_k and color_scene parameters are omitted

temperature_k

Change in color temperature in kelvins. The range is specified in the additional min and max fields. The default range is 2000—9000K.

The value will be converted to a color from the palette below.

Restriction.

If the device supports a single temperature mode, select the closest value from the table and pass it.

If you pass a value or range of values outside of the table, the user is offered the default color (white with the temperature of 4500 K).

Color palette


Color	Temperature, K	Default value
Fire white	1500	No
Soft white	2700	No
Warm white	3400	No
White	4500	Default value
Daylight white	5600	No
Cold white	6500	No
Mist white	7500	No
Sky white	9000	No


Color	Temperature, K	Default value
Fire white	1500	No
Soft white	2700	No
Warm white	3400	No
White	4500	Default value
Daylight white	5600	No
Cold white	6500	No
Mist white	7500	No
Sky white	9000	No

Yes, if the color_model and color_scene parameters are omitted

color_scene

Changing the operating mode of the device's lighting elements according to the preset lighting themes and scenarios.

Yes, if the color_model and temperature_k parameters are omitted

temperature_k object

min Integer The minimum acceptable color temperature in kelvins. No

max Integer The maximum color temperature in kelvins. No

The color_scene object

scenes Array of scene objects An array of scene objects that describe lighting themes and scenarios. Minimum number of elements in the array: 1. Yes

The scene object included in the scenes array

Lighting scenario ID. You can find the acceptable values in the list below.

Lighting themes and scenarios


Theme (scenario)	Name
`alarm`	Alarm
`candle`	Candle
`dinner`	Dinner
`fantasy`	Fantasy
`garland`	Garland
`jungle`	Jungle
`movie`	Movie
`neon`	Neon
`night`	Night
`ocean`	Ocean
`party`	Party
`reading`	Reading
`rest`	Rest
`romance`	Romance
`siren`	Siren
`sunrise`	Sunrise
`sunset`	Sunset


Theme (scenario)	Name
`alarm`	Alarm
`candle`	Candle
`dinner`	Dinner
`fantasy`	Fantasy
`garland`	Garland
`jungle`	Jungle
`movie`	Movie
`neon`	Neon
`night`	Night
`ocean`	Ocean
`party`	Party
`reading`	Reading
`rest`	Rest
`romance`	Romance
`siren`	Siren
`sunrise`	Sunrise
`sunset`	Sunset

Yes

Example of use

Yango Smart Home requests the details of user devices from the provider. The provider responds that the user has a light bulb with color control.

curl -i -X GET 'https://example.com/v1.0/user/devices' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...'
Copied to clipboard

HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "user_id": "user-001",
        "devices": [{
            "id": "lamp-001-xdl",
            "name": "light bulb",
            "description": "xdl smart light bulb",
            "room": "bedroom",
            "type": "devices.types.light",
            "custom_data": {
                "api_location": "rus"
            },
            "capabilities": [{
                "type": "devices.capabilities.color_setting",
                "retrievable": true,
                "reportable": false,
                "parameters": {
                    "color_model": "hsv",
                    "temperature_k": {
                        "max": 6500,
                        "min": 2700
                    },
                    "color_scene": {
                        "scenes": [{
                                "id": "party"
                            },
                            {
                                "id": "alarm"
                            },
                            {
                                "id": "fantasy"
                            },
                            {
                                "id": "reading"
                            }
                        ]
                    }
                }
            }],
            "device_info": {
                "manufacturer": "Provider-01",
                "model": "xdl 1",
                "hw_version": "3.2",
                "sw_version": "2.4"
            }
        }]
    }
}                             
Copied to clipboard

Current capability state

The structure is used in the response to the Information about the states of user devices operation and in the request body of the Notification about device state change operation.

Capability parameters


Parameter	Type	Description	Required
type	String	Type of capability.	Yes
state	Object	Capability state parameters.	Yes
`state` object
instance	String	Function name for this capability. Acceptable values: `hsv`: change color according to the HSV model. `rgb`: Change color according to the RGB model. `temperature_k`: Change color temperature in kelvins. `scene`: Change lighting themes and scenarios.	Yes
value	Object/Integer	Function value for this capability. The format depends on the `instance` parameter value. Acceptable values: If `"instance": "rgb"`, then the `value` passes the color value in the [0; 16777215] range based on the RGB model. If `"instance": "temperature_k"`, then the color temperature in kelvins is passed in the `value`. If `"instance": "hsv"`, then the additional parameters such as `h`, `s`, and `v` are passed in the `value`. If `"instance": "scene"`, the `value` includes the names of the current lighting themes (scenarios) as strings.	Yes
`value` object
h	Integer	The `hue` varies in the range [0; 360] degrees.	Yes, if `"instance": "hsv"`.
s	Integer	The `saturation` varies in the range [0; 100].	Yes, if `"instance": "hsv"`.
v	Integer	Color value or brightness (`value`), changes in the range [0; 100].	Yes, if `"instance": "hsv"`.


Parameter	Type	Description	Required
type	String	Type of capability.	Yes
state	Object	Capability state parameters.	Yes
`state` object
instance	String	Function name for this capability. Acceptable values: `hsv`: change color according to the HSV model. `rgb`: Change color according to the RGB model. `temperature_k`: Change color temperature in kelvins. `scene`: Change lighting themes and scenarios.	Yes
value	Object/Integer	Function value for this capability. The format depends on the `instance` parameter value. Acceptable values: If `"instance": "rgb"`, then the `value` passes the color value in the [0; 16777215] range based on the RGB model. If `"instance": "temperature_k"`, then the color temperature in kelvins is passed in the `value`. If `"instance": "hsv"`, then the additional parameters such as `h`, `s`, and `v` are passed in the `value`. If `"instance": "scene"`, the `value` includes the names of the current lighting themes (scenarios) as strings.	Yes
`value` object
h	Integer	The `hue` varies in the range [0; 360] degrees.	Yes, if `"instance": "hsv"`.
s	Integer	The `saturation` varies in the range [0; 100].	Yes, if `"instance": "hsv"`.
v	Integer	Color value or brightness (`value`), changes in the range [0; 100].	Yes, if `"instance": "hsv"`.

Example of use

Yango Smart Home requests the provider to change the state of the user device. The provider responds with the state of the user device.

curl -i -X POST 'https://example.com/v1.0/user/devices/query' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...' \
-H 'Content-Type: application/json' \
-d '{
      "devices": 
      [
        {
            "id": "lamp-001-xdl",
            "custom_data": {
                "api_location": "rus"
            } 
        },
        {
            "id": "lamp-002-xdl",
            "custom_data": {
                "api_location": "rus"
            } 
        },
        {
            "id": "lamp-003-xdl",
            "custom_data": {
                "api_location": "rus"
            } 
        },
        {
            "id": "lamp-004-xdl",
            "custom_data": {
                "api_location": "rus"
            } 
        }
      ]
    }' 
Copied to clipboard

HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "devices": [
            {
                "id": "lamp-001-xdl",
                "capabilities": [
                    {
                        "type": "devices.capabilities.color_setting",
                        "state": {
                            "instance": "hsv",
                            "value": {
                                "h": 255,
                                "s": 100,
                                "v": 50
                            }
                        }
                    }
                ]
            },
            {
                "id": "lamp-002-xdl",
                "capabilities": [
                    {
                        "type": "devices.capabilities.color_setting",
                        "state": {
                            "instance": "rgb",
                            "value": 13910520	
                        }
                    }
                ]
            },
            {
                "id": "lamp-003-xdl",
                "capabilities": [
                    {
                        "type": "devices.capabilities.color_setting",
                        "state": {
                            "instance": "temperature_k",
                            "value": 4500
                        }
                    }
                ]
            },
            {
                "id": "lamp-004-xdl",
                "capabilities": [
                    {
                        "type": "devices.capabilities.color_setting",
                        "state": {
                            "instance": "scene",
                            "value": "sunrise"
                        }
                    }
                ]
            }
        ]
    }
}
Copied to clipboard

Change the state of the device capability

The structure is used in the response to the Change device state operation.

Capability parameters


Parameter	Type	Description	Required
type	String	Type of capability.	Yes
state	Object	An object that describes the result of changing the state of the capability.	Yes
`state` object
instance	String	Function name for this capability. Acceptable values: `hsv`: change color according to the HSV model. `rgb`: Change color according to the RGB model. `temperature_k`: Change color temperature in kelvins. `scene`: Change lighting themes and scenarios.	Yes
action_result	Object	Result of changing the state of the device capability.	No
`action_result` object
status	String	Status of the device capability state change. Acceptable values: `DONE`: The state of the device capability state changed. `ERROR`: An error occurred when changing the state of the device capability.	Yes
error_code	String	An error code from the list of errors. If `status:"ERROR"`, the parameter is required.	No
error_message	String	Extended human-readable description of a possible error. It is displayed only in the Testing section of the developer console.	No


Parameter	Type	Description	Required
type	String	Type of capability.	Yes
state	Object	An object that describes the result of changing the state of the capability.	Yes
`state` object
instance	String	Function name for this capability. Acceptable values: `hsv`: change color according to the HSV model. `rgb`: Change color according to the RGB model. `temperature_k`: Change color temperature in kelvins. `scene`: Change lighting themes and scenarios.	Yes
action_result	Object	Result of changing the state of the device capability.	No
`action_result` object
status	String	Status of the device capability state change. Acceptable values: `DONE`: The state of the device capability state changed. `ERROR`: An error occurred when changing the state of the device capability.	Yes
error_code	String	An error code from the list of errors. If `status:"ERROR"`, the parameter is required.	No
error_message	String	Extended human-readable description of a possible error. It is displayed only in the Testing section of the developer console.	No

Example of use

Yango Smart Home requests the provider to change the state of the user's devices. The provider responds with the result of user device state change.

curl -i -X POST 'https://example.com/v1.0/user/devices/action' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...' \
-H 'Content-Type: application/json' \
-d '{
      "payload": {
        "devices": [{
            "id": "lamp-001-xdl",
            "custom_data": {
                "api_location": "rus"
            },
            "capabilities": [{
                "type": "devices.capabilities.color_setting",
                "state": {
                    "instance": "hsv",
                    "value": {
                        "h": 125,
                        "s": 25,
                        "v": 100
                    }
                }
            }]
        },
        {
            "id": "lamp-002-xdl",
            "custom_data": {
                "api_location": "rus"
            },
            "capabilities": [{
                "type": "devices.capabilities.color_setting",
                "state": {
                    "instance": "rgb",
                    "value": 14210514
                }
            }]
        },
        {
            "id": "lamp-003-xdl",
            "custom_data": {
                "api_location": "rus"
            },
            "capabilities": [{
                "type": "devices.capabilities.color_setting",
                "state": {
                    "instance": "temperature_k",
                    "value": 5100
                }
            }]
        },
        {
            "id": "lamp-004-xdl",
            "capabilities": [{
                "type": "devices.capabilities.color_setting",
                "state": {
                    "instance": "scene",
                    "value": "party"
                }
            }]
        }
        ]     
      }
    }'
Copied to clipboard

HTTP/1.1 200 OK

{
  "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": [{
        "id": "lamp-001-xdl",
        "capabilities": [{
          "type": "devices.capabilities.color_setting",
          "state": {
            "instance": "hsv",
            "action_result": {
              "status": "DONE"
            }
          }
        }]
      },
      {
        "id": "lamp-002-xdl",
        "capabilities": [{
          "type": "devices.capabilities.color_setting",
          "state": {
            "instance": "rgb",
            "action_result": {
              "status": "DONE"
            }
          }
        }]
      },
      {
        "id": "lamp-003-xdl",
        "capabilities": [{
          "type": "devices.capabilities.color_setting",
          "state": {
            "instance": "temperature_k",
            "action_result": {
              "status": "DONE"
            }
          }
        }]
      },
      {
        "id": "lamp-004-xdl",
        "capabilities": [{
          "type": "devices.capabilities.color_setting",
          "state": {
            "instance": "scene",
            "action_result": {
              "status": "DONE"
            }
          }
        }]
      }
    ]
  }
}                                   
Copied to clipboard