Export translations

Settings

Group
Language
Format	Export for off-line translation Export in native format

{{DISPLAYTITLE:Документация/Как/Создать модуль}}<languages/>
{{Info|
* '''Автор:''' [[User:RomanSavochenko|Роман Савоченко]]
* '''Спонсировано, полную ревизию на 1.8 {{CtxDetails|ЧД|человеко-дней, 1ЧД — 10 часов}}:''' SINGE SOFTWARE
* '''Изначально создано:''' в [http://wiki.oscada.org/Doc/ModuleBuild старой Wiki] }}

This manual is made to help in building the modules for OpenSCADA. The module creation may be required if you wish to add the support for new data source or other extension to OpenSCADA. Since OpenSCADA is an extremely modular system, all interfaces of interaction with the external environment are implemented by expanding it with modules of following types:
* databases;
* communication interfaces, transports;
* protocols of the communication interfaces;
* data sources and data acquisition;
* archives-history (messages and values);
* user interfaces (GUI, TUI, WebGUI, speech, signal ...);
* additional modules, special.

[[File:at.png]] To create modules for OpenSCADA you need to have some experience in C/C++ programming language, the build system [http://en.wikipedia.org/wiki/GNU_build_system AutoTools], as well as basic knowledge of Linux and the distribution you are using.

In order to post the developed module to the [http://oscada.org/websvn/listing.php?repname=OpenSCADA OpenSCADA source tree repository], you must do the following and comply with the following requirements:
* be the copyright holder or the author of the module code and distribute it under any free license, GPL preferred;
* prepare and store the module code as a separated archive of the module folder for any module subsystem of OpenSCADA with demands to the content:
** the source texts of the module at the beginning of each file must include correct copyrights information, be written and formatted according to some system where preference should be given to the [[Special:MyLanguage/Documents/API#CodeDesign|formatting style of the main OpenSCADA modules]];
** the localisation files of the module must be also correct, actual and proper formed.
* write a short information page of the module for placing it to [[Special:MyLanguage/Modules|the OpenSCADA Wiki]] in way like to the other ones there;
* for placing of this module, write a direct request in the forum topic "[http://oscada.org/en/forum/topics/openscada_development/ OpenSCADA development]", including proof of functionality from the OpenSCADA developer or a short demonstration video.

== Creating a New Module ==
Modules in OpenSCADA are the shared libraries, which are dynamically connected to the OpenSCADA core at startup or during the program operation. Many of the modules can be disabled, connected and updated during the operation from the [[Special:MyLanguage/Documents/Program_manual#CfgModSched|module scheduler]]. Modules can be also builtin-included into the OpenSCADA core during building by an argument '''-enable-{ModName}=incl''' to the '''configure''' configuration script, what you can learn from the [[Special:MyLanguage/Documents/How_to/Build_from_source|building manual]]. The OpenSCADA modules can be of seven types according to the presented [[Special:MyLanguage/Documents/Program_manual#Modularity|modular subsystems]]. For now the modules to OpenSCADA are written in the "'''C++'''" programming language, although bindings for other languages may appear in the future.

In the tree of the source texts, in the branch of each subsystem, to simplify the creation of new modules, the folder "=Tmpl=" with the module template of the corresponding subsystem is provided. The developer of the new module can take this folder and copy it with the name of his new module, although he can also always use as a sample any real working module if his new one is close in structure. You can create modules in the OpenSCADA sources tree or as an independent project of the external module for OpenSCADA.

=== Creation in the sources tree of the OpenSCADA project ===
It makes sense to create new modules in the sources tree of OpenSCADA project in case of further plans for the transfer of the new module to the OpenSCADA project. Since the module should not be contrary to the spirit of the open source project and license on the basis of which [http://oscada.org/en/main/about-the-project/licenses/ OpenSCADA is developed and distributed], license of the new module obviously should be one of the free licenses.

The procedure for creating a new module with inclusion in the source text tree based on a template is generally simpler than the procedure for an external module and includes the following steps:
:1. Get the source tree of the OpenSCADA project for:
:* ''the Work branch:''
:: {{InLineCode|<nowiki>svn co svn://oscada.org/trunk/OpenSCADA</nowiki>}}
:* ''the stable release branch — NOT RECOMMENDED, as only patches are accepted for stable LTS releases and this instruction requires version 0.9 or higher:''
:: {{InLineCode|<nowiki>svn co svn://oscada.org/tags/openscada_0.9</nowiki>}}
:2. Copy the template folder with the "NewMod" name of the new module, for example, for the "DB" subsystem:
:: {{InLineCode|<nowiki>cd OpenSCADA/src/moduls/bd; cp -r =Tmpl= NewMod; cd NewMod; rm -f configure.ac</nowiki>}}
::: ''for the "DAQ" subsystem the path is'' — "OpenSCADA/src/moduls/'''daq'''"
::: ''for the "Archive-History" subsystem the path is'' — "OpenSCADA/src/moduls/'''arhiv'''"
::: ''for the "Transport" subsystem the path is'' — "OpenSCADA/src/moduls/'''transport'''"
::: ''for the "Transport protocol" subsystem the path is'' — "OpenSCADA/src/moduls/'''protocol'''"
::: ''for the "UI" subsystem the path is'' — "OpenSCADA/src/moduls/'''ui'''"
::: ''for the "Special" subsystem the path is'' — "OpenSCADA/src/moduls/'''special'''"
:3. Edit the "module.cpp" file for:''
::: ''also can do that automatically by:'' {{InLineCode|<nowiki>sed -i "s/Tmpl/NewMod/g" *.{cpp,h}</nowiki>}}
:* ''changing the name of the builtin-inclusion functions of the module according to the name of the new module'':
:: "TModule::SAt '''bd_Tmpl_module'''( int n_mod )" —> "TModule::SAt '''bd_NewMod_module'''( int n_mod )"
:: "TModule *'''bd_Tmpl_attach'''( const TModule::SAt &AtMod, const string &source )" —> "TModule *'''bd_NewMod_attach'''( const TModule::SAt &AtMod, const string &source )"
:* ''information about the module in the "module.cpp" file, namely the section:''
<syntaxhighlight lang="CPP" style="margin-left: 45px">
//************************************************
//* 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"
</syntaxhighlight>
:4. Edit the module's building configuration in the "Makefile.am" file to:
::: ''also can do that automatically by:'' {{InLineCode|<nowiki>sed -i "s/Tmpl/NewMod/g" Makefile.am</nowiki>}}
<pre style="white-space: pre-wrap; margin-left: 30px">
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
</pre>
:5. Add an entry of the new module to the end of the subsystem's section of the OpenSCADA building system configuration file "OpenSCADA/configure.ac":
:* ''to the section "DB modules" end for the "DB" subsystem:''
<pre style="white-space: pre-wrap; margin-left: 30px">
AX_MOD_DB_EN(NewMod, [disable or enable[=incl] compilation module DB.NewMod], disable, incl, [
    # The code for external libraries of the module check
])
</pre>
:* ''to the section "DAQ modules" end for the "DAQ" subsystem:''
<pre style="white-space: pre-wrap; margin-left: 30px">
AX_MOD_DAQ_EN(NewMod, [disable or enable[=incl] compilation module DAQ.NewMod], disable, incl, [
    # The code for external libraries of the module check
])
</pre>
:* ''to the section "Archive modules" end for the "Archive-History" subsystem:''
<pre style="white-space: pre-wrap; margin-left: 30px">
AX_MOD_Archive_EN(NewMod, [disable or enable[=incl] compilation module Archive.NewMod], disable, incl, [
    # The code for external libraries of the module check
])
</pre>
:* ''to the section "Transport modules" end for the "Transport" subsystem:''
<pre style="white-space: pre-wrap; margin-left: 30px">
AX_MOD_Transport_EN(NewMod, [disable or enable[=incl] compilation module Transport.NewMod], disable, incl, [
    # The code for external libraries of the module check
])
</pre>
:* ''to the section "Transport protocol modules" end for the "Transport protocol" subsystem:''
<pre style="white-space: pre-wrap; margin-left: 30px">
AX_MOD_TrProt_EN(NewMod, [disable or enable[=incl] compilation module Protocol.NewMod], disable, incl, [
    # The code for external libraries of the module check
])
</pre>
:* ''to the section "UI modules" end for the "UI" subsystem:''
<pre style="white-space: pre-wrap; margin-left: 30px">
AX_MOD_UI_EN(NewMod, [disable or enable[=incl] compilation module UI.NewMod], disable, incl, [
    # The code for external libraries of the module check
])
</pre>
:* ''to the section "Special modules" end for the "Special" subsystem:''
<pre style="white-space: pre-wrap; margin-left: 30px">
AX_MOD_Special_EN(NewMod, [disable or enable[=incl] compilation module Special.NewMod], disable, incl, [
    # The code for external libraries of the module check
])
</pre>
:6. Now the new module can be built in OpenSCADA after the reorganisation of the building system:
:: {{InLineCode|<nowiki>autoreconf -if; ./configure --enable-NewMod; make</nowiki>}}
:7. Publication — form a patch with your module and send it to the OpenSCADA developers:
:: {{InLineCode|<nowiki>cd OpenSCADA; make distclean; rm -rf src/moduls/bd/NewMod/{Makefile.in,.deps}</nowiki>}}
:: {{InLineCode|<nowiki>svn add src/moduls/bd/NewMod; svn diff > NewMod.patch</nowiki>}}

=== Creation an external module to OpenSCADA ===
Creation an external module to OpenSCADA may make sense in the case of the development the integration interface with business (commercial) systems that require proprietary interaction code, as well as in the case of other commercial interfaces implementations in which the module for the OpenSCADA acquire the status of the separate project, that is distributed and maintained independently often in the form of binary buildings for a specific platform and version of OpenSCADA. The license of such modules, respectively, can be arbitrary.

The procedure for creation a new external module based on the template is largely similar to the previous procedure and includes the following steps:
:1. Get the source texts of the OpenSCADA project — for an external module as a source of the template you can use any OpenSCADA source files of version more than 0.9, because it is necessary to copy only the "=Tmpl=" directory and several files for build.
:2. Copy the template directory with the "NewMod" name of the new module, for example, for the "DB" subsystem; and in that directory already create and copy the necessary files of the external module. Further, the information files of the project "COPYING", "NEWS", "README", "AUTHORS" and "ChangeLog" must be filled accordingly to the nature of the new module.
:: {{InLineCode|<nowiki>cp -r OpenSCADA/src/moduls/bd/=Tmpl= NewMod; touch NewMod/{NEWS,README,AUTHORS,ChangeLog}; cp OpenSCADA/I18N.mk NewMod/</nowiki>}}
::: ''for the "DAQ" subsystem the path is'' — "OpenSCADA/src/moduls/'''daq'''/=Tmpl="
::: ''for the "Archive-History" subsystem the path is'' — "OpenSCADA/src/moduls/'''arhiv'''/=Tmpl="
::: ''for the "Transport" subsystem the path is'' — "OpenSCADA/src/moduls/'''transport'''/=Tmpl="
::: ''for the "Transport protocol" subsystem the path is'' — "OpenSCADA/src/moduls/'''protocol'''/=Tmpl="
::: ''for the "UI" subsystem the path is'' — "OpenSCADA/src/moduls/'''ui'''/=Tmpl="
::: ''for the "Special" subsystem the path is'' — "OpenSCADA/src/moduls/'''special'''/=Tmpl="
:3. Edit the module information in the "module.cpp" file similarly to the appropriate item in the previous section.
:4. Edit the module building configuration in the "Makefile.am" file similarly to the appropriate item in the previous section, excepts:
:* instead "db_NewMod_la_LDFLAGS = -module -avoid-version '''$(top_builddir)/src/liboscada.la'''" write "db_NewMod_la_LDFLAGS = -module -avoid-version", that is remove "$(top_builddir)/src/liboscada.la"
:* instead "include '''../../../../'''I18N.mk" write "include I18N.mk", that is remove the path "../../../../"
:5. Edit the build system configuration file "configure.ac" for:
::: ''also can do that automatically by:'' {{InLineCode|<nowiki>sed -i "s/Tmpl/NewMod/g" configure.ac</nowiki>}}
:* "AC_INIT(['''Tmpl'''],['''0.0.1'''],['''my@email.org'''])" — information about the module: name, version and EMail of the project
:* "AM_CONDITIONAL(['''TmplIncl'''],[test])" — "AM_CONDITIONAL(['''NewModIncl'''],[test])"
:6. Install the OpenSCADA development package "openscada-dev" or "openscada-devel" — because the module is an external one and the OpenSCADA source files are needed only at the first stage of the module creation, you need to install the OpenSCADA development package, which contains the header files and libraries.
:7. Now you can build the new module, after formation of the building system
:: {{InLineCode|<nowiki>autoreconf -if; ./configure; make</nowiki>}}

== API of the module ==
OpenSCADA API for the developer of OpenSCADA and modules to it is described in the document "[[Special:MyLanguage/Documents/API|OpenSCADA API]]", which should always be on hand at development for OpenSCADA. This document focuses on the detailed explanation of the main points of the modular API.
{{#lst:Documents/API/en|ModAPI}}

For the convenience of direct addressing to the root object of the module from any object lower in the hierarchy, it is recommended to define the global variable "mod" in the namespace of the module, with its initialization in the constructor of the root object. Also, for transparent translation of the text messages of the module, it is recommended to define the function templates of the module message translation call "'''_({Message})'''" and "'''trS({Message})'''" as:
<syntaxhighlight lang="CPP">
#undef _
#define _(mess) mod->I18N(mess).c_str()
#undef trS
#define trS(mess) mod->I18N(mess,mess_PreSave)
</syntaxhighlight>

In the constructor of the root module's object inherited from the '''TModule''' it is necessary to set the main information of the module by call the function '''void modInfoMainSet({Name}, {Type}, {Version}, {Authors}, {Description}, {License}, {Source})''' after init the fast link "mod" to the root object of the module.

Further receiving of the translation template file "po/oscd_NewMod.pot" of the text messages "'''_({Message})'''" and "'''trS({Message})'''", as well as updating-actualising the files of already existing translations "po/{uk|de|ru|...}.po" is carried out by the command {{InLineCode|make messages}} in the module folder.

During solve the tasks of the new module, it may be necessary to expand the configuration parameters, which is carried out in the virtual function '''void cntrCmdProc( XMLNode *req );'''. The content of this function, which adds properties, in the [[Special:MyLanguage/Modules/SQLite|SQLite module]] looks like this:
<syntaxhighlight lang="CPP">
void MBD::cntrCmdProc( XMLNode *opt )
{
    //Getting the page info
    if(opt->name() == "info") {
        TBD::cntrCmdProc(opt);
        ctrMkNode("fld",opt,-1,"/prm/cfg/ADDR",EVAL_STR,enableStat()?R_R___:RWRW__,"root",SDB_ID,3,
            "dest","sel_ed","select","/prm/cfg/dbFsList","help",
                    _("SQLite DB address must be written as: \"{FileDBPath}\".\n"
                      "Where:\n"
                      "  FileDBPath - full path to DB file (./oscada/Main.db).\n"
                      "               Use the empty path to create a temporary database on the disk.\n"
                      "               Use \":memory:\" to create a temporary database in memory."));
        if(reqCnt)
            ctrMkNode("comm",opt,-1,"/prm/st/end_tr",_("Close opened transaction"),RWRW__,"root",SDB_ID);
    }
    //Processing for commands to the page
    string a_path = opt->attr("path");
    if(a_path == "/prm/cfg/dbFsList" && ctrChkNode(opt)) {
        opt->childAdd("el")->setText(":memory:");
        TSYS::ctrListFS(opt, addr(), "db;");
    }
    else if(a_path == "/prm/st/end_tr" && ctrChkNode(opt,"set",RWRW__,"root",SDB_ID,SEC_WR) && reqCnt) transCommit();
    else TBD::cntrCmdProc(opt);
}
</syntaxhighlight>

The first half of this function serves the "info" information requests with the list and properties of the configuration fields. The second half serves all the other commands on getting, setting value, and others. The '''TBD::cntrCmdProc(opt);''' call is used to obtain the inherited interface. More details on appointment of the used functions are in the [[Special:MyLanguage/Documents/API#CntrNode|control interface]], as well as in the source code of existing modules.

The '''TCntrNode''' object, in addition to the control interface function, provides unified control mechanisms for modifying the object's configuration, loading, saving, and deleting configuration duplicates in the storage. You can use the '''modif()''' and '''modifG()''' functions to set the object data modification flag, and the module-specific loading and saving actions can be placed in virtual functions:
* ''void load_( TConfig *cfg );'', ''void load_( );'' — loading the object from a storage.
* ''void save_( );'' — saving the object to a storage.

Configuration actions typically occur through the [[Special:MyLanguage/Documents/API#TConfig|TConfig]] object, which contains a set of defined properties with structure and values. To directly reflect the properties of a module object, it inherits from '''TConfig''', and new properties are added with the command:
<syntaxhighlight lang="CPP">
fldAdd(new TFld("MOD_PRMS",trS("Module addition parameters"),TFld::String,TFld::FullText|TCfg::NoVal,"100000"));</syntaxhighlight>

Loading/saving/deleting of the properties specified in the '''TConfig''' object, from/to/in the storage, is made with the following commands:
<syntaxhighlight lang="CPP">
TBDS::dataGet(fullDB(), owner().nodePath()+tbl(), *this);
TBDS::dataSet(fullDB(), owner().nodePath()+tbl(), *this);
TBDS::dataDel(fullDB(flag&NodeRemoveOnlyStor), owner().nodePath()+tbl(), *this, TBDS::UseAllKeys);
</syntaxhighlight>
Where:
* ''fullDB()'' — the full name of the storage in the [[Special:MyLanguage/Documents/API#DataConcept|common form]];
* ''owner().nodePath()+tbl()'' — the common path, represented as the table, to the object node in the configuration file;
* ''*this'' — this object, inherited from '''TConfig'''.

To generate the debug messages [[Special:MyLanguage/Documents/Program_manual#Config|according the common debugging concept]], you need to use the function '''mess_debug()''' with call it conditionally at the program source part:
* the rarely invoked part — direct call to the function {{InLineCode|<nowiki>mess_debug(...);</nowiki>}};
* the often invoked part — conditional call {{InLineCode|<nowiki>if(mess_lev() == TMess::Debug) mess_debug(...);</nowiki>}};
* the critical to performance code part — wrapping to definition '''OSC_DEBUG''':
<syntaxhighlight lang="CPP">
#ifdef OSC_DEBUG
  mess_debug(...);
#endif
</syntaxhighlight>

Export translations

Views

Navigation menu

OpenSCADA

OpenSCADA Wiki

Search

Tools

MediaWiki

Personal tools