Клиент 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
в объект jsDate()
и обратно с использованием информации о часовом поясе сервера
Библиотека поддерживает работу с сервером 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, [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 |
Параметры подключения к серверу |
boolean
lmClient.loggedIn : Текущее состояние регистрации на сервере. Значение true соответствует тому, что клиент успешно подключен и зарегестрирован на сервере.
Kind: instance property of LMClient
Access: public
Read only: true
boolean
lmClient.connected : Текущее состояние подключения к серверу. Значение true соответствует тому, что клиент установил соединение с сервером. Состояние регистрации можно проконтролировать через свойство loggedIn.
Kind: instance property of LMClient
Access: public
Read only: true
number
lmClient.checkConnectInterval : Интервал проверки связи с сервером в мс. Значение по умолчанию 480000 мс (8 минут). Не рекомендуется устанавливать значение более 600000 мс (10 минут).
Kind: instance property of LMClient
Access: public
Map.<string, Channel2>
lmClient.channelsMap : Список каналов. Элементы списка является экземплярами класса Channel2, ключом в списке являются имена каналов. Вы не должны напрямую изменять элементы списка! Для изменения используйте вызовы методов класса.
Kind: instance property of LMClient
Access: public
Read only: true
Example
// получение канала по имениchannel = clientchannelsMap;// проверка на наличие каналаifclientchannelsMap ...; else ...;// перебор всех каналовclientchannelsMap;// получение количества каналовlet count = clientchannelsMapsize;
lmClient.connect()
Подключение и регистрация на сервере LM. Метод начинает процедуру подключения и регистрации к серверу системы LanMon. При подключении используются параметры указанные при создании класса. Если в параметрах указано значение reconnect: true, то соединение будет автоматически восстанавливаться в случаях обрыва связи или ошибок.
Kind: instance method of LMClient
Access: public
lmClient.disconnect()
Отключиться от сервера. Метод разрывает соединение с сервером если оно было ранее установлено вызовом метода connect().
Kind: instance method of LMClient
Access: public
boolean
lmClient.add(name, type, writeEnable, options) ⇒ Добавление нового канала. Метод добавляет новый канал для регистрации и передачи данных на сервер. Метод используется при подключении с типом учетной записи "опрос". Метод может быть вызван при любом состоянии подключения к сервреру. Метод возвращает значение false если канал с указанным именем уже существует или если указан некорректный тип данных.
Kind: instance method of LMClient
Access: public
Param | Type | Description |
---|---|---|
name | string |
Имя канала |
type | number |
Тип канала |
writeEnable | boolean |
Разрешение записи значений |
options | ChannelOptions |
Параметры канала |
boolean
lmClient.delete(name, [attrId]) ⇒ Удаление канала или атрибута канала. Метод выполняет передачу на сервер запроса на удаление канала или отдельного атрибута канала. При вызове метода клиент должен быть подключен и зарегистрирован на сервере. При наличии соотвествующих прав доступа клиента, сервер выполняет удаление соответствующей сущности и рассылет уведомления всем подключенным к нему клиентам, в том числе и вам. При удачном удалении через некоторое время после вызова метода клиент получит уведомление "delete". Метод используется при подключении с типом учетной записи "клиент".
Kind: instance method of LMClient
Access: public
Param | Type | Description |
---|---|---|
name | string |
имя канала |
[attrId] | number |
идентификатор атрибута |
Example
// удаление атрибута с идентификатором 100 к канала 'myChannel'client;// удпление канала 'myChannel'client;
boolean
lmClient.setValue(name, value) ⇒ Установка значения канала. Метод устанавливает значение для ранее созданного канала. Тип и значение параметра value должен соответствовать типу канала указанному при его создании. Установленное значение канала будет передано на сервер. Кроме того, метод устанавливает свойство канала quality (качество) в значение stOk. Метод используется при подключении с типом учетной записи "опрос". Метод может быть вызван при любом состоянии подключения к сервреру. Метод возвращает значение false если канал с указанным именем не найден или указан некорректный тип учетной записи.
Kind: instance method of LMClient
Access: public
Param | Type | Description |
---|---|---|
name | string |
Имя канала |
value | * |
Новое значение канала |
boolean
lmClient.setQuality(name, quality) ⇒ Установка качества канала. Метод устанавливает значение свойства качество для ранее созданного канала. Метод используется при подключении с типом учетной записи "опрос". Значение качества канала stOk автоматически устанавливается при установке значения канала методом setValue(name, value) и отдельно устанавливать его не требуется. Метод может быть вызван при любом состоянии подключения к сервреру. Метод возвращает значение false если канал с указанным именем не найден, указано некорректное значение качества или тип учетной записи.
Kind: instance method of LMClient
Access: public
Param | Type | Description |
---|---|---|
name | string |
Имя канала |
quality | number |
Новое значение качества |
boolean
lmClient.sendControl(name, value) ⇒ Формирование команды управления каналом. Метод используется при подключении с типом учетной записи "клиент". Для выполнения управления каналом должны выполняться следующие условия: клиент должен быть подключен и зарегистрирован на сервере, канал должен быть существующим, канал должен быть создан другим клиентом (опросчиком), у канала должны быть установлены признаки активности и разрешения записи значений, тип значения 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;
"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;
"count"
Событие формируется для учетных записей типа "клиент" после подключения к серверу и запроса списка имеющихся каналов.
Kind: event emitted by LMClient
Properties
Name | Type | Description |
---|---|---|
count | number |
количество каналов |
"error"
Событие формируется при возникновении ошибки. Программа должна содержать обработчик этого события.
Kind: event emitted by LMClient
Properties
Name | Type | Description |
---|---|---|
error | Error |
ошибка |
Object
Channel2 : Канал сервера
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 |
принадлежность группам каналов |
Object
Attribute : Атрибут канала
Kind: global typedef
Properties
Name | Type | Description |
---|---|---|
id | number |
идентификатор |
value | * |
значение |
dt | Date |
дата изменения |
fromServer | boolean |
получен от сервера |
Object
Control : Структура данных управления каналом
Kind: global typedef
Properties
Name | Type | Description |
---|---|---|
name | string |
имя канала для которого пришла команда управления |
value | * |
полученное значение команды |
dt | Date |
метка времени |
Object
ConnectOptions : Параметры подключения к серверу
Kind: global typedef
Properties
Name | Type | Description |
---|---|---|
host | string |
адрес сервера |
port | number |
номер TCP порта |
login | string |
логин |
password | string |
пароль |
reconnect | boolean |
автоматически переподключаться при ошибках и разрывах связи |
opros | boolean |
тип учетной записи "опрос" |
client | boolean |
тип учетной записи "клиент" |
Object
ChannelOptions : Параметры задаваемые при создании канала
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 ООО "МНПП Сатурн"