Range

devices.capabilities.range

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

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

  1. Алиса, поставь влажность в детской на 55%.

  2. Алиса, убавь яркость света в спальне.

  3. Алиса, сделай громче на 10.

  4. Алиса, поставь второй канал на телевизоре.

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

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

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

Параметр

Тип

Описание

Обязательный

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

Значение свойства для данного умения.

Да

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

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

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

Название функции для свойства. Допустимые значения можно посмотреть в разделе Список функций.

Да

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"
                            }
                        }
                    }
                ]
            }
        ]
    }
}

Число с плавающей точкой с точностью до 6-9 десятичных знаков.

Cтрока, выделяется кавычками, например "Hello world".

Логическое значение без кавычек: true (истина) или false (ложь).

Список пар "ключ": значение, разделенных запятой. Выделяется фигурными скобками {}.

{
  "name": "John",
  "surname": "Smith"
}
Предыдущая
Список режимов работы
Следующая
Список функций