Tutorial

About

GIMnet is essentially a service based communication middleware for building distributed applications. GIMnet provides an abstraction layer over TCP/IP and combines the client-server model with the peer-to-peer model. From an application point-of-view, GIMnet provides a virtual private network (VPN) in which all participating nodes may communicate point-to-point using simple name designators for addressing. GIMnet's communication model and features are especially designed to fit in the field of robotics.

GIMnet is divided in two major components: GIMnetAP (GIMnet Access Point) and GIMI (GIMnet Interface). The GIMnetAP component is responsible for data distribution and routing, whereas the GIMI implements the higher level communication mechanisms, and provides an application programming interface (API) for building applications utilizing GIMnet.

Here is some documentation for the usage of the GIMnet package. The GIMnet is provided in a tar package containing the source code for the GIMnetAP, GIMI, required utilities and some example applications.

The GIMnet communication framework is distributed under the GNU LESSER GENERAL PUBLIC LICENSE v3.

In case you run into trouble or have any questions, please see contact information from the Feedback page.

Getting the source

See page GIMnet download

Extracting

To use the framework, the package needs to be extracted.

To extract the package, execute the following: (The displayed file name is a template - use the most recent packet available)

tar -jvxf GIMnet-YYYYMMDD-rNNNNN.tar.bz2

This will create a folder named GIMnet-YYYYMMDD-rNNNNN, which in turn contains five directories: GIMI, GIMnetAP, GIMnetApps, include and utils. In addition to these, the base directory contains the licensing information files: COPYING and COPYING.LESSER

The roles of the directories are:

  • GIMI - Contains the GIMI interface sources and headers.
  • GIMnetAP - Contains the GIMnet core message dispatcher component. (GIMnetAP == GIMnet Access Point)
  • GIMnetApps - Contains a few example applications implemented using the GIMnet
  • include - Contains common header files required when linking to external applications
  • utils - Contains miscellaneous utilities used by GIMnet core components

In the following examples, we'll be using name 'GIMnet' to address the extracted base directory. For example GIMnet/GIMnetAP, which means the directory in which the GIMnetAP application resides.

Setting up

Environment

GIMnet requires the default C/C++ environment, including the standard make, gcc and g++. In addition to these, GIMnet requires a few extra libraries. In Debian based systems, you can install these by executing sudo apt-get install <package name>. The standard required package name is given in hyphens.

Required extra packages:

  • libxml2 (libxml2-dev)
  • OpenSSL (libssl-dev)

After setting up the environment, all the applications should compile in their own directories simply by executing make.

GIMnetAP

GIMnet is based on a network of interconnected GIMnetAPs. You will need at least one GIMnetAP to be able to operate. The following example compiles and starts an GIMnetAP listening in local TCP port 40002. If the 'make' command gives any errors, the application will not work as there was a problem compiling. In case you have followed the Environment setup section correctly, this may be a platform specific problem. If you are not able to resolve it by yourself, please send us a report as feedback.

Executing the master GIMnetAP

Compiling and executing the master GIMnetAP:

cd GIMnet/GIMnetAP
make
./start_session master -p 40002

If you look at the contents of the start_session script, you will notice that it is just a script. The purpose of this script is to streamline passing of required parameters to the GIMnetAP. If you want, you can execute the GIMnetAP directly by giving it the same parameters as given by the script.

After executing, the GIMnetAP should execute and wait for incoming connections. In case the execution fails (i.e. the parent shell reacquires control) check the following:

  • Did you get an error message like "../../GIMnetAP: No such file or directory"?
    • Did you succesfully compile the GIMnetAP (The make command did not report any errors)?
    • Do you have an executable file called 'GIMnetAP' in the directory?
If either of this are not true, please repeat the make step and watch the output.
  • Did you get an error message like "Failed to Initialize Sockets. Fatal error. Exit."? If, then the GIMnetAP could not start listening in the requested port. Check that:
    • You have specified an unprivileged port (> 1024)
    • You do not have another GIMnetAP session active in the same port
    • You don't have any other service in the requested port. For example, port 80 is a bad idea.
    • If you have very recently terminated a previous session, it might be that the port is still reserved. Please wait for a while and try again. In some very rare cases the port may get jammed for extended periods of time in which case the only option is to reboot the machine or choose another port.

For a brief listing of command line options, you can execute:

./GIMnetAP -h 

... which will list the currently accepted parameters with (very) brief descriptions.

Interconnecting GIMnetAPs

Connecting all nodes to each other through a single GIMnetAP has its limitations. All traffic must be routed through this single point, setting high demand for bandwidth and processing power on the central point. Even though routing data back and forth over a fast link is inefficient, even greater problem arises when this link is relatively slow, for example wireless. To overcome this limitation, GIMnet implements another connection scheme to solve this: interconnected GIMnet access points, namely AP2AP links (access point to access point links).

The GIMnetAP uses similar conventions as any network interface. In multi-AP network you must manually assign an identifier and default gateway for each AP. Additionally you will have to decide which of the APs acts as a master. If you need something else than a pure star connection schema, you will also need to specify routing entries in the routing table (Unfortunatly automatic routing is not implemented yet)

The role of the master AP in the GIMnet is only related to common services. Currently these services are the Nameservice and the server side Multicast service. In the future, these may be distributed to support scaling even higher, but currently only one instance of either service should exist.

To setup a master GIMnetAP with 'identifier' set to '1', listening in TCP port 40002 and verbosity level set to '2'. Parameter master is only a string identifier used to separate multiple instances running in the same directory from each other. This string can be anything, but must not include spaces.

./start_session master -p 40002 -i 1 -vv

To setup an AP2AP link between a new AP and the AP created in the previous example box:

  • Use script "start_subsession - used for making secondary AP sessions
  • Make AP2AP connection to 'localhost:40002'
  • Wait for application node/AP2AP connections in local TCP port 40003
  • Identifier set to '2'
  • Verbosity level set to '2'
  • Using AP with ID '1' as the default gateway for traffic destined to unknown (Not directly connected) targets. -d 1
./start_subsession sub1 -i 2 -vv -d 1 -c localhost:40002

After which you should see a similar execution printout as with the master, with the exception that there will be no "apservicebase" messages (they came from the APService execution, and they are only executed by the master AP). In case the parent shell reacquires control, the same troubleshooting instructions as with the master apply.

GIMI

GIMI API implements a service based infrastructure which supports the most common features required from a distributed communication middleware. These features include: Point-to-point messaging, subscription based messaging as well as means to locate and utilize services dynamically from the GIMnet network. GIMI is implemented as a C++ API, which is designed to allow creating new application nodes without excessive configuration.

GIMI provides you the API that you will use when developing GIMnet applications.

GIMI usage tutorials

GIMI comes with a few tutorials to demonstrate some most common features.These can be found from the folder GIM/src/GIMI/example/

  • gimisimplereceiver.cpp and gimisimplesender.cpp are an example of how to send and receive basic data with gimi.
  • gimiservicetutorial.cpp is an example of how to create a service that other clients can subscribe to with GIMI. Then you can easily and efficiently (multicast) send data to all subscribers of a service.
  • gimisubscribertutorial.cpp describes how to get list of available services, subscribe to a service and receive data.
  • gimimisctutorial.cpp contains usage examples for adjusting messagequeue sizes, pinging other clients, normal sending and additionally example code for implementing a simple signal-handler for your GIMI-client.
  • gimiredirectiontutorial.cpp contains examples for using redirections in GIMI.
  • gimisettingstutorial.cpp contains example of how to use readymade settings to set-up GIMI.

Create your program under your project source-tree, and copy "GIMnet/GIMI/example/Makefile.tutorial" and modify it to suit your project.

Follow one of the GIMI tutorials located under "GIMnet/GIMI/examples/" and make your own client.

Compile and run your program!

Example applications

GIMnet distribution includes a few example applications. These examples are located in directory "GIMnet/GIMnetApps".

More information added later.