API

Также доступна документация в формате OpenAPI (SwaggerUI): http://ptl-demo.fondev.ru/docs#/ с возможностью тестирования запросов.

Формат обмена API: JSON.

PTL-модуль

PTL-модуль - это пассивное устройство. Он не имеет возможности отправлять данные самостоятельно. За чтение и запись отвечает контроллер.

Каждый PTL-модуль имеет уникальный ID в рамках одного контроллера. ID - это целое число от 1 до 247. ID назначается при установке модулей на штатные места использования. Также PTL-модуль имеет встроенные параметры, которые отвечают за его состояние. Состояние изменяется через HTTP API или нажатием на кнопки модуля.

Взаимодействие через API выглядит упрощенно так:

Если мы хотим зажечь PTL модуль с числом 100 и синей кнопкой, то мы сначала должны выполнить команду /turn_on.
Если мы хотим узнать был ли PTL модуль нажат, мы выполняем команду /ptls

Текущий вариант API не подразумевает отправку события о нажатии на модуль на вебхук внешнего ПО или в брокер обмена сообщениями.

Параметры PTL модуля

Текущие параметры, которые поддерживаются API независимо от модели PTL-модуля.

Параметр	Назначение
unit	ID модуля
number	Число для отображения на основном блоке цифр
sub	Число для отображения на дополнительном блоке цифр
state	Состояние модуля
color	Цвет LED-кнопки
fun_hold_counter	Счетчик времени зажатия кнопки FUN
btn_led_pressed	Флаг "была нажата кнопка LED"
btn_fun_pressed	Флаг "была нажата кнопка FUN"
btn_arrows_pressed	Флаг "была нажата одна из кнопок "Стрелка"

Все параметры можно разделить на две группы доступности: чтения/записи и только для чтения.

Чтение/запись

Эти параметры можно изменять через API.

number
sub
color

Только чтение

Эти параметры можно только получить через API.

unit
state
fun_hold_counter
btn_led_pressed
btn_fun_pressed
btn_arrows_pressed

/_ping

Метод: GET

Сервисный метод для интеграции с сервисами мониторинга.

Возвращает код HTTP 200 и текстовое значение pong. Позволяет определить, что сервис API онлайн.

/config

Метод: GET

Метод возвращает текущую конфигурацию сервиса.

Описание параметров конфигурации и их значений указано в разделе "Конфигурация".

Пример ответа:

{
  "demo": true,
  "controllers": [
    {
      "ip": "192.168.0.100",
      "port": 502,
      "start_id": 1,
      "end_id": 30
    },
    {
      "ip": "192.168.0.101",
      "port": 502,
      "start_id": 1,
      "end_id": 30
    }
  ],
  "debug": false,
  "api_log": "/var/log/fontera/api.log",
  "db_path": "/app/ptls.db",
  "clean_ptl_on_startup": true
}

/ptls

Метод: POST

API используется для получения текущих состояний PTL модулей.

Все передаваемые параметры (кроме clear_after) работаю как фильтры, помогая делать выборку конкретных PTL модулей.

Параметры

ip

Обязательный параметр в запросе.

IP-адрес контроллера.
Передается как строка, в формате IPv4.
Пример: 192.168.0.100

clear_after

Опция: очищать данные PTL сразу после получения состояний или нет.

По-умолчанию: false

mode

ВНИМАНИЕ

В версии 2.4 мы будем использовать имя state вместо mode.

Состояние PTL модулей. Если указать, то будут возвращены только модули, которые находятся этом состоянии.

Допустимые значения:

Параметр	Пояснение
activated	Активное состояние. Ожидание нажатия PTL.
deactivated	Деактивированный PTL. Модуль был нажат или

ptl_ids

Список идентификаторов PTL модулей, которые нужно получить.

Например: [1, 3, 5, 6, 8]

Примеры запросов

Здесь мы запрашиваем все PTL-модули любой роли в активном состоянии, подключенные к контроллеру 192.168.0.100. При этом, сразу после выполнения запроса, данные на PTL-модулях будут очищены. Повторный запрос с данными параметрами вернет пустой список, так как данные PTL-модулей будут пустыми.

{
  "ip": "192.168.0.100",
  "clear_after": true,
  "mode": "Activated"
}

А здесь мы получим все PTL-модули независимо от их состояния и других факторов.

{
  "ip": "192.168.0.100"
}

/turn_on

Метод: POST

API активирует один или более PTL-модулей в рамках одного контроллера.

Запрос на включение состоит из двух частей: указания IP-адреса контроллера и списка команд для PTL.

Например, если мы хотим зажечь PTL-модуль #10 на контроллере 192.168.0.100 со значениями 99 0100 и кнопка LED должна быть синего цвета, то мы должны передать следующие параметры:

{
  "controller_ip": "192.168.0.100",
  "commands": [
    {
      "unit": 10,
      "number": 100,
      "sub": 99,
      "color": "Blue"
    }
  ]
}

Параметры запроса

Параметр	Пояснение
controller_ip	IP адрес контроллера в формате IPv4
commands	Список команд для зажигания PTL модулей

Параметры команды

Параметр	Пояснение
unit	ID PTL-модуля, целое число от 0 до 247
number	Число для основного блока цифр, целое число, длина зависит от модели PTL
sub	Число для дополнительного блока цифр, целое число, длина зависит от модели PTL
color	Цвет зажигания LED

Допустимые параметры цвета LED

Red
Green
Blue
Yellow
Pink
Cyan
White

Примеры запросов

/turn_off

Метод: POST

Используется для выключения (деактивации) одного или нескольких PTL-модулей в рамках указанного контроллера. PTL-модуль переводится в режим deactivated. Все параметры PTL-модуля сбрасываются.

/check

Метод: GET

Сервисный метод API для выполнения тестового зажигания всех модулей одного или всех контроллеров, указанных в конфигурации.

Если указан query-параметр ip в формате строки IPv4, то зажигание будет выполнено для указанного контроллера.

Например:

GET http://ptl-demo.fondev.ru/check?ip=192.168.0.100

После выполнения команды, кнопки PTL модулей будут гореть синим цветом с отображать диапазон PTL модулей.

/clear

Метод: GET

Метод очистки всех PTL-модулей одного или всех контроллеров.

Сбрасывает все параметры (кроме unit) и состояние. После выполнения операции модули будут выключены (как при выполнении /turn_off), значения number и sub будут пустыми, параметр mode будет deactivated.

Например:

GET http://ptl-demo.fondev.ru/clear?ip=192.168.0.100

/press

Метод: POST

Используется для имитации нажатия на LED-кнопку PTL-модуля. Недоступен в режиме продакшна (опция конфигурации приложения demo: false).

При этом, можно имитировать только изменение значений цифровых блоков без имитации нажатия на LED-кнопку. Таким образом можно разделить изменение цифровых блоков (нажатие на "стрелки") и подтверждение подбора.

Пример запроса:

{
  "controller_ip": "string",    # IP контроллера
  "ptls": [                     # Список команд для PTL, которые нужно "нажать"
    {
      "unit": 0,                # ID модуля, который нужно нажать
      "number": 0,              # Новое значение для number (как будто его изменили)
      "sub": 0,                 # Новое значение для sub (как будто его изменили)
      "led_btn_pressed": true   # Установить факт нажатия на LED
    }
  ]
}