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

Functions

crc16lm(buffer, len, offset): Расчёт CRC-16 CCITT

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, [ts]) ⇒ 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=>{...});// получение количества каналовletcount=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, [ts]) ⇒ `boolean`

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

Kind: instance method of LMClient
Access: public

Param	Type	Description
name	`string`	Имя канала
value	`*`	Новое значение канала
[ts]	`Date` \| `number` \| `string`	Метка времени: объект Date или количество мс от 01-01-1970 00:00:00

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');elseconsole.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`	ошибка

crc16lm(buffer, len, offset)

Расчёт CRC-16 CCITT

Kind: global function

Param	Type	Description
buffer	`Buffer`	Буфер данных
len	`Number`	Количество байт данных
offset	`Number`	Смещение первого элемента от начала буфера

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`	тип учетной записи "клиент"
hashAuth	`boolean`	авторизация с использованием MD5

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.

Name		Name	Last commit message	Last commit date
Latest commit History 70 Commits
doc		doc
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
lmclient.js		lmclient.js
package.json		package.json
testClient.js		testClient.js
testHashAuth.js		testHashAuth.js
testOpros.js		testOpros.js
testStress.js		testStress.js

Folders and files

Latest commit

History

Repository files navigation

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

Назначение

Установка

Classes

Functions

Typedefs

LMClient

new LMClient(options)

lmClient.loggedIn : boolean

lmClient.connected : boolean

lmClient.checkConnectInterval : number

lmClient.channelsMap : Map.<string, Channel2>

lmClient.connect()

lmClient.disconnect()

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

lmClient.delete(name) ⇒ boolean

lmClient.delete(name, attrId) ⇒ boolean

lmClient.setValue(name, value, [ts]) ⇒ boolean

lmClient.setQuality(name, quality) ⇒ boolean

lmClient.sendControl(name, value) ⇒ boolean

"connecting"

"connect"

"disconnect"

"loggedIn"

"checkConnection"

"timeSynchronize"

"control"

"channel"

"add"

"change"

"delete"

"count"

"error"

crc16lm(buffer, len, offset)

Channel2 : Object

Attribute : Object

Control : Object

ConnectOptions : Object

ChannelOptions : Object

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

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

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

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

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

lmClient.loggedIn : `boolean`

lmClient.connected : `boolean`

lmClient.checkConnectInterval : `number`

lmClient.channelsMap : `Map.<string, Channel2>`

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

lmClient.delete(name) ⇒ `boolean`

lmClient.delete(name, attrId) ⇒ `boolean`

lmClient.setValue(name, value, [ts]) ⇒ `boolean`

lmClient.setQuality(name, quality) ⇒ `boolean`

lmClient.sendControl(name, value) ⇒ `boolean`

Channel2 : `Object`

Attribute : `Object`

Control : `Object`

ConnectOptions : `Object`

ChannelOptions : `Object`