Mode

devices.capabilities.mode

Switching device operation modes (for example, switching between air conditioner temperature modes: “Cooling”, “Heating”, or “Auto”).

Common voice commands

Алиса, включи автоматический режим вентиляции.

Translation: Alice, set the fan to automatic.
Алиса, включи экспресс режим уборки на пылесосе.

Translation: Alice, turn on the vacuum cleaner in express mode.
Алиса, поставь скорость работы в режим турбо.

Translation: Alice, set the speed to turbo.

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. Copied	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. Copied	No
parameters	Object	`parameters` object.	Yes

parameters object

Parameter	Type	Description	Required
instance	String	Function name for this capability. You can find the acceptable values in the List of functions section.	Yes
modes	Array of mode objects	The array of `mode` objects describing the function's modes. Minimum number of modes in the array: 1. Limitation When resending the `mode` object array for the same device, keep in mind the order of modes. The order must be the same as in the latest array sent.	Yes

The mode object that is a part of the modes array

Parameter	Type	Description	Required
value	String	The value of the function operating mode processed on the provider side. You can find the acceptable values on the List of operating modes.	Yes

Example of use

Yandex Smart Home requests the details of user devices from the provider. The provider responds that the user has an air conditioner with different temperature modes.

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": "ac-001-xdc",
            "name": "кондиционер",
            "description": "умный кондиционер xdc",
            "room": "спальня",
            "type": "devices.types.thermostat.ac",
            "custom_data": {
                "api_location": "rus"
            },
            "capabilities": [{
                "type": "devices.capabilities.mode",
                "retrievable": true,
                "reportable": false,
                "parameters": {
                    "instance": "thermostat",
                    "modes": [
                        {
                            "value": "fan_only"
                        },
                        {
                            "value": "heat"
                        },
                        {
                            "value": "cool"
                        },
                        {
                            "value": "dry"
                        },
                        {
                            "value": "auto"
                        }
                    ]
                }
            }],
            "device_info": {
                "manufacturer": "Provider-01",
                "model": "xdc 1",
                "hw_version": "1.2",
                "sw_version": "5.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 this capability. You can find the acceptable values in the List of functions section.	Yes
value	String	The value of the function operating mode processed on the provider side. You can find the acceptable values on the List of operating modes.	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": "ac-001-xdc",
            "custom_data": {
                "api_location": "rus"
            }
        }
      ]
    }'

HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "devices": [
            {
                "id": "ac-001-xdc",
                "capabilities": [
                    {
                        "type": "devices.capabilities.mode",
                        "state": {
                            "instance": "thermostat",
                            "value": "cool"
                        }
                    }
                ]
            }
        ]
    }
}

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	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 this capability. 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. Copied	Yes
error_code	String	An error code from the list of errors. If `status:"ERROR"`, the parameter is required. Copied	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": "ac-001-xdc",
            "custom_data": {
                "api_location": "rus"
            },
            "capabilities": [{
                "type": "devices.capabilities.mode",
                "state": {
                    "instance": "thermostat",
                    "value": "heat"
                }
            }]
        }]
      }
    }'

HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "devices": [
            {
                "id": "ac-001-xdc",
                "capabilities": [
                    {
                        "type": "devices.capabilities.mode",
                        "state": {
                            "instance": "thermostat",
                            "action_result": {
                                "status": "DONE"
                            }
                        }
                    }
                ]
            }
        ]
    }
}

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

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

An array of elements separated by a comma. As array items, you can use standard JSON elements: a string, number, true, false, object, or array. Arrays are enclosed in square brackets []:

"cities": ["Moscow", "Tokyo", "New York"]

Was the article helpful?

Video_stream

List of functions