Руководство по скриптам SAMUTAG

ST-подобные скрипты SAMUTAG: синтаксис, контексты выполнения, отладка и ограничения.

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

Серверный скрипт шаблона выполняется отдельно для каждого экземпляра этого шаблона. Унаследованный скрипт доступен потомку, а ближайший одноимённый скрипт его переопределяет.

Язык SAMUTAG поддерживает часть конструкций Structured Text стандарта IEC 61131-3. Перечень поддерживаемых конструкций приведён в разделе «Совместимость IEC ST и CODESYS».

Первый серверный скрипт

1. В своём шаблоне создайте INT-тэг CounterTag без I/O.
2. Создайте скрипт с периодическим запуском 1000 мс и лимитом исполнения 100 мс.
3. Введите код ниже, проверьте синтаксис и сохраните.
4. В Runtime-проверке добавьте CounterTag в «Отладку значений» и нажмите «Пуск».
5. Для автономной работы создайте экземпляр, назначьте модель Runtime-узлу и загрузите проект на узел. Сохранение скрипта в Studio не обновляет работающий узел.

this.CounterTag := this.CounterTag + 1;
IF this.CounterTag > 50 THEN
    this.CounterTag := 0;
END_IF;
Log('Объект ', this.MyName, ': ', this.CounterTag);

Место выполнения и сохранение состояния

Скрипты шаблонов и символов поддерживают одинаковые строковые и битовые функции, преобразования типов, массивы, циклы и функциональные блоки. Локальные переменные сохраняются между вызовами одного сценария. У разных сценариев независимые состояния.

Скрипт шаблона выполняется на Runtime независимо от открытых видеокадров.

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

System. читает ресурсы сервера Runtime, а не компьютера оператора. При обращении к серверным тэгам, включая запись через MyTags[i], проверяются права доступа и замки настроек. MyModel требует назначенной модели экземпляра.

Скрипты экземпляров не запускаются повторно при каждом открытии кадра. На каждом АРМ клиентские скрипты выполняются независимо.

Типы и литералы

В таблице приведены типы переменных ST. Тип UDINT доступен в карте Modbus; для локального целого значения в скрипте используйте INT.

Локальные переменные и теги

VAR
  Counter: INT := 0;
  Enabled: BOOL := TRUE;
  Ratio: REAL;
END_VAR

Локальные переменные сохраняются отдельно для каждой пары «скрипт–экземпляр».

Тег является объектом: обращение Pressure эквивалентно Pressure.value, свойство только для чтения Pressure.alarm сообщает, активно ли аварийное условие, а Pressure.alarmStatus содержит состояние аварии и её подтверждения.

Pressure.IsIO показывает, включён ли обмен, а Pressure.alarmIO — произошла ли ошибка чтения или записи.

При общей I/O-ссылке используется Pressure.ioLink; в раздельном режиме доступны Pressure.ioReadLink и Pressure.ioWriteLink. Каждая отображаемая ссылка изменяется из скрипта только при открытом собственном замке. Запись в значение тега разрешена только для READ_WRITE.

Counter := Counter + 1;
PumpOutput.value := Counter;
IF Pressure.alarm THEN PumpOutput := 0; END_IF;
Pressure.ioReadLink := "Pump_2.RawPressure";
Pressure.ioWriteLink := "ModbusServer.PressureOut";

Замените имена в примерах именами объектов своего проекта. Historian не является I/O-ссылкой: запись истории включается отдельной конфигурацией тэга.

В начале цикла Runtime получает значения включённых I/O-входов из данных драйверов, затем выполняет скрипты и передаёт изменённые выходные значения на запись. Сетевой опрос драйверов выполняется со своим периодом. При отключённом I/O обмен по ссылке не выполняется.

Теги любого экземпляра проекта доступны через его имя. Например, Pump_2.Speed, Pump_2.Speed.value, Pump_2.Speed.alarm, Pump_2.Speed.alarmStatus, Pump_2.Speed.ioReadLink и Pump_2.Speed.ioWriteLink. Имена экземпляров в загружаемом проекте должны быть уникальны без учёта регистра, иначе ссылка была бы неоднозначной.

Фиксированные массивы

Поддерживаются одно- и многомерные локальные массивы с произвольной целочисленной нижней границей. Индексы проверяются при анализе и во время выполнения.

VAR
  Samples: ARRAY[0..3] OF INT := [10, 20, 30, 40];
  Matrix: ARRAY[1..2, -1..1] OF REAL;
END_VAR

Samples[1] := Samples[0] + 5;
Matrix[2, 0] := INT_TO_REAL(Samples[1]);

Если значений в инициализаторе меньше размера массива, остальные элементы получают начальное значение базового типа. Выход за границы завершает текущий цикл диагностикой. Один локальный массив может содержать не более 8 измерений и 10 000 элементов.

Операторы и выражения

Поддерживаются скобки, унарные NOT, +, -, арифметика * / MOD + -, сравнения = <> < <= > >= и AND XOR OR. Для двух значений STRING оператор + объединяет строки.

Для BOOL операции NOT/AND/OR/XOR логические. Для BYTE/WORD/DWORD/LWORD они выполняются побитово; результат получает ширину более широкого операнда.

VAR
  InputMask: WORD := 16#00F3;
  OutputMask: WORD;
END_VAR

OutputMask := (InputMask AND 16#00FF) XOR 16#0003;

Функции SHL, SHR, ROL, ROR принимают битовую строку и число позиций типа INT.

Операции выполняются в порядке: унарные → умножение/деление → сложение/вычитание → сравнения → AND → XOR → OR. Скобки изменяют порядок.

Ветвление

IF Pressure >= 5.0 AND Enabled THEN
  State := 'high';
ELSIF Pressure > 0.0 THEN
  State := 'normal';
ELSE
  State := 'stopped';
END_IF;

Комментарии: (* многострочный комментарий *) и // до конца строки.

Циклы, выбор и функциональные блоки

VAR i: INT; delay: TON; pulses: CTU; edge: R_TRIG; END_VAR
FOR i := 1 TO 10 BY 1 DO Counter := Counter + 1; END_FOR;
WHILE Counter < 20 DO Counter := Counter + 1; END_WHILE;
CASE Counter OF
  0, 1: Log('Начало: ', Counter);
  2..20: Log('Значение: ', Counter);
ELSE Log('Вне диапазона');
END_CASE;
delay(IN := Counter > 5, PT := T#2s);
edge(CLK := delay.Q);
pulses(CU := edge.Q, R := FALSE, PV := 10);

FOR использует локальный счётчик типа INT. Начальное и конечное значения входят в диапазон цикла. Шаг BY может быть отрицательным, но не может равняться нулю.

CASE выбирает ветвь по целочисленному значению. Ветви задаются отдельными значениями или непересекающимися диапазонами.

Функциональный блок объявляется в VAR как локальная переменная. Он сохраняет своё состояние между вызовами отдельно для каждого скрипта и экземпляра.

TON задаёт задержку включения, TOF — задержку выключения, TP — импульс заданной длительности.

R_TRIG обнаруживает переход FALSE→TRUE, а F_TRIG — переход TRUE→FALSE. Счётчики изменяют значение при переходе их счётного входа из FALSE в TRUE. Вход R сбрасывает счётчик, а LD загружает начальное значение PV.

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

Время и преобразования

TIME — длительность в миллисекундах: T#1h30m, T#500ms.

DATE — дата (DATE#2026-09-09), TOD/TIME_OF_DAY — время суток (TOD#12:30:00.123), DT/DATE_AND_TIME — дата и время (DT#2026-09-09-12:30:00). Календарные значения используют UTC — всемирное координированное время.

Доступны преобразования по схеме ИСХОДНЫЙ_ТИП_TO_ЦЕЛЕВОЙ_ТИП с краткими именами TIME, DATE, TOD, DT: INT_TO_TIME(500), TIME_TO_INT(T#1s), STRING_TO_TIME('T#2s'), DT_TO_DATE, DT_TO_TOD, TIME_TO_STRING. Числовые значения времени измеряются в миллисекундах, не секундах.

Состояние таймеров переносится вместе с локальными переменными; для резервной пары требуется синхронизация часов UTC. После простоя следующий вызов учитывает прошедшее время.

Log и ограничение исполнения

Log('Значение Counter: ', Counter); объединяет параметры без дополнительного разделителя и пишет сообщение уровня INFO. На один запуск сохраняются до 100 сообщений по 4096 символов; фильтр уровня журнала может скрывать INFO.

Поле «Максимальное время исполнения» задаёт предельное время выполнения скрипта в миллисекундах: по умолчанию 100, диапазон 1–60000.

Интерпретатор проверяет время на операциях и итерациях, включая пустые циклы. При превышении скрипт получает status=error, частичные изменения тегов и локальных переменных не публикуются; остальные скрипты продолжают работу. Превышение времени обнаруживается между операциями; точность остановки зависит от длительности текущей операции. Дополнительно ограничены число операций, размер строк и объём журнала пошагового выполнения.

Преобразования типов

Имя функции не зависит от регистра. Каждая функция принимает ровно один аргумент исходного типа.

Temperature := INT_TO_REAL(RawTemperature);
Rounded := REAL_TO_INT(Value);
Active := STRING_TO_BOOL('TRUE');
Caption := BOOL_TO_STRING(Active);

REAL_TO_INT удаляет дробную часть без округления: 2.9 → 2, −2.9 → −2. Число преобразуется в BOOL по правилу «ноль — FALSE, ненулевое — TRUE». Для STRING → BOOL допустимы TRUE/FALSE и 1/0. Ошибка разбора строки завершает текущий цикл с ошибкой.

Режимы запуска

Доступны запуск при старте и остановке Runtime, периодический режим, выполнение пока выражение TRUE/FALSE и запуск по фронтам FALSE→TRUE/TRUE→FALSE.

Условие запуска является полноценным BOOL-выражением: Pressure >= 5, Ready AND Enabled, Control.status = 'error'.

Контекст текущего экземпляра

MyName — системная переменная STRING только для чтения. В Runtime она содержит полный путь текущего экземпляра с учётом композиции. Это позволяет формировать ссылки без явно заданного в коде имени экземпляра:

Pressure.ioLink := MyName + ".tagname";

Каждый экземпляр одного шаблона получает собственное значение MyName. В обычной проверке шаблона без выбранного экземпляра значение пустое; в проверке конкретного экземпляра используется его имя.

Теги вложенных шаблонов доступны относительно текущей группы по имени компонента. Например, this.Drive.Speed.value обращается к тегу Speed вложенного компонента Drive. Для нескольких уровней сегменты продолжаются слева направо: this.Line.Drive.Speed.value.

this.Speed и Speed обращаются к значению одного тэга текущего объекта.

this.InstanceName содержит собственное имя экземпляра. this.AbsoluteName и this.MyName содержат его полный путь в композиции. this.TemplateName возвращает имя непосредственного шаблона, из которого создан экземпляр.

this.description возвращает описание текущего владельца, определённое для экземпляра при подготовке проекта. Это свойство доступно только для чтения.

У скриптов доступны this.Control.status, this.Control.LastRunTimestamp и this.Control.LastRunTime. Для скрипта дочернего объекта используется полный относительный путь, например this.Drive.Control.status. Скрипты и графические символы также предоставляют свойства .name и .description. Эти свойства нельзя изменять присваиванием.

MyModel — объект модели, которой назначена группа экземпляров. Запись this.MyModel равнозначна. У дочернего экземпляра используется назначение корневого экземпляра его группы.

Свойства MyModel.name, MyModel.description и MyModel.displayName возвращают имя, описание и отображаемое имя модели. Системные свойства alarm, alarmCount, UnAckCount, AckCount и instanceCount доступны только для чтения.

К собственным тэгам модели обращаются через MyModel.TagName. Запись разрешается с учётом прав и настроек тэга. При редактировании шаблона конкретная модель ещё не определена, поэтому такие ссылки полностью проверяются перед загрузкой проекта на Runtime.

Без назначенной модели её строковые системные свойства пусты, числовые равны нулю, а alarm равен FALSE. В Runtime счётчики относятся к ветви модели, доступной рабочему процессу. В изолированной проверке шаблона без модели они равны нулю. Скрипты символов получают свойства модели от Runtime через HMI.

MyTags и проверка существования тэга

this.MyTags — собственные и унаследованные тэги текущего объекта, без тэгов вложенной композиции. Порядок — по имени без учёта регистра, индексы начинаются с 1. LEN(this.MyTags) возвращает количество. Доступ к существующим свойствам сохраняет их типы, права и замки.

VAR i: INT; END_VAR
FOR i := 1 TO LEN(this.MyTags) DO
  Log(this.MyTags[i].name);
END_FOR;

IF isTagExists('Pump1.Pressure') THEN
  Log('Тэг экземпляра существует');
END_IF;
IF isTagExists('SHUN_OT.Sensor') THEN
  Log('Переменная I/O-сервера существует');
END_IF;

isTagExists(tagname: STRING): BOOL проверяет строковый путь по снимку конфигурации проекта. Поддерживаются абсолютные пути вложенных экземпляров и уникальные имена экземпляров, переменные Modbus и OPC UA. Регистр не имеет значения.

Отсутствующий путь возвращает FALSE; качество и доступность устройства не проверяются. Поиск охватывает конфигурацию проекта, а не только тэги текущего рабочего процесса или назначенные ему I/O-серверы. Изменения имён и карт становятся видны после новой загрузки конфигурации. Проверка существования не предоставляет права чтения или записи.

Состояния аварий

Tag.alarmStatus — строковое свойство только для чтения. Его можно сравнивать со следующими значениями:

IF Pressure.alarmStatus = 'UnAckAlarm' THEN
  Horn := TRUE;
END_IF;

Логическое Tag.alarm остаётся TRUE только пока аварийное условие физически активно. Подтверждение не сбрасывает это свойство.

Объекты I/O-серверов

Каждый настроенный I/O-сервер проекта предоставляет диагностические свойства только для чтения:

IF MainPlc.alarmConnection THEN
  ConnectionErrors := ConnectionErrors + 1;
END_IF;
Traffic := MainPlc.TotalByteSent + MainPlc.TotalByteResived;

Счётчики и авария относятся к текущему процессу Runtime и сбрасываются при остановке и повторном запуске I/O-сервера.

Объекты скриптов

Каждый скрипт, включённый в итоговую конфигурацию объекта с учётом наследования, предоставляет свойства только для чтения:

Скрипты символов и действий

У символа предусмотрены три сценария: при открытии, при закрытии и периодический.

Action Script назначается отдельному элементу. В его настройках выбираются левая или правая кнопка мыши и действие: нажатие либо удержание.

Для периодических действий задаётся интервал от 10 до 86400000 мс. Предельное время одного выполнения — от 1 до 1000 мс. Сценарии одного размещённого символа не выполняются одновременно.

Params.Name — локальный параметр; Tags.Name — тэг владельца. Доступны this.Name, this.Child.Name, this.MyName, this.description, MyModel и свойства объектов текущего контекста. Выберите существующий тэг с помощью автодополнения.

Параметр без привязки к серверному тэгу изменяется только в браузере. Запись в серверный тэг передаётся через HMI с проверкой прав. При обязательном повторном пароле запрашивается подтверждение. Проверьте выполнение команды по сигналу обратной связи от оборудования.

При навигации отменяются периодические действия и удержания, запускается только сценарий закрытия. Ожидание ограничено четырьмя секундами; запрещённые/недоступные записи и записи с повторным паролем пропускаются. Принудительное закрытие браузера не гарантирует выполнение OnClose. Не используйте OnClose для защитного останова оборудования.

При скрытой вкладке циклы приостанавливаются. После превышения предельного времени выполнения сценарий останавливается с ошибкой до следующего открытия символа. После изменения символа загрузите обновлённый проект на HMI; обновление кода исполнителя требует обновления службы.

Проверка Runtime

Кнопка «Выполнить один цикл» создаёт одну возможность запуска только для открытого скрипта. «Пуск» запускает общую сессию всех эффективных скриптов шаблона, «Стоп» прекращает её и выполняет скрипты режима «При остановке Runtime».

В локальной проверке Studio основной цикл Runtime выполняется с периодом 100 мс. Условия режимов «пока» и переходы FALSE→TRUE/TRUE→FALSE проверяются в каждом цикле. Период скрипта дополнительно ограничивает частоту выполнения его команд. Скрипты используют общие тестовые теги, но отдельные локальные переменные. Теги и локальные значения любого скрипта можно менять прямо во время работы — следующий цикл получает новые значения.

Сначала вычисляется условие запуска. Если оно не выполнено, тело скрипта не запускается, локальные переменные не изменяются, а LastRunTimestamp и LastRunTime сохраняют прежние значения. Эти свойства обновляются только при фактическом запуске тела, даже если само тело затем завершилось ошибкой.

В окне проверки задайте тестовые значения и просмотрите последовательность присваиваний. Локальные переменные сохраняются между тестовыми циклами; значения экземпляров проекта не изменяются.

Диагностика

Для обращения в поддержку сохраните исходный текст скрипта, режим запуска, период, лимит выполнения, имя объекта и время ошибки в UTC. Не передавайте токены и пароли.

Служебные слова, объекты и свойства

Справочник общий для скриптов шаблонов и символов. Имена TagName, Child, Script, Symbol, Instance, Server и Alias в примерах нужно заменить на имена объектов проекта. Регистр идентификаторов не влияет на поиск. Не добавляйте свойства, которых нет в справочнике или автодополнении: например, this.TagName.name не является поддерживаемым свойством тэга.

Объекты и свойства

Служебные слова языка

Глоссарий всех функций

Имена функций нечувствительны к регистру. В таблицах указаны типы аргументов и результата. Функциональные блоки сначала объявляются в VAR (например, timer: TON;), затем вызываются по имени переменной.

INDEXOF('Клапан', 'пан') возвращает 3, INDEXOF('abc', 'x') — -1. Поиск чувствителен к регистру, возвращает первое вхождение; пустая подстрока имеет индекс 0. Индекс считается по символам Unicode, не по байтам. FIND сохранён для совместимости: позиция с 1, отсутствие — 0.

VAR position: INT; END_VAR
position := INDEXOF('SHUN_OT.Pressure', '.');
IF position >= 0 THEN
  Log('Точка найдена, индекс: ', position);
END_IF;

Совместимость IEC ST и CODESYS

SAMUTAG выполняет скрипты собственным интерпретатором и не запускает скомпилированные приложения CODESYS. Поддерживаемые конструкции перечислены ниже. Версии языка в Studio и установленном Runtime должны быть совместимы для проверки и выполнения загружаемого проекта.

Глоссарий служебных и зарезервированных слов

Поддерживаемые служебные слова

Встроенные функции

Зарезервированы для совместимости имён

Эти слова нельзя использовать как имена проектов, шаблонов, тегов, символов, скриптов, моделей, экземпляров и узлов. Поддерживаемые конструкции перечислены в разделе совместимости; остальные слова зарезервированы для имён.

Полный пример

VAR
  Starts: INT := 0;
  EngineeringValue: REAL;
END_VAR

EngineeringValue := INT_TO_REAL(RawValue) / 10.0;
IF StartCommand AND Control.status <> 'error' THEN
  Starts := Starts + 1;
  Output := TRUE;
ELSE
  Output := FALSE;
END_IF;