lmclient

1.0.0 • Public • Published

node npm npm module downloads license

Клиент 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

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, [attrId]) ⇒ boolean

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

Kind: instance method of LMClient
Access: public

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

Example

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

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
Todo

  • проверить работу
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 идентификатор атрибута

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 ООО "МНПП Сатурн"

Readme

Keywords

Package Sidebar

Install

npm i lmclient

Weekly Downloads

0

Version

1.0.0

License

MIT

Unpacked Size

145 kB

Total Files

8

Last publish

Collaborators

  • crossrw