On_off - Платформа умного дома Яндекса

Протокол работы с платформой

Умения

On_off

devices.capabilities.on_off

Удаленное включение и выключение устройства (аналог нажатия кнопки питания на устройстве или его пульте управления). Является базовым умением для большинства устройств.

Общие голосовые команды

Для большинства устройств используются отдельные команды включения и выключения. Голосовые команды зависят от типа устройства и приведены в описании соответствующих типов.

Алиса, включи свет.
Алиса, поставь чайник.

Описание умения

Структура используется в ответе операции Информация об устройствах пользователя.

Параметры умения


Параметр	Тип	Описание	Обязательный
type	String	Тип умения.	Да
retrievable	Boolean	Доступен ли для данного умения устройства запрос состояния. Допустимые значения: `true` — для умения доступен запрос состояния. Является значением по умолчанию; `false` — для умения недоступен запрос состояния.	Нет
reportable	Boolean	Признак включенного оповещения об изменении состояния умения при помощи сервиса уведомлений. Допустимые значения: `true` — оповещение включено. Производитель оповещает платформу умного дома о каждом изменении состояния умения; `false` — оповещение выключено. Производитель не оповещает платформу об изменении состояния умения. Является значением по умолчанию.	Нет
parameters	Object	Объект `parameters`.	Нет
Объект `parameters`
split	Boolean	Параметр используется совместно с `retrievable:false` и показывает, что за включение/выключение устройства у провайдера отвечают разные команды. На главном экране приложения Дом с Алисой у поддерживаемых устройств будет показана опция включения. Допустимые значения: `true` — за включение и выключение отвечают разные команды; `false` — за включение и выключение отвечает одна команда. Является значением по умолчанию.	Нет


Параметр	Тип	Описание	Обязательный
type	String	Тип умения.	Да
retrievable	Boolean	Доступен ли для данного умения устройства запрос состояния. Допустимые значения: `true` — для умения доступен запрос состояния. Является значением по умолчанию; `false` — для умения недоступен запрос состояния.	Нет
reportable	Boolean	Признак включенного оповещения об изменении состояния умения при помощи сервиса уведомлений. Допустимые значения: `true` — оповещение включено. Производитель оповещает платформу умного дома о каждом изменении состояния умения; `false` — оповещение выключено. Производитель не оповещает платформу об изменении состояния умения. Является значением по умолчанию.	Нет
parameters	Object	Объект `parameters`.	Нет
Объект `parameters`
split	Boolean	Параметр используется совместно с `retrievable:false` и показывает, что за включение/выключение устройства у провайдера отвечают разные команды. На главном экране приложения Дом с Алисой у поддерживаемых устройств будет показана опция включения. Допустимые значения: `true` — за включение и выключение отвечают разные команды; `false` — за включение и выключение отвечает одна команда. Является значением по умолчанию.	Нет

Пример использования

Платформа умного дома отправляет провайдеру запрос на получение информации об устройствах пользователя. Провайдер в ответ передает информацию о том, что у пользователя есть розетка с удаленным включением и выключением.

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"
                }
            }
        ]
    }
}
Скопировано

Текущее состояние умения

Структура используется в ответе операции Информация о состояниях устройств пользователя и в теле запроса операции Уведомление об изменении состояний устройств.

Параметры умения


Параметр	Тип	Описание	Обязательный
type	String	Тип умения.	Да
state	Object	Параметры состояния умения.	Да
Объект `state`
instance	String	Название функции для данного умения. Допустимые значения: `on` — удаленное включение и выключение устройства.	Да
value	Boolean	Значение функции для данного умения. Допустимые значения: `true` — устройство включено; `false` — устройство выключено.	Да


Параметр	Тип	Описание	Обязательный
type	String	Тип умения.	Да
state	Object	Параметры состояния умения.	Да
Объект `state`
instance	String	Название функции для данного умения. Допустимые значения: `on` — удаленное включение и выключение устройства.	Да
value	Boolean	Значение функции для данного умения. Допустимые значения: `true` — устройство включено; `false` — устройство выключено.	Да

Пример использования

Платформа умного дома отправляет провайдеру запрос о состоянии устройств пользователя. Провайдер в ответ передает информацию о состоянии устройств пользователя.

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
                        }
                    }
                ]
            }
        ]
    }
}  
Скопировано

Изменение состояния умения у устройства

Структура используется в ответе операции Изменение состояния у устройств.

Параметры умения


Параметр	Тип	Описание	Обязательный
type	String	Тип умения.	Да
state	Object	Объект, который описывает результат изменения состояния умения.	Да
Объект `state`
instance	String	Название функции для данного умения. Допустимые значения: `on` — удаленное включение и выключение устройства.	Да
action_result	Object	Результат изменения состояния умения устройства.	Нет
Объект `action_result`
status	String	Статус изменения состояния умения устройства. Допустимые значения: `DONE` — состояние умения устройства успешно изменено; `ERROR` — при изменении состояния умения устройства произошла ошибка.	Да
error_code	String	Код возможной ошибки из списка ошибок. Если `status:"ERROR"`, параметр является обязательным.	Нет
error_message	String	Расширенное человекочитаемое описание возможной ошибки. Отображается только в разделе Тестирование в консоли разработчика.	Нет


Параметр	Тип	Описание	Обязательный
type	String	Тип умения.	Да
state	Object	Объект, который описывает результат изменения состояния умения.	Да
Объект `state`
instance	String	Название функции для данного умения. Допустимые значения: `on` — удаленное включение и выключение устройства.	Да
action_result	Object	Результат изменения состояния умения устройства.	Нет
Объект `action_result`
status	String	Статус изменения состояния умения устройства. Допустимые значения: `DONE` — состояние умения устройства успешно изменено; `ERROR` — при изменении состояния умения устройства произошла ошибка.	Да
error_code	String	Код возможной ошибки из списка ошибок. Если `status:"ERROR"`, параметр является обязательным.	Нет
error_message	String	Расширенное человекочитаемое описание возможной ошибки. Отображается только в разделе Тестирование в консоли разработчика.	Нет

Пример использования

Платформа умного дома отправляет провайдеру запрос на изменение состояния у устройств пользователя. Провайдер в ответ передает результат изменения состояния у устройств пользователя.

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"
                            }
                        }
                    }
                ]
            }
        ]
    }
}              
Скопировано

Была ли статья полезна?

Расскажите, что вам не понравилось в статье:

Об умениях

Color_setting

В этой статье

Общие голосовые команды Описание умения Текущее состояние умения Изменение состояния умения у устройства

Об умениях

Color_setting