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

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

Умения

Range

devices.capabilities.range

Управление параметрами устройства, которые имеют диапазон. Например, яркость лампы, громкость звука, температура обогревателя.

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

Алиса, поставь влажность в детской на 55%.
Алиса, убавь яркость света в спальне.
Алиса, сделай громче на 10.
Алиса, поставь второй канал на телевизоре.

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

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

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


Параметр	Тип	Описание	Обязательный
type	String	Тип умения.	Да
retrievable	Boolean	Доступен ли для данного умения устройства запрос состояния. Допустимые значения: `true` — для умения доступен запрос состояния. Является значением по умолчанию; `false` — для умения недоступен запрос состояния.	Нет
reportable	Boolean	Признак включенного оповещения об изменении состояния умения при помощи сервиса уведомлений. Допустимые значения: `true` — оповещение включено. Производитель оповещает платформу умного дома о каждом изменении состояния умения; `false` — оповещение выключено. Производитель не оповещает платформу об изменении состояния умения. Является значением по умолчанию.	Нет
parameters	Object	Объект `parameters`.	Да
Объект `parameters`
instance	String	Название функции для данного умения. Допустимые значения можно посмотреть в разделе Список функций.	Да
unit	String	Единицы измерения значений функции. Допустимые значения можно посмотреть в разделе Список функций.	Нет
random_access	Boolean	Возможность устанавливать произвольные значения функции. Если эта возможность выключена, пользователю будет доступно только последовательное изменение значений — в большую или меньшую сторону. Например, изменение громкости телевизора при работе через ИК пульт. Допустимые значения: `true` — возможность задавать произвольные значения включена; `false` — возможность выключена. По умолчанию: `true`.	Нет
range	Object	Объект с описанием диапазона значений функции.	Нет
Объект `range`
`min`	Float	Минимальное допустимое значение. Значение отличается в зависимости от функции умения. Подробности можно посмотреть в разделе Список функций.	Нет
`max`	Float	Максимальное допустимое значение. Значение отличается в зависимости от функции умения. Подробности можно посмотреть в разделе Список функций.	Нет
`precision`	Float	Минимальный шаг изменения значений внутри диапазона. Значение по умолчанию: 1.	Нет


Параметр	Тип	Описание	Обязательный
type	String	Тип умения.	Да
retrievable	Boolean	Доступен ли для данного умения устройства запрос состояния. Допустимые значения: `true` — для умения доступен запрос состояния. Является значением по умолчанию; `false` — для умения недоступен запрос состояния.	Нет
reportable	Boolean	Признак включенного оповещения об изменении состояния умения при помощи сервиса уведомлений. Допустимые значения: `true` — оповещение включено. Производитель оповещает платформу умного дома о каждом изменении состояния умения; `false` — оповещение выключено. Производитель не оповещает платформу об изменении состояния умения. Является значением по умолчанию.	Нет
parameters	Object	Объект `parameters`.	Да
Объект `parameters`
instance	String	Название функции для данного умения. Допустимые значения можно посмотреть в разделе Список функций.	Да
unit	String	Единицы измерения значений функции. Допустимые значения можно посмотреть в разделе Список функций.	Нет
random_access	Boolean	Возможность устанавливать произвольные значения функции. Если эта возможность выключена, пользователю будет доступно только последовательное изменение значений — в большую или меньшую сторону. Например, изменение громкости телевизора при работе через ИК пульт. Допустимые значения: `true` — возможность задавать произвольные значения включена; `false` — возможность выключена. По умолчанию: `true`.	Нет
range	Object	Объект с описанием диапазона значений функции.	Нет
Объект `range`
`min`	Float	Минимальное допустимое значение. Значение отличается в зависимости от функции умения. Подробности можно посмотреть в разделе Список функций.	Нет
`max`	Float	Максимальное допустимое значение. Значение отличается в зависимости от функции умения. Подробности можно посмотреть в разделе Список функций.	Нет
`precision`	Float	Минимальный шаг изменения значений внутри диапазона. Значение по умолчанию: 1.	Нет

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

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

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": "lamp-001-xdl",
                "name": "лампочка",
                "description": "умная лампочка xdl",
                "room": "спальня",
                "type": "devices.types.light",
                "custom_data": {
                    "api_location": "rus"
                },
                "capabilities": [{
                    "type": "devices.capabilities.range",
                    "retrievable": true,
                    "reportable": false,
                    "parameters": {
                        "instance": "brightness",
                        "random_access": true,
                        "range": {
                            "max": 100,
                            "min": 0,
                            "precision": 10
                        },
                        "unit": "unit.percent"
                    }
                }],
                "device_info": {
                    "manufacturer": "Provider-01",
                    "model": "xdl 1",
                    "hw_version": "3.2",
                    "sw_version": "2.4"
                }
            },
            {
                "id": "lamp-002-xdl",
                "name": "лампочка два",
                "description": "умная лампочка xdl",
                "room": "спальня",
                "type": "devices.types.light",
                "custom_data": {
                    "api_location": "rus"
                },
                "capabilities": [{
                    "type": "devices.capabilities.range",
                    "retrievable": true,
                    "reportable": false,
                    "parameters": {
                        "instance": "brightness",
                        "random_access": true,
                        "range": {
                            "max": 100,
                            "min": 0,
                            "precision": 10
                        },
                        "unit": "unit.percent"
                    }
                }],
                "device_info": {
                    "manufacturer": "Provider-01",
                    "model": "xdl 1",
                    "hw_version": "3.2",
                    "sw_version": "2.4"
                }
            }
        ]
    }
}
Скопировано

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

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

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


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


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

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

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

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": "lamp-001-xdl",
            "custom_data": {
                "api_location": "rus"
            } 
        }
      ]
    }' 
Скопировано

HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "devices": [
            {
                "id": "lamp-001-xdl",
                "capabilities": [
                    {
                        "type": "devices.capabilities.range",
                        "state": {
                            "instance": "brightness",
                            "value": 50
                        }
                    }
                ]
            }
        ]
    }
}
Скопировано

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

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

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


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


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


Параметр	Тип	Описание	Обязательный
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": "lamp-001-xdl",
                "custom_data": {
                    "api_location": "rus"
                },
                "capabilities": [{
                    "type": "devices.capabilities.range",
                    "state": {
                        "instance": "brightness",
                        "value": 50
                    }
                }]
            },
            {
                "id": "lamp-002-xdl",
                "custom_data": {
                    "api_location": "rus"
                },
                "capabilities": [{
                    "type": "devices.capabilities.range",
                    "state": {
                        "instance": "brightness",
                        "relative": true,
                        "value": 10
                    }
                }]
            }
        ]
      }
    }'
Скопировано

HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "devices": [
            {
                "id": "lamp-001-xdl",
                "capabilities": [
                    {
                        "type": "devices.capabilities.range",
                        "state": {
                            "instance": "brightness",
                            "action_result": {
                                "status": "DONE"
                            }
                        }
                    }
                ]
            },
            {
                "id": "lamp-002-xdl",
                "capabilities": [
                    {
                        "type": "devices.capabilities.range",
                        "state": {
                            "instance": "brightness",
                            "action_result": {
                                "status": "DONE"
                            }
                        }
                    }
                ]
            }
        ]
    }
}                          
Скопировано

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

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

Список режимов работы

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

В этой статье

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

Список режимов работы

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