Основные объекты

Устройство (device)

Объект, который описывает умное устройство, как реальное так и виртуальное, созданное пользователем (например, пульт ДУ). Каждое устройство имеет тип и набор умений (минимально устройство описывается одним умением).

Типы устройств
Тип Описание Пример устройства
devices.types.light Устройство, которое имеет управляемые светящиеся элементы Лампочка, лампа-светильник, ночник.
devices.types.socket Розетка Умная розетка.
devices.types.switch Переключатель Настенный выключатель света, тумблер, автомат в электрическом щитке.
devices.types.thermostat

Устройство с возможностью регулирования температуры *

Водонагреватель, теплый пол, обогреватель, электровентилятор.
devices.types.thermostat.ac Устройство с возможностью регулирования температуры Кондиционер.
devices.types.media_device

Аудио и видеотехника *

DVD-плееры, медиаприставки и другие медиаустройства.
devices.types.media_device.tv Аудио и видеотехника Телевизоры.
devices.types.cooking

Кухонная техника *

Кофемашина, мультиварка.
devices.types.cooking.kettle Кухонная техника Чайник.
devices.types.other Остальные устройства Остальные устройства, не подходящие под типы выше.

Примечания

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

Пример описания устройства

{
    "id": "abc-123",
    "name": "лампa",
    "description": "цветная лампа",
    "room": "спальня",
    "type": "devices.types.light",
    "custom_data": {
      "foo": 1,
      "bar": "two",
      "baz": false,
      "qux": [1, "two", false],
      "quux": {
        "quuz": {
          "corge": []
        }
      }
    },
    "capabilities": [{
            "type": "devices.capabilities.range",
            "retrievable": true,
            "parameters": {
                "instance": "brightness",
                "unit": "unit.percent",
                "range": {
                    "min": 0,
                    "max": 100,
                    "precision": 10
                }
            }
        },
        {
            "type": "devices.capabilities.on_off"
        },
        {
            "type": "devices.capabilities.color_setting",
            "parameters": {
                "color_model": "hsv",
                "temperature_k": {
                    "min": 2700,
                    "max": 9000,
                    "precision": 1
                }
            }
        }
    ],
    "device_info": {
        "manufacturer": "Provider2",
        "model": "hue g11",
        "hw_version": "1.2",
        "sw_version": "5.4"
    }
}

Умение (capability)

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

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

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

В зависимости от выполняемой операции в объекте Capability передается разный набор полей:
  1. Описание умения устройства используется в операции Информация об устройствах пользователя:
    {
        "type": {string},
        "retrievable": {boolean},
        "parameters": {CapabilityParameterObject}
    }
  2. Статус умения устройства используется в операции Информация о состояниях устройств пользователя:
    {
        "type": {string},
        "state": {CapabilityParameterObject}
    }
  3. Команды для управления умением устройства используются в операции Изменение состояния у устройств:
    {
        "type": {string},
        "state": {CapabilityParameterObject}
    }