== API контроллера с squid в составе LTS ==

Протокол предназначен для связи squid с системами мониторинга и диспетчеризации (SCADA).

=== Дерево узлов и адресация ===

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

Для устройств StampLine адрес имеет вид:

{{{
sl:<канал шлюза StampLine>:<Адрес устройства StampLine 1-254>
}}}

Пример полного адреса устройства на канале 0 с адресом StampLine 16:

{{{
sl:0:16
}}}

Для головного устройства:

{{{
h:<адрес head-устройства 1-254>
}}}

Для шлюза (канала подключения) линии StampLine:

{{{
sl:<канал шлюза StampLine>
}}}

== Общая структура протокола и параметры подключения ==

Обмен данными осуществляется по протоколу tcp, подключение осуществляется со стороны сервера диспетчеризации и мониторинга (клиент) к головному контроллеру squid на порт 5700/tcp.

``` Обеспечение безопасности доступа (шифрование, изоляция, авторизация) осуществляется вышестоящей сетевой инфраструктурой.

``` Сервер диспетчеризации выступает в роли TCP-клиента при подключении, а контроллер в качестве TCP-сервера. Однако в описании протокола под сервером понимается именно сервер диспетчирезации.

Обмен осуществляется в рамках потокового xml протокола. 

После после успешного подключения к контроллеру сервер отправляет заголовок и базовый элемент xml-документа:

{{{
<stream t='head:0' v='1.0'>
}}}

В качестве получателя (stream/@t) указывается адрес головного устройства.
Ответ контроллера:

{{{
<stream f='head:0' v='1.0'>
}}}

При обнаружении проблем с потоком каждая сторона обязана закрыть соединение с посылкой тэга <error> и завершением тэга <stream>, после чего соединение может быть оборвано:

{{{
<error errcode="xmlerror"/>
</stream>
}}}


== Получение конфигурации дерева устройств ==


Для получения конфигурации дерева устройств сервер запрашивает конфигурацию тэгом <config>

{{{
<config/>
}}}

Ответ контроллера содержит конфигурацию дерева устройств:

{{{
<config>
  <n a="head:0" t="head">
    <n a="sl:0" t="gateway">
      <n a="sl:0:20" t="iopoint-lts" mv="1.0" p="transit_full"/>
      <n a="sl:1:20" t="iopoint-lts" mv="1.0" p="carousel"/>
    </n>
  </n>
<config>
}}}

Параметры (в терминах xpath):
 * n - [node] узел дерева конфигурации
 * n/@a - [address] полный адрес
 * n/@mv - [min version] минимальная версия устройства
 * n/@t - [type] тип устройства
 * n/@p - [profile] профиль устройства

== Получение статуса дерева устройств ==

Для получения текущего состояния дерева устройств клиент запрашивает статус тэгом <status>

{{{
<status/>
}}}

Ответ контроллера содержит детализацию дерева устройств с детализацией актуального статуса:

{{{
<status>
  <n a="head:0" o="t" v="1.0" s="auto">
    <n a="sl:0" o="t">
      <n a="sl:0:20" o="t" v="1.0" s="auto" ds="stop" fws="f" bws="f" ar="t" lp="0"/>
    </n>
    <n a="sl:1" o="t">
      <n a="sl:1:20" o="t" v="1.0" s="error" ds="fw" fws="t" bws="f" ar="f" lp="1">
        <e e="bw_jam"/>
      </n>
    </n>
  </n>
</status>
}}}


Параметры (в терминах xpath):
 * n - узел дерева конфигурации
 * n/@a - [address] полный адрес
 * n/@o - [online] доступность устройства (текущая): t = true, f = false
 * n/@v - [version] версия
 * n/@s - [status] статус устройства
 * n/@ds - [drive state] статус движения: stop - остановка, bw - назад, fw - вперед
 * n/@bws - [forward sensor] статус стартового датчика (в начале ленты): t = пересечён, f = открыт
 * n/@fws - [forward sensor] статус финишного датчика (в конце ленты): t = пересечён, f = открыт
 * n/@ar - [accept ready] готовность приёма багажа с предыдущей секции: t = готов принимать, f = не готов
 * n/@lp - [luggage present] наличие багажа на ленте