NoTA is a modular distributed service-oriented architecture. NoTA consists of subsystems that implement Application Nodes (ANs) and Service Nodes (SNs). SNs provide services that can be used by ANs and other SNs. The SNs are accessed through Service API (SAPI) that is usually described using WSDL. The SNs and ANs communicate using interconnect, the Device Interconnect Protocol DIP.
In NoTA the DIP is divided into two parts that are H_IN and L_IN. Further, L_IN is divided to L_INup and L_INdowns. L_INdowns are transport specific interconnect implementations. The L_INup is a module that can use multiple Ldowns and it provides unified communication interface to the H_IN. H_IN adds on top of service management functionality like service registration and discovery. ANs and SNs work on top of H_IN.
There is also a NoTA stub generator available for generating communication related code to ANs and SNs. Stub generator can be used to generate both AN and SN side stubs. It is also possible to use Stub Generator at the other end but not on the other end. The stub generator is a perl script that generates C-language source code files. Stubs require stub adapter to work. The stub adapter contains platform specific parts.
The purpose of this guide is to provide overview how to use the H_IN interface and how to get the NoTA Interconnect running.
NoTA DIP is divided into two software packages that are H_IN and L_IN. Both packages utilize GNU autotools and are compiled same way as typical open source projects. The packages are also available as debian packages. Debian packages are the preferred distribution method. The stub generator is also distributed same way.
The L_IN building is initialized by executing configure script inside the source package. The configure takes normal configure parameters and couple of NoTA specific ones. Table below lists the configuration parameters.
| Parameter | Values | Purpose |
| --with-platform | posix | Platform to which to build. Currently only posix is supported. |
| --with-transports | tcp, fifo, bt, usb, dummy, none | Which Ldown to use. Comma separated list |
After executing configure script the L_IN can be built with make command. The makefile supports normal installation and the L_IN is installed with make install command.
To build and install L_IN, do
./configure ./make ./make install
TCP L_IN is ready to use within one device and between several devices within the subnetwork without any special configuration. Multicasting must be enabled in IP interface in order for device discovery to work. Nodes, which are in different subnetwork, cannot be detected. Multicast IP address is 239.255.123.123 and port 2345.
If multicast routing is not already enabled in your network, you can use:
# route add -net 224.0.0.0 netmask 240.0.0.0 dev eth0
LdTCP implements own simple discovery mechanism, which is used to locate other LdTCP compatible nodes. The mechanisms is based on IP multicasting. When the user of LdTCP wants to discover other devices, it multicasts scene request (SCENE_REQ) messages. Scene request message includes information, which specifies searched types of nodes. This type is given in 32-bit integer, which is user-specific and whose meaning is unknown for LdTCP. Each NoTA compatible device, which wants to be discoverable, must listen scene discovery messages through multicast group address and reply if searched node type matches node's own node type. Response contains information on device's type and port numbers used for LdTCP communication.
The H_IN is built same way as L_IN by first executing configure script and then with make. It can be also installed same way. The H_IN configure script extra parameters are listed in the table below. The H_IN is built as two different versions. One is single-process and one is daemon version.
| Parameter | Values | Purpose |
| --with-platform | posix | Platform to which to build. Currently only posix is supported. |
In some Linux distributions you may need to modify the PKG_CONFIG_PATH, before running the configure, i.e.
export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/usr/local/lib/pkgconfig/
Simple H_IN test programs are available in test-folder, e.g. to exchange data between two nodes. Open a terminal window, go to test directory and type
NOTA_LMANAGER=1 ./dump_datacheck_sn_sp
This launches the single process version of the sevice node. NOTA_LMANAGER=1 tells that this H_IN instance should act as the Hmanager to keep the list of the services in the network. Open other terminal window and type
./dump_datacheck_an_sp
This launches the single process version of the application node.
Also the Stub Adapter is built same way. The stub generator does not need to built but the stub adapter makefile will install it. The table below lists configure parameters.
| Parameter | Values | Purpose |
| --with-platform | posix | Platform to which to build. Currently only posix is supported. |
The debian packages can be installed with dpkg -i <package name>.deb command. apt-get also installs the needed dependencies automatically.
DIP Interconnect stack can be used in two different ways. The interconnect package is available as daemon version and single-process versions. The difference is that with single-process version the interconnect stack is run as part of the AN / SN. The daemon version uses a system daemon that runs the stack and the ANs and SNs use the stack through a library. The daemon version library is called libh_in3 and the single-process version library is libh_in3_sp. There are also two versions of the stub adapter that are named respectively libstubadapter_h_in3 and libstubadapter_h_in3_sp.
The single-process version is meant for embedded subsystems and daemon version for full-blown linux subsystems. If the single-process version is used, the nodes inside same subsystem use L_IN to communicate with each other, and if the daemon version is used, the H_IN provides local loopback inside the H_IN that is much more efficient. Also the single-process version provides local loopback but it can be only used inside same memory space (in Linux inside same process).
The pkg-config program can be used to automatically include the interconnect stack inside a project. The command pkg-config nota-h_in-3.0 --cflags will provide needed compiler flags and pkg-config nota-h_in-3.0 --libs will provide needed libraries. The single-process version can be used by replacing nota-h_in-3.0 with nota-h_in-sp-3.0. Below is an example of simple makefile. The H_IN source code package contains more complete and thorough examples.
Makefile:
CFLAGS=`pkg-config nota-h_in-3.0 --cflags` -WallLDFLAGS=`pkg-config nota-h_in-3.0 --libs` service: service.o $(CC) $(LDFLAGS) -o service service.o
The program needs to use the header files and link against the H_IN library. Those can be also defined manually in embedded configurations. Below is example of Makefile without pkg-config.
Makefile:
CFLAGS=-I/usr/include/nota3 -WallLDFLAGS=-lh_in3 service: service.o $(CC) $(LDFLAGS) -o service service.o
The stub generator program will generate stub files from the wsdl file. It can also include xsd file if the types are defined separately. Below is stubgenerator syntax and an example how to run stub generator. The program using the stubs can call the stub functions that correspond the signal names to send a signal to network. The program needs to implement signals that the program is to receive. Those functions are postfixed _process in the generated stub header file. The program needs to also implement disconnect and error callbacks that are in the header file.
Syntax:nota-stubgen [-platform posix] <output_dir> <wsdl_file> [xsd_file]Example:nota-stubgen3.pl -platform posix . test.wsdl test.xsd
The stub generator can be also easily integrated to makefile. Below is example how to integrate it to the makefile. The stub generator source code package contains a more complete example.
Makefile:
CFLAGS=`pkg-config nota-h_in-3.0 --cflags` `pkg-config nota-stubgen-3.0 --cflags`LDFLAGS=`pkg-config nota-h_in-3.0 --libs` `pkg-config nota-stubgen-3.0 --libs`STUBGEN=nota-stubgen3.plWSDL_FILE=test.wsdlXSD_FILE=test.xsd# Test_service.c and .h are generated by stubgenservice: service.o Test_service.o $(CC) $(LDFLAGS) -o service service.o Test_service.oTest_service.c: $(WSDL_FILE) $(XSD_FILE) $(STUBGEN) -platform posix . $(WSDL_FILE) $(XSD_FILE)
