Об умениях

Умение (capability) — свойство объекта Устройство (device), которое описывает его возможности (умения). Устройство описывается как минимум одним умением, если у него при этом нет свойств. Платформа умного дома не ограничивает провайдеров в выборе возможностей для устройств, поэтому у пользователя могут появиться устройства с нестандартной связкой device_type:capability, например, у телевизора может быть функция «температура».

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

Совет

Проверить валидность параметров и увидеть соответствующие ошибки валидации можно с помощью раздела Тестирование в консоли разработчика.

На основе заданных умений голосовой помощник Алиса или приложение Дом с Алисой строят модель управления устройством: Алиса выбирает соответствующие голосовые сценарии управления, а приложение  Дом с Алисой отображает соответствующие умениям элементы управления и экраны.

В зависимости от выполняемой операции в объекте Capability передается разный набор полей:

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

    {
    "type": {string},
    "retrievable": {boolean},
    "reportable": {boolean},
    "parameters": {CapabilityParameterObject}
}

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

    {
    "type": {string},
    "state": {
        "instance": {string},
        "value": {InstanceValue}
    }
}

  3. Команды для управления умением устройства используются в операции Изменение состояния у устройств:

    {
    "type": {string},
    "state": {
        "instance": {string},
        "value": {InstanceValue}
    }
}

Поля retrievable и reportable

В описании умения устройства (в ответе на запрос Информация об устройствах пользователя) могут передаваться два логических поля:

Поле

Тип

Описание

Обязательность

retrievable

Boolean

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

  • true (по умолчанию) — состояние умения доступно для запроса. Платформа отправляет query и ожидает актуальное значение в ответе.
  • false — состояние умения недоступно для запроса. Платформа не запрашивает состояние этого умения, а полагается только на уведомление /callback/state.

Если поле не указано, по умолчанию используется true.

Нет

reportable

Boolean

Указывает, должно ли изменение состояния этого умения доставляться через сервис уведомлений (уведомление /callback/state).

  • true — изменение состояния умения доставляется уведомлением /callback/state, в том числе если оно произошло без команды со стороны Яндекса: физической кнопкой, пультом, из приложения провайдера, локальным сценарием провайдера.
  • false (по умолчанию) — изменение состояния умения не требуется отправлять уведомлением. Платформа получает актуальное состояние через запрос query, который отправляется по действию пользователя.

Если поле не указано, по умолчанию используется false.

Если у умения одновременно retrievable: false и reportable: false, платформа не получает актуальное состояние ни одним из способов.

Нет

Важно

С 1 декабря 2026 года изменение каждого умения и каждого свойства, у которых указано reportable: true, должно доставляться в платформу умного дома запросом Уведомление об изменении состояния устройства — POST /api/v1/skills/{skill_id}/callback/state.

Событие отправляется по факту его наступления, без ожидания запроса со стороны Яндекса. Ответы на запросы Информация о состояниях устройств пользователя и Изменение состояния у устройств уведомление не заменяют.

Исчерпывающий перечень событий, при которых нужно отправлять уведомление, см. в разделе Требования к уведомлениям.

Поля retrievable и reportable описывают отдельное умение или отдельное свойство. Не путайте их с полем status_info.reportable, которое относится к устройству целиком и отвечает за передачу статуса доступности online и offline. Подробнее см. в разделе Информация об устройствах пользователя.

Типы умений

Тип умения

Описание

on_off

Удаленное включение и выключение устройства (аналог нажатия кнопки питания на устройстве или его пульте управления). Является базовым умением для большинства устройств.

color_setting

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

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

mode

Переключение режимов работы устройства, например, переключение между температурными режимами работы кондиционера: «Охлаждение», «Нагрев» или «Авто».

range

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

toggle

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

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