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

API PTL

HTTP и WebSocket API для управления PTL-модулями через Ethernet-шлюзы Modbus TCP. Клиент задаёт желаемое состояние модуля, сервис применяет его к оборудованию, фактическое состояние читается отдельно.

Базовый адрес: http://<сервер>:8000. Тело запросов и ответов — application/json, кроме /_ping и /metrics. Авторизации нет: доступ ограничивайте сетью объекта.

Соглашения

Служебные

МетодПутьНазначение
GET /_ping Проверка живости. Ответ — текст pong.
GET /version Версия продукта, вшитая при сборке.
GET /metrics Метрики в формате Prometheus.

Контроллеры и устройства

МетодПутьНазначение
GET /alive Сетевая доступность контроллеров (ping).
GET /controllers Список контроллеров со статусом online/offline.
POST /controllers Добавить контроллер.
PUT /controllers/{ip} Обновить контроллер.
DELETE /controllers/{ip} Удалить контроллер.
GET /controllers/{ip}/health Здоровье контроллера.
GET /controllers/{ip}/units/{unit}/health Здоровье одного модуля.
GET /devices/{ip}/{unit}/info Тип, прошивка, UID и дата устройства.
POST /assign_ids Запуск или остановка назначения Modbus-адресов.
GET /assign_ids/status Статус назначения адресов.
POST /reboot Перезагрузка устройств по IP.

PTL-модули

МетодПутьНазначение
GET /check Тестовое зажигание всех модулей: 8888 / 88, случайный цвет.
POST /ptls Прочитать фактическое состояние модулей.
POST /bulk/ptls Прочитать состояние с нескольких контроллеров.
POST /turn_on Включить модули контроллера.
POST /turn_off Выключить модули контроллера.
GET /clear Погасить все модули контроллера; без ip — все контроллеры.
POST /bulk/turn_on Включить модули на нескольких контроллерах.
POST /bulk/turn_off Выключить модули на нескольких контроллерах.
POST /bulk/clear Погасить модули на нескольких контроллерах.
POST /apply Применить декларативный снапшот с sequence.
POST /press Симулировать нажатие кнопок. Только demo.

Сценарии

МетодПутьНазначение
GET /scenarios/tasks Список активных задач.
POST /scenarios/tasks Запустить задачу.
GET /scenarios/tasks/history История задач.
GET /scenarios/tasks/{id} Статус задачи.
DELETE /scenarios/tasks/{id} Отменить задачу.
GET /scenarios/presets Список пресетов.
POST /scenarios/presets Создать пресет.
GET /scenarios/presets/{id} Получить пресет.
PUT /scenarios/presets/{id} Обновить пресет.
DELETE /scenarios/presets/{id} Удалить пресет.
POST /scenarios/presets/{id}/run Запустить пресет.
GET /scenarios/demo/programs Список демо-программ.
POST /scenarios/demo/run Запустить демо-программу.
DELETE /scenarios/demo/{runID} Остановить демо-программу.

Конфигурация

МетодПутьНазначение
GET /config Текущая конфигурация.
PUT /config Частично изменить и сохранить конфигурацию.
POST /config/import Импортировать конфигурацию целиком.
POST /_restart Перезапустить сервис.

События и аналитика

МетодПутьНазначение
GET /events Последние события из Redis Stream.
GET /stats Аналитика: активации, нажатия, цвета.
DELETE /stats Сбросить аналитику.
WS /ws/events WebSocket с трансляцией событий.

Примеры

Список контроллеров

Запрос
curl http://localhost:8000/controllers

Прочитать состояние модуля

Запрос
curl -X POST http://localhost:8000/ptls \
  -H 'Content-Type: application/json' \
  -d '{"ip": "10.0.0.1", "ptl_ids": [1]}'
Ответ
[
  {
    "unit": 1,
    "controller": "10.0.0.1",
    "state": "Activated",
    "color": "Green",
    "number": 5,
    "sub": 1,
    "fun_hold_counter": 0,
    "btn_led_pressed": false,
    "btn_fun_pressed": false,
    "btn_min_pressed": false,
    "btn_arrows_pressed": false
  }
]

Включить модуль

Запрос
curl -X POST http://localhost:8000/turn_on \
  -H 'Content-Type: application/json' \
  -d '{
    "controller_ip": "10.0.0.1",
    "commands": [
      {"unit": 1, "number": 5, "sub": 1, "color": "Green"}
    ]
  }'

Погасить все модули контроллера

Запрос
curl "http://localhost:8000/clear?ip=10.0.0.1"

Декларативный снапшот

Запрос
curl -X POST http://localhost:8000/apply \
  -H 'Content-Type: application/json' \
  -d '{
    "controllers": [
      {
        "controller_ip": "10.0.0.1",
        "sequence": 1,
        "units": [
          {"unit": 1, "active": true, "number": 5, "color": "Green"}
        ]
      }
    ]
  }'

Запустить задачу

Запрос
curl -X POST http://localhost:8000/scenarios/tasks \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Заказ 123",
    "mode": "guide",
    "highlight_color": "Green",
    "base_color": "Blue",
    "timeout_sec": 300,
    "commands": [
      {"controller_ip": "10.0.0.1", "unit": 1, "number": 5, "sub": 1, "color": "Green"}
    ]
  }'

WebSocket

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

JavaScript
var ws = new WebSocket('ws://' + location.host + '/ws/events');
ws.onmessage = function (e) {
  var event = JSON.parse(e.data);
  console.log(event);
};

Типы событий: button, state_update, unit_health, task_confirmed, task_completed, task_timeout, task_cancelled, controller_online, controller_offline.

Ошибки

КодКогда возникаетЧто делать
400Некорректный JSON, неизвестный цвет, адрес вне диапазонаПроверить тело запроса и значения полей
404Контроллер, модуль, задача или пресет не найденыПроверить IP, адрес и ID
409На контроллере выполняется назначение адресовДождаться завершения или остановить Assign IDs
500Внутренняя ошибка или таймаут примененияПроверить журнал, доступность контроллера и apply_timeout_sec

На установленном сервисе доступна машинночитаемая спецификация OpenAPI 3.0: http://<сервер>:8000/openapi.yaml. Эта страница описывает фактическое поведение API и не зависит от формата спецификации.