Продукты
АКС Комплекс PTL RID Световые маяки Все продукты
Услуги Загрузки Оборудование Документация FAQ
Контакты
Документация · версия 3.0

Интерфейс PTL

Веб-интерфейс для управления PTL-модулями, контроля оборудования и диагностики. Открывается по адресу http://<сервер>:8000/ и не требует установки отдельного клиента.

Один экран — десять вкладок. Верхнее меню переключает разделы. Все изменения применяются сразу, кроме режима Demo и импорта конфигурации — им нужен перезапуск сервиса. Скриншоты сделаны на демо-стенде с виртуальными контроллерами.

Обзор

Стартовый экран показывает состояние сервиса и все настроенные контроллеры. Данные обновляются автоматически каждые 10 секунд, а изменения состояния приходят по WebSocket.

Вкладка «Обзор»: сводка, контроллеры и сетка PTL-модулей
Обзор: сводные карточки, статусы контроллеров и сетка модулей.

Что показывает

Ниже — таблица контроллеров (IP, порт, диапазон адресов, тип устройства, статус) и сетка модулей. Плитка модуля показывает адрес, число, суб-позицию и цвет; неактивные модули — серые. Нажатие на плитку открывает карточку модуля.

Карточка модуля

В карточке видны желаемое и фактическое состояние, число и суб-позиция, цвет, здоровье модуля и счётчик ошибок. Здесь же можно зажечь или погасить модуль, изменить значения и — в демо-режиме — сымитировать нажатие кнопок LED, FUN, MIN и стрелок.

Управление

Ручное управление одним модулем, массовые операции и чтение фактических состояний.

Вкладка «Управление»: включение PTL, массовые операции и чтение
Управление: одиночные команды, массовые операции и чтение PTL.

Включить PTL

ПолеЗначениеНазначение
КонтроллерIP из конфигурацииШлюз, на котором находится модуль
Адрес модуля1–247Modbus-адрес PTL на контроллере
Число на дисплее0–9999Основное число на табло
Суб-позиция0–99Дополнительное табло
ЦветRed, Green, Blue, Yellow, Pink, Cyan, WhiteЦвет LED-кнопки

Кнопка «Включить» отправляет POST /turn_on, «Выключить» — POST /turn_off. Ответ приходит после применения команды к оборудованию или по таймауту apply_timeout_sec.

Массовые операции

Это тест, а не рабочая задача. Массовое зажигание не предназначено для комплектации. Для реальных заданий используйте /apply или сценарии.

Чтение PTL

Выберите контроллер, при необходимости укажите адреса через запятую и фильтр состояния. Результат — таблица с адресом, состоянием, цветом, числом, суб-позицией и нажатыми кнопками. Запрос выполняется через POST /ptls.

Настройка

Сервисные операции с оборудованием: назначение Modbus-адресов, проверка доступности и чтение информации об устройстве.

Вкладка «Настройка»: назначение адресов, проверка доступности, информация об устройстве
Настройка: Assign IDs, проверка доступности и информация об устройстве.

Назначение адресов (Assign IDs)

  1. Выберите контроллер.
  2. Укажите адрес, с которого начинать: 0 — с начала диапазона контроллера.
  3. Нажмите «Запустить». Контроллер последовательно назначит адреса подключённым модулям.
  4. Кнопка «Статус» показывает текущее состояние, «Остановить» — прерывает операцию.

Назначение адресов — монопольная операция: на время её выполнения команды управления и очистки на этом контроллере отклоняются с кодом 409.

Проверка доступности

Выберите контроллер или «Все контроллеры» и нажмите «Проверить». Таблица покажет IP, порт и доступность (GET /alive). Проверка идёт по сети и не меняет состояние модулей.

Информация об устройстве

Укажите контроллер и адрес модуля. Запрос GET /devices/{ip}/{unit}/info вернёт тип устройства, версию прошивки, UID и дату прошивки. Если устройство не отвечает, блок останется пустым.

События

Два независимых потока: живой WebSocket-лог и история из Redis Stream.

Вкладка «События»: WebSocket-лог и история событий
События: подключение WebSocket, живой лог и история.

В лог попадают нажатия кнопок, изменения состояния, здоровье модулей и события задач. Формат — JSON, по одному объекту на строку.

Сценарии

Задачи комплектации, которые приходят от WMS через API, и демо-программы для проверки оборудования.

Вкладка «Сценарии»: выполняемые задачи, демо-программы и журнал
Сценарии: прогресс задач, демо-программы и журнал задач.

Выполняемые задачи

Задача создаётся внешней системой через POST /scenarios/tasks. В таблице видны ID, название, режим, прогресс подтверждений, время старта и кнопка отмены. Отмена — DELETE /scenarios/tasks/{id}.

Демо-программы

Три группы:

Запущенная программа появляется в списке выполняемых задач и останавливается той же кнопкой отмены. Демо-программы не предназначены для рабочей эксплуатации.

Журнал задач

Кнопка «Загрузить» запрашивает историю через GET /scenarios/tasks/history: ID, режим, состояние, количество подтверждений и время.

Аналитика

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

Вкладка «Аналитика»: активации, нажатия, цвета и нагрузка
Аналитика: топ модулей, кнопки, цвета, нагрузка и активность.

«Обновить» перечитывает GET /stats. «Сбросить статистику» вызывает DELETE /stats и очищает только аналитику — состояние модулей и задачи не затрагиваются.

Метрики

Prometheus-метрики сервиса. Эндпоинт /metrics можно подключить к Prometheus через scrape_configs.

Вкладка «Метрики»: карточки, список метрик и примеры PromQL
Метрики: сводные карточки, список метрик и примеры PromQL.
МетрикаТипОписание
ptl_controller_onlinegaugeКонтроллер онлайн (1) / оффлайн (0)
ptl_units_activegaugeАктивных PTL на контроллере
ptl_controllers_totalgaugeВсего контроллеров
ptl_button_events_totalcounterНажатий кнопок
ptl_bus_queue_lengthgaugeОчередь команд на шине
ptl_poll_cycle_duration_secondshistogramВремя цикла опроса
ptl_reconcile_cycle_duration_secondshistogramВремя цикла сверки
modbus_requests_totalcounterModbus-запросы по операциям
modbus_request_duration_secondshistogramВремя Modbus-запросов
api_requests_totalcounterHTTP-запросы по 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.

Вкладка «Конфигурация»: параметры, контроллеры, webhooks, импорт и экспорт
Конфигурация: параметры, контроллеры, webhooks и JSON.

Параметры

ПараметрДиапазонЧто делает
Режим работыProduction / DemoDemo — эмуляция без 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

Перезапуск. Смена режима Demo/Production и импорт конфигурации применяются после перезапуска сервиса: sudo systemctl restart ptl-api.

API

Вкладка кратко описывает HTTP API, соглашения и ссылки на машинночитаемую спецификацию. Полный справочник с параметрами, ответами и примерами — на отдельной странице API PTL.

Вкладка «API»: соглашения, методы и адреса, примеры запросов
API: соглашения, таблицы методов и примеры запросов.

На установленном сервисе спецификация доступна по адресу http://<сервер>:8000/openapi.yaml. Авторизации нет; доступ ограничивайте сетью.

О приложении

Сведения о версии, правообладателе и поддержке, а также переключатель телеметрии.

Вкладка «О приложении»: версия, документы, поддержка и телеметрия
О приложении: версия, документы, контакты и телеметрия.

Телеметрия не передаёт IP-адреса, данные оборудования, URL вебхуков и содержимое дисплеев. Подробнее — политика телеметрии.

Доступ и безопасность

Встроенной авторизации нет. Любой, кто открыл порт 8000, может управлять модулями. Ограничивайте доступ сетью объекта, VPN или reverse proxy с Basic Auth.

Типовые сценарии

Первый запуск

  1. Установите сервис и укажите контроллеры в config.json.
  2. Откройте интерфейс и убедитесь, что все контроллеры Online.
  3. Во вкладке «Настройка» назначьте адреса модулям.
  4. Во вкладке «Управление» зажгите один модуль и проверьте цвета и числа.
  5. Настройте webhooks для WMS и проверьте событие нажатия.

Ежедневная работа

  1. WMS создаёт задачу через POST /scenarios/tasks.
  2. Модули зажигаются, оператор снимает товар и нажимает кнопку.
  3. События приходят в WMS по webhook или через WebSocket.
  4. Прогресс задачи виден во вкладке «Сценарии».

Диагностика

Демо-режим

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