Toggle

devices.capabilities.toggle

Control of device parameters that can only be in one of two states. For example, buttons, toggles, and similar controls that enable or disable an additional function of the device.

Common voice commands

Yasmina, turn on the ionizer on the humidifier.
Yasmina, mute sound on the TV.
Yasmina, turn on the teapot backlight.

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	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 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.	No
parameters	Object	`parameters` object.	Yes
`parameters` object
instance	String	Function name for this capability. You can find the acceptable values in the List of functions section.	Yes


Parameter	Type	Description	Required
type	String	Type of capability.	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 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.	No
parameters	Object	`parameters` object.	Yes
`parameters` object
instance	String	Function name for this capability. You can find the acceptable values in the List of functions section.	Yes

Example of use

Yango Smart Home requests the details of user devices from the provider. The provider responds that the user has a humidifier with an ionizer.

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": "humidifier-001-xdh",
                "name": "humidifier",
                "description": "xdh smart humidifier",
                "room": "bedroom",
                "type": "devices.types.humidifier",
                "custom_data": {
                    "api_location": "rus"
                },
                "capabilities": [
                    {
                        "type": "devices.capabilities.toggle"
                        "retrievable": true,
                        "reportable": false,
                        "parameters": {
                            "instance": "ionization"
                        }
                    }
                ],
                "device_info": {
                    "manufacturer": "Provider-01",
                    "model": "xdh 1",
                    "hw_version": "1.2",
                    "sw_version": "5.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. You can find the acceptable values in the List of functions section.	Yes
value	Boolean	Function value for this capability. Acceptable values: `true`: The function is enabled. `false`: The function is disabled.	Yes


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. You can find the acceptable values in the List of functions section.	Yes
value	Boolean	Function value for this capability. Acceptable values: `true`: The function is enabled. `false`: The function is disabled.	Yes

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": "humidifier-001-xdh",
            "custom_data": {
                "api_location": "rus"
            } 
        }
      ]
    }' 
Copied to clipboard

HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "devices": [
            {
                "id": "humidifier-001-xdh",
                "capabilities": [
                    {
                        "type": "devices.capabilities.toggle",
                        "state": {
                            "instance": "ionization",
                            "value": true
                        }
                    }
                ]
            }
        ]
    }
}
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. 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
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. 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
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://endpoint_url/v1.0/user/devices/action' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...' \
-H 'Content-Type: application/json' \
-d '{
      "payload": {
        "devices": [{
            "id": "humidifier-001-xdh",
            "custom_data": {
                "api_location": "rus"
            },
            "capabilities": [{
                "type": "devices.capabilities.toggle",
                "state": {
                    "instance": "ionization",
                    "value": false
                }
            }]
        }]
      }
}'
Copied to clipboard

HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "devices": [
            {
                "id": "humidifier-001-xdh",
                "capabilities": [
                    {
                        "type": "devices.capabilities.toggle",
                        "state": {
                            "instance": "ionization",
                            "action_result": {
                                "status": "DONE"
                            }
                        }
                    }
                ]
            }
        ]
    }
}                                       
Copied to clipboard