Event

devices.properties.event

Display of readings of device properties (properties can have one of the specified states).

Property description

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

Property parameters

Parameter

Type

Description

Required

type

String

Property type.

Yes

retrievable

Boolean

Whether it's possible to request the state of the device property. Acceptable values:

  • true: A state request is available for the property. Default value.
  • false: A state request is not available for the property. The value is available if reportable:true.

No

reportable

Boolean

Whether the property reports the state change to Yandex Smart Home using the notification service. Acceptable values:

  • true: Notification is enabled. The manufacturer notifies Yandex Smart Home of every property state change.
  • false: Notification is disabled. The manufacturer doesn't notify Yandex Smart Home of the property 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

events

Array of event objects

Array of event objects that describe events supported by the property. Minimum number of events in the array: 1.

Yes

The event object that is a part of the events 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 in the List of functions section.

Yes

Example of use

Yandex Smart Home requests the details of user devices from the provider. The provider responds that the user has a sensor that can display window/door opening events.

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": "sensor-001-snsr",
            "name": "Сенсор",
            "description": "Сенсор в спальне",
            "room": "Спальня",
            "type": "devices.types.sensor",
            "custom_data": {
                "api_location": "rus"
            },
            "capabilities": [],
            "properties": [{
                "type": "devices.properties.event",
                "retrievable": true,
                "reportable": true,
                "parameters": {
                    "instance": "open",
                    "events": [{
                            "value": "opened"
                        },
                        {
                            "value": "closed"
                        }
                    ]
                }
            }],
            "device_info": {
                "manufacturer": "Provider-01",
                "model": "snsr 1",
                "hw_version": "1.2",
                "sw_version": "5.4"
            }
        }]
    }
}

Current property 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.

Property parameters

Parameter

Type

Description

Required

type

String

Property type.

Yes

state

Object

Property 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

String

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 that the property shows the opening of a window or a door.

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

HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "devices": [{
            "id": "sensor-001-snsr",
            "properties": [{
                "type": "devices.properties.event",
                "state": {
                    "instance": "open",
                    "value": "opened"
                }
            }]
        }]
    }
}
Previous
List of functions
Next
List of functions