Common/Exposes

---

Общие сведения

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

Cпособности устройств это абстрактные сущности, на которых основана работа функции Home Assistant MQTT Discovery, работа сервиса HOMEd Cloud, а так же работа веб-интерфейса. Например, способность "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" - единица измерения

Селектор (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" - массив или объект со значениями

Триггер (button)

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

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

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

Следующие параметры способностей используются для функции Home Assistant MQTT Discovery:
"icon" - иконка из набора Material Design Icons, применимо ко всем типовым способностям
"class" - класс устройства, применимо к способностям "binary" и "sensor"
"state" - способ ведения статистики, возможные значения: "measurement" или "total_increasing", применимо к способности "sensor"

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

Специальные способности устройств имеют фиксированные имена и делятся на 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}
  }
  ...
}

Необязательные опции:
"level" - набор дополнительных свойств, возможные значения: "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