Color_setting
devices.capabilities.color_setting
Управление цветом для светящихся элементов в устройстве. Устройство может иметь одну или несколько из перечисленных функций:
- изменение температуры цвета своих светящихся элементов;
- воспроизведение различных визуальных эффектов.
Примеры таких устройств (можно посмотреть на странице с описанием устройства типа devices.types.light):
- цветная лампочка;
- обычная белая лампочка с возможностью менять температуру белого цвета;
- электрический чайник с подсветкой цветными светодиодами.
Общие голосовые команды
Алиса, включи красный свет.
Алиса, сделай свет теплее.
Алиса, поставь зеленый цвет на лампочке.
Алиса, включи свет в режим вечеринки.
Описание умения
Структура используется в ответе операции Информация об устройствах пользователя.
Параметры умения
| Параметр | Тип | Описание | Обязательный | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| type | String | Тип умения. | Да | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| retrievable | Boolean | Доступен ли для данного умения устройства запрос состояния. Допустимые значения:
| Нет | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| reportable | Boolean | Признак включенного оповещения об изменении состояния умения при помощи сервиса уведомлений. Допустимые значения:
| Нет | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| parameters | Object | Объект parameters. Объект должен содержать хотя бы один параметр. | Да | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Объект parameters | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| color_model | String | Произвольное изменение цвета светящихся элементов устройства. Допустимые значения:
| Да, если отсутствуют параметры temperature_k и color_scene | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| temperature_k | Object | Изменение температуры цвета в кельвинах. Диапазон указывается в дополнительных полях Значение будет преобразовано в цвет из палитры цветов ниже. Ограничение. Если устройство поддерживает только один температурный режим, необходимо выбрать наиболее близкое значение из таблицы и передавать его. Если передать значение или диапазон значений, которые не пересекаются с таблицей, пользователю будет предложен вариант по умолчанию (белый цвет со значением 4500 К). Палитра цветов
| Да, если отсутствуют параметры color_model и color_scene | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| color_scene | Object | Изменение режима работы светящихся элементов устройства в соответствии с предустановленными темами и сценариями освещения. | Да, если отсутствуют параметры color_model и temperature_k | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Объект temperature_k | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| min | Integer | Минимальная допустимая температура цвета в кельвинах. | Нет | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| max | Integer | Максимальная температура цвета в кельвинах. | Нет | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Объект color_scene | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| scenes | Array of scene objects | Массив объектов scene, которые описывают темы и сценарии освещения. Минимальное количество элементов в массиве: 1. | Да | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Объект scene, который входит в массив scenes | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | String | Идентификатор сценария освещения. Допустимые значения можно посмотреть в списке ниже. Темы и сценарии освещения
| Да | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Параметр | Тип | Описание | Обязательный | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| type | String | Тип умения. | Да | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| retrievable | Boolean | Доступен ли для данного умения устройства запрос состояния. Допустимые значения:
| Нет | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| reportable | Boolean | Признак включенного оповещения об изменении состояния умения при помощи сервиса уведомлений. Допустимые значения:
| Нет | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| parameters | Object | Объект parameters. Объект должен содержать хотя бы один параметр. | Да | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Объект parameters | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| color_model | String | Произвольное изменение цвета светящихся элементов устройства. Допустимые значения:
| Да, если отсутствуют параметры temperature_k и color_scene | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| temperature_k | Object | Изменение температуры цвета в кельвинах. Диапазон указывается в дополнительных полях Значение будет преобразовано в цвет из палитры цветов ниже. Ограничение. Если устройство поддерживает только один температурный режим, необходимо выбрать наиболее близкое значение из таблицы и передавать его. Если передать значение или диапазон значений, которые не пересекаются с таблицей, пользователю будет предложен вариант по умолчанию (белый цвет со значением 4500 К). Палитра цветов
| Да, если отсутствуют параметры color_model и color_scene | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| color_scene | Object | Изменение режима работы светящихся элементов устройства в соответствии с предустановленными темами и сценариями освещения. | Да, если отсутствуют параметры color_model и temperature_k | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Объект temperature_k | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| min | Integer | Минимальная допустимая температура цвета в кельвинах. | Нет | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| max | Integer | Максимальная температура цвета в кельвинах. | Нет | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Объект color_scene | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| scenes | Array of scene objects | Массив объектов scene, которые описывают темы и сценарии освещения. Минимальное количество элементов в массиве: 1. | Да | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Объект scene, который входит в массив scenes | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | 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": "lamp-001-xdl", "name": "лампочка", "description": "умная лампочка xdl", "room": "спальня", "type": "devices.types.light", "custom_data": { "api_location": "rus" }, "capabilities": [{ "type": "devices.capabilities.color_setting", "retrievable": true, "reportable": false, "parameters": { "color_model": "hsv", "temperature_k": { "max": 6500, "min": 2700 }, "color_scene": { "scenes": [{ "id": "party" }, { "id": "alarm" }, { "id": "fantasy" }, { "id": "reading" } ] } } }], "device_info": { "manufacturer": "Provider-01", "model": "xdl 1", "hw_version": "3.2", "sw_version": "2.4" } }] } }Скопировано
Текущее состояние умения
Структура используется в ответе операции Информация о состояниях устройств пользователя и в теле запроса операции Уведомление об изменении состояний устройств.
Параметры умения
| Параметр | Тип | Описание | Обязательный |
|---|---|---|---|
| type | String | Тип умения. | Да |
| state | Object | Параметры состояния умения. | Да |
Объект state | |||
| instance | String | Название функции для данного умения. Допустимые значения:
| Да |
| value | Object/Integer | Значение функции для данного умения. Формат зависит от значения параметра instance. Допустимые значения:
| Да |
Объект 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 | Название функции для данного умения. Допустимые значения:
| Да |
| value | Object/Integer | Значение функции для данного умения. Формат зависит от значения параметра instance. Допустимые значения:
| Да |
Объект 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" } }, { "id": "lamp-004-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.color_setting", "state": { "instance": "hsv", "value": { "h": 255, "s": 100, "v": 50 } } } ] }, { "id": "lamp-002-xdl", "capabilities": [ { "type": "devices.capabilities.color_setting", "state": { "instance": "rgb", "value": 13910520 } } ] }, { "id": "lamp-003-xdl", "capabilities": [ { "type": "devices.capabilities.color_setting", "state": { "instance": "temperature_k", "value": 4500 } } ] }, { "id": "lamp-004-xdl", "capabilities": [ { "type": "devices.capabilities.color_setting", "state": { "instance": "scene", "value": "sunrise" } } ] } ] } }Скопировано
Изменение состояния умения у устройства
Структура используется в ответе операции Изменение состояния у устройств.
Параметры умения
| Параметр | Тип | Описание | Обязательный |
|---|---|---|---|
| type | String | Тип умения. | Да |
| state | Object | Объект, который описывает результат изменения состояния умения. | Да |
Объект state | |||
| instance | String | Название функции для данного умения. Допустимые значения:
| Да |
| action_result | Object | Результат изменения состояния умения устройства. | Нет |
Объект action_result | |||
| status | String | Статус изменения состояния умения устройства. Допустимые значения:
| Да |
| error_code | String | Код возможной ошибки из списка ошибок. Если status:"ERROR", параметр является обязательным. | Нет |
| error_message | String | Расширенное человекочитаемое описание возможной ошибки. Отображается только в разделе Тестирование в консоли разработчика. | Нет |
| Параметр | Тип | Описание | Обязательный |
|---|---|---|---|
| type | String | Тип умения. | Да |
| state | Object | Объект, который описывает результат изменения состояния умения. | Да |
Объект state | |||
| instance | String | Название функции для данного умения. Допустимые значения:
| Да |
| action_result | Object | Результат изменения состояния умения устройства. | Нет |
Объект action_result | |||
| status | String | Статус изменения состояния умения устройства. Допустимые значения:
| Да |
| 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 } }] }, { "id": "lamp-004-xdl", "capabilities": [{ "type": "devices.capabilities.color_setting", "state": { "instance": "scene", "value": "party" } }] } ] } }'Скопировано
HTTP/1.1 200 OK { "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "devices": [{ "id": "lamp-001-xdl", "capabilities": [{ "type": "devices.capabilities.color_setting", "state": { "instance": "hsv", "action_result": { "status": "DONE" } } }] }, { "id": "lamp-002-xdl", "capabilities": [{ "type": "devices.capabilities.color_setting", "state": { "instance": "rgb", "action_result": { "status": "DONE" } } }] }, { "id": "lamp-003-xdl", "capabilities": [{ "type": "devices.capabilities.color_setting", "state": { "instance": "temperature_k", "action_result": { "status": "DONE" } } }] }, { "id": "lamp-004-xdl", "capabilities": [{ "type": "devices.capabilities.color_setting", "state": { "instance": "scene", "action_result": { "status": "DONE" } } }] } ] } }Скопировано
