OpenSCADA

Documents/How to/Create module

English • ‎mRussian • ‎Українська
Constr.png Generic revision and updating

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 the OpenSCADA. Since OpenSCADA is extremely modular system, all interfaces of interaction with the external environment are implemented by expanding it with specialized modules of following types:

At.png To create the OpenSCADA modules you need to have an experience in C/C++ programming language, build system AutoTools, as well as basic knowledge of Linux and the distribution you are using.

For placing developed module to main repository of OpenSCADA tree of source texts you need to do next and to follow to shown demands:

Contents

1 Creating a New Module

Modules in OpenSCADA are the shared libraries, which are dynamically connected to the OpenSCADA core at the time of the program execution. Many of the modules can be disabled, connected and updated during the execution from modules scheduler. Modules can also be included into the OpenSCADA core during building, by an argument -enable-{ModName}=incl to the "configure" configuration script, what can you learn from building manual. OpenSCADA modules can be of seven types according to the present modular subsystems. For now the modules for the OpenSCADA are written in the "C++" programming language, although in the future the bindings to other languages may appear.

In order to facilitate the creation of new modules in the sources tree, the branches of each subsystem provide the "=Tmpl=" directory with the module's template for the appropriate subsystem. The developer of the new module can copy this directory with the name of the new module. You can create modules in the OpenSCADA sources tree or as an independent project of the external module for the OpenSCADA.

1.1 Creation of the module 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 a new module to the OpenSCADA. Since the module should not be contrary to the spirit of open source project and to the license, on the basis of which the OpenSCADA is developed and distributed; the license of the new module obviously should be one of the free licenses.

The procedure of a new module creation based on the template with its inclusion to the sources tree is easier than such procedure for the external module and includes the following steps:

1. Getting the sources tree of the OpenSCADA project.
For a working branch:
$ svn co svn://oscada.org/trunk/OpenSCADA
For a stable release branch (not desirable because only corrections are accepted for the stable LTS releases and the instruction demand 0.9 version and more):
$ svn co svn://oscada.org/tags/openscada_0.8.0
2. Copy the template directory with the "NewMod" name of the new module (for example, for the "DB" subsystem):
$ cd OpenSCADA/src/moduls/bd
$ cp -r =Tmpl= NewMod; cd NewMod
$ rm -f configure.ac
3. Editing the "module.cpp" file.
Change the names of the functions of a module's including with the name of the new module:
"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
Information about the module in the "module.cpp" file, namely the area:
//************************************************
//* 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. Edit the module's building configuration in the "Makefile.am" file:
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. Adding an entry of the new module to the end of the subsystem's section (for us it is "> DB modules") of the OpenSCADA building system configuration file (OpenSCADA/configure.ac):
AX_MOD_DB_EN(NewMod,[disable or enable[=incl] build module DB.NewMod],disable,incl,
[
    # The code for external libraries of the module check
])
6. Now, the new module can be built in the OpenSCADA after the reorganization of the building system:
$ autoreconf -if
$ ./configure --enable-NewMod
$ make
7. Publication. The formation of the patch with your module and send it to the OpenSCADA developers:
$ cd OpenSCADA; make distclean; rm -f src/moduls/bd/NewMod/Makefile.in
$ svn add src/moduls/bd/NewMod
$ svn diff > NewMod.patch

1.2 Creation of an external module for OpenSCADA

Creation of an external module for 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 of a new external module based on the template is largely similar to the previous procedure and includes the following steps:

1. Getting the sources of the OpenSCADA project. For an external module as a source of 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). Creating and copying the necessary files for an external module. Further the information files of the project "COPYING", "NEWS", "README", "AUTHORS" and "ChangeLog" must be filled according to the nature of the new module.
$ cp -r OpenSCADA/src/moduls/bd/=Tmpl= NewMod
$ touch NewMod/{NEWS,README,AUTHORS,ChangeLog}
$ cp OpenSCADA/I18N.mk NewMod/
3. Editing the "module.cpp" file, similar to the appropriate item in the previous section.
4. Edit the module's building configuration in the "Makefile.am" file, similar to the appropriate item in the previous section, excepts:
# Instead "db_NewMod_la_LDFLAGS = -module -avoid-version $(top_builddir)/src/liboscada.la"
db_NewMod_la_LDFLAGS = -module -avoid-version
# Instead "include ../../../../I18N.mk"
include I18N.mk
5. Editing the "configure.ac" configuration file of the build system:
"AC_INIT([DB.Tmpl],[0.0.1],[my@email.org])" — information about the module: name, version and e-mail of the project.
"AM_CONDITIONAL([TmplIncl],[test])" — AM_CONDITIONAL([NewModIncl],[test])
6. Installing the OpenSCADA development package. Because the module is an external one and the OpenSCADA source files are needed only at the first stage of the module's creation, you must install the OpenSCADA development package (openscada-devel), which contains the header files and libraries.
7. Now you can build the new module, after formation of the building system
$ autoreconf -if
$ ./configure
$ make

2 Module's API

OpenSCADA API for the developer of OpenSCADA and modules for it is exhaustively, in a formal form, described in the paper OpenSCADA API, which should always be on hand for the development of OpenSCADA. This document focuses on the detailed explanation of the main points of the modular API.

The inheritance of root object-class of the module from the TModule class via a class of modular subsystem is common for all modules, which means that there is a common part of the module's interface, it'll be discussed below. In general, to present the architecture of modules in the context of the overall OpenSCADA architecture, it is strongly recommended to have before eyes the overall OpenSCADA class diagram!

The entry point of any module are the following functions:

For the convenience of a direct addressing to the root object of the module from any module's object below in the hierarchy it is recommended to determine the global variable "mod" in the namespace of the module with its initialization in the module's root object constructor. Also, for the transparent translation of the module's text messages it is recommended to define the template of the function for call messages' translation of the module "_({Message})": 

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

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 root object of the module.

As well as to initiate the environment of the module with the following functions:

Followed getting for the translations template file "po/NewMod.pot" of the text messages "_({Message})", and also updating-actualizing already presented translations "po/{en|ru|uk|de|...}.po" performed by the command into the module directory "$ make messages".

For the purpose of general module's management the TModule class provides a number of virtual functions that can be defined in the root object of the module with the implementation of the necessary response to the OpenSCADA core commands to the module:

All interface modules' objects inherit the TCntrNode node class, which provides the control interface mechanism, one of whose functions is to provide the configuration interface of the object in any OpenSCADA configurator. To solve the new module's tasks it may be necessary to expand the parameters of the configuration; it is made in the void cntrCmdProc(XMLNode *opt); virtual function. The contents of this function that adds a property in the simplest case has the following form: 

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);
}

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 the getting, setting the value, and others. The TBD::cntrCmdProc(opt); call is used to obtain the inherited interface. More details on the appointment of the used functions are in the control interface, as well as in the source code of existing modules.

In addition to the control interface functions TCntrNode object provides standardized control mechanisms for the modification of the object's configuration, for the loading and saving the configuration to the storage. To complete the setting of the modification flag of object's data you can use the modif() and modifG() functions, and module specific actions for the loading and saving can be placed in the virtual functions:

Typically the work with configuration is made through the TConfig object, which contains a set of specified properties. For a direct reflection of the module's object properties it is inherited from TConfig, and new properties are added by the following command: 

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

Loading and saving of the properties specified in the TConfig object, to/from the storage is made with the following command: 

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

Where:

To place debug messages, into common debugging concept, need to use the function mess_debug() with call it conditional by the program source part: 

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

2.1 "Data Bases (DB)" subsystem's module

This module is designed for the OpenSCADA integration with the DBMS, implemented by the module.

OpenSCADA interface to process the requests to the DB is presented by the objects and virtual functions of the calls from the OpenSCADA core:

2.2 "Transports" subsystem's module

The module of this type should provide OpenSCADA communications through the interface, often it is the network one, implemented by the module.

Software OpenSCADA interface to service input and output requests through a network interface is presented by the objects and virtual functions of the calls from the OpenSCADA core:

2.3 "Transport protocols" subsystem's module

The module of this type should provide OpenSCADA with the protocol layer communications, implemented by the module, for data access of the external systems and for OpenSCADA data from external systems.

Software OpenSCADA interface to implement the protocol layer is presented by the objects and virtual functions of the calls from the OpenSCADA core:

2.4 "Data acquisition" (DAQ) subsystem's module

The module of this type should provide the real-time data acquisition from the external systems or their formation in the calculators, implemented by the module.

The software OpenSCADA interface to implement access to real-time data is presented by the objects and virtual functions of the calls from the OpenSCADA core:

For specialized diagnostics you can place debug messages for condition to select diagnostic level "Debug (0): if(messLev() == TMess::Debug) mess_debug_(...);.

2.5 "Archives" subsystem's module

This type of the module is used for archiving and maintaining the history of OpenSCADA messages and real-time data obtained in the "Data acquisition" subsystem with the help of the module.

The OpenSCADA software interface to implement an access to the archived data is presented by the objects and virtual functions of the calls from the OpenSCADA core:

2.6 "User interfaces" (UI) subsystem's module

The module of this type should provide a user interface by its own method. The root object of the module is TUI->TModule, which does not contain specific interfaces, and the user interface is formed in accordance with the implemented concept and mechanisms, for example, of the graphic primitives library.

2.7 "Specials" subsystem's module

The module of this type should implement specific functions that are not included in any of the above subsystems. The root object of this module is TSpecial->TModule, which does not contain specific interfaces and specific functions are formed according to their needs, using all the features of OpenSCADA API.

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