Диагностика и частые вопросы

Команды выполняются на СА-02м от root. Запросы к 127.0.0.1 работают на самом устройстве; с компьютера используйте <IP-адрес СА-02м>.

Как посмотреть состояние

Службы

systemctl status vplc vplc-plant-ui --no-pager

Рантайм: `GET /api/status`

curl -s http://127.0.0.1:1234/api/status | python3 -m json.tool

Поле	Смысл
`state`	`IDLE` — программа не загружена; `STOPPED` — загружена, скан остановлен; `RUNNING` — скан работает; `ERROR` — скан остановлен из-за ошибки программы
`program`	Имя загруженной программы (`universal` для типовых установок)
`cycle_ms`	Действующий период скана, мс
`cycle_count`	Сканов с запуска процесса (не сбрасывается)
`last_cycle_ms`	Длительность последнего скана
`max_cycle_ms`, `overrun_count`	Самый долгий скан и число перегрузок (скан дольше периода) с последнего сброса статистики
`p95_cycle_ms`, `stats_window`	95-й процентиль длительности скана по окну последних (до 1000) сканов
`stats_cycles`, `stats_age_s`	Сканов и секунд с последнего сброса статистики
`cycle_hist`	Гистограмма длительности сканов: `0-2`, `2-5`, `5-10`, `10-20`, `20-50`, `50+` мс
`scan_profile`	Максимумы фаз скана (входы, программа, выходы) и разбор самого долгого скана
`scan_sched`	Политика потока скана, например `SCHED_FIFO 10` или `SCHED_OTHER`
`var_count`	Число переменных программы
`version`	Версия рантайма

Статистика сбрасывается при загрузке программы (первые 5 сканов после загрузки не учитываются) и командой:

curl -s -X POST http://127.0.0.1:1234/api/scan/stats/reset

Обмен

curl -s http://127.0.0.1:1234/api/mqtt/status     # connected, broker, topics, rx, tx
curl -s http://127.0.0.1:1234/api/modbus/status   # slave: enabled, listening, port, last_error; devices[]
curl -s http://127.0.0.1:1234/api/program/info    # loaded, name, path, var_count
curl -s "http://127.0.0.1:1234/api/variables?names=SimEnable,MQTT_ok,BRIDGE_ok,AhuIoMapMissing,AlarmState61,MeterOk"

Состояние карты ввода-вывода (веб установки):

curl -s http://127.0.0.1:8088/api/iomap/status

Если веб слушает только unix-сокет:

curl -s --unix-socket /run/vplc-plant-ui/ui.sock http://localhost/api/iomap/status

Журнал

journalctl -u vplc -n 100 --no-pager
journalctl -u vplc -f                    # в реальном времени
journalctl -u vplc-plant-ui -n 100 --no-pager

Сообщение журнала `vplc`	Что значит
`vPLC runtime v… starting`	Запуск процесса
`Config file not found: /etc/vplc.conf — using defaults`	Нет файла конфигурации, работают значения по умолчанию
`Loaded .vplc: N tasks, N modbus devices, N mqtt_io maps`	Прочитан проект: сколько задач, устройств Modbus и строк карты MQTT
`REST+WS server on port 1234`	REST запущен
`REST server failed: mg_http_listen failed on port N`	Порт REST занят — процесс завершается
`Autostart: loading …`	Загрузка программы при запуске (`autostart`)
`Loaded program '…' from '…' (N variables)`	Программа загружена
`Restored dump: N applied`	Значения переменных восстановлены из `dump.bin`
`Skip dump restore: program mismatch …`	Дамп от другой программы — значения не восстановлены
`Saved N variables to … (program='…')`	Переменные сохранены в `dump.bin`
`Cycle overrun: X ms (limit N ms)`	Скан не уложился в период
`Scan thread tid N: SCHED_FIFO priority N`	Поток скана получил приоритет реального времени
`… SCHED_FIFO priority N refused …`	Приоритет не выдан (нет права CAP_SYS_NICE) — скан работает обычным потоком
`Connecting to … (inputs N, outputs N, devices N)`	Подключение к брокеру MQTT и размер карты
`Connection lost to … — auto-reconnect`	Потеря связи с брокером, идёт переподключение
`mqtt_io_map: переменная X не объявлена — вход … пропущен`	В карте переменная, которой нет в программе
`Invalid payload '…' on … — value held, quality FALSE`	Значение в топике не разбирается — вход недостоверен
`Modbus TCP slave on port N (…)`	Modbus slave слушает порт
`Modbus slave init failed: …`	Modbus slave не запустился (например, порт занят); рантайм продолжает работу
`Scan cycle error: … — program stopped`	Ошибка в программе: скан остановлен, программа выгружена

Типовые проблемы

Веб «ЦИНТРОН · Установка» не открывается

Проверьте службу и журнал:

systemctl status vplc-plant-ui --no-pager
journalctl -u vplc-plant-ui -n 50 --no-pager

Найдите в журнале причину:

Сообщение	Причина	Что сделать
`Ошибка: не удалось занять 0.0.0.0:8088.`	Порт занят другим процессом. Сервер другой порт сам не выбирает	Найдите процесс: `ss -ltnp \| grep ':8088'`; освободите порт или задайте другой `--port` в службе
`Порт 80 — панель устройства. Используйте --port 8088.`	В службе задан порт 80	Верните `--port 8088`
`Ошибка: не удалось открыть unix-сокет …`	На месте сокета лежит обычный файл или нет прав	Удалите посторонний файл, перезапустите службу
`Внимание: модель не загружена (…)`	Нет файлов модели (контракт, `schema_gen.json`, `tags_gen.json`) рядом с `server.py` — работают только страницы	Выложите веб заново скриптом

Если служба работает, а страница не открывается:
- В строке ExecStart службы есть --socket, но нет --host/--port — TCP 8088 не открыт, веб доступен только через маршрут панели /vplc/.
- Задан --host 127.0.0.1 — порт 8088 доступен только с самого устройства.
- Через маршрут панели /vplc/ сначала войдите в панель СА-02м.

«Нет связи» в вебе

Где видно	Что значит	Что проверить
Часы в шапке окна показывают `--:--:--`, подсказка «Нет связи с прибором»	Два запроса состояния подряд к серверу веба остались без ответа	Сеть до устройства, служба `vplc-plant-ui`
Мнемосхема — «Нет связи с контроллером»	Веб не получает снимок переменных	Службы `vplc-plant-ui` и `vplc`: `curl -s http://127.0.0.1:1234/api/status`
Мнемосхема внешней установки — «Нет связи с устройством»	Устройство на шине не отвечает мосту	Питание и линию RS-485 устройства, состояние устройства в панели СА-02м
Энергопотребление — «Нет связи со счётчиком»	Счётчик не на связи	Счётчик в панели СА-02м

Если vplc не отвечает на 127.0.0.1:1234, смотрите journalctl -u vplc и раздел «Порт занят».

Авария 61 «неполная карта ввода-вывода»

Авария вентиляционной установки (PlantType = 1) класса «авария» с реакцией «останов через продувку» и автосбросом. Пока она активна, пуск без модели невозможен. Возникает только при выключенной модели (SimEnable = FALSE), если:

обязательная для текущего состава установки точка (вход или выход) не привязана к каналу модуля;
привязки изменены в окне «Карта I/O», но не применены в ПЛК;
недостоверен один из критичных датчиков (например, температура приточного или наружного воздуха, температура обратной воды калорифера).

Что сделать:

Проверьте состояние привязки:

curl -s http://127.0.0.1:8088/api/iomap/status

Поле	Смысл
`pending`	Привязки изменены, но не применены — ПЛК работает по старой карте
`missing`	Обязательные точки без привязки (по словам масок)
`applied`, `masks_match`	Привязка применена, маски в программе совпадают с файлом привязок
`program_has_masks`	Программа поддерживает применение привязки без пересборки

В окне «Карта I/O» привяжите недостающие точки и нажмите «Применить в ПЛК». Строка состояния покажет «обязательных точек без привязки: N — авария 61», если что-то осталось. Если какого-то узла на объекте физически нет, уберите его из состава установки в окне «Установка».

Ответы при применении:

Ответ	Причина	Что сделать
`409 plant_running`	Установка работает: применение перезагружает программу и на доли секунды останавливает скан	Остановите установку или подтвердите применение (повтор с `force`)
`409 program_without_masks`	Программа на ПЛК собрана без поддержки применения привязки	Загрузите актуальную сборку `universal`
`503 vplc`	Рантайм не отвечает	Проверьте службу `vplc`

После применения в журнале vplc должна быть строка Loaded .vplc: 0 tasks, 0 modbus devices, N mqtt_io maps с ненулевым N, а в /etc/vplc.conf — "project_path": "/var/lib/vplc/project.vplc".
Авария сбрасывается автоматически, когда причина устранена.

Для типов 2…5 (освещение, ИТП, вода, холод) признак привязки задаётся при сборке программы.

Подробнее о привязке — Настройка установки, об авариях — Справочник аварий.

Датчики показывают «—»

Вид на мнемосхеме	Что значит
«—» в красной рамке, подсказка «нет достоверных данных (обрыв, нет привязки или связи с модулем)»	Программа считает значение недостоверным (признак качества входа `q_<тег>` = FALSE)
Температура в красной рамке, подсказка «обрыв (вне −60…150 °C)»	Значение температуры вне допустимого диапазона
«—» в серой рамке, подсказка «датчик не подключён»	Датчика нет в составе внешней установки — это не авария
«—» без рамки сразу после открытия страницы	Данные ещё не получены

Причины недостоверности входа:

точка не привязана в «Карте I/O» или привязка не применена (pending в /api/iomap/status);
нет сообщений в топике дольше mqtt_stale_ms (по умолчанию 125 с);
мост отметил устройство или канал как неисправный (meta/error = "r");
нет связи с брокером (MQTT_ok = FALSE) или мост не работает (BRIDGE_ok = FALSE);
значение в топике не разбирается (Invalid payload … в журнале).

Проверка:

curl -s http://127.0.0.1:1234/api/mqtt/status
curl -s "http://127.0.0.1:1234/api/variables?names=MQTT_ok,BRIDGE_ok,SimEnable"
journalctl -u vplc --no-pager | grep -E 'MqttAdapter|mqtt_io_map' | tail -20
mosquitto_sub -h 127.0.0.1 -t '/devices/<id>/controls/<канал>' -v -C 1

inputs 0 в строке Connecting to … означает, что у рантайма нет карты: проект не загружен (project_path пуст) — выполните «Применить в ПЛК».

Счётчик энергии: «недостоверно», «—»

Надпись в блоке энергии	Причина	Что сделать
Источник коэффициента «недостоверно»	Приращение счётчика не сходится с мощностью ни для Вт·ч, ни для 1/320 Вт·ч на единицу — кВт·ч в суммы не входят	Проверьте счётчик; если единица показаний известна, задайте коэффициент `energy.scale` в настройках установки
Источник «по умолчанию»	Маркера единицы нет, сверка с мощностью ещё не завершена (нужно не меньше 10 мин)	Подождите
«Счётчик не задан или не найден среди устройств панели СА-02м»	В настройках установки не выбран счётчик	Выберите счётчик (`energy.meter_id`)
«Нет связи со счётчиком»	Счётчик не отвечает мосту	Счётчик и линию RS-485
«Счётчик энергии не растёт…»	Показание энергии стоит при ненулевой мощности	Счётчик
«Нет доступа к истории панели СА-02м», «Сессия панели СА-02м истекла»	Нет входа в панель — архив недоступен	Войдите в панель
Стоимость «—», «Итог не показан: …»	В окне есть недостоверные интервалы архива	Причина — в подсказке
«За пуск» «—»	`MeterOk = FALSE`	См. ниже

MeterOk = FALSE в программе означает, что значения счётчика не доходят до программы. Частая причина — у рантайма нет карты (пустой project_path): строки счётчика входят в карту, когда в настройках установки выбран счётчик. Выполните «Применить в ПЛК» и проверьте:

curl -s "http://127.0.0.1:1234/api/variables?names=MeterOk,MeterPowerQ,MeterEnergyQ,MeterPowerW"

Программа не загружается

Ответ или сообщение	Причина	Что сделать
`422` с текстом ошибки загрузки библиотеки	Файл собран не для armhf или повреждён	Соберите программу для armhf
`422 Symbol plc_run not found …` / `Symbol plc_variables or plc_variable_count not found`	Файл — не программа vPLC	Соберите программу компилятором vPLC
`404 program file not found` на `/api/program/reload`	Нет файла `program_path`	Скопируйте программу в `/var/lib/vplc/program.so`
`409 no program loaded` на `/api/start`	Программа не загружена (`IDLE`)	Загрузите программу
`409 already running` / `409 not running`	Скан уже запущен / уже остановлен	—
`400 not a sqlite project`, `400 project size` на `/api/project/upload`	Файл не SQLite или больше 8 МБ	Проверьте файл проекта
`401 unauthorized`	Задан `api_token`	Передайте заголовок `Authorization: Bearer <токен>`
Состояние `ERROR`, в журнале `Scan cycle error: … — program stopped`	Ошибка при выполнении программы; программа выгружена	Исправьте программу и загрузите заново; для повтора — `/api/program/reload`
После `/api/program/upload` состояние `STOPPED`	Загрузка не запускает скан	`curl -X POST …/api/start`

Порт занят

Порт	Признак	Что сделать
1234 (REST)	В журнале `REST server failed: mg_http_listen failed on port 1234`; служба перезапускается каждые 5 с	`ss -ltnp \| grep ':1234'` — найдите процесс; либо смените `rest_port` (веб установки тогда запускайте с `--vplc http://127.0.0.1:<порт>`)
Modbus slave	В журнале `Modbus slave init failed: …`; в `GET /api/modbus/status` `slave.listening: false` и текст `slave.last_error`	На СА-02м используйте `"modbus_slave_port": 1502`
OPC UA	В журнале `OPC UA init: …`	Порт 4840 зарезервирован для CODESYS — задайте `"opcua_port": 4842`
8088 (веб)	`Ошибка: не удалось занять 0.0.0.0:8088.`	См. раздел «Веб «ЦИНТРОН · Установка» не открывается» выше

ss -ltnp | grep -E ':(1234|1502|502|4840|4842|8088) '

Высокая загрузка процессора, перегрузки скана

Оцените скан:
Окно терминала
```
curl -s -X POST http://127.0.0.1:1234/api/scan/stats/reset
sleep 300
curl -s http://127.0.0.1:1234/api/status | python3 -m json.tool
journalctl -u vplc --since "10 min ago" --no-pager | grep -c 'Cycle overrun'
```
Ориентир для universal при периоде 100 мс на СА-02м с приоритетом скана 10: p95_cycle_ms около 12 мс, max_cycle_ms около 20 мс, overrun_count 0.

Посмотрите потоки процесса:

top -H -p $(pidof vplc)
ps -L -o tid,cls,rtprio,comm -p $(pidof vplc)

Возможные причины и меры:

Причина	Мера
Поток скана обычный (`scan_sched: SCHED_OTHER`) на загруженном устройстве	`"scan_rt_priority": 10` и дополнение службы с CAP_SYS_NICE — см. Установку
Открыты живые потоки переменных (вкладка переменных встроенной страницы, монитор VS Code, клиенты `/ws/variables`, `/api/events/variables`) — пока есть подписчик, все переменные сериализуются каждый скан	Закройте ненужные мониторы
`"log_level": "debug"`	Верните `info`
Включён OPC UA при большом числе переменных	Выключите OPC UA или увеличьте `opcua_publish_ms`
Нагрузка других служб СА-02м	Облегчённый профиль служб
Поток ядра `sugov:0` занимает до ~20 % ядра	Это регулятор частоты процессора (`schedutil`), а не vPLC

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

Признак	Причина	Что сделать
`state: IDLE`, программа не загружена	`"autostart": false` (значение по умолчанию)	Задайте `"autostart": true`, `systemctl restart vplc`
Параметры вернулись к прежним значениям	Значения записаны по Modbus, REST или OPC UA в обход веба и не сохранены; при отключении питания дамп не пишется	После изменения выполните `curl -X POST http://127.0.0.1:1234/api/dump/save`. Веб сохраняет сам после каждой записи
Значения сброшены после обновления программы	Программа перезагружена без предварительного `dump/save`	Перед `/api/program/reload` всегда выполняйте `/api/dump/save`
Все параметры заводские, в журнале `Skip dump restore: program mismatch …`	Имя программы изменилось	Значения из прежнего дампа можно применить вручную: `POST /api/dump/restore` (без проверки имени)
В журнале после загрузки программы нет строки `Restored dump`, ручной `POST /api/dump/restore` отвечает `Invalid dump file magic`	Файл `dump.bin` повреждён	Восстановите `dump.bin` из резервной копии (служба остановлена)
Служба остановлена при остановленном скане	Дамп при остановке пишется только при работающем скане	Сохраняйте вручную перед остановкой

Проверка восстановления: journalctl -u vplc -b --no-pager | grep -E 'Restored dump|Skip dump'. Маски привязки ввода-вывода после потери dump.bin веб восстанавливает сам в течение 30 с.

Частые вопросы

Можно ли открыть веб без панели? Да, напрямую http://<IP-адрес СА-02м>:8088/, если служба запущена с --host/--port.

Почему модули не управляются, хотя установка в работе? Включена модель (SimEnable = TRUE) и привязка не применена, или у рантайма нет карты (inputs 0, outputs 0 в журнале). См. аварию 61.

Что будет с выходами при остановке скана? Выходы MQTT с заданным safe_value получают это значение; остальные остаются в последнем состоянии. При аварийном завершении процесса брокер публикует /devices/<mqtt_client_id>/meta/error = "r".

Как узнать версию? curl -s http://127.0.0.1:1234/api/status — поле version; dpkg -s vplc.

/api/restart сбрасывает переменные? Нет — только останавливает и запускает скан.

Сбор сведений для поддержки

Соберите отчёт на устройстве:

{
  date; uname -a; head -3 /etc/os-release
  dpkg -s vplc | grep -E '^(Version|Status)'
  systemctl status vplc vplc-plant-ui --no-pager
  for p in status program/info config mqtt/status modbus/status; do
    echo "== /api/$p"; curl -s http://127.0.0.1:1234/api/$p; echo
  done
  echo "== iomap"; curl -s http://127.0.0.1:8088/api/iomap/status; echo
  ls -la /var/lib/vplc /opt/vplc-plant-ui
  free -m; df -h /; uptime
  journalctl -u vplc -n 300 --no-pager
  journalctl -u vplc-plant-ui -n 200 --no-pager
} > /tmp/vplc-support.txt 2>&1

Заберите файл: scp root@<IP-адрес СА-02м>:/tmp/vplc-support.txt .

GET /api/config отдаёт пароль брокера и токен как *** — его вывод можно передавать. Сам файл /etc/vplc.conf не передавайте: в нём секреты открытым текстом.
При заданном api_token добавьте к запросу /api/config заголовок -H 'Authorization: Bearer <токен>', иначе ответ будет 401.
Опишите: что делали, когда началось, что видно в вебе (снимок экрана без адресов и паролей).