Color_setting

devices.capabilities.color_setting

Управление цветом для светящихся элементов в устройстве. Устройство может иметь одну или несколько из перечисленных функций:

  • изменение цвета своих светящихся элементов на произвольный из схемы HSV или из модели RGB;
  • изменение температуры цвета своих светящихся элементов;
  • воспроизведение различных визуальных эффектов.

Примеры таких устройств (можно посмотреть на странице с описанием устройства типа devices.types.light):

  • цветная лампочка;
  • обычная белая лампочка с возможностью менять температуру белого цвета;
  • электрический чайник с подсветкой цветными светодиодами.

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

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

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

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

  4. Алиса, включи свет в режим вечеринки.

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

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

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

Параметр

Тип

Описание

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

type

String

Тип умения.

Да

retrievable

Boolean

Доступен ли для данного умения устройства запрос состояния. Допустимые значения:

  • true — для умения доступен запрос состояния. Является значением по умолчанию;
  • false — для умения недоступен запрос состояния.

Нет

reportable

Boolean

Признак включенного оповещения об изменении состояния умения при помощи сервиса уведомлений. Допустимые значения:

  • true — оповещение включено. Производитель оповещает платформу умного дома о каждом изменении состояния умения;
  • false — оповещение выключено. Производитель не оповещает платформу об изменении состояния умения. Является значением по умолчанию.

Нет

parameters

Object

Объект parameters. Объект должен содержать хотя бы один параметр.

Да

Объект parameters

Параметр

Тип

Описание

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

color_model

String

Произвольное изменение цвета светящихся элементов устройства. Допустимые значения:

  • hsv — изменение цвета в соответствии со схемой HSV;
  • rgb — изменение цвета в соответствии с моделью RGB. Значение должно быть представлено в 24-битном формате (TrueColor).

Да, если отсутствуют параметры temperature_k и color_scene

temperature_k

Object

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

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

Ограничение

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

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

Палитра цветов

Цвет

Температура, К

Значение по умолчанию

Огненный белый

1500

Нет

Мягкий белый

2700

Нет

Теплый белый

3400

Нет

Белый

4500

Является значением по умолчанию

Дневной белый

5600

Нет

Холодный белый

6500

Нет

Туманный белый

7500

Нет

Небесный белый

9000

Нет

Да, если отсутствуют параметры 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

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

Темы и сценарии освещения

Тема (сценарий)

Название

alarm

Тревога

alice

Алиса

candle

Свеча

dinner

Ужин

fantasy

Фантазия

garland

Гирлянда

jungle

Джунгли

movie

Кино

neon

Неон

night

Ночь

ocean

Океан

party

Вечеринка

reading

Чтение

rest

Отдых

romance

Романтика

siren

Сирена

Да

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

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

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

Название функции для данного умения. Допустимые значения:

  • hsv — изменение цвета в соответствии со схемой HSV;
  • rgb — изменение цвета в соответствии с моделью RGB;
  • temperature_k — изменение температуры цвета в кельвинах;
  • scene — изменение тем и сценариев освещения.

Да

value

Object/Integer

Значение функции для данного умения. Формат зависит от значения параметра instance. Допустимые значения:

1. Если "instance": "rgb" — в valueпередается значение цвета в соответствии с моделью RGB в диапазоне [0; 16777215].

2. Если "instance": "temperature_k" — в value передается значение цветовой температуры в кельвинах.

3. Если "instance": "hsv" — в value передаются дополнительные параметры h, s, v в отдельных полях.

4. Если "instance": "scene" — в value передаются названия текущих тем (сценариев) освещения в виде строки.

Да

Объект 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": "party"
                        }
                    }
                ]
            }
        ]
    }
}

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

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

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

Параметр

Тип

Описание

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

type

String

Тип умения.

Да

state

Object

Объект, который описывает результат изменения состояния умения.

Да

Объект state

Параметр

Тип

Описание

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

instance

String

Название функции для данного умения. Допустимые значения:

  • hsv — изменение цвета в соответствии со схемой HSV;
  • rgb — изменение цвета в соответствии с моделью RGB;
  • temperature_k — изменение температуры цвета в кельвинах;
  • scene — изменение тем и сценариев освещения.

Да

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
                }
            }]
        },
        {
            "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 (ложь).

Предыдущая
On_off
Следующая
Video_stream