====== arctrm ======

Модуль ''arctrm'' предназначен для периодического архивирования температурных значений в базе данных Firebird. На текущий момент значения считываются только из тегов модулей ''promauto.termo5''. В дальнейшем возможно расширение поддержки других модулей термометрии.

Модуль сохраняет:

  * температурные срезы по подвескам с актуальными данными;
  * сведения о подвесках;
  * события запуска архива, изменения состояния связи с устройствами и потери актуальности данных подвесок.

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

[[doc:jroboplc:modules:arctrm_dev]]

===== Конфигурация =====

Пример настройки:

<code yaml>
plugin.arctrm:
  module.arctrm:
    database: db
    schema: AT
    period: 5s
    size: 1000000
    sensorCount: 6

    promauto.termo5:
      mytrm1:
        p0: 231 силос, корпус 2
        p5: 232 силос, корпус 2

      mytrm2:
        p1: 401 силос, корпус 4
</code>

==== Параметры ====

^ Параметр ^ По умолчанию ^ Описание ^
| ''database'' | ''db'' | Имя модуля базы данных. Модуль должен использовать Firebird. |
| ''schema'' | ''AT'' | Префикс таблиц базы данных. |
| ''period'' | ''1h'' | Период сохранения архива. Поддерживаются суффиксы ''ms'', ''s'', ''m'', ''h'', ''d''. |
| ''size'' | ''1000000'' | Максимальное количество строк в таблице ''TEMPER''. |
| ''sensorCount'' | ''6'' | Количество датчиков в каждой подвеске. |
| ''promauto.termo5'' | — | Список модулей-источников и настроенных подвесок. |

Значения ''size'', ''period'' и ''sensorCount'' должны быть больше нуля.

==== Настройка устройств ====

Ключ первого уровня в секции ''promauto.termo5'' является именем модуля-источника тегов. Ключ подвески состоит из произвольного первого символа и числового номера. Например, из ключа ''p5'' модуль получает номер подвеса ''5''.

Для каждой подвески создаются ссылки на теги:

<code text>
<deviceName>:Pdv<podvesNum>.T0
<deviceName>:Pdv<podvesNum>.T1
...
<deviceName>:Pdv<podvesNum>.T<sensorCount-1>
</code>

Актуальность данных подвески определяется по тегу:

<code text>
<deviceName>:Pdv<podvesNum>.Time
</code>

Данные считаются актуальными, если ссылка на тег существует, а его значение находится в диапазоне от ''0'' до ''600'' включительно.

Состояние связи с устройством определяется по тегу:

<code text>
<deviceName>:SYSTEM.ErrorFlag
</code>

===== Принцип работы =====

После подключения к базе модуль автоматически:

  - создаёт необходимые таблицы и индексы;
  - добавляет отсутствующие колонки ''T0...Tn'' в таблицу ''TEMPER'';
  - синхронизирует справочник подвесок;
  - загружает дату последней архивной записи;
  - записывает событие запуска архива.

На каждом рабочем цикле модуль сначала проверяет ''Pdv<podvesNum>.Time'' каждой подвески. Значения датчиков считываются только для подвесок с актуальными данными. Время архивного среза берётся с сервера базы данных и округляется вниз до границы периода ''period''.

Если наступил новый период, в ''TEMPER'' записывается по одной строке для каждой подвески с актуальными данными. Для подвески с отсутствующим тегом ''Time'' или значением вне диапазона ''0...600'' строка не создаётся. При превышении лимита ''size'' удаляются строки с наименьшими значениями ''ID''.

===== База данных =====

^ Таблица ^ Назначение ^
| ''PODVES'' | Справочник подвесок: имя и описание. |
| ''TEMPER'' | Архив температурных срезов. Содержит ''PODVES_ID'', ''DT'' и динамические колонки ''T0...Tn''. |
| ''EVENTLOG'' | Журнал запуска архива, изменения состояния связи с устройствами и потери актуальности данных подвесок. |

Основные связи:

<code text>
PODVES.ID <- TEMPER.PODVES_ID
</code>

Одна строка ''TEMPER'' содержит значения всех датчиков одной подвески за один архивный период.

===== Значения датчиков =====

Обычные значения записываются без изменения. Ошибочные состояния сохраняются в тех же колонках ''T0...Tn'' как специальные числа.

^ Значение ^ Состояние ^
| ''3010'' | Значение ниже допустимого диапазона — короткое замыкание. |
| ''3011'' | Значение выше допустимого диапазона — обрыв. |
| ''3013'' | Тег датчика не найден — ''NOLINK''. |

Допустимый диапазон обычного значения: от ''-1000'' до ''2000'' включительно.

===== События =====

^ Код ^ Событие ^
| ''0'' | Ссылка на ''SYSTEM.ErrorFlag'' не найдена. |
| ''1'' | Связь с устройством потеряна: ''SYSTEM.ErrorFlag = true''. |
| ''3'' | Данные подвески неактуальны: ссылка на ''Pdv<podvesNum>.Time'' не найдена или значение находится вне диапазона ''0...600''. |
| ''99'' | Связь с устройством установлена. |
| ''100'' | Инициализация архивации. |

Для событий состояния устройства в поле ''MESSAGE'' записывается имя устройства, для события неактуальных данных — имя подвески в формате ''<deviceName>.<podvesNum>'', для события инициализации — пустая строка.

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

===== Теги модуля =====

^ Тег ^ Тип ^ Описание ^
| ''connected'' | boolean | Установлен, когда модуль подключён к базе и рабочий цикл выполняется без ошибки. |

===== Диагностика =====

Метод ''getInfo()'' возвращает краткую строку состояния, например:

<code text>
devices=2 podves=3 sensors=18 cursize=30 last=2026-07-23 00:16:50
</code>

^ Поле ^ Описание ^
| ''devices'' | Количество настроенных устройств. |
| ''podves'' | Общее количество подвесок. |
| ''sensors'' | Общее количество датчиков. |
| ''nolinkSensors'' | Количество датчиков без ссылки; выводится только при ненулевом значении. |
| ''cursize'' | Текущий размер таблицы ''TEMPER'', учтённый модулем. |
| ''last'' | Дата и время последнего архивного периода или ''never''. |

При отсутствии подключения в начало строки добавляется ''NOT CONNECTED!''. Если модуль выключен, возвращается ''disabled''.

===== Ограничения =====

  * Поддерживается только Firebird.
  * Значение ''sensorCount'' является общим для всех подвесок.
  * Таблица ''EVENTLOG'' автоматически не очищается.
  * Удаление архивных строк выполняется по ''ID'', а не по дате ''DT''.