Common/Exposes: различия между версиями

Текущая версия от 13:22, 5 сентября 2024

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

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

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

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

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

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

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

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

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

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

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

{
  "type": "binary"
}

Сенсор

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

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

{
  "type": "sensor",
  "unit": "°C"
}

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

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

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

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

{
  "type": "toggle"
}

Диапазон

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

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

{
  "type": "number",
  "min": 0,
  "max": 100,
  "unit": "%"
}

Обязательные опции:
"min" - минимальное возможное значение
"max" - максимальное возможное значение

Дополнительные опции:
"unit" - единица измерения
"step" - минимальный шаг изменения значения

Селектор

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

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

{
  "type": "select",
  "enum": ["toggle", "momentary", "multifunction"]
}

Или:

{
  "type": "select",
  "enum": {"0": "off", "1": "on", "2": "toggle", "255": "previous"}
}

Обязательные опции:
"enum" - массив или объект со значениями (в случае использования массива, в качестве передаваемого устройству значения будет использован индекс элемента в массиве, а в случае использования объкета - ключ элемента)

Триггер

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

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

{
  "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)

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

@@ Строка 3: / Строка 3: @@
 == Общие сведения ==
-После долгих дискуссий было решено, что <code class="value">способности</code> это максимально подходящее по смыслу слово русского языка, которое может заменить слово <code class="value">exposes</code> в контексте описания сервисов HOMEd и других систем умного дома.
+После долгих дискуссий было решено, что <code class="value">"способности"</code> это максимально подходящее по смыслу слово русского языка, которое может заменить слово <code class="value">"exposes"</code> в контексте описания сервисов HOMEd и других систем умного дома.
 Cпособности устройств это абстрактные сущности, на которых основана работа функции [https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery Home Assistant MQTT Discovery], работа сервиса [[Cloud|HOMEd Cloud]], а так же работа [[Web|веб-интерфейса]]. Например, способность <code class="value">"temperature"</code> указывает на наличие датчика темературы, а <code class="value">"light"</code> описывает осветительный прибор.
@@ Строка 16: / Строка 16: @@
 * Триггер (button)
-Категоря способности, как и прочие параметры, настраивается при помощи [[Common/Options|опций]].
+Категория типовой способности, как и прочие параметры, настраивается при помощи [[Common/Options|опций]].
 === Бинарный сенсор ===
@@ Строка 29: / Строка 29: @@
 === Сенсор ===
-Данная способность описывает любые сенсоры, такие, как датчик температуры или силы тока. Данная способность ''не предполагает'' возможности установки значения.
+Данная способность описывает любые сенсоры, такие, как датчик температуры или силы тока. Показания сенсора могут быть как числовыми, так и строковыми. Данная способность ''не предполагает'' возможности установки значения.
 Пример описания:
 <syntaxhighlight lang="json">
 {
-   "type": "binary",
+   "type": "sensor",
    "unit": "°C"
 }
@@ Строка 40: / Строка 40: @@
 Дополнительные опции:<br>
+<code>"round"</code> - округление числового значения (количество знаков после запятой)<br>
 <code>"unit"</code> - единица измерения
@@ Строка 45: / Строка 46: @@
 Данная способность описывает органы управления или настройки устройства, имеющие два состояния (включено/выключено). Данная способность ''предполагает'' возможность установки значения.
-Обязательные опции:<br>
+Пример описания:
-<code>"type"</code> - категория способности, всегда <code class="value">"toggle"</code>
+<syntaxhighlight lang="json">
+{
+  "type": "toggle"
+}
+</syntaxhighlight>
 === Диапазон ===
 Данная способность описывает органы управления или настройки устройства, имеющие числовой дипазон значений. Данная способность ''предполагает'' возможность установки значения.
+Пример описания:
+<syntaxhighlight lang="json">
+{
+  "type": "number",
+  "min": 0,
+  "max": 100,
+  "unit": "%"
+}
+</syntaxhighlight>
 Обязательные опции:<br>
-<code>"type"</code> - категория способности, всегда <code class="value">"number"</code><br>
 <code>"min"</code> - минимальное возможное значение<br>
 <code>"max"</code> - максимальное возможное значение
 Дополнительные опции:<br>
-<code>"unit"</code> - единица измерения, например <code class="value">"°C"</code> или <code class="value">"%"</code>
+<code>"unit"</code> - единица измерения<br>
-<br>
+<code>"step"</code> - минимальный шаг изменения значения
-<code>"step"</code> - минимальный шаг изменения значения, например <code class="value">0.1</code>
 === Селектор ===
+Данная способность описывает органы управления или настройки устройства, имеющие несколько строковых значений. Данная способность ''предполагает'' возможность установки значения.
+Пример описания:
+<syntaxhighlight lang="json">
+{
+  "type": "select",
+  "enum": ["toggle", "momentary", "multifunction"]
+}
+</syntaxhighlight>
+Или:
+<syntaxhighlight lang="json">
+{
+  "type": "select",
+  "enum": {"0": "off", "1": "on", "2": "toggle", "255": "previous"}
+}
+</syntaxhighlight>
+Обязательные опции:<br>
+<code>"enum"</code> - массив или объект со значениями (в случае использования массива, в качестве передаваемого устройству значения будет использован индекс элемента в массиве, а в случае использования объкета - ключ элемента)
 === Триггер ===
+Данная способность описывает сущность, необходимую для вызова какого-либо действия со стороны устройства, например для запуска калибровки или сброса настроек. С точки зрения пользовательского интерфейса это просто кнопка.
+Пример описания:
+<syntaxhighlight lang="json">
+{
+  "type": "button"
+}
+</syntaxhighlight>
-=== Общие опции ===
+=== Опции Home Assistant ===
+Следующие опции способностей используются для функции [https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery Home Assistant MQTT Discovery]:<br>
+<code>"icon"</code> - иконка из набора [https://pictogrammers.com/library/mdi/ Material Design Icons], применимо ко всем типовым способностям<br>
+<code>"class"</code> - класс устройства, применимо к способностям <code class="value">"binary"</code> и <code class="value">"sensor"</code><br>
+<code>"state"</code> - выбор способа ведения статистики, возможные значения - <code class="value">"measurement"</code> или <code class="value">"total_increasing"</code>, применимо к способности <code class="value">"sensor"</code>
 == Специальные способности ==
-{{ Later }}
+Специальные способности устройств делятся на 5 основных категорий:
+* Осветительный прибор (light)
+* Выключатель (switch)
+* Штора (cover)
+* Замок (lock)
+* Термостат (thermostat)
+Эти способности отличаются от типовых тем, что имеют свои уникальные наборы опций. {{ Later }}
 [[Category:Common]]
 [[Category:Custom]]
 [[Category:ZigBee]]