« Aalto « ELEC « AS

AS-84.3144 Field and Service Robotics


Interface Package

Fetching and extracting

First of all, you will need to download the most up-to-date interface package from the Downloads-page. After downloading, extract the downloaded archive file (.tar.bz2) with the following command:

tar -jvxf FSR-dist-buildXXX.tar.bz2

where 'XXX' stands for the current interface package build number.

After extracting you should have a directory 'FSR-dist' in your current working directory.


'FSR-dist' directory contains the following entries:

  • application/ - Contains the example application (and will contain your application)
  • bin/ - Contains required binaries. (Update: Link to architecture specific directory)
  • simulator/ - Contains simulator settings.
  • include/ - Contains header files required to use the Interface.
  • lib/ - Contains libraries required to use the Interface. (Update: Link to architecture specific directory)
  • fsrdist_initialize - Utility to setup the package.
  • execute_simulator - Script to execute the simulator with your parameters.
  • FSR-dist_build.stat - File containing a number representing the Build number of the package. This is the number to reference against when checking for updated packages.
  • FSR-dist_build.h - Same as previous, but as C/C++ header file.
  • ChangeLog.txt - Interface package changelog. Check this to see what has been updated since previous release.


We provide a Simulated environment to ease up your software developement. The course software package contains a complete package for running a Simulated J2B2 on your local (Linux) computer.


Starting the simulator is easy. The package root directory contains two script files: "fsrdist_initialize" and "execute_simulator". To make use of the sim, you must first call (once) the 'fsrdist_initialize' script providing a number from 0-9 to select a communication port. The selected port and any configuration made is stored on the same directory. Hence, when you have selected a port once, you do not need to do it again unless you have problems starting the simulator.

For example:

./fsrdist_initialize 1

Will initialize the package to execute in port 40021. The selected number must be between 0 and 9, and corresponds to local TCP ports 40020-40029.

After this, you can execute the local simulator session by executing command:


This command will load up the FSRSim graphical interface, and all required MaCI service modules. Loading the simulator and the modules takes a while, so wait for about 30 seconds before launching your application against the simulator. After this the simulator is ready to accept commands from the client interface.

If you ran into problems in the simulator, or just want to reset its state - just hit Ctrl-C on the terminal, and the simulator will be terminated. Then follow the starting procedure instructions again :) Warning: Do not start two simulator sessions with the same port at once at the same computer!

Please remember that the simulator package only replaces the Real J2B2 part of the software, so you will still need to follow the following section describing on how to run your own application.

Your Application

Your application is the part of the system which makes all the work :)


All application files are located in subdirectory "application" under the "FSR-dist" directory.

We have provided a few application examples consisting of three separate implementation (.cpp) files:

  • J2B2-UI-example.cpp
    • This file is the example main() module for the application. This takes care of processing the command line parameters and initializing the J2B2 interface, as well as dispatching the command to the Demo module (see below).
  • J2B2-UI-example-simple.cpp
    • This file is another example with a main() function. It is almost identical to the example above, except that it does nothing else than initializes the J2B2 interface and exits. This is a good starting point for your own application. Just copy this file to another file, and modify the Makefile to include a build target for your own application.
  • J2B2-API.hpp
    • This is the J2B2 Interface class header + implementation. If you look at the contents of this file, you will notice that it is a very simple wrapper for the underlying MaCI control architecture.
  • J2B2Demo.cpp
    • This is the demonstrator class. The J2B2-UI-example.cpp example application creates an instance of this class, which executes most of the functions in the J2B2-API. Use this as a reference and example for using the interface library.


For creating your own application, you can create a similar class as the CJ2B2Demo, and construct an instance of it from your main module. It is recommended to keep the J2B2Demo class as-is, as it may be updated during the course based on user feedback.

Compiling the application

External libraries

Although the distribution packet includes everything related to the GIMnet/MaCI framework, it still needs some external libraries to compile. Before the application may be built, atleast the following libraries must be installed: * SDL + SDL GFX (1.2+) * libXML2 (dev) * GLUT3 * OpenSSL

If you are using a Debian or Ubuntu based Linux, these packages may be easily installed by running (as root):

apt-get install libxml2-dev libsdl1.2-dev libsdl-gfx1.2-dev libsdl-image1.2-dev libssl-dev libglut3-dev

For 64 bit systems, you will also need to install the 32 bit libraries in order to run the 32 bit executables. For most systems, these are pulled in by installing package ia32-libs in addition to libraries listed above. This is usually the problem if you get error like "./Launcher: No such file or directory" when attempting to start the simulator. J2B2-UI-example-OrderSystem.cpp This command will also pull all required dependencies and install them automatically.

In case you don't have root permissions on the computer you are using, and the packets mentioned above are not installed, you can still download, compile and install these packages locally for your user, and modify the Makefile accordingly. However, this is only recommended for experienced users.

See instructions for installing the most common missing libraries as per-user local installations

Modifying the Makefile

To compile and link your application, add your own / modified sources to the source list of the J2B2App target Makefile. ("application/Makefile").

In the Makefile, there is a line:

J2B2App_SOURCES_CPP=J2B2-UI-example.cpp J2B2Demo.cpp

This tells the make utility that these sources belong to the J2B2App. Replace and add to these at your will. You may completely remove the currently included sources, as they are provided as an example only. I still recommend you to keep these files as a reference and example.


Compile the application by calling:


This call will compile the application code and link it against the MaCI library.


After calling the fsrdist_initialize script mentioned above, the application directory will contain two scripts: execute_simulator_client and execute_realJ2B2_client.

Remember that the Simulator and RealJ2B2 are just backends for you application. You will always need to run your application as standalone application when testing against either one of the backends.

So, still working in the ''application' This command will also pull al' subdirectory:

... running with Simulator

Call the script:


... running with Real J2B2

Call the script:


Remember that you must be inside the laboratory network to be able to control the real J2B2. Also remember, that you are now controlling a real machine, so be careful.

MaCI Clients

For controlling and getting data from the robot you must use different clients. You don't have to worry about opening and closing them and pointers for all clients are found at J2B2Client. J2B2 offers following clients:

  • ImageClient
    • Client for getting Images from the robot. To get the ImageData, use GetImageData function. ImageData contains lots of functions but you actually need GetImage function. The image is stored in a CimageContainer, and you have to call GetImageDataPtr- function for getting the pointer to imagedata. In the case of J2B2, there's always one JPEG image at imageData.
    • Example for using imageClient can be found at J2B2Demo.cpp at the RunCameraDemo-function or at RunSDLDemo function.
    • iImageCameraFront at J2B2Client is a CImageClient instance.

  • iImageCameraExtra at J2B2Client is another CImageClient instance, providing imagedata from the separate camera. (This is disabled per default; hence to use this interface, please see file 'J2B2Client.cpp', looking for a text 'FOR EXTRACAM SUPPORT', and the instructions following that) Using this feature requires at least course package version 108.
  • See more detailed description of ImageClient interface and interface functions
  • JointGroupCtrlClient
    • Client for commanding servos of the robot. J2B2 servos can only be commanded with position values (in radians, 0 in the middle,from -pi/2 to pi/2).For commanding servos to wanted position use SetPosition-function. It takes two parameters, position and the number of the servo. JointNumbers are enumerated at J2B2Client, KServoCameraPTUPan for pan and KServoCameraPTUTilt for tilt.
    • Example for using JointGroupClient can be found at J2B2Demo.cpp at the RunCameraDemo-function or at RunSDLDemo function.
    • iServoCtrl at J2B2Client is a jointGroupCtrlClient
    • See more detailed description of jointGroupCtrlClient interface and interface functions
  • SpeedCtrlClient
    • Client for controlling robot wheels. It is commanded with SetSpeed function by giving speed (m/s), angular speed(rad/s, positive CCW) and acceleration (m/s^2) values. For stopping the robot as fast as possible use SetStop function. Maximum speed for J2B2 is 0.5 m/s but normally 0.1-0.2 is quite enough and maximum acceleration is 0.2 m/sē
    • Simulator and the real J2B2 must receive speedctrl commands at minimum rate of 0.5Hz. Recommended SetSpeed() interval is 200-250ms. This is a security mechanism that stops the robot when the command link goes down.
    • Example for using SpeedCtrlClient can be found at J2B2Demo.cpp at the RunMotionDemo-function or at RunSDLDemo function.
    • iMotionCtrl at J2B2Client is a SpeedCtrlClient
    • See more detailed description of SpeedCtrlClient interface and interface functions
  • PositionClient
    • Client for getting position information. J2B2 has one Odometry Position source, which is calculated from the wheel movements. For reading the estimated position, use GetPositionEvent() function from the Position interface. It stores the information to CPositionData container where you can get the real coordainte with the GetPose2D() function.
    • Example for using position client can be found at J2B2Demo.cpp at the RunInfoDemo-function.
    • See more detailed description of PositionClient interface and interface functions
  • BehaviourClient
    • Client for controlling behaviours. J2B2 has one behaviour which is use for stopping the robot when bumpers and behviour is active. When the behaviour stops the robot, other speed commands are ignored, so you have to set it off for getting off the wall.
    • When hitting to wall it is safe to set speeds to 0 with speedCtrlClient(just to be sure the robot is not moving when closing the behaviour), then set the behaviour off(with setStop function), drive a little bit off the wall, and set the behaviour back on( setStart function).
    • iBehaviourCtrl at J2B2Client is a behaviourClient
    • Example for using behaviour client can be found at J2B2Demo.cpp at the RunMotionDemo-function or at RunSDLDemo function.
    • See more detailed description of BehaviourClient interface and interface functions
  • RangingClient
    • Client for getting ranging information. J2B2 has two different ranging sources, laser scanner and bumpers. For getting ranging information use GetDistanceArray function. Distance informations are stored in a TDistanceArray, which is a vector of Tdistance. TDistance contains the angle and distance value.
    • Example for using ranging client can be found at J2B2Demo.cpp at the RunSensorsDemo-function or at RunSDLDemo function.
    • iRangingLaser and iRangingBumpers at J2B2Client are both RangingClient.
    • See more detailed description of RangingClient interface and interface functions
  • IOClient
    • Client for commanding IO-board of the robot. It has digital and analog inputs/outputs. Digital output/inputs can be commanded with SetDigitalPin/GetDigitalPin functions and analog output/inputs can be commanded with SetAnalogVoltage/GetAnalogVoltage functions. This client can only be used with real J2B2.
    • iIOBoardESC at J2B2Client is a IOClient. This is the recommended IO interface to use, as the hardware contains some level of protection agains short circuits. Pins 8-15 are for OUTPUT (mapped on pins 0-7 on board) and pins 16-23 are for INPUT. Use the given pin numbers when controlling the IOClient. This device only supports Digital IO.
    • iIOBoardAD5414 at J2B2Client is another IOClient. This device has multiple programmable digital IO ports, and has also A/D capability. This device is not protected in any way, so if you must use it - be very careful!!
    • See more detailed description of IOClient interface and interface functions
  • TextClient

  • OrderSystem
OrderSystem is the system used in the final demonstrations for ordering the robot. This interface is not integrated to the J2B2-API module, but instead is provided as a separate library + header.
The newest course package includes directory "OrderSystem", which contains the server part of the ordersystem. The basic idea is, that each group may run the ordersystem server locally when testing, and in the final demonstration the OrderSystemClient is connected to the master OrderSystem server.
In order the get orders to your application, you will need the OrderSystem server running. The server will read the orders from file (orders.txt), and provides them as a service to the client. After running the "fsrdist_initialize", the OrderSystem directory will contain two launcher scripts. These are used to start the OrderSystem server either against the simulator environment, or against the "real" environment. In the final demonstration, we will have a "staff managed" OrderSystem server.
File J2B2-UI-example-OrderSystem.cpp in the application directory contains an simple usage example for the OrderSystem client library.

  • SerialLink
    • SerialLink interface provides methods for direct communication with a serial device. Using the serial client interface is simple, but different devices may require some changes on the server side. Currently we have one Serial 2 USB device connected, which is shown as 'J2B2.ttyACM0' on the GIMnet (The example code connects to this service per default). However, this device operates on 500kb/s speed, hence it may not be fully compatible with "normal" serial devices. In case you are planning on using the serial link, contact course staff in advance to get you going :)
    • More information on the interface can be found from the interface reference, which is located here.
    • Examples of usage can be found from the 'J2B2Demo.cpp', surrounded by ENABLE_SERIALLING #ifdef tags. (Try pressing 'i' when connected to the Real J2B2; you should get a print with 'Hello, World!' in it)
  • Generic useful utils

Useful links

  • GIMBugs Bugtracker
    • This is the bugtracker for all GIM related software (Which this library is too). The tracker includes a project with name FSR - if you encounter a problem with the interface and are certain that it is a BUG in the system, please report it here!
  • MaCI Class Reference
    • This contains the Doxygen generated documentation for the MaCI interface. Using this is simple; just look for the name of the interface required, and open its documentation page from the list of all classes. If you find that the documentation is inadequate, please report it - by posting to the forum, or by filling a bugtracker report; however, please do it, as feedback is the only way to improve the system!