Differences

This shows you the differences between two versions of the page.

--- doc:jroboplc:functags [2026/09/04 13:05] – [Функциональные теги] denis
+++ doc:jroboplc:functags [2026/09/04 14:47] (current) – denis
@@ Line 1: / Line 1: @@
 ====== Функциональные теги ======
-Функциональный тег является вычисляемым тегом по заданной функции и значениям другого тега (одного или нескольких). Любой из модулей может иметь любое количество функциональных тегов.
+Функциональный тег является вычисляемым тегом, значение которого рассчитывается по заданной функции и значению входного тега. Любой модуль может иметь любое количество функциональных тегов. Функциональные теги задаются в секции ''func.tags'' конфигурации модуля.
+===== Общие параметры =====
+Каждый функциональный тег имеет параметр ''beforeExecute''. По умолчанию функциональные теги выполняются после обработки сигналов модуля. Значение ''beforeExecute: on'' позволяет выполнить тег до обработки сигналов.
+Обязательный параметр ''func'' выбирает функцию. Поддерживаются идентификаторы ''avg'' и ''mul'', записанные строчными буквами. Неизвестный или отсутствующий идентификатор приводит к ошибке загрузки функциональных тегов модуля.
+В одном цикле модуль и функциональные теги выполняются в следующем порядке:
+  - выполняется модуль
+  - выполняются функциональные теги с ''beforeExecute: on'', расположенные непрерывно в начале секции ''func.tags''
+  - обрабатываются сигналы модуля
+  - выполняются все оставшиеся функциональные теги
+<WRAP important>Порядок описания тегов в ''func.tags'' имеет значение. После первого тега с ''beforeExecute: off'' все последующие теги выполняются после обработки сигналов, независимо от значения их параметра ''beforeExecute''.</WRAP>
+Все реализованные функции создают тег результата с типом, заданным параметром ''type''. Поддерживаются типы ''INT'', ''LONG'', ''DOUBLE'', ''BOOL'' и ''STRING'', регистр символов не имеет значения. По умолчанию используется ''INT''. Вычисления производятся с типом ''double'', после чего результат преобразуется к типу тега: для ''INT'' и ''LONG'' дробная часть отбрасывается, для ''BOOL'' ноль преобразуется в ''off'', а ненулевое значение — в ''on'', для ''STRING'' создаётся строковое представление числа. Если указан неизвестный тип, регистрируется ошибка и используется ''INT''.
+Если ссылка ''input'' не может быть разрешена, функция не изменяет текущее значение тега результата и повторяет попытку привязки в следующем цикле.
-  // todo:
-  // описать общий параметр beforeExecute
 ===== avg =====
-Функция усреднения значения тега за период времени.
+Функция вычисления среднего значения входного тега за период времени.
 <code yaml>
 plugin.peripherial:
   module.W1:
     descr:    promauto.gelios.flow
     type:     modbus
@@ Line 18: / Line 32: @@
         type:          int32
         access:        ro
     func.tags:
       CurFlowAvg:
@@ Line 26: / Line 40: @@
         period:        30_000
 </code>
-В данном примере создается функциональный тег с именем ''CurFlowAvg'', в котором будет вычислятся среднее значение тега ''CurFlow'' за последние 30 секунд. При каждом выполнении в задаче происходит следующее:
+В данном примере создаётся функциональный тег с именем ''CurFlowAvg'', в котором вычисляется среднее значение тега ''CurFlow'' за последние 30 секунд. При каждом выполнении функции происходит следующее:
-  * входное значение добавляется в массив накопления
+  * входное значение считывается как ''double'' и, с учётом параметра ''distinct'', добавляется в массив накопления
-  * из массива накопления удаляются старые элементы, время жизни которых больше ''period''
+  * из массива накопления удаляются отсчёты старше ''period'', при этом в массиве всегда сохраняется как минимум один последний отсчёт
-  * результат деления суммы всех значений массива накопления на количество элементов в массиве записывается в тег результата
+  * обычное арифметическое среднее всех отсчётов массива записывается в тег результата
-  * если в тег результата записать ноль извне, то массив накопления очищается
+Среднее вычисляется по накопленным отсчётам без учёта длительности каждого значения. При ''distinct: off'' отсчёт добавляется в каждом цикле выполнения. При ''distinct: on'' отсчёт добавляется только тогда, когда его значение типа ''double'' отличается от последнего добавленного значения.
+Если в тег результата извне записать ноль, массив накопления очищается. При доступном входном теге в том же цикле после очистки в массив добавляется текущее значение, и результат вычисляется заново.
 ^Параметр  ^Умолчание  ^Описание  ^
-| ''**func**''    |  |''**avg**'' - идентификатор функции  |
+| ''**func**''    |  |''**avg**'' — идентификатор функции  |
-| ''**type**''    |  ''INT''  |Тип тега результата. Возможные значения:<WRAP>
+| ''**type**''    |  ''INT''  |Тип тега результата: ''INT'', ''LONG'', ''DOUBLE'', ''BOOL'' или ''STRING''  |
-  * INT
-  * LONG
-  * DOUBLE
-</WRAP>  |
 | ''**input**''   |  |Ссылка на тег входных данных, см. [[doc:jroboplc:refs]]  |
-| ''**period**''  |  ''0''  |Период усреднения в миллисекундах  |
+| ''**period**''  |  ''0''  |Период усреднения в миллисекундах. Отрицательное значение заменяется нулём  |
-| ''**distinct**''  |  ''off''  |В данном режиме входное значение добавляется в массив накопления только тогда, когда оно отличается от последнего добавленного значения в массиве  |
+| ''**distinct**''  |  ''off''  |Если ''on'', входное значение добавляется только при его отличии от последнего добавленного значения  |
+| ''**beforeExecute**''  |  ''off''  |Если ''on'' и тег расположен в начальной группе таких тегов, функция выполняется до обработки сигналов модуля  |
-<WRAP info>Другие функции будут создаваться по заявкам пользователей</WRAP>
+===== mul =====
+Функция умножения значения входного тега на постоянный коэффициент.
+<code yaml>
+plugin.peripherial:
+  module.W1:
+    descr:    promauto.gelios.flow
+    type:     modbus
+    tags:
+      - name:          CurFlow
+        address:       0x1002
+        type:          int32
+        access:        ro
+    func.tags:
+      CurFlowScaled:
+        func:          mul
+        type:          double
+        input:         CurFlow
+        mul:           0.001
+</code>
+В данном примере создаётся функциональный тег ''CurFlowScaled''. При каждом выполнении значение ''CurFlow'' считывается как ''double'', умножается на ''0.001'', а результат записывается в ''CurFlowScaled''.
+^Параметр  ^Умолчание  ^Описание  ^
+| ''**func**''    |  |''**mul**'' — идентификатор функции  |
+| ''**type**''    |  ''INT''  |Тип тега результата: ''INT'', ''LONG'', ''DOUBLE'', ''BOOL'' или ''STRING''  |
+| ''**input**''   |  |Ссылка на тег входных данных, см. [[doc:jroboplc:refs]]  |
+| ''**mul**''     |  ''1.0''  |Постоянный коэффициент, на который умножается входное значение  |
+| ''**beforeExecute**''  |  ''off''  |Если ''on'' и тег расположен в начальной группе таких тегов, функция выполняется до обработки сигналов модуля  |