Базовый адрес: http://<сервер>:8000.
Тело запросов и ответов — application/json,
кроме /_ping и /metrics.
Авторизации нет: доступ ограничивайте сетью объекта.
Соглашения
- Желаемое и фактическое состояние. Команда задаёт желаемое состояние; фоновый процесс применяет его к модулю. Синхронный запрос ждёт применения не дольше
apply_timeout_sec; фактическое состояние читается через /ptls. - Цвета — имена:
Red, Green, Blue, Yellow, Pink, Cyan, White. «Погасить» — режим без цвета или active: false. - Диапазоны: адрес модуля 1–247, число 0–9999, суб-позиция 0–99.
- Идемпотентность
/apply — снапшот содержит sequence; снапшот с меньшей последовательностью игнорируется. - Ошибки — JSON
{"detail": "…"} с кодом 400, 404, 409 или 500.
Служебные
| Метод | Путь | Назначение |
| 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 и не зависит
от формата спецификации.