Перейти к содержанию

Cпособности устройств

После долгих дискуссий было решено, что способности это максимально подходящее по смыслу слово русского языка, которое может заменить слово exposes в контексте описания сервисов HOMEd и других систем умного дома.

Cпособности устройств это абстрактные сущности, на которых основана работа веб-интерфейса, работа сервиса HOMEd Cloud, а также работа функции Home Assistant MQTT Discovery. Например, способность temperature указывает на наличие датчика температуры, а light описывает осветительный прибор.

Типовые способности

Типовые способности устройств могут иметь произвольные названия и делятся на 6 категорий:

  • Бинарный сенсорор: binary
  • Сенсор: sensor
  • Переключатель: toggle
  • Диапазон: number
  • Селектор: select
  • Триггер: button

Каждая типовая способность добавляет одноименное свойство. Категория типовой способности, как и прочие параметры, настраивается при помощи опций.

Типовым способностям можно давать любые названия, однако есть небольшие ограничения:

Название не должно содержать пробелов, а символ нижнего подчеркивания _ желательно использовать только совместно с целым числом, для разделения нескольких одинаковых способностей, например, temperature_1 и temperature_2.

В случае, когда название способности состоит из нескольких слов, рекомендуется использовать формат camelCase, например, waterLeak или childLock.

Бинарный сенсор: binary

Данная способность описывает сенсоры, имеющие всего два состояния (активен/не активен), например, датчик протечки воды или датчик движения. Данная способность не предполагает возможности установки значения. Пример описания:

{
  ...
  "exposes": ["myBinary"],
  "options":
  {
    "myBinary": {"type": "binary"}
  }
  ...
}

Сенсор: sensor

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

{
  ...
  "exposes": ["mySensor"],
  "options":
  {
    "mySensor": {"type": "sensor", "unit": "°C", "round": 2}
  }
  ...
}

Необязательные параметры:

Параметр Описание
unit единица измерения
round округление числового значения (количество знаков после запятой)

Переключатель: toggle

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

{
  ...
  "exposes": ["myToggle"],
  "options":
  {
    "myToggle": {"type": "toggle"}
  }
  ...
}

Диапазон: number

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

{
  ...
  "exposes": ["myNumber"],
  "options":
  {
    "myNumber": {"type": "number", "min": 0, "max": 100, "step": 0.1, "unit": "%"}
  }
  ...
}

Обязательные параметры:

Параметр Описание
min минимальное возможное значение
max максимальное возможное значение

Необязательные параметры:

Параметр Описание
step минимальный шаг изменения значения
unit единица измерения
collapse принудительное отображение поля для ввода значения, вместо ползунка

Селектор: select

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

{
  ...
  "exposes": ["mySelect"],
  "options":
  {
    "mySelect": {"type": "select", "enum": ["toggle", "momentary", "multifunction"]}
  }
  ...
}

{
  ...
  "exposes": ["mySelect"],
  "options":
  {
    "mySelect": {"type": "select", "enum": {"0": "off", "1": "on", "2": "toggle", "255": "previous"}}
  }
  ...
}

Обязательные параметры:

Параметр Описание
enum массив или объект со значениями

Необязательные параметры:

Параметр Описание
collapse принудительное отображение выпадающего меню, вместо списка

Триггер: button

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

{
  ...
  "exposes": ["myButton"],
  "options":
  {
    "myButton": {"type": "button"}
  }
  ...
}

Параметры для Home Assistant

Следующие параметры типовых способностей используются для функции Home Assistant MQTT Discovery:

Параметр Описание
icon иконка из набора Material Design Icons, применимо ко всем типовым способностям
class класс устройства, применимо к способностям binary и sensor
state способ ведения статистики для способности sensor, возможные значения: measurement, total_increasing

Специальные способности

Специальные способности устройств имеют фиксированные имена и делятся на 5 категорий:

  • Выключатель: switch
  • Замок: lock
  • Осветительный прибор: light
  • Штора: cover
  • Термостат: thermostat

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

Выключатель: switch

Данная способность описывает возможность устройства быть включенным или выключенным, например, если это реле или выключатель, и добавляет специальное свойство status. Пример описания:

{
  ...
  "exposes": ["switch"],
  "options":
  {
    "switch": "outlet"
  }
  ...
}

Опции для Home Assistant:

Опция Описание
switch тип выключателя, возможные значения: outlet

Замок: lock

Данная способность описывает механизм, который может быть открыт или закрыт, например, замок или кран, а также, как и способность switch, добавляет свойство status. Пример описания: 

{
  ...
  "exposes": ["lock"],
  "options":
  {
    "lock": "valve"
  }
  ...
}

Опции для Home Assistant:

Опция Описание
lock тип замка, возможные значения: valve

Осветительный прибор: light

Данная способность описывает любые осветительные приборы, такие как лампочки или контроллеры светодиодных лент. По умолчанию данная способность добавляет только свойство status, так же, как это делают способности switch и lock, остальные свойства добавляются при помощи одноименной опции. Пример описания:

{
  ...
  "exposes": ["light"],
  "options":
  {
    "light": ["level", "colorTemperature"],
    "colorTemperature": {"min": 200, "max": 400}
  }
  ...
}

Необязательные опции:

Опция Описание
light набор дополнительных свойств, возможные значения: level, color, colorTemperature, colorMode
colorTemperature минимальное и максимальное значения для свойства colorTemperature

Штора: cover

Данная способность описывает шторы, рольставни или жалюзи, и добавляет специальные свойства cover и position. Пример описания:

{
  ...
  "exposes": ["cover"],
  "options":
  {
    "invertCover": true,
    "cover": "blind"
  }
  ...
}

Необязательные опции:

Опция Описание
invertCover инверсия значения положения шторы

Опции для Home Assistant:

Опция Описание
cover тип шторы, возможные значения: blind

Термостат: thermostat

Данная способность описывает устройства для контроля и управления климатом, и добавляет свойство temperature, а также дополнительные свойства, набор которых зависит от опций. Пример описания:

{
  ...
  "exposes": ["thermostat"],
  "options":
  {
    "systemMode": {"enum": ["off", "heat"]},
    "operationMode": {"enum": ["manual", "comfort"]},
    "targetTemperature": {"min": 10, "max": 40},
    "runningStatus": true
  }
  ...
}

Необязательные опции:

Опция Описание
systemMode основные режимов работы, добавляет одноименное свойство, возможные значения: off, auto, cool, heat, dry, fan
operationMode дополнительные режимов работы, добавляет одноименное свойство
targetTemperature минимальное и максимальное значения установки целевой температуры, добавляет одноименное свойство
runningStatus индикатор текущего состояния (работа/простой), добавляет свойство running

Отображаемое имя

Любой типовой способности, а также специальным способностям switch и lock можно задать произвольное имя, отличающееся от названия способности. Для этого нужно использовать параметр title, например:

{
  ...
  "exposes": ["mySpecialExpose"],
  "options":
  {
    "mySpecialExpose": {"type": "sensor", "title": "Моя суперспособность"}
  }
  ...
}

Параметр title не применим к специальным способностям light, cover и thermostat.