Nerds Publishing Monstrosities

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

    Keywords

    Install

    npm i lmclient

    DownloadsWeekly Downloads

    4

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    145 kB

    Total Files

    8

    Last publish

    Collaborators

    • crossrw