Интерфейс PTL
Веб-интерфейс для управления PTL-модулями, контроля оборудования
и диагностики. Открывается по адресу
http://<сервер>:8000/ и не требует установки
отдельного клиента.
Один экран — десять вкладок. Верхнее меню переключает разделы. Все изменения применяются сразу, кроме режима Demo и импорта конфигурации — им нужен перезапуск сервиса. Скриншоты сделаны на демо-стенде с виртуальными контроллерами.
Обзор
Стартовый экран показывает состояние сервиса и все настроенные контроллеры. Данные обновляются автоматически каждые 10 секунд, а изменения состояния приходят по WebSocket.
Что показывает
- Контроллеры — общее число настроенных шлюзов.
- Онлайн — сколько контроллеров отвечает.
- Активных PTL — количество зажжённых модулей.
- Деградированных — модули с ошибками чтения/записи.
- Всего PTL — сумма всех адресов во всех контроллерах.
Ниже — таблица контроллеров (IP, порт, диапазон адресов, тип устройства, статус) и сетка модулей. Плитка модуля показывает адрес, число, суб-позицию и цвет; неактивные модули — серые. Нажатие на плитку открывает карточку модуля.
Карточка модуля
В карточке видны желаемое и фактическое состояние, число и суб-позиция, цвет, здоровье модуля и счётчик ошибок. Здесь же можно зажечь или погасить модуль, изменить значения и — в демо-режиме — сымитировать нажатие кнопок LED, FUN, MIN и стрелок.
Управление
Ручное управление одним модулем, массовые операции и чтение фактических состояний.
Включить PTL
| Поле | Значение | Назначение |
|---|---|---|
| Контроллер | IP из конфигурации | Шлюз, на котором находится модуль |
| Адрес модуля | 1–247 | Modbus-адрес PTL на контроллере |
| Число на дисплее | 0–9999 | Основное число на табло |
| Суб-позиция | 0–99 | Дополнительное табло |
| Цвет | Red, Green, Blue, Yellow, Pink, Cyan, White | Цвет LED-кнопки |
Кнопка «Включить» отправляет POST /turn_on,
«Выключить» — POST /turn_off.
Ответ приходит после применения команды к оборудованию или по
таймауту apply_timeout_sec.
Массовые операции
- «Зажечь все» вызывает
GET /check: все модули всех контроллеров зажигаются тестовым шаблоном8888 / 88со случайным цветом. - «Потушить все» вызывает
GET /clearбез параметров и гасит все модули. - В блоке по каждому контроллеру доступны отдельные кнопки «Зажечь» и «Потушить».
Это тест, а не рабочая задача.
Массовое зажигание не предназначено для комплектации.
Для реальных заданий используйте /apply или
сценарии.
Чтение PTL
Выберите контроллер, при необходимости укажите адреса через запятую
и фильтр состояния. Результат — таблица с адресом,
состоянием, цветом, числом, суб-позицией и нажатыми кнопками.
Запрос выполняется через POST /ptls.
Настройка
Сервисные операции с оборудованием: назначение Modbus-адресов, проверка доступности и чтение информации об устройстве.
Назначение адресов (Assign IDs)
- Выберите контроллер.
- Укажите адрес, с которого начинать:
0— с начала диапазона контроллера. - Нажмите «Запустить». Контроллер последовательно назначит адреса подключённым модулям.
- Кнопка «Статус» показывает текущее состояние, «Остановить» — прерывает операцию.
Назначение адресов — монопольная операция: на время её
выполнения команды управления и очистки на этом контроллере
отклоняются с кодом 409.
Проверка доступности
Выберите контроллер или «Все контроллеры» и нажмите
«Проверить». Таблица покажет IP, порт и доступность
(GET /alive). Проверка идёт по сети и не меняет
состояние модулей.
Информация об устройстве
Укажите контроллер и адрес модуля. Запрос
GET /devices/{ip}/{unit}/info вернёт тип устройства, версию
прошивки, UID и дату прошивки. Если устройство не отвечает,
блок останется пустым.
События
Два независимых потока: живой WebSocket-лог и история из Redis Stream.
- WebSocket — статус «Подключен / Отключен». При обрыве клиент переподключается каждые 3 секунды.
- Живой лог — последние события, до 500 строк. Кнопка «Очистить лог» очищает только отображение.
- История — кнопка «Загрузить» запрашивает последние 100 событий через
GET /events?count=100.
В лог попадают нажатия кнопок, изменения состояния, здоровье модулей и события задач. Формат — JSON, по одному объекту на строку.
Сценарии
Задачи комплектации, которые приходят от WMS через API, и демо-программы для проверки оборудования.
Выполняемые задачи
Задача создаётся внешней системой через POST /scenarios/tasks.
В таблице видны ID, название, режим, прогресс подтверждений, время
старта и кнопка отмены. Отмена — DELETE /scenarios/tasks/{id}.
Демо-программы
Три группы:
- Legacy (per-unit) — «Бегущий огонь», «Радуга», «Волна», «Мигание», «Показать ID», «Случайные», «Обратный отсчёт», «Шахматка», «Версия прошивки».
- Декларативные (/apply) — «Волна», «Радуга», «Пульсация», «Каскад», «Схождение».
- Тестовые сценарии — Stress /apply, Out-of-order, Freeze-window, Multi-controller burst.
Запущенная программа появляется в списке выполняемых задач и останавливается той же кнопкой отмены. Демо-программы не предназначены для рабочей эксплуатации.
Журнал задач
Кнопка «Загрузить» запрашивает историю через
GET /scenarios/tasks/history: ID, режим, состояние,
количество подтверждений и время.
Аналитика
Статистика использования модулей и кнопок. Данные хранятся в Redis и накапливаются между перезапусками, пока не сброшены.
- Сводка — ключевые счётчики.
- Топ модулей — модули с наибольшим числом активаций.
- Кнопки — количество нажатий по контроллеру, адресу и типу кнопки.
- Цвета — распределение использованных цветов.
- Нагрузка по контроллерам — число команд на каждый шлюз.
- Активность по часам и дням — распределение команд.
«Обновить» перечитывает GET /stats.
«Сбросить статистику» вызывает DELETE /stats и очищает
только аналитику — состояние модулей и задачи не затрагиваются.
Метрики
Prometheus-метрики сервиса. Эндпоинт /metrics можно
подключить к Prometheus через scrape_configs.
| Метрика | Тип | Описание |
|---|---|---|
ptl_controller_online | gauge | Контроллер онлайн (1) / оффлайн (0) |
ptl_units_active | gauge | Активных PTL на контроллере |
ptl_controllers_total | gauge | Всего контроллеров |
ptl_button_events_total | counter | Нажатий кнопок |
ptl_bus_queue_length | gauge | Очередь команд на шине |
ptl_poll_cycle_duration_seconds | histogram | Время цикла опроса |
ptl_reconcile_cycle_duration_seconds | histogram | Время цикла сверки |
modbus_requests_total | counter | Modbus-запросы по операциям |
modbus_request_duration_seconds | histogram | Время Modbus-запросов |
api_requests_total | counter | HTTP-запросы по method/path/status |
Блок «Полный вывод» показывает сырой ответ /metrics.
Примеры PromQL: rate(api_requests_total[5m]),
rate(modbus_requests_total[5m]),
histogram_quantile(0.95, rate(modbus_request_duration_seconds_bucket[5m])).
Конфигурация
Часть параметров редактируется в интерфейсе, полная конфигурация
хранится в /etc/ptl_api/config.json.
Параметры
| Параметр | Диапазон | Что делает |
|---|---|---|
| Режим работы | Production / Demo | Demo — эмуляция без Modbus. Переключение требует перезапуска |
| Интервал опроса | 50–60000 мс | Как часто поллер читает состояния |
| Опрашивать только активные | Да / Нет | Экономит шину, читая только зажжённые модули |
| Интервал сверки | 1–300 с | Как часто reconciler сравнивает желаемое и фактическое состояние |
| Таймаут применения | 1–60 с | Максимальное ожидание применения команды |
Остальные параметры (таймауты Modbus, пороги degraded/unreachable, частота монитора, ротация журналов) задаются в файле конфигурации и описаны в развёртывании.
Контроллеры
Таблица показывает IP, порт, адреса PTL и тип устройства. Кнопка
«Сохранить» отправляет PUT /controllers/{ip},
«Удалить» — DELETE /controllers/{ip}.
Кнопка WH открывает webhooks конкретного контроллера.
«Добавить контроллер» открывает форму: IP, порт (по умолчанию 502),
адреса в виде 1-30, 101 и тип устройства. Создание —
POST /controllers.
Webhooks
Глобальные webhooks срабатывают для событий на любом контроллере.
Для каждого URL можно выбрать события: button,
task_confirmed, task_completed,
task_timeout, task_cancelled,
controller_offline, controller_online.
Пустой список — все события.
Импорт, экспорт и JSON
- Экспорт скачивает текущую конфигурацию в JSON-файл.
- Импорт заменяет конфигурацию целиком через
POST /config/import; после импорта рекомендуется перезапуск. - Конфигурация (JSON) показывает ответ
GET /config.
Перезапуск.
Смена режима Demo/Production и импорт конфигурации применяются
после перезапуска сервиса: sudo systemctl restart ptl-api.
API
Вкладка кратко описывает HTTP API, соглашения и ссылки на машинночитаемую спецификацию. Полный справочник с параметрами, ответами и примерами — на отдельной странице API PTL.
На установленном сервисе спецификация доступна по адресу
http://<сервер>:8000/openapi.yaml. Авторизации нет;
доступ ограничивайте сетью.
О приложении
Сведения о версии, правообладателе и поддержке, а также переключатель телеметрии.
- Версия — вшита при сборке, запрашивается через
GET /version. - Регистрация ПО — свидетельство № 2025687159.
- Документы — отказ от ответственности и лицензионное соглашение.
- Поддержка — support@whsoft.ru.
- Телеметрия — тумблер «Отправлять обезличенную телеметрию». Отключение применяется сразу через
PUT /config.
Телеметрия не передаёт IP-адреса, данные оборудования, URL вебхуков и содержимое дисплеев. Подробнее — политика телеметрии.
Доступ и безопасность
Встроенной авторизации нет. Любой, кто открыл порт 8000, может управлять модулями. Ограничивайте доступ сетью объекта, VPN или reverse proxy с Basic Auth.
- Интерфейс и API работают по HTTP; для внешнего доступа ставьте TLS-терминацию (Caddy, nginx).
- Не публикуйте порт 8000 в интернет и не разрешайте его в межсетевом экране.
- Публичный демо-стенд ptl-demo.whsoft.ru не содержит реального оборудования и сбрасывается каждые 15 минут.
- Ролей и учётных записей нет: все действия выполняются от имени сервиса. Для аудита используйте журнал событий и логи.
Типовые сценарии
Первый запуск
- Установите сервис и укажите контроллеры в
config.json. - Откройте интерфейс и убедитесь, что все контроллеры Online.
- Во вкладке «Настройка» назначьте адреса модулям.
- Во вкладке «Управление» зажгите один модуль и проверьте цвета и числа.
- Настройте webhooks для WMS и проверьте событие нажатия.
Ежедневная работа
- WMS создаёт задачу через
POST /scenarios/tasks. - Модули зажигаются, оператор снимает товар и нажимает кнопку.
- События приходят в WMS по webhook или через WebSocket.
- Прогресс задачи виден во вкладке «Сценарии».
Диагностика
- Контроллер Offline — проверьте питание, сеть и порт 502; во вкладке «Настройка» нажмите «Проверить».
- Модуль не зажигается — проверьте адрес, тип устройства и статус Degraded; откройте карточку модуля.
- Нет событий — проверьте WebSocket и историю; убедитесь, что поллер опрашивает нужные адреса.
- Неверный цвет или число — сравните желаемое и фактическое состояние, проверьте
apply_timeout_sec.
Демо-режим
Включите Demo во вкладке «Конфигурация», перезапустите сервис и используйте демо-программы и имитацию нажатий. Для рабочей эксплуатации верните Production.