On_off

devices.capabilities.on_off

Remote device on/off (similar to pressing the power button on the device or its remote control). This is a basic capability for most devices.

Common voice commands

Most devices use separate turn on and turn off commands. Voice commands depend on the device type and are given in the description of the applicable types.

Алиса, включи свет.

Translation: Alice, turn on the light.
Алиса, поставь чайник.

Translation: Alice, put the kettle on.

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

parameters object

Parameter

Type

Description

Required

split

Boolean

This parameter is used with retrievable:false and shows that the provider uses different commands to turn on and off the device. The home screen of the Home with Alice app will show the turn-on settings for all supported devices. Acceptable values:

true: Different commands are used to turn the device on and off.
false: One command is used to turn the device on and off. Default value.

Example of use

Yandex Smart Home requests the details of user devices from the provider. In response, the provider sends information that the user has a socket with remote turn-on and turn-off.

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": "socket-001-xda",
                "name": "розетка",
                "description": "умная розетка xda",
                "room": "спальня",
                "type": "devices.types.socket",
                "custom_data": {
                    "api_location": "rus"
                },
                "capabilities": [
                    {
                        "type": "devices.capabilities.on_off",
                        "retrievable": false,
                        "reportable": false,
                        "parameters": {
                            "split": false
                        }
                    }
                ],
                "device_info": {
                    "manufacturer": "Provider-01",
                    "model": "xda 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. Acceptable values:

on: Remotely turn a device on and off.

Yes

value

Boolean

Function value for this capability. Acceptable values:

true: the device is on.
false: the device is off.

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": "socket-001-xda",
            "custom_data": {
                "api_location": "rus"
            }
        }
      ]
    }'

HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "devices": [
            {
                "id": "socket-001-xda",
                "capabilities": [
                    {
                        "type": "devices.capabilities.on_off",
                        "state": {
                            "instance": "on",
                            "value": true
                        }
                    }
                ]
            }
        ]
    }
}

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. Acceptable values:

on: Remotely turn a device on and off.

Yes

action_result

Object

Result of changing the state of the device capability.

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": "socket-001-xda",
            "custom_data": {
              "api_location": "rus"
            },
            "capabilities": [
              {
                 "type": "devices.capabilities.on_off",
                 "state": {
                   "instance": "on",
                   "value": false
                 }
              }
            ]
          }
        ]
      }
    }'

HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "devices": [
            {
                "id": "socket-001-xda",
                "capabilities": [
                    {
                        "type": "devices.capabilities.on_off",
                        "state": {
                            "instance": "on",
                            "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?

About capabilities

Color_setting