Документирование проекта AgavaSCADA/AgavaPLC

AgavaSCADA/AgavaPLC предоставляет функцию документирования проекта по пользовательскому макету (шаблону).

Функция доступна, начиная с версии AS 1.7+

Вся работа по документированию ведется в окне «Документы».

1 Окно «Документы»

Окно «Документы» предназначено для подготовки оформленных описаний проекта AgavaSCADA. В документ можно включить сведения об узлах проекта и их свойствах, расположить их на страницах, просмотреть результат, сохранить его в PDF или распечатать.

Ниже в этой инструкции рассмотрен пример: описание одного транспорта TCP с его настройками и перечнем всех вложенных регистров Modbus. Названия транспорта, регистров и значения в примере условные; при работе выбирайте узлы своего проекта.

1.1 Состав документа

Для подготовки документа используются три составляющие:

Составляющая	Назначение
Узел «Документ» в окне «Документы»	Хранит имя документа, ссылку на макет и наборы данных.
Наборы данных документа	Определяют, какие узлы проекта и их свойства будут доступны для заполнения макета.
Макет .lrxml	Задаёт страницы, заголовки, текст, таблицы и оформление.

При формировании документа поля макета заполняются данными выбранных узлов. Например, поле имени транспорта заменяется его именем, а строка таблицы регистров повторяется для каждого регистра из набора данных.

1.2 Создание документа

1. Откройте нужный проект в среде разработки.
2. Выберите «Вид → Показать окно "Документы"».
3. В появившемся дереве щёлкните правой кнопкой мыши по корневому узлу коллекции документов.
4. В меню «Добавить узел» выберите тип «Документ».
5. Задайте имя, например Перечень регистров — Котельная. Для переименования можно использовать контекстное меню «Переименовать» или клавишу F2.
6. При необходимости заполните свойство «Описание»: Настройки транспорта TCP и перечень регистров Modbus.

Для организации нескольких документов в корне можно создавать узлы типа «Группа узлов» и размещать документы в них.

Выделение документа или набора данных в дереве позволяет изменять его свойства в окне «Свойства». Если оно скрыто, выберите «Вид → Показать окно свойств». В документе есть свойство «Путь к файлу макета». У нового документа макет ещё не сохранён; путь будет установлен после его сохранения в редакторе.

2 Практический пример

Рассмотрим на примере создание документа, описывающего структуру и состав транспортов проекта.

Предположим, в проекте есть следующая структура:

Транспорт TCP «Котельная_TCP»

├── Протокол Modbus «Контроллер_1»

│   ├── Регистр Modbus «Температура_подачи»

│   └── Регистр Modbus «Давление»

└── Протокол Modbus «Контроллер_2»

   └── Регистр Modbus «Режим_работы»

Создадим внутри документа два набора данных:

Настройка	Набор Transport	Набор Registers
Узлы	Только транспорт Котельная_TCP	Тот же транспорт Котельная_TCP
Фильтр по имени типа	Оставить пустым	Регистр Modbus
Включать вложенные	Выключить	Включить
Результат	Одна строка со свойствами транспорта	По одной строке на каждый вложенный регистр Modbus

2.1 Создание набора Transport

1. Щёлкните правой кнопкой мыши по созданному документу.
2. В «Добавить узел» выберите «Набор данных документа».
3. Переименуйте его в Transport.
4. Выделите набор и найдите группу свойств «Набор данных».
5. Откройте редактор свойства «Узлы» кнопкой справа от значения («Открыть свойство...»).
6. Нажмите «Добавить существующий» или кнопку с подсказкой «Добавить существующий узел».
7. В окне выбора узлов найдите транспорт Котельная_TCP, выберите его и подтвердите выбор. Убедитесь, что он появился в списке свойства «Узлы».
8. Подтвердите изменение списка кнопкой «OK».
9. Оставьте «Фильтр по имени типа» пустым.
10. Выключите «Включать вложенные».

Так набор будет содержать только выбранный транспорт, без его протоколов и регистров. В данном примере выбирайте ровно один транспорт.

2.2 Создание набора Registers

1. Добавьте в тот же документ ещё один «Набор данных документа».
2. Задайте имя Registers.
3. В свойстве «Узлы» добавьте тот же транспорт Котельная_TCP.
4. Включите «Включать вложенные».
5. В «Фильтр по имени типа» введите:

Регистр Modbus

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

Отдельного отбора по включённости, адресу устройства или функции чтения эта настройка не выполняет: в перечень входят все найденные узлы указанного типа.

2.3 Правила настройки наборов

• Имя набора используется в макете как имя источника данных. Используйте латинские буквы, цифры и _; первый символ не должен быть цифрой. Например: Transport, Registers, Registers_2.
• Задавайте разным наборам одного документа разные имена.
• Фильтр проверяет название типа узла, а не имя конкретного узла. Имя Температура_подачи не подходит для отбора регистра по типу.
• Фильтр допускает часть названия типа и несколько вариантов через ;. Достаточно соответствия одному из вариантов. Регистр букв не важен.
• Пустой фильтр разрешает любые типы. При включённых вложенных узлах это добавит в набор также транспорт, протоколы, группы и другие дочерние узлы.
• Настройка «Включать вложенные» относится к иерархии дерева проекта. Она не собирает произвольные узлы, на которые имеются ссылки из свойств.

Для других видов регистров используйте названия соответствующих типов из своего проекта. Пример с фильтром «Регистр Modbus» описывает именно Modbus.

2.4 Открытие редактора макета

1. Дважды щёлкните по документу в окне «Документы». Другой способ: контекстное меню «Открыть → Открыть редактор макета отчета».
2. Откроется встроенный редактор LimeReport. Название команды содержит слово «отчета» и для документов.
3. В панели «Инспектор данных» найдите источники Transport и Registers.
4. Раскройте их, чтобы увидеть доступные поля.
5. Для проверки содержимого выделите источник и нажмите кнопку «Просмотр данных в источнике».

Проверьте данные до оформления: в Transport должна быть одна строка, а в Registers — все ожидаемые регистры выбранного транспорта. В приведённой структуре это три строки.

Наборы данных формируются при открытии редактора. Если после этого вы изменили состав наборов, добавили регистры или исправили свойства узлов, сохраните макет, нажмите «Назад», внесите необходимые изменения и заново откройте редактор документа. Это обновит доступные поля и значения.

Какие поля доступны

У каждого набора есть общие поля:

Поле	Что содержит
Name	Имя узла.
Description	Описание узла.
TypeName	Название типа узла, например «Регистр Modbus».
Path	Полный путь узла в проекте.
ParentPath	Полный путь непосредственного родителя узла.

Кроме них доступны поля читаемых свойств выбранных узлов. В инспекторе они отображаются по внутренним именам, например IPAddr или ReadRegister. Подписи в готовом документе задавайте понятными словами: «IP-адрес», «Регистр чтения» и т. п.

У перечислений обычное поле содержит название значения, например Master или Float32, а поле с окончанием _Raw — числовой код этого значения. Для пользовательского описания обычно достаточно обычного поля.

Скрытые свойства и пароли не включаются в набор. Если разные строки представляют разные типы узлов, список полей объединяет их доступные свойства; поле, которого у конкретного узла нет, останется пустым.

2.5 Создание и наполнение макета

2.5.1 Настройка страницы

1. Используйте страницу, созданную редактором для нового макета. Если страницы нет, выберите «Новая страница отчета».
2. Выделите страницу и в «Инспекторе объектов» задайте «Размер страницы» (pageSize) — A4.
3. Задайте «Ориентация страницы» (pageOrientation) — «Альбомная».
4. Настройте поля страницы так, чтобы текст и таблица размещались внутри печатной области.

Альбомная ориентация удобна для широкой таблицы регистров. Если требуется больше параметров, используйте несколько строк на один регистр, а не уменьшайте текст до трудно читаемого размера.

2.5.2 Добавление разделов

Откройте кнопку «Разделы» на панели редактора. Раздел задаёт, когда и сколько раз выводить размещённые в нём элементы. Для нашего примера нужна следующая последовательность:

Порядок	Раздел	Содержимое и настройки
1	Заголовок отчета	Название документа и дата формирования. Выводится один раз.
2	Данные	Карточка транспорта. «Источник данных» = Transport.
3	Заголовок данных	Заголовки колонок перечня. Привязан ко второму разделу «Данные», который выводит регистры.
4	Данные	Строка таблицы регистров. «Источник данных» = Registers. Повторяется для каждой строки набора.
5	Нижний колонтитул	Номер страницы.

Чтобы создать такую структуру:

1. Добавьте «Заголовок отчета».
2. Добавьте «Данные», выделите этот раздел и установите «Источник данных» (datasource) = Transport.
3. Добавьте ещё один раздел «Данные» и установите его источник = Registers.
4. Выделите раздел данных регистров и добавьте «Заголовок данных». Этот заголовок должен относиться именно к перечню регистров.
5. Добавьте «Нижний колонтитул».
6. Проверьте порядок разделов в макете: карточка транспорта должна предшествовать таблице регистров.

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

2.5.3 Добавление названия и даты

Выберите инструмент «Текстовый элемент» и разместите элемент в разделе «Заголовок отчета». Откройте его редактор двойным щелчком или измените «Содержимое» (content) в свойствах.

Введите:

$V{DocumentName}

Второй текстовый элемент заполните так:

Сформировано: $V{GeneratedAt}

DocumentName — имя документа в окне «Документы». GeneratedAt — дата и время открытия редактора, в формате дд.ММ.гггг ЧЧ:мм. Для обновления этой отметки откройте редактор заново перед выпуском документа.

Заголовок сделайте крупнее основного текста, например 16 пт и полужирным.

2.5.4 Заполнение карточки транспорта

В разделе «Данные» с источником Transport разместите текстовые элементы со следующими строками. Каждую строку можно сделать отдельным элементом:

Транспорт: $D{Transport.Name}

Описание: $D{Transport.Description}

Тип: $D{Transport.TypeName}

IP-адрес: $D{Transport.IPAddr}

Порт: $D{Transport.IPPort}

Режим работы: $D{Transport.TransportMode}

Режим передачи: $D{Transport.TimingMode}

Таймаут приема: $D{Transport.RXTimeout} мс

Пауза между пакетами: $D{Transport.PacketDelay} мс

Эти поля настроек относятся к транспорту TCP. Для последовательного или другого транспорта выбирайте соответствующие поля в инспекторе данных; поля IPAddr и IPPort у него могут отсутствовать.

Поле также можно перетащить из «Инспектора данных» в нужный раздел макета. Редактор создаст текстовый элемент со ссылкой вида $D{Transport.IPAddr}. Допишите перед ссылкой нужную подпись и после неё — единицу измерения.

Увеличьте высоту раздела, чтобы все строки карточки находились внутри него.

2.5.5 Создание таблицы регистров

В разделе «Заголовок данных», относящемся к Registers, разместите текстовые элементы с названиями колонок. Под ними, в разделе «Данные» с источником Registers, разместите элементы с полями:

Заголовок колонки	Содержимое элемента в строке данных
Имя	$D{Registers.Name}
Описание	$D{Registers.Description}
Устройство	$D{Registers.DeviceAddr}
Функция чтения	$D{Registers.ReadFunction}
Регистр чтения	$D{Registers.ReadRegister}
Размер, бит	$D{Registers.ParamSize}
Тип значения	$D{Registers.ValueType}
Функция записи	$D{Registers.WriteFunction}
Регистр записи	$D{Registers.WriteRegister}

В макете достаточно создать одну строку данных. При формировании она будет повторена для всех регистров набора Registers. Не копируйте строку вручную под каждый регистр.

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

Адреса регистров выводятся в том виде, в котором заданы в свойствах проекта. Макет из примера не прибавляет к ним 1 и не преобразует их в обозначения вида 40001. При необходимости поясните принятую адресацию обычным текстом.

Для нескольких протоколов добавьте поле $D{Registers.ParentPath} в колонку «Родитель» или строку под именем регистра. Оно показывает непосредственного родителя: если регистр расположен в группе, это будет путь группы. Поле $D{Registers.Path} показывает полный путь и помогает различать регистры с одинаковыми именами.

2.5.6 Включение дополнительных свойств регистров

Если нужна подробная характеристика каждого регистра, увеличьте высоту раздела данных регистров и под основной строкой добавьте элементы:

Порядок байт: $D{Registers.ByteOrder}

Приоритет: $D{Registers.Priority}

Путь: $D{Registers.Path}

Весь раздел будет повторяться для каждого регистра, поэтому дополнительные строки останутся рядом с его основными параметрами. Другие нужные свойства добавляйте из полей источника Registers. Наличие свойства в наборе не означает, что оно уже выведено: для его отображения нужен элемент в макете.

2.5.7 Настройка длинных текстов и продолжение таблицы

1. Для элементов имени и описания включите «Автоматическая высота» (autoHeight), чтобы длинный текст мог занимать несколько строк.
2. Для раздела данных также включите автоматическую высоту.
3. При необходимости включите «Растягивать до максимальной высоты» (stretchToMaxHeight) у ячеек строки, чтобы границы таблицы были ровными.
4. В свойствах «Заголовка данных» включите «Печатать на каждой странице» (reprintOnEachPage), если таблица занимает несколько страниц.
5. В «Нижнем колонтитуле» добавьте текстовый элемент:

Страница $V{#PAGE}

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

2.6 Сохранение макета и настройка документа

1. В редакторе выберите «Файл → Сохранить отчет как» (Ctrl+Shift+S).
2. Сохраните макет с расширением .lrxml внутри каталога проекта, например в подкаталог Documents под именем TransportRegisters.lrxml.
3. Для последующих сохранений используйте «Сохранить отчет» (Ctrl+S).
4. После сохранения нажмите «Назад» в меню редактора.
5. Выделите документ в окне «Документы» и проверьте свойство «Путь к файлу макета». Оно должно указывать на сохранённый файл; для файла внутри проекта используется относительный путь, например Documents/TransportRegisters.lrxml.
6. Сохраните сам проект командой «Файл → Сохранить проект».

Макет хранится отдельным файлом. При переносе проекта передавайте и этот файл по сохранённому относительному пути. Сохранение проекта не заменяет сохранение макета в его редакторе.

Перед нажатием «Назад» явно сохраните изменения макета: не рассчитывайте на автоматическое сохранение при возврате.

2.7 Получение оформленного документа

1. В редакторе макета выберите «Файл → Сгенерировать отчет» или нажмите Ctrl+P.
2. Откроется предварительный просмотр сформированных страниц.
3. Проверьте название документа, свойства транспорта и список регистров.
4. Перейдите на следующие страницы и проверьте продолжение таблицы, повторение заголовков, номера страниц и длинные описания.
5. Чтобы получить файл, нажмите «Печать в PDF», выберите имя и место сохранения, например Котельная_перечень_регистров.pdf.
6. Откройте полученный PDF и убедитесь, что все страницы и колонки сохранены.
7. Для бумажного экземпляра используйте «Печать» в окне просмотра.

В редакторе Ctrl+P запускает формирование и просмотр, а в окне предварительного просмотра — печать.

При необходимости исправлений закройте просмотр, измените макет, сохраните его и снова выполните «Сгенерировать отчет». После правок исходных узлов проекта предварительно откройте редактор заново.

Как может выглядеть результат

Ниже показано условное содержимое готового документа.

Перечень регистров — Котельная
Сформировано: 07.10.2026 14:30

Транспорт: Котельная_TCP

Описание: Связь с контроллерами котельной
IP-адрес: 192.168.1.10
Порт: 502
Режим работы: Master
Режим передачи: По задержкам
Таймаут приема: 1000 мс
Пауза между пакетами: 100 мс

Имя	Описание	Устройство	Функция чтения	Регистр чтения	Размер, бит	Тип значения
Температура_подачи	Температура подачи	1	3	100	32	Float32
Давление	Давление теплоносителя	1	3	102	16	UInt16
Режим_работы	Режим контроллера	2	3	10	16	UInt16

2.8 Редактирование существующего документа

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

Чтобы изменить состав данных, сохраните макет и нажмите «Назад». Выделите нужный набор данных, измените «Узлы», фильтр или включение вложенных. Сохраните проект, откройте редактор заново и проверьте источники данных.

Для выпуска того же описания по другому транспорту можно изменить «Узлы» обоих наборов: Transport и Registers должны ссылаться на один и тот же новый транспорт. Если тип транспорта изменился, скорректируйте поля карточки.

Имена наборов после наполнения макета лучше сохранять. Если переименовать Registers в Registers_2, ссылки вида $D{Registers.ReadRegister} потребуется заменить в макете.

2.9 Частые вопросы и ошибки

Что произошло	Что проверить
Пункт открытия «Документов» недоступен	Сначала откройте проект.
«Не заданы узлы набора данных»	Добавьте транспорт в свойство «Узлы» соответствующего набора.
«Несуществующий узел включен в набор данных»	Исходный узел мог быть удалён. Исправьте список «Узлы», выбрав существующий транспорт.
Ошибка имени набора данных	Используйте латинские буквы, цифры и _, без пробелов; не начинайте имя с цифры.
В инспекторе нет Transport или Registers	Убедитесь, что наборы находятся непосредственно внутри нужного документа, имеют разные имена, затем откройте редактор заново.
Набор Registers пуст	Проверьте выбранный транспорт, включение вложенных и фильтр Регистр Modbus. В выбранной ветви должны быть узлы этого типа.
В таблице появились транспорт, протоколы и группы	Фильтр пуст или слишком широкий. Задайте тип регистров.
Видно меньше регистров, чем ожидалось	Проверьте все вложенные ветви выбранного транспорта и типы отсутствующих регистров. Другие типы не соответствуют фильтру Modbus.
В документе выведен только один регистр	Проверьте, что источник раздела «Данные» установлен в Registers, а поля строки находятся внутри этого раздела.
Вместо значения пустая ячейка	Проверьте имя поля в инспекторе, наличие этого свойства у узла и заполненность значения. Для другого типа транспорта набор полей может отличаться.
Ошибка «Источник данных … не найден» или «Поле … не найдено»	Имя набора или поля в выражении не совпадает с текущим источником. Исправьте ссылку и проверьте регистр букв.
После изменения проекта в просмотре старые значения	Сохраните макет, вернитесь кнопкой «Назад» и заново откройте редактор документа.
«Путь до макета отчета не задан»	Сохраните макет из редактора и проверьте «Путь к файлу макета» у документа.
«Невозможно открыть файл макета»	Проверьте наличие файла по указанному пути. При переносе проекта скопируйте также .lrxml.
Повторное открытие документа показывает пустой макет	Проверьте путь и файл макета. Для описанного порядка работы сохраняйте файл внутри проекта с относительным путём.
Текст обрезан или таблица слишком широкая	Увеличьте ширину или высоту элементов, включите автоматическую высоту, используйте альбомную страницу или перенесите часть свойств на следующую строку каждого регистра.
После исправления макета PDF остался прежним	Заново сформируйте документ и сохраните новый PDF. Ранее созданный файл сам не обновляется.