Клиент SCADA системы LanMon для Node.js

Назначение

Библиотека предназначена для организации подключения к серверу SCADA системы LanMon из программ написанных на языке js.

Для выполнения необходим Node.js версии 6.17.0 или более новый.

Более подробное описание SCADA системы LanMon можно получить на сайте МНПП "Сатурн".

Основные функции библиотеки:

• подключение к серверу системы
• поддержка типов учетной записи "опрос" и "клиент"
• автоматическое восстанвление подключения при обрывах или ошибках
• автоматическая проверка канала связи с сервером
• создание каналов со всеми поддерживаемыми сервером типами данных, включая массивы
• поддержка всех типов атрибутов каналов
• поддержка установки значения свойства quality
• фильтрация значений каналов с типом VT_R4 и VT_R8 с использованием атрибута ATTR_PERCENTDB
• поддержка передачи и получения команд управления
• автоматическое преобразование кодировки значений каналов типа VT_STRING из кодировки CP1251 в UTF-8 и обратно
• преообразование типа данных VT_DATE в объект js Date() и обратно с использованием информации о часовом поясе сервера

Библиотека поддерживает работу с сервером LanMon начиная с его версии 4.12.

Библиотека не содержит внешних зависимостей.

Установка

$ npm install lmclient

Classes

LMClient

Класс клиента сервера LM

Typedefs

Channel2 : Object

Канал сервера

Attribute : Object

Атрибут канала

Control : Object

Структура данных управления каналом

ConnectOptions : Object

Параметры подключения к серверу

ChannelOptions : Object

Параметры задаваемые при создании канала

LMClient

Класс клиента сервера LM

Kind: global class
Emits: connecting, connect, disconnect, loggedIn, checkConnection, timeSynchronize, control, channel, add, change, delete, count, error

• LMClient
  • new LMClient(options)
  • .loggedIn : boolean
  • .connected : boolean
  • .checkConnectInterval : number
  • .channelsMap : Map.<string, Channel2>
  • .connect()
  • .disconnect()
  • .add(name, type, writeEnable, options) ⇒ boolean
  • .delete(name) ⇒ boolean
  • .delete(name, attrId) ⇒ boolean
  • .setValue(name, value) ⇒ boolean
  • .setQuality(name, quality) ⇒ boolean
  • .sendControl(name, value) ⇒ boolean
  • "connecting"
  • "connect"
  • "disconnect"
  • "loggedIn"
  • "checkConnection"
  • "timeSynchronize"
  • "control"
  • "channel"
  • "add"
  • "change"
  • "delete"
  • "count"
  • "error"

new LMClient(options)

Конструктор класса. Создает новый экземпляр класса подключения к серверу. В параметрах конструктора указываются настройки используемые при подключении к серверу.

Param	Type	Description
options	ConnectOptions	Параметры подключения к серверу

lmClient.loggedIn : boolean

Текущее состояние регистрации на сервере. Значение true соответствует тому, что клиент успешно подключен и зарегестрирован на сервере.

Kind: instance property of LMClient
Access: public
Read only: true

lmClient.connected : boolean

Текущее состояние подключения к серверу. Значение true соответствует тому, что клиент установил соединение с сервером. Состояние регистрации можно проконтролировать через свойство loggedIn.

Kind: instance property of LMClient
Access: public
Read only: true

lmClient.checkConnectInterval : number

Интервал проверки связи с сервером в мс. Значение по умолчанию 480000 мс (8 минут). Не рекомендуется устанавливать значение более 600000 мс (10 минут).

Kind: instance property of LMClient
Access: public

lmClient.channelsMap : Map.<string, Channel2>

Список каналов. Элементы списка является экземплярами класса Channel2, ключом в списке являются имена каналов. Вы не должны напрямую изменять элементы списка! Для изменения используйте вызовы методов класса.

Kind: instance property of LMClient
Access: public
Read only: true
Example

// получение канала по имени
channel = client.channelsMap.get('my_channel_name');
// проверка на наличие канала
if(client.channelsMap.has('my_channel_name')) {...}; else {...};
// перебор всех каналов
client.channelsMap.forEach(channel => {...});
// получение количества каналов
let count = client.channelsMap.size;

lmClient.connect()

Подключение и регистрация на сервере LM. Метод начинает процедуру подключения и регистрации к серверу системы LanMon. При подключении используются параметры указанные при создании класса. Если в параметрах указано значение reconnect: true, то соединение будет автоматически восстанавливаться в случаях обрыва связи или ошибок.

Kind: instance method of LMClient
Access: public

lmClient.disconnect()

Отключиться от сервера. Метод разрывает соединение с сервером если оно было ранее установлено вызовом метода connect().

Kind: instance method of LMClient
Access: public

lmClient.add(name, type, writeEnable, options) ⇒ boolean

Добавление нового канала. Метод добавляет новый канал для регистрации и передачи данных на сервер. Метод используется при подключении с типом учетной записи "опрос". Метод может быть вызван при любом состоянии подключения к сервреру. Метод возвращает значение false если канал с указанным именем уже существует или если указан некорректный тип данных.

Kind: instance method of LMClient
Access: public

Param	Type	Description
name	string	Имя канала
type	number	Тип канала
writeEnable	boolean	Разрешение записи значений
options	ChannelOptions	Параметры канала

lmClient.delete(name) ⇒ boolean

Удаление канала. Метод выполняет передачу на сервер запроса на удаление канала с указанным именем. При вызове метода клиент должен быть подключен и зарегистрирован на сервере. При наличии соотвествующих прав доступа клиента, сервер выполняет удаление соответствующей сущности и рассылет уведомления всем подключенным к нему клиентам, в том числе и вам. При наличии прав доступа, через некоторое время после вызова метода, клиент получит уведомление "delete". Метод используется при подключении с типом учетной записи "клиент". При отсутствии указанного канала, неверном типе учетной записи или отсутствии регистрации на сервере метод возвращает значение false.

Kind: instance method of LMClient
Access: public

Param	Type	Description
name	string	Имя канала

Example

// удаление канала 'myChannel'
client.delete('myChannel');

lmClient.delete(name, attrId) ⇒ boolean

Удаление атрибута канала. Метод выполняет передачу на сервер запроса на удаление атрибута с идентификатором attrId у канала с именем name. При вызове метода клиент должен быть подключен и зарегистрирован на сервере. При наличии соотвествующих прав доступа клиента, сервер выполняет удаление соответствующей сущности и рассылет уведомления всем подключенным к нему клиентам, в том числе и вам. При наличии прав доступа, через некоторое время после вызова метода, клиент получит уведомление "delete". Метод используется при подключении с типом учетной записи "клиент". При отсутствии указанного канала, неверном типе учетной записи или отсутствии регистрации на сервере метод возвращает значение false.

Kind: instance method of LMClient
Access: public

Param	Type	Description
name	string	Имя канала
attrId	number	Идентификатор атрибута

Example

// удаление атрибута с идентификатором 100 к канала 'myChannel'
client.delete('myChannel', 100);

lmClient.setValue(name, value) ⇒ boolean

Установка значения канала. Метод устанавливает значение для ранее созданного канала. Тип и значение параметра value должен соответствовать типу канала указанному при его создании. Установленное значение канала будет передано на сервер. Кроме того, метод устанавливает свойство канала quality (качество) в значение stOk. Метод используется при подключении с типом учетной записи "опрос". Метод может быть вызван при любом состоянии подключения к сервреру. Метод возвращает значение false если канал с указанным именем не найден или указан некорректный тип учетной записи.

Kind: instance method of LMClient
Access: public

Param	Type	Description
name	string	Имя канала
value	*	Новое значение канала

lmClient.setQuality(name, quality) ⇒ boolean

Установка качества канала. Метод устанавливает значение свойства качество для ранее созданного канала. Метод используется при подключении с типом учетной записи "опрос". Значение качества канала stOk автоматически устанавливается при установке значения канала методом setValue(name, value) и отдельно устанавливать его не требуется. Метод может быть вызван при любом состоянии подключения к сервреру. Метод возвращает значение false если канал с указанным именем не найден, указано некорректное значение качества или тип учетной записи.

Kind: instance method of LMClient
Access: public

Param	Type	Description
name	string	Имя канала
quality	number	Новое значение качества

lmClient.sendControl(name, value) ⇒ boolean

Формирование команды управления каналом. Метод используется при подключении с типом учетной записи "клиент". Для выполнения управления каналом должны выполняться следующие условия: клиент должен быть подключен и зарегистрирован на сервере, канал должен быть существующим, канал должен быть создан другим клиентом (опросчиком), у канала должны быть установлены признаки активности и разрешения записи значений, тип значения value должен быть совместим с типом канала. При выполнении перечисленных выше условий метод возвращает true, иначе - false. Метод не устанавливает значение канала, полученную команду управления сервер пересылает клиенту типа "опрос", который сформировал этот канал.

Kind: instance method of LMClient
Access: public

Param	Type	Description
name	string	Имя канала
value	*	Значение команды управления

"connecting"

Событие формируется при начале подключения к серверу.

Kind: event emitted by LMClient
Properties

Name	Type	Description
host	string	адрес сервера к которому происходит подключение
port	number	номер TCP-порта сервера

"connect"

Событие формируется когда соединение с сервером установлено.

Kind: event emitted by LMClient

"disconnect"

Событие формируется когда соединение с сервером разорвано.

Kind: event emitted by LMClient
Properties

Name	Type	Description
err	boolean	признак того, что соединение разорвано в результате ошибки

"loggedIn"

Событие формируется когда клиент успешно зарегистрировался на сервере.

Kind: event emitted by LMClient
Properties

Name	Type	Description
serverId	number	идентификатор клиента на сервере
version	string	версия сервера в формате "hi.lo"

"checkConnection"

Событие формируется при успешном выполнении проверки связи с сервером.

Kind: event emitted by LMClient
Properties

Name	Type	Description
delay	number	задержка в миллисекундах при ответе сервера на команду проверки связи

"timeSynchronize"

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

Kind: event emitted by LMClient
Properties

Name	Type	Description
time	Date	значение времени полученное от сервера

"control"

Событие формируется при получении от сервера команды записи в канал управления. Для подтверждения получения и обработки этого события необходимо установить полученное значение канала вызовом setValue(name, value).

Kind: event emitted by LMClient
Properties

Name	Type	Description
control	Control	полученная команда управления каналом

Example

client.on('control', function(control){
  console.log('receive control "' + control.name + '" value="' + control.value + '"');
  client.setValue(control.name, control.value); // подтверждаем прием
});

"channel"

Событие формируется при получении клиентом от сервера нового значения канала. При отключении от сервера событие формируется для всех ранее полученных от него каналов с установленным свойством quality в значение stOff. Событие используется при работе в режиме учетной записи "клиент".

Kind: event emitted by LMClient
Properties

Name	Type	Description
channel	Channel2	объект состояние канала

"add"

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

Kind: event emitted by LMClient
Properties

Name	Type	Description
channel	Channel2	новый канал

"change"

Уведомление о изменении настроек (свойств или атрибутов) канала. Измениться могут перечень и значения атрибутов, значения свойств active, writeEnable и saveServer. Изменение значения самого канала не приводит к появлению данного уведомления. Уведомление формируется только для учетных записей типа "клиент".

Kind: event emitted by LMClient
Properties

Name	Type	Description
channel	Channel2	измененный канал

"delete"

Уведомление об удалении канала с именем "name" или его атрибута с идентификатором "attrId". Если аргумент "attrId" не определен, то событие сообщает об удалении канала "name". В противном случае событие сообщает об удалении атрибута "attrId". Уведомление формируется только для учетных записей типа "клиент".

Kind: event emitted by LMClient
Properties

Name	Type	Description
name	string	имя канала
[attrId]	number | undefined	идентификатор атрибута

Example

client.on('delete', function(name, attrId){
  if(attrId === undefined) console.log('channel "' + name + '" was removed');
  else console.log('attribute ' + attrId + ' was removed from channel "' + name + '" deleted');
});

"count"

Событие формируется для учетных записей типа "клиент" после подключения к серверу и запроса списка имеющихся каналов.

Kind: event emitted by LMClient
Properties

Name	Type	Description
count	number	количество каналов

"error"

Событие формируется при возникновении ошибки. Программа должна содержать обработчик этого события.

Kind: event emitted by LMClient
Properties

Name	Type	Description
error	Error	ошибка

Channel2 : Object

Канал сервера

Kind: global typedef
Properties

Name	Type	Description
name	string	наименование
number	number	числовой идентификатор на сервере
type	number	тип
value	*	значение
quality	number	качество
dt	Date	время изменения
needRegister	boolean	необходимо зарегистрировать
needSend	boolean	необходимо передать
active	boolean	активен
writeEnable	boolean	разрешение записи
saveServer	boolean	сохранять значение на сервере при откоючении источника
attributes	Object.<number, Attribute>	массив атрибутов
[creator]	number	идентификатор создателя канала
[owner]	number	источник значения для канала
[groups]	number	принадлежность группам каналов

Attribute : Object

Атрибут канала

Kind: global typedef
Properties

Name	Type	Description
id	number	идентификатор
value	*	значение
dt	Date	дата изменения
fromServer	boolean	получен от сервера

Control : Object

Структура данных управления каналом

Kind: global typedef
Properties

Name	Type	Description
name	string	имя канала для которого пришла команда управления
value	*	полученное значение команды
dt	Date	метка времени

ConnectOptions : Object

Параметры подключения к серверу

Kind: global typedef
Properties

Name	Type	Description
host	string	адрес сервера
port	number	номер TCP порта
login	string	логин
password	string	пароль
reconnect	boolean	автоматически переподключаться при ошибках и разрывах связи
opros	boolean	тип учетной записи "опрос"
client	boolean	тип учетной записи "клиент"

ChannelOptions : Object

Параметры задаваемые при создании канала

Kind: global typedef
Properties

Name	Type	Description
[units]	string	единицы измерения
[comment]	string	текстовое описание
[signification]	number	назначение
[saveValue]	boolean	сохранять значение на сервере при отключении опросчика
[enum]	Array.<string>	массив строк, соответствующих значению канала
[bounds]	Array.<number>	массив из двух элементов [нижняя граница, верхняя граница]
[percentDeadband]	number	величина "мертвой зоны" изменения значения канала в процентах

Примеры использования

Примеры испоьзования библиотеки для типов учетной записи "опрос" и "клиент" приведены в файлах testOpros.js и testClient.js соответственно.

Существующие ограничения

• Поддержка только каналов второго типа
• Не реализована возможность изменения значений атрибутов каналов

Текущий статус

Весь заявленный функционал протестирован на больших нагрузках и работает. Дальнейшие планы:

• оптимизация затрат памяти и загрузки процессора
• добавление не реализованных функций
• добавление поддержки каналов первого типа (далекие планы)

Обратная связь

Замечания и предложения отправляйте на адрес lanmon@mnppsaturn.ru или непосредственно в Issues/Pull requests.

---

© 2019 ООО "МНПП Сатурн"