Range

devices.capabilities.range

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

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

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

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

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

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

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

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

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

  1. Параметры умения
  2. Пример использования

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

Параметр Тип Описание Обязательный
type String Тип умения. Да
retrievable 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 — для умения недоступен запрос состояния.
Нет
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...'
Скопировано

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

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

  1. Параметры умения
  2. Пример использования

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

Параметр Тип Описание Обязательный
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"
            } 
        }
      ]
    }' 
Скопировано

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

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

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

Параметр Тип Описание Обязательный
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.
Нет

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

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

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