Common/Exposes

---

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

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

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

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

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

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

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

Бинарный сенсор (binary)

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

Пример описания:

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

Сенсор (sensor)

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

Пример описания:

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

Необязательные опции:
"unit" - единица измерения
"round" - округление числового значения (количество знаков после запятой)

Переключатель (toggle)

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

Пример описания:

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

Диапазон (number)

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

Пример описания:

{
  ...
  "exoses": ["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)

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

Пример описания:

{
  "type": "button"
}

Опции Home Assistant

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

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

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

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

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

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

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

Пример набора опций:

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