OpenSCADA

Документація/Як зробити/Створити модуль

This page is a translated version of the page Documents/How to/Create module and the translation is 100% complete.
English • ‎mRussian • ‎Українська
Constr.png Generic revision and updating

Цей керівний документ покликано допомогти у створені модулів для системи OpenSCADA. Створення модуля може знадобитися у випадку бажання додати підтримку нового джерела даних або іншого розширення до системи OpenSCADA. Оскільки OpenSCADA є гранично модульною то всі інтерфейси взаємодії з зовнішнім середовищем здійснюється за посередництвом розширення спеціалізованими модулями типів:

At.png Для створення модулів OpenSCADA потрібні знання у програмуванні на мові C/C++, складальної системи AutoTools, а також базові знання у ОС Linux та використовуваного дистрибутиву Linux.

Для розміщення розробленого модуля у основному репозиторії дерева вихідних текстів OpenSCADA Ви маєте виконати наступне та слідувати наведеним вимогам:

Contents

1 Створення нового модуля

Модулі в OpenSCADA представляють із себе поділювані бібліотеки, які підключаються до ядра OpenSCADA динамічно, під час роботи програми. Багато модулів у процесі роботи можуть бути відключені, підключені та оновлені із менеджера модулів. Модулі також можуть бути включені у ядро OpenSCADA під час збірки, за посередництвом аргументу --enable-{ModName}=incl до скрипту конфігурації "configure", про що можна дізнатися із посібника по збірці. Модулі OpenSCADA можуть бути семи типів, згідно присутнім модульним підсистемам. Наразі модулі до системи OpenSCADA пишуться на мові програмування "C++", хоча у подальшому можлива поява біндінгів на інші мови.

Для полегшення створення нових модулів у дереві вихідних текстів, у гілці кожної підсистеми, передбачено теку "=Tmpl=" з шаблоном модуля відповідної підсистеми. Розробник нового модуля може взяти цю теку та скопіювати її з ім'ям свого нового модуля. Передбачено можливість створення модулів у дереві вихідних текстів проекту OpenSCADA або як незалежного проекту зовнішнього модуля до OpenSCADA.

1.1 Створення у дереві вихідних текстів проекту OpenSCADA

Створювати нові модулі у дереві вихідних текстів проекту OpenSCADA має сенс у випадку подальших планів передачі нового модуля проекту OpenSCADA. Оскільки модуль не має суперечити духу відкритого проекту та ліцензії на основі якої розробляється та розповсюджується OpenSCADA то ліцензією нового модуля вочевидь має бути одна із вільних ліцензій.

В цілому процедура створення нового модуля з включенням до дерева вихідних текстів, на основі шаблону, є простішою за процедуру для зовнішнього модуля та включає в себе кроки:

1. Отримання дерева вихідних текстів проекту OpenSCADA.
Для робочої гілки:
$ svn co svn://oscada.org/trunk/OpenSCADA
Для гілки стабільного релізу (небажано оскільки до стабільних LTS релізів приймаються тільки виправлення та ця інструкція потребує версії 0.9 або більше):
$ svn co svn://oscada.org/tags/openscada_0.8.0
2. Копіювання теки шаблону з ім'ям нового модуля "NewMod" (наприклад, для підсистеми "БД"):
$ cd OpenSCADA/src/moduls/bd
$ cp -r =Tmpl= NewMod; cd NewMod
$ rm -f configure.ac
3. Редагування файлу "module.cpp".
Змінити імена функцій включення модуля згідно імені нового модуля:
"TModule::SAt bd_Tmpl_module( int n_mod )" — bd_NewMod_module
"TModule *bd_Tmpl_attach( const TModule::SAt &AtMod, const string &source )" — bd_NewMod_attach
Інформація про модуль у файлі "module.cpp", а саме ділянка:
//************************************************
//* Modul info!                                  *
#define MOD_ID          "NewMod"
#define MOD_NAME        _("DB NewMod")
#define MOD_TYPE        SDB_ID
#define VER_TYPE        SDB_VER
#define MOD_VER         "0.0.1"
#define AUTHORS         _("MyName MyFamily")
#define DESCRIPTION     _("BD NewMod description.")
#define MOD_LICENSE     "GPL2"
4. Редагування конфігурації збірки модуля у файлі "Makefile.am", до такого вигляду:
EXTRA_DIST = *.h po/*

if NewModIncl
noinst_LTLIBRARIES = db_NewMod.la
db_NewMod_la_CXXFLAGS = -DMOD_INCL -fpic
db_NewMod_la_LIBTOOLFLAGS = --tag=disable-shared
db_NewMod_la_LDFLAGS = -module
else
oscd_modul_LTLIBRARIES = db_NewMod.la
db_NewMod_la_CXXFLAGS =
db_NewMod_la_LIBTOOLFLAGS = --tag=disable-static
db_NewMod_la_LDFLAGS = -module -avoid-version $(top_builddir)/src/liboscada.la
endif

db_NewMod_la_CXXFLAGS += $(NewMod_CFLAGS)
db_NewMod_la_LDFLAGS += $(NewMod_LDLAGS)
db_NewMod_la_SOURCES = module.cpp

I18N_mod = $(oscd_modulpref)NewMod
include ../../../../I18N.mk
5. Додання запису нового модуля в кінець секції підсистеми (у нас "> DB modules"), конфігураційного файлу (OpenSCADA/configure.ac) складальної системи OpenSCADA:
AX_MOD_DB_EN(NewMod,[disable or enable[=incl] build module DB.NewMod],disable,incl,
[
    # Код перевірки зовнішніх бібліотек модуля
])
6. Тепер новий модуль можна скласти у складі OpenSCADA, після переформування складальної системи:
$ autoreconf -if
$ ./configure --enable-NewMod
$ make
7. Публікація. Формування патча з вашим модулем та відправка його розробникам OpenSCADA:
$ cd OpenSCADA; make distclean; rm -f src/moduls/bd/NewMod/Makefile.in
$ svn add src/moduls/bd/NewMod
$ svn diff > NewMod.patch

1.2 Створення зовнішнього модуля до OpenSCADA

Створення зовнішнього модуля до OpenSCADA може мати сенс у випадку розробки інтерфейсу інтеграції з комерційними системами, які вимагають закриття коду взаємодії, а також у випадку інших реалізацій комерційних інтерфейсів при яких модуль до OpenSCADA отримує статус окремого проекту, розповсюджується та підтримується незалежно, часто у вигляді бінарних збірок під конкретну платформу та версію OpenSCADA. Ліцензія таких модулів відповідно може бути будь-якою.

Процедура створення нового зовнішнього модуля, на основі шаблону, багато в чому схожа на попередню процедуру та включає в себе кроки:

1. Отримання вихідних текстів проекту OpenSCADA. Для зовнішнього модуля у якості джерела шаблону можна використати будь-які файли OpenSCADA версії більш 0.9 оскільки із них потрібно скопіювати тільки теку "=Tmpl=" та декілька файлів для збірки.
2. Копіювання теки шаблону з ім'ям нового модуля "NewMod" (наприклад, для підсистеми "БД"). Створення та копіювання потрібних файлів для зовнішнього модуля. В подальшому інформаційні файли проекту "COPYING", "NEWS", "README", "AUTHORS" та "ChangeLog" потрібно заповнити згідно сутності нового модуля.
$ cp -r OpenSCADA/src/moduls/bd/=Tmpl= NewMod
$ touch NewMod/{NEWS,README,AUTHORS,ChangeLog}
$ cp OpenSCADA/I18N.mk NewMod/
3. Редагування інформації про модуль у файлі "module.cpp", аналогічно цьому пункту попереднього розділу.
4. Редагування конфігурації збірки модуля у файлі "Makefile.am", аналогічно цьому пункту попереднього розділу, окрім:
# Замість "db_NewMod_la_LDFLAGS = -module -avoid-version $(top_builddir)/src/liboscada.la"
db_NewMod_la_LDFLAGS = -module -avoid-version
# Замість "include ../../../../I18N.mk"
include I18N.mk
5. Редагування файлу конфігурації складальної системи "configure.ac":
"AC_INIT([DB.Tmpl],[0.0.1],[my@email.org])" — інформація про модуль: ім'я, версія та email проекту.
"AM_CONDITIONAL([TmplIncl],[test])" — AM_CONDITIONAL([NewModIncl],[test])
6. Встановлення пакету розробки OpenSCADA. У зв'язку з ти що модуль зовнішній та вихідні файли OpenSCADA потрібні тільки на першому етапі створення модуля то потрібно встановити пакет розробки OpenSCADA (openscada-devel), який містить заголовні файли та бібліотеки.
7. Тепер новий модуль можна скласти, після формування складальної системи:
$ autoreconf -if
$ ./configure
$ make

2 API модуля

API системи OpenSCADA для розробника OpenSCADA та модулів до неї вичерпно, у формальній формі, описано у відповідному документі API системи OpenSCADA, який має бути завжди під рукою при розробці для OpenSCADA. В цьому ж документі ухил зроблено на детальне роз'яснення основних моментів модульного API.

Загальним для всіх модулів є наслідування кореневого об'єкта-класу модуля від класу TModule, за посередництвом класу модульної підсистеми, а це означає що є загальна частина інтерфейсу модуля який розглянемо нижче. В цілому, для представлення собі архітектури модулів у контексті загальної архітектури OpenSCADA, наполегливо рекомендується мати перед очима загальну діаграму класів OpenSCADA

Точкою входу будь-якого модуля є функції:

Для зручності прямої адресації до кореневого об'єкта модуля із будь-якого об'єкта модуля нижче за ієрархією рекомендується визначити глобальну змінну "mod", у області імен модуля, з ініціалізацією її у конструкторі кореневого об'єкта модуля. Також, для прозорого перекладу текстових повідомлень модуля, рекомендується визначити шаблон функції виклику перекладу повідомлень модуля "_({Повідомлення})", як: 

#undef _
#define _(mess) mod->I18N(mess)

У конструкторі кореневого об'єкту модуля, успадкованого від TModule, потрібно встановити основну інформацію модуля викликом функції void modInfoMainSet({Ім'я}, {Тип}, {Версія}, {Автори}, {Опис}, {Ліцензія}, {Джерело}), після ініціалізації швидкого посилання "mod" на кореневий об'єкт цього модуля.

А також ініціювати оточення модуля за допомогою функцій:

Подальше отримання файлу шаблону перекладів "po/NewMod.pot" текстових повідомлень "_({Повідомлення})", а також обновлення-актуалізація файлів вже існуючих перекладів "po/{en|ru|uk|de|...}.po" здійснюється командою у теці модуля "$ make messages".

З метою загального управління модулем у класі TModule передбачено низку віртуальних функцій, які можуть бути визначені у кореневому об'єкту модуля з реалізацією потрібної реакції на команди ядра OpenSCADA до модуля:

Всі інтерфейсні об'єкти модулів успадковують клас вузла TCntrNode, який надає механізм інтерфейсу управління, однієї із задач якого є надання інтерфейсу конфігурації об'єкту в будь-якому конфігураторі OpenSCADA. Для вирішення задач нового модуля може знадобитися розширення параметрів конфігурації, що робиться у віртуальній функції void cntrCmdProc( XMLNode *opt );. Вміст цієї функції, який додає властивість, у найпростішому випадку має вигляд: 

void MBD::cntrCmdProc( XMLNode *opt )
{
    //> Get page info
    if(opt->name() == "info")
    {
        TBD::cntrCmdProc(opt);
        ctrMkNode("comm",opt,-1,"/prm/st/end_tr",_("Close opened transaction"),RWRWRW,"root",SDB_ID);
        return;
    }
    //> Process command to page
    string a_path = opt->attr("path");
    if(a_path == "/prm/st/end_tr" && ctrChkNode(opt,"set",RWRWRW,"root",SDB_ID,SEC_WR)) transCommit();
    else TBD::cntrCmdProc(opt);
}

Перша половина цієї функції обслуговує інформаційні запити "info", з переліком та властивостями полів конфігурації. Друга половина обслуговує всі інші команди, на отримання, встановлення значення та інше. Виклик TBD::cntrCmdProc(opt); використовується для отримання успадкованого інтерфейсу. Детальніше про призначення використаних функцій дивіться у інтерфейсі управління, а також у вихідних текстах існуючих модулей.

Крім функції інтерфейсу управління об'єкт TCntrNode надає уніфіковані механізми контролю за модифікацією конфігурації об'єкта, завантаження та збереження конфігурації у сховищі. Для здійснення встановлення прапорця модифікації даних об'єкта можна використовувати функції modif() та modifG(), а специфічні для модуля дії по завантаженню та збереженню можна розташовувати у віртуальні функції:

Типово, робота з конфігурацією здійснюється за посередництвом об'єкта TConfig, яких містить набір вказаних властивостей. Для прямого відображення властивостей об'єкта модуля він успадковується від TConfig, а нові властивості додаються командою: 

fldAdd(new TFld("PRM_BD",_("Parameters cache table"),TFld::String,TFld::NoFlag,"30",""));

Завантаження та збереження властивостей, вказаних у об'єкті TConfig, із/у сховище здійснюється командами: 

SYS->db().at().dataGet(fullDB(),owner().nodePath()+"DAQ",*this);
SYS->db().at().dataSet(fullDB(),owner().nodePath()+"DAQ",*this);

Де:

Для розміщення налагоджувальних повідомлень, у контексті загальної концепції налаштувань, потрібно використовувати функцію mess_debug() з умовою виклику по ділянці вихідного тексту програми: 

#ifdef OSC_DEBUG
  mess_debug(...);
#endif

2.1 Модуль підсистеми "Бази Даних (БД)"

Модуль даного типа призначено для інтеграції OpenSCADA зі СУБД, яку реалізується модулем.

Інтерфейс OpenSCADA для обслуговування запитів до БД представлено об'єктами та віртуальними функціями викликів із ядра OpenSCADA:

2.2 Модуль підсистеми "Транспорти"

Модуль даного типу призначено для забезпечення комунікації OpenSCADA за посередництвом інтерфейсу, часто мережевого, який реалізується модулем.

Програмний інтерфейс OpenSCADA, для обслуговування вхідних та вихідних запитів через мережевий інтерфейс, представлено об'єктами та віртуальними функціями викликів із ядра OpenSCADA:

2.3 Модуль підсистеми "Транспортні протоколи"

Модуль даного типу призначено для забезпечення протокольного шару комунікацій OpenSCADA, який реалізується модулем, як для доступу к даним зовнішніх систем, так і даних OpenSCADA, із зовнішніх систем.

Програмний інтерфейс OpenSCADA, для реалізації протокольного шару, представлено об'єктами та віртуальними функціями викликів із ядра OpenSCADA:

2.4 Модуль підсистеми "Збір даних (DAQ)"

Модуль цього типу призначено для отримання даних реального часу зовнішніх систем або їх формування, у обчислювачах, які реалізуються модулем.

Програмний інтерфейс OpenSCADA для реалізації доступу до даних реального часу представлено об'єктами та віртуальними функціями викликів із ядра OpenSCADA:

Для спеціалізованої діагностики можна поміщати налагоджувальні повідомлення для умови вибору рівня діагностики "Налаштування (0)": if(messLev() == TMess::Debug) mess_debug_(...);.

2.5 Модуль підсистеми "Архіви"

Модуль цього типу призначено для архівування та ведення історії, повідомлень OpenSCADA та даних реального часу, отриманих у підсистемі "Збір даних", засобом який реалізується модулем.

Програмний інтерфейс OpenSCADA, для реалізації доступу до архівних даних, представлено об'єктами та віртуальними функціями викликів із ядра OpenSCADA:

2.6 Модуль підсистеми "Користувацькі інтерфейси (UI)"

Модуль цього типу призначено для надання користувацького інтерфейсу, засобом який реалізується модулем. Кореневим об'єктом модуля даної підсистеми є TUI->TModule, який не містить специфічних інтерфейсів, а користувацький інтерфейс формується згідно із реалізованої концепції та механізмами, наприклад, бібліотеки графічних примітивів.

2.7 Модуль підсистеми "Спеціальні"

Модуль цього типу призначено для реалізації специфічних функцій, які не увійшли до жодної з вищеперелічених підсистем, реалізованим модулем засобом. Кореневим об'єктом модуля даної підсистеми є TSpecial->TModule, який не містить специфічних інтерфейсів, а специфічні функції формуються згідно їх вимогами з використанням всіх можливостей API OpenSCADA.

Documents/How_to/Create_module/uk - GFDLMay 2022OpenSCADA 0.9.5