Color_setting

devices.capabilities.color_setting

Управление цветом для светящихся элементов в устройстве. Устройство может иметь одно или несколько из перечисленных функций:
  • изменение цвета своих светящихся элементов на произвольный из схемы HSV или из модели RGB;
  • изменение температуры цвета своих светящихся элементов.
Примеры таких устройств (можно посмотреть на странице с описанием устройства типа devices.types.light):
  • цветная лампочка;
  • обычная белая лампочка с возможностью менять температуру белого цвета;
  • электрический чайник с подсветкой цветными светодиодами.
  1. Общие голосовые команды
  2. Описание умения
  3. Текущее состояние умения
  4. Изменение состояния умения у устройства

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

  1. Алиса, включи красный свет.

  2. Алиса, сделай свет теплее.

  3. Алиса, поставь зеленый цвет на лампочке.

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

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

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

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

Параметр Тип Описание Обязательный
type String Тип умения. Да
retrievable Boolean Доступен ли для данного умения устройства запрос состояния. Допустимые значения:
  • true — для умения доступен запрос состояния. Является значением по умолчанию;
  • false — для умения недоступен запрос состояния.
Нет
parameters Object Объект parameters. Объект должен содержать хотя бы один параметр. Да
Объект parameters
color_model String Произвольное изменение цвета светящихся элементов устройства. Допустимые значения:
  • hsv — изменение цвета в соответствии со схемой HSV;
  • rgb — изменение цвета в соответствии с моделью RGB. Значение должно быть представлено в 24-битном формате (TrueColor).
Да, если отсутствует параметр temperature_k
temperature_k Object

Изменение температуры цвета в кельвинах. Диапазон указывается в дополнительных полях min и max. Диапазон по умолчанию 2000—9000К.

Значение будет преобразовано в цвет из палитры цветов ниже.

Ограничение.

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

Если передать значение или диапазон значений, которые не пересекаются с таблицей, пользователю будет предложен вариант по умолчанию (белый цвет со значением 4500 К).

Палитра цветов
Цвет Температура, К Значение по умолчанию
Огненный белый 1500 Нет
Мягкий белый 2700 Нет
Теплый белый 3400 Нет
Белый 4500 Является значением по умолчанию
Дневной белый 5600 Нет
Холодный белый 6500 Нет
Туманный белый 7500 Нет
Небесный белый 9000 Нет
Цвет Температура, К Значение по умолчанию
Огненный белый 1500 Нет
Мягкий белый 2700 Нет
Теплый белый 3400 Нет
Белый 4500 Является значением по умолчанию
Дневной белый 5600 Нет
Холодный белый 6500 Нет
Туманный белый 7500 Нет
Небесный белый 9000 Нет
Да, если отсутствует параметр color_model
Объект temperature_k
min Integer Минимальная допустимая температура цвета в кельвинах. Нет
max Integer Максимальная температура цвета в кельвинах. Нет
Параметр Тип Описание Обязательный
type String Тип умения. Да
retrievable Boolean Доступен ли для данного умения устройства запрос состояния. Допустимые значения:
  • true — для умения доступен запрос состояния. Является значением по умолчанию;
  • false — для умения недоступен запрос состояния.
Нет
parameters Object Объект parameters. Объект должен содержать хотя бы один параметр. Да
Объект parameters
color_model String Произвольное изменение цвета светящихся элементов устройства. Допустимые значения:
  • hsv — изменение цвета в соответствии со схемой HSV;
  • rgb — изменение цвета в соответствии с моделью RGB. Значение должно быть представлено в 24-битном формате (TrueColor).
Да, если отсутствует параметр temperature_k
temperature_k Object

Изменение температуры цвета в кельвинах. Диапазон указывается в дополнительных полях min и max. Диапазон по умолчанию 2000—9000К.

Значение будет преобразовано в цвет из палитры цветов ниже.

Ограничение.

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

Если передать значение или диапазон значений, которые не пересекаются с таблицей, пользователю будет предложен вариант по умолчанию (белый цвет со значением 4500 К).

Палитра цветов
Цвет Температура, К Значение по умолчанию
Огненный белый 1500 Нет
Мягкий белый 2700 Нет
Теплый белый 3400 Нет
Белый 4500 Является значением по умолчанию
Дневной белый 5600 Нет
Холодный белый 6500 Нет
Туманный белый 7500 Нет
Небесный белый 9000 Нет
Цвет Температура, К Значение по умолчанию
Огненный белый 1500 Нет
Мягкий белый 2700 Нет
Теплый белый 3400 Нет
Белый 4500 Является значением по умолчанию
Дневной белый 5600 Нет
Холодный белый 6500 Нет
Туманный белый 7500 Нет
Небесный белый 9000 Нет
Да, если отсутствует параметр color_model
Объект temperature_k
min Integer Минимальная допустимая температура цвета в кельвинах. Нет
max Integer Максимальная температура цвета в кельвинах. Нет

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

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

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 Название функции для данного умения. Допустимые значения:
  • hsv — изменение цвета в соответствии со схемой HSV;
  • rgb — изменение цвета в соответствии с моделью RGB;
  • temperature_k — изменение температуры цвета в кельвинах.
Да
value Object/Integer Значение функции для данного умения. Формат зависит от значения параметра instance. Допустимые значения:
  1. Если "instance": "rgb" — в valueпередается значение цвета в соответствии с моделью RGB в диапазоне [0; 16777215].
  2. Если "instance": "temperature_k" — в value передается значение цветовой температуры в кельвинах.
  3. Если "instance": "hsv" — в value передаются дополнительные параметры h, s, v в отдельных полях.
Да
Объект value
h Integer Цветовой тон (hue), изменяется в диапазоне [0; 360] градусов. Да, если "instance": "hsv".
s Integer Насыщенность (saturation), изменяется в диапазоне [0; 100]. Да, если "instance": "hsv".
v Integer Значение цвета или яркость (value), изменяется в диапазоне [0; 100]. Да, если "instance": "hsv".
Параметр Тип Описание Обязательный
type String Тип умения. Да
state Object Параметры состояния умения. Да
Объект state
instance String Название функции для данного умения. Допустимые значения:
  • hsv — изменение цвета в соответствии со схемой HSV;
  • rgb — изменение цвета в соответствии с моделью RGB;
  • temperature_k — изменение температуры цвета в кельвинах.
Да
value Object/Integer Значение функции для данного умения. Формат зависит от значения параметра instance. Допустимые значения:
  1. Если "instance": "rgb" — в valueпередается значение цвета в соответствии с моделью RGB в диапазоне [0; 16777215].
  2. Если "instance": "temperature_k" — в value передается значение цветовой температуры в кельвинах.
  3. Если "instance": "hsv" — в value передаются дополнительные параметры h, s, v в отдельных полях.
Да
Объект value
h Integer Цветовой тон (hue), изменяется в диапазоне [0; 360] градусов. Да, если "instance": "hsv".
s Integer Насыщенность (saturation), изменяется в диапазоне [0; 100]. Да, если "instance": "hsv".
v Integer Значение цвета или яркость (value), изменяется в диапазоне [0; 100]. Да, если "instance": "hsv".

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

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

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

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

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

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

Параметр Тип Описание Обязательный
type String Тип умения. Да
state Object Объект, который описывает результат изменения состояния умения. Да
Объект state
instance String Название функции для данного умения. Допустимые значения:
  • hsv — изменение цвета в соответствии со схемой HSV;
  • rgb — изменение цвета в соответствии с моделью RGB;
  • temperature_k — изменение температуры цвета в кельвинах.
Да
action_result Object Результат изменения состояния умения устройства. Нет
Объект action_result
status String Статус изменения состояния умения устройства. Допустимые значения:
  • DONE — состояние умения устройства успешно изменено;
  • ERROR — при изменении состояния умения устройства произошла ошибка.
Да
error_code String Код возможной ошибки из списка ошибок. Если status:"ERROR", параметр является обязательным. Нет
error_message String Расширенное человекочитаемое описание возможной ошибки. Отображается только в разделе Тестирование в консоли разработчика. Нет
Параметр Тип Описание Обязательный
type String Тип умения. Да
state Object Объект, который описывает результат изменения состояния умения. Да
Объект state
instance String Название функции для данного умения. Допустимые значения:
  • hsv — изменение цвета в соответствии со схемой HSV;
  • rgb — изменение цвета в соответствии с моделью RGB;
  • temperature_k — изменение температуры цвета в кельвинах.
Да
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.color_setting",
                "state": {
                    "instance": "hsv",
                    "value": {
                        "h": 125,
                        "s": 25,
                        "v": 100
                    }
                }
            }]
        },
        {
            "id": "lamp-002-xdl",
            "custom_data": {
                "api_location": "rus"
            },
            "capabilities": [{
                "type": "devices.capabilities.color_setting",
                "state": {
                    "instance": "rgb",
                    "value": 14210514
                }
            }]
        },
        {
            "id": "lamp-003-xdl",
            "custom_data": {
                "api_location": "rus"
            },
            "capabilities": [{
                "type": "devices.capabilities.color_setting",
                "state": {
                    "instance": "temperature_k",
                    "value": 5100
                }
            }]
          }
        ]     
      }
    }'
Скопировано