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

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

Умения

Mode

devices.capabilities.mode

Переключение режимов работы устройства, например, переключение между температурными режимами работы кондиционера: «Охлаждение», «Нагрев» или «Авто».

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

Алиса, включи автоматический режим вентиляции.
Алиса, включи экспресс режим уборки на пылесосе.
Алиса, поставь скорость работы в режим турбо.

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

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

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


Параметр	Тип	Описание	Обязательный
type	String	Тип умения.	Да
retrievable	Boolean	Доступен ли для данного умения устройства запрос состояния. Допустимые значения: `true` — для умения доступен запрос состояния. Является значением по умолчанию; `false` — для умения недоступен запрос состояния.	Нет
reportable	Boolean	Признак включенного оповещения об изменении состояния умения при помощи сервиса уведомлений. Допустимые значения: `true` — оповещение включено. Производитель оповещает платформу умного дома о каждом изменении состояния умения; `false` — оповещение выключено. Производитель не оповещает платформу об изменении состояния умения. Является значением по умолчанию.	Нет
parameters	Object	Объект `parameters`.	Да
Объект `parameters`
instance	String	Название функции для данного умения. Допустимые значения можно посмотреть в разделе Список функций.	Да
modes	Array of mode objects	Массив объектов `mode`, которые описывают режимы работы функции. Минимальное количество режимов в массиве: 1. Ограничение. При повторной отправке массива объектов `mode`, для одного и того же устройства, необходимо соблюдать порядок режимов. Он должен совпадать с предыдущим отправленным вариантом.	Да
Объект `mode`, который входит в массив `modes`
value	String	Значение режима работы функции, обрабатываемое на стороне провайдера. Допустимые значения можно посмотреть в разделе Список режимов работы.	Да


Параметр	Тип	Описание	Обязательный
type	String	Тип умения.	Да
retrievable	Boolean	Доступен ли для данного умения устройства запрос состояния. Допустимые значения: `true` — для умения доступен запрос состояния. Является значением по умолчанию; `false` — для умения недоступен запрос состояния.	Нет
reportable	Boolean	Признак включенного оповещения об изменении состояния умения при помощи сервиса уведомлений. Допустимые значения: `true` — оповещение включено. Производитель оповещает платформу умного дома о каждом изменении состояния умения; `false` — оповещение выключено. Производитель не оповещает платформу об изменении состояния умения. Является значением по умолчанию.	Нет
parameters	Object	Объект `parameters`.	Да
Объект `parameters`
instance	String	Название функции для данного умения. Допустимые значения можно посмотреть в разделе Список функций.	Да
modes	Array of mode objects	Массив объектов `mode`, которые описывают режимы работы функции. Минимальное количество режимов в массиве: 1. Ограничение. При повторной отправке массива объектов `mode`, для одного и того же устройства, необходимо соблюдать порядок режимов. Он должен совпадать с предыдущим отправленным вариантом.	Да
Объект `mode`, который входит в массив `modes`
value	String	Значение режима работы функции, обрабатываемое на стороне провайдера. Допустимые значения можно посмотреть в разделе Список режимов работы.	Да

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

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

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

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

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

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


Параметр	Тип	Описание	Обязательный
type	String	Тип умения.	Да
state	Object	Параметры состояния умения.	Да
Объект `state`
instance	String	Название функции для данного умения. Допустимые значения можно посмотреть в разделе Список функций.	Да
value	String	Значение режима работы функции, обрабатываемое на стороне провайдера. Допустимые значения можно посмотреть в разделе Список режимов работы.	Да


Параметр	Тип	Описание	Обязательный
type	String	Тип умения.	Да
state	Object	Параметры состояния умения.	Да
Объект `state`
instance	String	Название функции для данного умения. Допустимые значения можно посмотреть в разделе Список функций.	Да
value	String	Значение режима работы функции, обрабатываемое на стороне провайдера. Допустимые значения можно посмотреть в разделе Список режимов работы.	Да

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

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

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

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

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

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


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


Параметр	Тип	Описание	Обязательный
type	String	Тип умения.	Да
state	Object	Объект, который описывает результат изменения состояния умения.	Да
Объект `state`
instance	String	Название функции для данного умения. Допустимые значения можно посмотреть в разделе Список функций.	Да
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": "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"
                            }
                        }
                    }
                ]
            }
        ]
    }
}                                                         
Скопировано

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

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

Video_stream

Список функций

В этой статье

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

Video_stream

Список функций