Справочник конфигурации

Файл	Что настраивает	Кто читает
/etc/vplc.conf	Рантайм: скан, пути, REST, Modbus, MQTT, OPC UA, журнал, токен API	Служба vplc
Проект .vplc (project_path)	Карта MQTT mqtt_io_map, устройства Modbus master, задачи, переопределение части настроек	Служба vplc
/var/lib/vplc/plant_config.json	Объект, установки, счётчики энергии, тарифы, расписания, вид страницы	Служба vplc-plant-ui
/etc/systemd/system/vplc-plant-ui.service	Параметры запуска веба (адрес, порт, сокет, пути)	systemd

/etc/vplc.conf

Файл в формате JSON. Если файла нет, рантайм работает со значениями по умолчанию и пишет в журнал Config file not found: /etc/vplc.conf — using defaults. Путь к файлу можно изменить ключом запуска --config <путь> (или -c <путь>).

Отсутствующий ключ оставляет значение по умолчанию. Пустая строка "" — это значение (например, пустой api_token выключает проверку токена).

Ключи

Столбец «Применение»: сразу — изменение через POST /api/config действует без перезапуска; перезапуск — нужен systemctl restart vplc (ответ POST /api/config в этом случае содержит "restart_required": true). Изменения, внесённые правкой файла вручную, всегда требуют перезапуска.

Скан и программа

Ключ	Тип	По умолчанию	Смысл	Применение
cycle_ms	целое	100	Период скана, мс. Ограничивается диапазоном 1…60 000. У многозадачных программ — базовый период задач без своего периода	сразу
scan_rt_priority	целое	0	0 — обычный поток скана; 1…49 — поток скана с приоритетом реального времени SCHED_FIFO (больше 49 ограничивается). На СА-02м рекомендуется 10. Нужно право CAP_SYS_NICE (см. установку)	сразу
scan_mlock	логический	false	Закрепить всю память процесса в ОЗУ при старте. На СА-02м (без подкачки) не нужен	перезапуск
program_path	строка	/var/lib/vplc/program.so	Файл программы	перезапуск
dump_path	строка	/var/lib/vplc/dump.bin	Файл сохранённых переменных	перезапуск
project_path	строка	""	Проект .vplc. Пусто — проекта нет (нет карты MQTT и устройств Modbus master). При первой загрузке проекта через REST рантайм сам записывает сюда /var/lib/vplc/project.vplc	перезапуск
autostart	логический	false	При запуске службы загрузить program_path и запустить скан	перезапуск

REST API

Ключ	Тип	По умолчанию	Смысл	Применение
rest_port	целое	1234	Порт REST, WebSocket, SSE и встроенной страницы	перезапуск
api_token	строка	""	Токен API. Пусто — проверка выключена. См. Токен API	перезапуск

Modbus TCP slave

Ключ	Тип	По умолчанию	Смысл	Применение
modbus_slave_enabled	логический	false	Включить Modbus TCP slave	перезапуск
modbus_slave_port	целое	502	Порт. На СА-02м используйте 1502	перезапуск
modbus_mw_size	целое	1024	Число holding-регистров. В режиме packed — не больше 1024; в режиме mp02 ограничивается диапазоном 9216…10240	перезапуск
modbus_map_mode	строка	"packed"	packed — переменные раскладываются по регистрам автоматически; mp02 — карта адресов, совместимая с контроллером MP-02 (нужна для программы universal). Любое другое значение считается packed	перезапуск
modbus_mp02_rw_ranges	строка	""	Только mp02: какие регистры внутри блока 4000…4299 (только чтение) разрешено записывать. Диапазоны A-B и отдельные адреса через запятую, все в пределах 4000…4299. Пусто — набор по умолчанию; "none" — весь блок только чтение. Ошибочное значение заменяется набором по умолчанию, ошибка видна в GET /api/modbus/status → slave.last_error	перезапуск

MQTT

Ключ	Тип	По умолчанию	Смысл	Применение
mqtt_enabled	логический	false	Включить обмен по MQTT	перезапуск
mqtt_host	строка	"127.0.0.1"	Адрес брокера	перезапуск
mqtt_port	целое	1883	Порт брокера	перезапуск
mqtt_client_id	строка	"vplc"	Идентификатор клиента и имя собственного дерева устройства /devices/<mqtt_client_id>/…. После ввода в работу не меняйте: прежнее retained-дерево останется на брокере	перезапуск
mqtt_username	строка	""	Имя пользователя брокера	перезапуск
mqtt_password	строка	""	Пароль брокера. В GET /api/config показывается как ***	перезапуск
mqtt_retain_outputs	логический	true	Флаг retain для публикаций в собственном дереве. Команды в …/on всегда публикуются без retain	перезапуск
mqtt_stale_ms	целое	125000	Через сколько миллисекунд без сообщений вход считается недостоверным (минимум 5000)	перезапуск
mqtt_bridge_id	строка	"sa02m-bridge"	Идентификатор устройства моста на брокере; по нему вычисляется BRIDGE_ok. Пусто — не следить за мостом	перезапуск

OPC UA

Ключ	Тип	По умолчанию	Смысл	Применение
opcua_enabled	логический	false	Включить сервер OPC UA	перезапуск
opcua_port	целое	4840	Порт. На СА-02м используйте 4842	перезапуск
opcua_name	строка	"vPLC OPC UA Server"	Имя сервера	перезапуск
opcua_publish_ms	целое	500	Период обновления изменившихся значений в узлах OPC UA, мс; 0 — как можно чаще	сразу

Журнал

Ключ	Тип	По умолчанию	Смысл	Применение
log_level	строка	"info"	debug, info, warn, error	сразу
log_ring_size	целое	1000	Сколько последних записей хранить в памяти для GET /api/logs	сразу

Карта MQTT и устройства Modbus master

Карта mqtt_io_map и список устройств Modbus master в /etc/vplc.conf не задаются — рантайм берёт их только из проекта .vplc (project_path). Из массива modbus_devices в /etc/vplc.conf читается только поле template — оно дополняет устройство проекта с тем же name.

Рекомендуемая конфигурация для СА-02м

Для программы universal с модулями через мост панели:

{
  "cycle_ms": 100,
  "scan_rt_priority": 10,
  "scan_mlock": false,
  "rest_port": 1234,
  "program_path": "/var/lib/vplc/program.so",
  "dump_path": "/var/lib/vplc/dump.bin",
  "project_path": "/var/lib/vplc/project.vplc",
  "autostart": true,

  "modbus_slave_enabled": true,
  "modbus_slave_port": 1502,
  "modbus_mw_size": 10240,
  "modbus_map_mode": "mp02",
  "modbus_mp02_rw_ranges": "",

  "mqtt_enabled": true,
  "mqtt_host": "127.0.0.1",
  "mqtt_port": 1883,
  "mqtt_client_id": "vplc-sa02m",
  "mqtt_username": "",
  "mqtt_password": "",

  "opcua_enabled": false,
  "opcua_port": 4842,

  "log_level": "info",
  "log_ring_size": 1000,
  "api_token": ""
}

Если Modbus TCP для SCADA не нужен, оставьте "modbus_slave_enabled": false. project_path можно оставить пустым — рантайм заполнит его при первом «Применить в ПЛК» в вебе установки.

Изменение через REST

# прочитать (секреты замаскированы как "***")
curl -s http://127.0.0.1:1234/api/config
# изменить часть ключей
curl -s -X POST http://127.0.0.1:1234/api/config \
     -H 'Content-Type: application/json' \
     -d '{"cycle_ms": 100, "log_level": "warn"}'

POST /api/config применяет переданные ключи, сохраняет полную конфигурацию в /etc/vplc.conf и отвечает {"ok":true,"restart_required":false} или true, если нужен перезапуск службы. Значение *** для mqtt_password и api_token игнорируется — прочитанную конфигурацию можно отправить обратно без потери секретов.

Проект .vplc

Проект — база SQLite. Его создаёт расширение VS Code или веб установки; рантайм читает проект, указанный в project_path, при запуске службы и при каждой загрузке программы.

Таблица	Столбцы	Что берёт рантайм
project	key, value (или id, value)	Строка key='settings' с JSON-настройками (см. ниже). Строка без JSON — только имя проекта
tasks	id, name, code, cycle_ms	Периоды задач многозадачной программы (cycle_ms < 1 — берётся общий cycle_ms). Код code нужен компилятору
variables	id, name, type, direction, initial_value, comment, task_id	Нужна компилятору: объявления переменных. direction: input, output, memory, inout
mqtt_io_map	topic, var_name, is_input, scale, offset, publish_suffix, safe_value, on_stop, stale_ms, quality_var	Карта MQTT
modbus_devices	name, mode, host, port, serial, baud, unit_id, read_start, read_count, write_start, write_count, template	Устройства Modbus master
mqtt_brokers	host, port, client_id, username, password	Если есть строка — её значения заменяют настройки MQTT из /etc/vplc.conf, и MQTT включается

При загрузке проекта карта MQTT, устройства Modbus и задачи заменяются содержимым проекта. Пустая таблица означает «нет устройств» / «нет карты».

Настройки в project

JSON в строке key='settings' переопределяет одноимённые ключи /etc/vplc.conf (пустые значения пропускаются): cycle_ms, rest_port, autostart, program_path, dump_path, mqtt_enabled, mqtt_host, mqtt_port, mqtt_client_id, modbus_slave_enabled, modbus_slave_port, modbus_mw_size, modbus_map_mode, modbus_mp02_rw_ranges. Поддерживаются и устаревшие имена: cycleDuration (= cycle_ms), modbusEnabled, modbusPort, modbusMemorySize.

Таблица mqtt_io_map

Столбец	Тип	По умолчанию	Смысл
topic	текст	—	Топик. Для выхода на устройство моста — базовый топик контрола /devices/<id>/controls/<name>, суффикс /on добавляется сам
var_name	текст	—	Имя переменной программы
is_input	целое	1	1 — вход (топик → переменная), 0 — выход (переменная → топик)
scale, offset	число	1.0, 0.0	Вход: переменная = значение × scale + offset. Выход: значение = (переменная − offset) / scale
publish_suffix	текст	NULL	Выход: суффикс топика записи. NULL — /on для чужих устройств /devices/<id>/controls/<name>, без суффикса — для собственного дерева; '' — ровно topic
safe_value	текст	NULL	Выход: значение, публикуемое при останове скана
on_stop	текст	NULL	Выход: safe (по умолчанию при заданном safe_value) или hold — ничего не публиковать
stale_ms	целое	NULL	Вход: время свежести, мс (минимум 5000). NULL или 0 — mqtt_stale_ms
quality_var	текст	NULL	Вход: логическая переменная качества. NULL — <var_name>_q

Столбцы начиная с publish_suffix необязательны: старые проекты из пяти столбцов читаются как раньше.

Таблица modbus_devices

Столбец	Смысл
name	Имя устройства — префикс переменных
mode	tcp или rtu
host, port	Адрес и порт для TCP
serial, baud	Порт и скорость для RTU
unit_id	Адрес устройства Modbus
read_start, read_count	Блок holding-регистров для чтения → переменные <name>_IW<адрес>
write_start, write_count	Блок holding-регистров для записи ← переменные <name>_MW<адрес>
template	Необязательно: шаблон устройства из библиотеки — каналы декодируются в масштабированные значения <name>.<канал> / <name>_<канал>

Важно

На СА-02м порты RS-485 занимает мост панели. Не задавайте устройства RTU на портах, которые опрашивает мост: два ведущих на одной линии мешают друг другу.

plant_config.json (веб установки)

Файл /var/lib/vplc/plant_config.json ведёт веб «ЦИНТРОН · Установка»: его меняют окна «Настройки системы», «Объекты» и настройки установок. Править вручную обычно не нужно.

• Нет файла — одна локальная установка «Приточная установка» (local); файл создаётся при первом сохранении.
• Запись атомарная; прежняя версия сохраняется как plant_config.json.bak. Если файл повреждён, берётся .bak; повреждённый файл при следующей записи сохраняется как .broken.
• Паролей и токенов файл не содержит.
• Образец — /opt/vplc-plant-ui/plant_config.example.json.

{
  "version": 1,
  "site": {"name": "Объект", "contacts": {"phone": "", "email": ""}},
  "display": {"sensors": true, "top": true, "bottom": true},
  "theme": "dark",
  "presence": {},
  "schedule": {"enable": true},
  "units": [
    {"id": "local", "name": "Приточная установка", "kind": "local-ahu", "group": "supply",
     "source": {}, "composition": {},
     "energy": {"meter_id": null, "tariff": 10.5, "scale": null, "scale_confirmed": null},
     "schedule": {"enable": false, "days": [[8, 0, 8, 0], [8, 0, 8, 0], [8, 0, 8, 0], [8, 0, 8, 0], [8, 0, 8, 0], [8, 0, 8, 0], [8, 0, 8, 0]]},
     "order": 0}
  ]
}

Ключ	Значения	Смысл
site.name	строка до 120 символов	Название объекта: в верхней полосе и заголовке вкладки браузера
site.contacts.phone, .email	строки	Контакты объекта
display.sensors	true/false	Показывать блок датчиков на мнемосхеме
display.top	true/false	Показывать верхние блоки — подписи над элементами
display.bottom	true/false	Показывать нижние блоки — таблички состояния под элементами
theme	dark, light	Тема оформления
presence	{группа: true/false}	Наличие систем; пусто — по списку установок
schedule.enable	true/false	Общий выключатель планировщика веба
units[]	список, до 64	Установки объекта

Поля установки units[]:

Поле	Значения	Смысл
id	латиница, цифры, _, -	Идентификатор; local — установка программы vPLC
name	строка	Отображаемое имя
kind	local-ahu, local-itp, local-water, local-light, carel, carel-crst, carel-uaria, mp02-tcp, vplc-tcp, wilo-sk712	Вид: local-* — тип программы vPLC (вентиляция, ИТП, вода, освещение), остальные — внешние устройства через мост
group	supply, exhaust, heat, light, drain, vru, ac	Группа в меню
source.device_id	строка	Для внешних: идентификатор устройства моста
composition	{узел: 0/1}	Для внешних: состав мнемосхемы; у локальной вентиляции состав хранится в параметрах программы
energy.meter_id	идентификатор устройства или null	Счётчик электроэнергии
energy.tariff	0…1000	Тариф, ₽/кВт·ч (по умолчанию 10,5). Для локальной установки передаётся в программу
energy.scale	число или null	Вт·ч на единицу показаний счётчика; null — определяется автоматически
energy.scale_confirmed	true/false/null	Подтверждён ли коэффициент
schedule.enable	true/false	Расписание установки
schedule.days	7 элементов, понедельник…воскресенье	День — [вкл_ч, вкл_м, выкл_ч, выкл_м]; у вентиляции — три интервала [вкл_ч, вкл_м, выкл_ч, выкл_м, скорость_%, уставка_°C] (скорость 0…100, уставка 5…40)
order	целое	Порядок в меню
labels, pumps	необязательно	Подписи окна, групп и зон освещения; число насосов дренажного шкафа (1…6)

Подробнее о настройке установок — Настройка установки.

Параметры запуска веба установки

Задаются в строке ExecStart файла /etc/systemd/system/vplc-plant-ui.service. По умолчанию:

/usr/bin/python3 /opt/vplc-plant-ui/server.py --socket /run/vplc-plant-ui/ui.sock --host 0.0.0.0 --port 8088 --vplc http://127.0.0.1:1234 --plant-config /var/lib/vplc/plant_config.json

Ключ	По умолчанию	Смысл
--host	0.0.0.0	Адрес TCP. 127.0.0.1 — доступ к порту только с самого устройства (например, когда веб открывают через маршрут панели /vplc/)
--port	8088	Порт TCP. Порт 80 не принимается: на устройстве его могут занимать другие службы. Если порт занят, сервер завершается с ошибкой и другой порт не выбирает
--socket	нет	Дополнительно слушать unix-сокет (для маршрута панели /vplc/). С --socket TCP открывается, только если задан --host или --port
--socket-group	www-data	Группа файла сокета ('' — не менять)
--socket-mode	0660	Права файла сокета
--vplc	http://127.0.0.1:1234	Адрес REST рантайма
--plant-config	/var/lib/vplc/plant_config.json (если есть каталог /var/lib/vplc)	Файл конфигурации объектов
--events-file	<каталог страницы>/events.jsonl	Журнал событий (последние 1000 записей); '' — только в памяти
--static-root	каталог server.py	Каталог страниц
--contract, --bindings	рядом со страницами / server.py	Контракт переменных и файл привязок bindings.json
--panel-url	http://127.0.0.1:9999	Панель СА-02м: история энергии, проверка сессии; '' — не обращаться
--mqtt	127.0.0.1:1883	Брокер MQTT для внешних установок
--agent-token-file	/etc/vplc/sa02m-agent-token	Файл токена API агента панели для реестра устройств; нет файла — реестр по MQTT
--no-units	—	Выключить маршруты объектов (/api/units…)
--quiet	—	Не писать журнал запросов

После правки файла службы:

systemctl daemon-reload
systemctl restart vplc-plant-ui

Повторная выкладка веба скриптом приводит ExecStart к шаблону из репозитория.

Сохранение переменных (dump)

Значения всех переменных программы (параметры, уставки, состав установки, наработки, служебные маски привязки) хранятся в dump_path (/var/lib/vplc/dump.bin).

Когда сохраняется	Когда восстанавливается
POST /api/dump/save	При загрузке программы: запуск службы с autostart, /api/program/upload, /api/program/reload
Веб установки — после каждой записи параметров и настроек	POST /api/dump/restore — вручную, без проверки имени программы
Остановка службы, если скан работал (RUNNING)

Правила:

• Автоматически дамп восстанавливается, только если имя программы в дампе совпадает с именем загружаемой программы. Иначе в журнале Skip dump restore: program mismatch …, программа стартует с начальными значениями.
• Периодического сохранения нет. Значения, записанные по Modbus или REST в обход веба, сохраняются только при POST /api/dump/save или штатной остановке работающего скана.
• /api/restart только останавливает и запускает скан — переменные остаются в памяти.
• Перед /api/program/reload выполните /api/dump/save, иначе несохранённые изменения пропадут.

Проверка в журнале: Saved N variables to /var/lib/vplc/dump.bin (program='…') и Restored dump: N applied.

Токен API

Если задан api_token, рантайм требует заголовок Authorization: Bearer <токен>:

Требует токен	Без токена
Все запросы POST (запись переменных, загрузка программы и проекта, пуск/стоп, конфигурация, dump)	GET /api/status, GET /api/variables, GET /api/program/info, GET /api/mqtt/status, GET /api/modbus/status
GET /api/config, GET /api/logs	Потоки /ws/variables, /ws/logs, /api/events/variables, /api/events/status; встроенная страница /

Без токена или с неверным токеном ответ — 401 {"error":"unauthorized"}.

curl -X POST http://<IP-адрес СА-02м>:1234/api/start -H 'Authorization: Bearer <токен>'

Токен и веб установки

Сервер веба «ЦИНТРОН · Установка» в этом дереве обращается к REST рантайма без токена. При заданном api_token запись параметров, команды, сохранение переменных и «Применить в ПЛК» из веба получат отказ 401. Встроенная страница рантайма (порт 1234) с токеном тоже не сможет пускать и останавливать скан и записывать переменные.

Файл /etc/vplc.conf с токеном и паролем брокера держите доступным только root:

chmod 600 /etc/vplc.conf

Сетевой доступ к REST

В этом дереве рантайм слушает порт REST (rest_port) на всех интерфейсах; ключа для привязки только к 127.0.0.1 нет. Через REST можно загрузить и выполнить программу с правами root, поэтому:

• задайте api_token, если доступ к порту 1234 из сети не нужен для управления (с учётом ограничения для веба выше);
• ограничьте доступ к порту 1234 средствами сети;
• веб установки, который открывают через маршрут панели /vplc/, можно закрыть от сети ключом --host 127.0.0.1 (или оставить только сокет — убрать --host и --port).

Журналы

Журнал	Где смотреть
Рантайм	journalctl -u vplc (-f — в реальном времени); GET /api/logs?limit=N (до 2000 последних, из памяти, объём — log_ring_size); поток /ws/logs; вкладка журнала встроенной страницы
Веб установки	journalctl -u vplc-plant-ui
События объекта	Окно «Журнал событий» веба; файл /opt/vplc-plant-ui/events.jsonl (последние 1000 записей)

Строка журнала рантайма: [время] [уровень] [модуль] сообщение. Каталог /var/log/vplc создаётся, но рантайм пишет журнал только в systemd-journal.