Открытый API

Для обмена информацией с Центральным блоком ИСО Тополь используется протокол HTTP/1.1 в соответствии с RFC 2616 “Hypertext Transfer Protocol -- HTTP/1.1” https://tools.ietf.org/html/rfc2616

Адрес запроса формируется из указателя протокола http:// + IP адреса центрального блока + стандартного разделителя «:» + номер порта, указанного в конфигурации центрального блока (по умолчанию 8765) + тело команды + переменные, перед именем первой переменной используется символ «?» перед последующими «&»

Пример запроса к центральному пульту с IP адресом 192.168.0.68:
http://192.168.0.68:8765/json/getinputsrawvalues?lastEvent=0&inputUuid=3cfa823e-098c-4778-910d-6f3190b3c607

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

Код
Описание
200 (OK) Команда успешно получена, выполнена и далее последует результат выполнения
400 (Bad Request) Команда успешно получена но не выполнялась т.к. не верно указаны (или не указаны вообще) необходимые переменные для выполнения команды. 
Например запрос http://192.168.0.68:8765/json/topol3/scanline?serialport=2&firstAddress=2&lastAddress=122 не может быть
выполнен т.к. в нем не указана переменная «IP», указывающая на IP адрес линейного блока
401 (Unauthorized)
Команда не была выполнена т.к. для ее выполнения требуются привилегии выше стандартных, а токен авторизации не был предоставлен либо не действителен
403 (Forbidden)
Команда не была выполнена т.к. предоставленный токен авторизации не имеет необходимых привилегий
404 (Not Found)
Команда не найдена – ошибка в синтаксисе команды или отличие в версии протокола
500 (Internal Server Error)
Произошла ошибка во время выполнения команды, при этом создается запись в журнале ERRATA
501 (Not Implemented)
Запрошенная команда не поддерживается данной версией программного обеспечения

К ответу прикрепляются следующие заголовки:

Заголовок
Описание
Content-Type
MIME Тип содержимого в ответе, для JSON части протокола = «application/json; charset=utf-8»
Content-Length
Количество байт в ответе. Указывается всегда при статусе = 200, по этому заголовку можно ориентироваться сколько байт необходимо дождаться от центрального пульта в случае запроса больших массивов по медленным сетям передачи данных.

Все запросы разделены на две группы:

- запросы начинающиеся на /json – в результате выполнения этих запросов центральный блок возвращает набор данных, например запрос событий, устройств, пользователей и т.п. Набор данных представляет из себя JSON
в соответствии с rfc 8259 «The JavaScript Object Notation (JSON) Data Interchange Format» https://tools.ietf.org/html/rfc8259

- запросы начинающиеся на /cmd – в ответ блок возвращает результат выполнения команды, например добавление нового прибора, отметка тревоги обработанной и т.п. В большинстве случаев это либо «ОК» либо описание ошибки выполнения.

Данные поля типа дата (например дата события) передаются в формате POSIX time (Unix epoch) + три регистра для миллисекунд т.е. например дата 1519220475466 = 1519220475 POSIX (21 Февраля 2018 13:41:15 GMT) + 466 миллисекунд = 21.02.2018 13:41:15:466 GMT

Данные типа UUID представляют из себя уникальный идентификатор, сформированный в соответствии с RFC 4122 «A Universally Unique IDentifier (UUID) URN Namespace» https://tools.ietf.org/html/rfc4122 Передаются UUID в строковом виде в формате, описанном в пункте 3. Namespace Registration Template, «The formal definition of the UUID string representation».

Поиск линейных блоков в локальной сети

Для поиска линейных блоков в локальной сети используется запрос

/json/topol3/scanLan 

Например: http://192.168.0.68:8765/json/topol3/scanLan

Центральный блок, получив данный запрос, выполнит процедуру широковещательного поиска линейных блоков в локальной сети. В случае если будут обнаружены блоки, отсутствующие в конфигурации центрального
блока, они будут автоматически добавлены в конфигурацию и им будут присвоены уникальные идентификаторы (uuid).

После выполнения широковещательного поиска, центральный пульт вернет JSON пакет, в котором будут перечислены все найденные линейные блоки:

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

[

  {

    "uuid":
"07ecafc6-9744-4a3d-8955-284f7ae1bd30",

    "type":10,

    "serialNumber": "37 ff d7 05
4b 4e 38 34 36 40 23 43 ",

    "ip": "192.168.0.170",

    "typeName":"Тополь-3 Линейный блок",

    "inputs":[     ]

  },

  {

    "uuid":
"459d5a1f-3d74-4f6e-8fe4-3c2cd6ffc803",

    "type":10,

    "serialNumber": "37
ff d8 05 4b 4e 38 34 43 39 23 43 ",

    "ip":
"192.168.0.172"

    "typeName":"Тополь-3 Линейный блок",

    "inputs":[     ]

  }

]

uuid = Уникальный идентификатор прибора в ИСО Тополь
type = Тип пробора
serialNumber = Серийный номер линейного блока
ip = Текущий IP адрес
typeName = Расшифровка имени типа прибора
inputs = Массив входов

Присвоение IP адреса линейному блоку

Запрос:

/json/topol3/applyLanSettings?serialNumber=&ip=&mask=&gateway=

Например: http://192.168.0.68:8765/json/topol3/applyLanSettings?serialNumber=37ffd7054b4e383436402343&ip=192.168.0.170&mask=255.255.255.0&gateway=192.168.0.1192

serialNumber = Серийный номер линейного блока
ip = Новый IP адрес линейного блока
mask = Новая маска подсети линейного блока
gateway = Новый шлюз линейного блока

 Ответ:

  {

    "uuid":
"07ecafc6-9744-4a3d-8955-284f7ae1bd30",

   
"type":10,

    "serialNumber":
"37 ff d7 05 4b 4e 38 34 36 40 23 43 ",

    "ip":
"192.168.0.170",

    "typeName":"Тополь-3
Линейный блок",

    "inputs":[     ]



  }

uuid = Уникальный идентификатор прибора в ИСО Тополь
type = Тип пробора
serialNumber = Серийный номер линейного блока
ip = Текущий IP адрес, в случае если адрес присвоен удачно = Новый IP адрес линейного блока
typeName = Расшифровка имени типа прибора
inputs = Массив входов

Запрос текущей конфигурации приборов

В ответ на запрос /json/getdevicelist центральный пульт возвращает полный список всех зарегистрированных приборов в системе, включая их входы, выходы и состояния. При этом запросе не передаются накопленные значения
сигналов

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

[

  {

    "uuid": "1a2ca932-3f1c-467a-af21-2faadf5c7062",

    "type": 10,

    "serialAddress": 0,

    "serialNumber": "37 ff d7 05
4b 4e 38 34 36 40 23 43 ",

    "ip": "192.168.0.170",

    "online": true,

    "skud": false,

    "typeName": "Тополь-3 Линейный блок",

    "inputs": []

  },

  {

    "uuid":
"f4384474-c107-4adf-9115-d0f78c702684",

    "type": 40,

    "serialAddress": 1,

    "serialPortName": "0",

    "serialNumber":
"00022L17",

    "ip": "192.168.0.170",

    "online":
false,

    "skud": false,

    "typeName": "СД-3",

    "inputs": [

      {

        "type": 100,

        "name": "Уровень вибрации",

        "address": 0,

        "uuid":
"f8d96369-ba76-4535-be41-439e68a0deec",

        "holdValues": 150,

        "alarm": false,

        "prealarm": false,

        "prearm": false,

        "arm": false,

        "fault": false

      }

    ]

  },

  {

    "uuid":
"21fe9f93-0bc3-4c4e-9b12-1d0cf44afc6a",

    "type": 50,

    "serialAddress": 13,

    "serialPortName": "0",

    "serialNumber":
"00033L18",

    "ip": "192.168.0.170",

    "online":
false,

    "skud": false,

    "typeName": "ДД-1",

    "inputs": [

      {

        "type": 100,

        "name": "Уровень вибрации",

        "address": 0,

        "uuid":
"c10dc9b8-5855-458f-9708-d0cbc61a8957",

        "holdValues": 150,

        "alarm": false,

        "prealarm": false,

        "prearm": false,

        "arm": false,

        "fault": false,

        "link": false

      }

    ]

  }

]

Логическая схема:
[
{
Описание прибора
             Описание входов прибора[]
             Описание выходов прибора[]
}
]

Формат описания прибора:

UUID uuid
Device unique id
Уникальный идентификатор прибора
String name
Device user-friendly name
Имя прибора
Integer type
Device type
Тип
прибора (см таблицу ниже)
Integer serialAddress
Device address inside serial network it is physically connected to. Address should be set even if device is connected
via Ethernet but uses serial interface (like RS-485 Modbus devices, connected via Ethernet converters)
Адрес устройства в последовательной сети, к которой прибор физически подключен.
Адрес должен быть установлен даже если прибор подключен через Ethernet но использует последовательную линию связи (например линию RS-485 подключенную через преобразователь в Ethernet)

 String serialPortName
Serial port name for devices connected directly to PC running this software OR serial port number for devices connected to multi-port RS-485 to Ethernet converters. Currently only NPF Polyservice multi-port converters are supported in direct operation mode.
Имя последовательного порта, к которому физически подключен прибор. Если прибор подключен к многопортовому преобразователю RS-485-Ethernet, то указывается номер порта.


String serialNumber

Device serial number, generated by
manufacturer

Серийный номер прибора

 

String firmwareVersion

Device firmware version

Версия прошивки прибора

 

String hardwareVersion

Device hardware version or revision

Аппаратная версия прибора

 

String ip

IP address if device is connected via
Ethernet.

IP адрес
прибора, в случае если прибор подключен через Ethernet

 

Boolean online

True if device should be inited and
updated automatically, false if device

should be ignored during auto init and
update

 

Прибор
опрашивается (если true то центральный пульт опрашивает прибор, если

false то
центральный пульт игнорирует прибор при опросе приборов)

 

Boolean skud

True if device contains keys for access
control subsystem

Прибор
участвует в подсистеме СКУД и является хранилищем ключей

 

String typeName

User-friendly device type name

Название
типа прибора

 

List<Input> inputs

List of device inputs

Список входов прибора

 

List<Output> outputs

List of device outputs

Список выходов прибора

 

Boolean fault

Device has faults that are not referred to
communication with device. True if

device reported fault or device input or
output value is inside fault range.

 

Истина
если у прибора зарегистрирована неисправность, не имеющая отношения к

линиии
связи. Возникает в случае если прибор сам доложил о неисправности либо

текущие
значение входа или выхода находится за пределами нормы.

     

Boolean link

Communication with device is ok.

Связь с
прибором установлена.

     

Integer ping

Last delay during device update

Время
задержки во время последнего опроса прибора

 

Long lastUpdated 

Time when device was last successfully
updated

Время
когда прибор был последний раз успешно обновлен

 

Integer linkErrorsСonsThreshold

Amount of consecutive errors before link
error will be raised

Количество
последовательных ошибок обмена перед формированием события неисправности линии

 

Integer linkErrorsСons

Amount of consecutive errors

Количество
последовательных ошибок в текущий момент

     

Integer linkErrors

Amount of link errors from system startup

Количество
ошибок обмена с момента запуска системы

     

Integer lastError

Last error code

Код последней ошибки

 

Boolean inited

Device was successfully inited

Прибор
был успешно инициализирован

 

Типы
приборов (поле type):

 

TYPE_TOPOL3L = 10

NPF Polyservice Topol-3 Ethernet module with RS-485

НПФ
Полисервис Тополь-3 Линейный блок
Ethernet c RS-485

 

TYPE_VD3 = 20

NPF Polyservice Vibration sensor VD-3

НПФ
Полисервис Вибродатчик ВД-3

 

TYPE_VD5 = 30     

NPF Polyservice Vibration sensor VD-5

НПФ
Полисервис Вибродатчик ВД-5

 

TYPE_SD3 = 40     

NPF Polyservice Seismic sensor SD-3

НПФ
Полисервис Сейсмодатчик СД-3

 

TYPE_DD1 = 50     

NPF Polyservice Vibration sensor DD-1

НПФ
Полисервис Вибродатчик ДД-1

 

TYPE_KX6T3 = 60   

NPF Polyservice Input loop hub KX-6 with Topol-3 protocol

НПФ
Полисервис Концентратор входных шлейфов КХ-6 с протоколом Тополь-3

 

TYPE_EX6T3 = 70   

NPF Polyservice Output loop hub KX-6 with Topol-3 protocol

НПФ
Полисервис Концентратор выходных шлейфов EХ-6 с протоколом Тополь-3

 

Формат
описания входа:

 

UUID uuid

Уникальный
идентификатор входа

 

Integer type     

Тип
входа (см таблицу ниже)

 

String name

Имя входа

 

Integer address  

Адрес
(номер) входа

 

Integer holdValues          

Сколько
последних значений удерживать в оперативной памяти для регистрации событий и
обмена с внешними системами

 

Integer holdValuesPostEvent

Сколько
значений после события (тревоги или неисправности) необходимо записывать в
регистратор данных

     

Double nonFaultMin    

Минимально
допустимое входное значение. Если входное значение будет ниже указанного то
будет сформировано событие неисправности

 

Double nonFaultMax    

Максимально
допустимое входное значение. Если входное значение будет выше указанного то
будет сформировано событие неисправности

 

Double nonAlarmMin    

Минимальное
нормальное значение не формирующее тревогу. Если входное значение будет ниже
указанного то будет сформировано событие тревоги

 

Double nonAlarmMax    

Максимальное
нормальное значение не формирующее тревогу. Если входное значение будет выше
указанного то будет сформировано событие тревоги

 

Double nonPreAlarmMin

Максимальное
нормальное значение не формирующее предварительную тревогу. Если входное
значение будет выше указанного то будет сформировано событие тревоги

     

Double nonPreAlarmMax

Максимальное
нормальное значение не формирующее предварительную тревогу. Если входное
значение будет выше указанного то будет сформировано событие тревоги

     

Boolean alarm    

Вход
находится в тревога

 

Boolean prealarm

Вход
находится в предварительной тревоге

 

Long prealarmDelay

Задержка
перед взятием на охрану

 

Boolean prearm

Вход
находится в стадии постановки на охрану

 

Boolean arm

Вход
поставлен на охрану

 

Boolean fault

Истина
если у входа зарегистрирована неисправность, не имеющая отношения к

линиии
связи. Возникает в случае если прибор сам доложил о неисправности входа либо

текущие
значение входа находится за пределами нормы.

 

Boolean link

Связь со
входом установлена.

 

Типы входов (поле type):

 

TYPE_ALARM_LOOP = 10

Охранный шлейф

 

TYPE_FIRE_LOOP = 20

Пожарный шлейф

 

TYPE_FAULT_LOOP = 30     

Шлейф неисправности

 

TYPE_TAMPER_LOOP = 40    

Тампер

 

YPE_VIBRATION = 100

Уровень вибрации

 

TYPE_TEMPERATURE = 110   

Температура

 

TYPE_VOLTAGE_INPUT = 1000

Входное
напряжение питания

 

TYPE_VOLTAGE_OUTPUT = 1010

Выходное
напряжение питания

 

Формат
описания выхода:

UUID uuid

Уникальный
идентификатор выхода

 

Integer type

Тип
выхода

     

String name

Имя
выхода

     

Integer address

Адрес (номер) выхода

 

Boolean fault

Истина
если у выхода зарегистрирована неисправность, не имеющая отношения к

линиии
связи. Возникает в случае если прибор сам доложил о неисправности выхода либо

текущие
значение выхода находится за пределами нормы.

 

Boolean link

Связь с
выходом установлена.

 

Double value

Выходное
значение выхода. Для дискретных выходов 0=выключен, 1=включен

 

Double defaultValue = 0d;

Значение выхода по умолчанию. Для
дискретных выходов 0=выключен, 1=включен

 

Типы выходов (поле type):

 

TYPE_LOOP = 10;

Дискретный шлейф

 

TYPE_PWM = 20

Выход ШИМ (Задается дискретность)

 

TYPE_VOLTAGE = 30

Выход с регулируемым напряжением

 

TYPE_CURRENT = 40

Выход с регулируемым током потребления
(для 4..20)

 

TYPE_BUZZER = 50

Звуковой выход

 

TYPE_STROBE = 60

Стробирующий выход

 

Запрос одного прибора

/json/getdevice?deviceUuid=
ИЛИ /json/getdevice?deviceSerialNumber=

 

Возвращает один объект описывающий прибор с запрошенным уникальным
идентификатором или серийным номером.

 

Прямое управление выходами прибора

/json/setoutput?outputUuid=&value=

 

Позволяет напрямую задать значение для выхода с указанным уникальным
идентификатором. Для управления дискретными выходами (шлейфами EX, реле С2000СП1 и т.п.) value=0 выключит выход, value=1 – включит.

 

Запрос последних значений входа

/json/getinputvalues?inputUuid=  опционально lastEvent=

Возвращает массив объектов следующего содержания:

 

long date

Время
получения значения

 

double value

Значение

 

Если вход успел
получить значений больше чем holdValues,
то возвращаются последние holdValues
значений, если значений пока меньше, то возвращаются все полученные с момента
запуска системы значения

Если указана
переменная lastEvent то
передаются значения, полученные с момента указанной даты

 

Запрос событий

 

Запрос /json/getevents?fromDate= ИЛИ /json/getevents?fromUuid=

В
запросе используется одна из двух переменных на выбор:

fromDate указывает на значение даты, начиная с
которой необходимо получить события (для получения всех событий можно указать
0) либо

fromUuid указывает на уникальный идентификатор
события, начиная с которого необходимо получить события

Т.е.
если последнее событие, которое было прочитано имело метку времени 1519220475466 и уникальный идентификатор e4af3824-3ce8-4c9b-b84c-13bc9405a759, то последующие события можно получить
использовав либо запрос /json/ getevents?fromDate=1519220475466 либо
запрос /json/ getevents?fromUuid=e4af3824-3ce8-4c9b-b84c-13bc9405a759

В ответ на запрос событий, центральный
пульт возвращает набор объектов:

[

  {

    "uuid":
"d3ec15b0-5bed-4ff7-aa75-1fdd65a3f946",

    "date": 1519228102760,

    "code": 130,

    "device": "1f8fc675-45d5-4b6f-b4aa-3e9c2c68dbb9"

  },

  {

    "uuid":
"506c1028-795d-4d1d-bb88-85f6f0592112",

    "date": 1519228102764,

    "code": 130,

    "device":
"4e524c3c-c6a5-4939-879d-1143359580b1"

    "io":
"84f1d403-413a-4f1b-8e06-ef541552e0cf"

  }

]

 

uuid –
уникальный идентификатор события

date –
дата события

code –
код события

device –
уникальный идентификатор прибора (при наличии)

io –
уникальный идентификатор входа или выхода (при наличии)

zone –
уникальный идентификатор зоны (при наличии)

user –
уникальный идентификатор пользователя (при наличии)

 

 

Запрос событий (режим совместимости)

В
режиме совместимости центральный пульт возвращает упрощенное видоизмененное
описание события, в котором уникальные идентификаторы используются только для
маркировки событий. Данный режим можно использовать для упрощенного получения
основных событий (тревоги, постановка и снятие с охраны, неисправности, наличие
связи и т.п.) в случае интеграции с АПК сторонних производителей, когда
конфигурация системы осуществляется штатными средствами ИСО Тополь, а
отображение информации об основных событиях осуществляется средствами
стороннего АПК.

Запрос: /json/getcompatibleevents?fromDate= ИЛИ /json/getcompatibleevents?fromUuid=

В
запросе используется одна из двух переменных на выбор:

fromDate указывает на значение даты, начиная с
которой необходимо получить события (для получения всех событий можно указать
0) либо

fromUuid указывает на уникальный идентификатор
события, начиная с которого необходимо получить события

Т.е.
если последнее событие, которое было прочитано имело метку времени 1519220475466 и уникальный идентификатор e4af3824-3ce8-4c9b-b84c-13bc9405a759, то последующие события можно получить
использовав либо запрос /json/getcompatibleevents?fromDate=1519220475466 либо
запрос /json/getcompatibleevents?fromUuid=e4af3824-3ce8-4c9b-b84c-13bc9405a759

В
ответ на запрос событий, центральный пульт возвращает набор объектов:

[

 {

    "uuid":
"e4af3824-3ce8-4c9b-b84c-13bc9405a759",

    "date": 1519220475466,

    "description": "",

    "code": 100,

    "deviceIP":
"192.168.0.170",

    "deviceSerialPortName":
"1",

    "deviceSerialAddress": 3,

    "deviceInput": 0,

  },


{

    "uuid":
"05098153-9b31-4796-b74e-458ba7191cd8",

    "date": 1519220479865,

    "description": "",

    "code": 101,

    "deviceIP":
"192.168.0.170",

    "deviceSerialPortName":
"1",

    "deviceSerialAddress": 3,

    "deviceInput": 0,

  }

]

 

Где:

uuid – уникальный идентификатор события в системе

date – дата события

description – текстовое описание события при его наличии,
может не передаваться

code – код события (таблица с расшифровкой ниже)

deviceIP – IP адрес
линейного блока, к которому подключен прибор. Если прибор подключен напрямую к
центральному пульту то не передаётся

deviceSerialPortName – имя последовательного порта, к которому
подключен прибор. Если прибор подключен к линейному блоку то номер линии RS-485, если прибор подключен напрямую к
центральному пульту то имя последовательного порта (например «COM3» или «/dev/ttyUSB0»)

deviceSerialAddress – адрес прибора в линии RS-485

deviceInput – номер входа, по которому произошло событие,
номер входа зависит от типа прибора:

Для модулей
КХ-ЕХ:

0..5 = номер шлейфа

100 = тампер (например тревога вскрытия
корпуса)

1000 = уровень входящего напряжения (например
неисправность по слишком низкому уровню напряжения)

 

Для
вибродатчиков ВД, ДД или СД:

0 = уровень вибрации (например тревога по
вибрации)

100 = тампер (например тревога вскрытия
корпуса)

1000 = уровень входящего напряжения (например
неисправность по слишком низкому уровню напряжения)