Color_setting
devices.capabilities.color_setting
Управление цветом для светящихся элементов в устройстве. Устройство может иметь одну или несколько из перечисленных функций:
- изменение цвета своих светящихся элементов на произвольный из схемы HSV или из модели RGB;
- изменение температуры цвета своих светящихся элементов;
- воспроизведение различных визуальных эффектов.
Примеры таких устройств (можно посмотреть на странице с описанием устройства типа devices.types.light):
- цветная лампочка;
- обычная белая лампочка с возможностью менять температуру белого цвета;
- электрический чайник с подсветкой цветными светодиодами.
Общие голосовые команды
-
Алиса, включи красный свет.
-
Алиса, сделай свет теплее.
-
Алиса, поставь зеленый цвет на лампочке.
-
Алиса, включи свет в режим вечеринки.
Описание умения
Структура используется в ответе операции Информация об устройствах пользователя.
Параметры умения
Параметр |
Тип |
Описание |
Обязательный |
type |
String |
Тип умения. |
Да |
retrievable |
Boolean |
Доступен ли для данного умения устройства запрос состояния. Допустимые значения:
|
Нет |
reportable |
Boolean |
Признак включенного оповещения об изменении состояния умения при помощи сервиса уведомлений. Допустимые значения:
|
Нет |
parameters |
Object |
Объект |
Да |
Объект parameters
Параметр |
Тип |
Описание |
Обязательный |
|||||||||||||||||||||||||||
color_model |
String |
Произвольное изменение цвета светящихся элементов устройства. Допустимые значения:
|
Да, если отсутствуют параметры |
|||||||||||||||||||||||||||
temperature_k |
Object |
Изменение температуры цвета в кельвинах. Диапазон указывается в дополнительных полях Значение будет преобразовано в цвет из палитры цветов ниже. Ограничение Если устройство поддерживает только один температурный режим, необходимо выбрать наиболее близкое значение из таблицы и передавать его. Если передать значение или диапазон значений, которые не пересекаются с таблицей, пользователю будет предложен вариант по умолчанию (белый цвет со значением 4500 К). Палитра цветов
|
Да, если отсутствуют параметры |
|||||||||||||||||||||||||||
color_scene |
Object |
Изменение режима работы светящихся элементов устройства в соответствии с предустановленными темами и сценариями освещения. |
Да, если отсутствуют параметры |
Объект temperature_k
Параметр |
Тип |
Описание |
Обязательный |
min |
Integer |
Минимальная допустимая температура цвета в кельвинах. |
Нет |
max |
Integer |
Максимальная температура цвета в кельвинах. |
Нет |
Объект color_scene
Параметр |
Тип |
Описание |
Обязательный |
scenes |
Array of scene objects |
Массив объектов |
Да |
Объект 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 |
Значение функции для данного умения. Формат зависит от значения параметра 1. Если 2. Если 3. Если 4. Если |
Да |
Объект value
Параметр |
Тип |
Описание |
Обязательный |
h |
Integer |
Цветовой тон ( |
Да, если |
s |
Integer |
Насыщенность ( |
Да, если |
v |
Integer |
Значение цвета или яркость ( |
Да, если |
Пример использования
Платформа умного дома отправляет провайдеру запрос о состоянии устройств пользователя. Провайдер в ответ передает информацию о состоянии устройств пользователя.
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": "party"
}
}
]
}
]
}
}
Изменение состояния умения у устройства
Структура используется в ответе операции Изменение состояния у устройств.
Параметры умения
Параметр |
Тип |
Описание |
Обязательный |
type |
String |
Тип умения. |
Да |
state |
Object |
Объект, который описывает результат изменения состояния умения. |
Да |
Объект state
Параметр |
Тип |
Описание |
Обязательный |
instance |
String |
Название функции для данного умения. Допустимые значения:
|
Да |
action_result |
Object |
Результат изменения состояния умения устройства. |
Нет |
Объект action_result
Параметр |
Тип |
Описание |
Обязательный |
status |
String |
Статус изменения состояния умения устройства. Допустимые значения:
|
Да |
error_code |
String |
Код возможной ошибки из списка ошибок. Если |
Нет |
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"
}
}
}]
}
]
}
}
Список пар "ключ": значение
, разделенных запятой. Выделяется фигурными скобками {}
.
{
"name": "John",
"surname": "Smith"
}
Cтрока, выделяется кавычками, например "Hello world"
.
Целое число без кавычек, например 25
.
Массив элементов, разделенных запятой. Элементом могут быть стандартные элементы JSON: строка, число, true
, false
, объект или массив. Массив выделяется квадратными скобками []
:
"cities": ["Moscow", "Tokyo", "New York"]
Логическое значение без кавычек: true
(истина) или false
(ложь).