Range

devices.capabilities.range

Control of device parameters that have a range of values. For example, the brightness of a lamp, the volume of sound, or the temperature of a heater.

Common voice commands

Алиса, поставь влажность в детской на 55%.

Translation: Alice, set humidity in the nursery at 55%.
Алиса, убавь яркость света в спальне.

Translation: Alice, turn down the light in the bedroom.
Алиса, сделай громче на 10.

Translation: Alice, turn up the volume by 10.
Алиса, поставь второй канал на телевизоре.

Translation: Alice, put the TV on the second channel.

Capability description

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

Capability parameters

Parameter	Type	Description	Required
type	String	Capability type.	Yes
retrievable	Boolean	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.	No
reportable	Boolean	Indicates that the notification service reports the capability state change. Acceptable values: `true`: Notification is enabled. The manufacturer notifies Yandex Smart Home of every change in the capability state. `false`: Notification is disabled. The manufacturer doesn't notify Yandex Smart Home of the capability state change. Default value.	No
parameters	Object	`parameters` object.	Yes

parameters object

Parameter	Type	Description	Required
instance	String	Function name for the property. You can find the acceptable values in the List of functions section.	Yes
unit	String	Function value units. You can find the acceptable values in the List of functions section.	No
random_access	Boolean	Setting arbitrary function values. If this feature is disabled, the user can only change the values gradually, either up or down. For example, turning the TV volume up or down via an IR remote. Acceptable values: `true`: Setting arbitrary values is enabled. `false`: The feature is disabled. Default value: `true`.	No
range	Object	Object that describes the range of function values.	No

range object

Parameter	Type	Description	Required
min	Float	Minimum acceptable value. The value varies depending on the capability function. Read more on the List of functions.	No
max	Float	Maximum acceptable value. The value varies depending on the capability function. Read more on the List of functions.	No
precision	Float	The minimum step between values in the range. Default value: 1.	No

Example of use

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

Request

Response

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

HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "user_id": "user-001",
        "devices": [{
                "id": "lamp-001-xdl",
                "name": "лампочка",
                "description": "умная лампочка xdl",
                "room": "спальня",
                "type": "devices.types.light",
                "custom_data": {
                    "api_location": "rus"
                },
                "capabilities": [{
                    "type": "devices.capabilities.range",
                    "retrievable": true,
                    "reportable": false,
                    "parameters": {
                        "instance": "brightness",
                        "random_access": true,
                        "range": {
                            "max": 100,
                            "min": 0,
                            "precision": 10
                        },
                        "unit": "unit.percent"
                    }
                }],
                "device_info": {
                    "manufacturer": "Provider-01",
                    "model": "xdl 1",
                    "hw_version": "3.2",
                    "sw_version": "2.4"
                }
            },
            {
                "id": "lamp-002-xdl",
                "name": "лампочка два",
                "description": "умная лампочка xdl",
                "room": "спальня",
                "type": "devices.types.light",
                "custom_data": {
                    "api_location": "rus"
                },
                "capabilities": [{
                    "type": "devices.capabilities.range",
                    "retrievable": true,
                    "reportable": false,
                    "parameters": {
                        "instance": "brightness",
                        "random_access": true,
                        "range": {
                            "max": 100,
                            "min": 0,
                            "precision": 10
                        },
                        "unit": "unit.percent"
                    }
                }],
                "device_info": {
                    "manufacturer": "Provider-01",
                    "model": "xdl 1",
                    "hw_version": "3.2",
                    "sw_version": "2.4"
                }
            }
        ]
    }
}

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	Capability type.	Yes
state	Object	Capability state parameters.	Yes

state object

Parameter	Type	Description	Required
instance	String	Function name for the property. You can find the acceptable values in the List of functions section.	Yes
value	Float	Property value for this capability.	Yes

Example of use

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

Request

Response

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"
            }
        }
      ]
    }'

HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "devices": [
            {
                "id": "lamp-001-xdl",
                "capabilities": [
                    {
                        "type": "devices.capabilities.range",
                        "state": {
                            "instance": "brightness",
                            "value": 50
                        }
                    }
                ]
            }
        ]
    }
}

Change the state of the device capability

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

Capability parameters

Request

Response

Parameter

Parameter	Type	Description	Required
type	String	Capability type.	Yes
state	Object	An object that describes the necessary changes for the capability state.	Yes

state object

Parameter	Type	Description	Required
instance	String	Function name for the property. You can find the acceptable values in the List of functions section.	Yes
value	Float	Property value for this capability.	Yes
relative	Boolean	The method to calculate the function value for the skill. `true`: The new function value is calculated from the current value by incrementing it by `value`. `false`: The skill function is set to `value`. By default: `false`.	No

Parameter	Type	Description	Required
type	String	Capability type.	Yes
state	Object	An object that describes the result of changing the state of the capability.	Yes

state object

Parameter	Type	Description	Required
instance	String	Function name for the property. You can find the acceptable values in the List of functions section.	Yes
action_result	Object	Result of changing the state of the device capability.	No

action_result object

Parameter	Type	Description	Required
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

Yandex 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.

Request

Response

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.range",
                    "state": {
                        "instance": "brightness",
                        "value": 50
                    }
                }]
            },
            {
                "id": "lamp-002-xdl",
                "custom_data": {
                    "api_location": "rus"
                },
                "capabilities": [{
                    "type": "devices.capabilities.range",
                    "state": {
                        "instance": "brightness",
                        "relative": true,
                        "value": 10
                    }
                }]
            }
        ]
      }
    }'

HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "devices": [
            {
                "id": "lamp-001-xdl",
                "capabilities": [
                    {
                        "type": "devices.capabilities.range",
                        "state": {
                            "instance": "brightness",
                            "action_result": {
                                "status": "DONE"
                            }
                        }
                    }
                ]
            },
            {
                "id": "lamp-002-xdl",
                "capabilities": [
                    {
                        "type": "devices.capabilities.range",
                        "state": {
                            "instance": "brightness",
                            "action_result": {
                                "status": "DONE"
                            }
                        }
                    }
                ]
            }
        ]
    }
}

List of "key": value pairs separated by commas. The list is enclosed in curly brackets {}.

{
  "name": "John",
  "surname": "Smith"
}

Was the article helpful?

List of operating modes

List of functions