Manual-5

From jderobot

Jump to: navigation, search

This is the manual for jderobot-5. The most updated release of the documentation for this experimental release is this mediawiki. The API documentation can be found here.

Contents

Introduction

What is this Manual for?

This manual is intended to describe the JDErobot 5.0 software, its design and its components. It is oriented to JDErobot users and JDErobot developers. For developers it includes descriptions for each piece of software in this experimental distribution.

This is the official most up to date documentation of JDErobot 5.0. It is written in the mediawiki tool because reading a mediawiki is more handy than reading a manual in paper and because videos can be included, enhancing the descriptions.

What is JDErobot 5.0?

JDErobot 5.0 is a collection of components that communicate between them through ICE. These components use a set of defined interfaces to interact with each other, being this the only coupling mechanism between components. This way we can achieve what we were trying with older versions of JDErobot, a components based architecture, but without the drawbacks of trying to program middleware related code.

Installing JDErobot 5.0

Installing JDErobot 5.0 on Linux Ubuntu 10.04

Here we install JDErobot 5.0 on a Linux Ubuntu 10.04 Lucid Lynx system.

Installing previous recommended libraries

Some extra libraries are necessary to compile, link or run JDErobot-5. You just type the following "aptitude install" commands:

Basic libraries: 

sudo aptitude install build-essential libltdl3 libltdl3-dev libfltk1.1 libfltk1.1-dbg libfltk1.1-dev libtool cmake g++

Xforms libraries: 

sudo aptitude install libforms-bin libforms-dev libforms1 libformsgl-dev libformsgl1 libforms-doc

OpenGL libraries: 

sudo aptitude install libglut3 libglut3-dev freeglut3 freeglut3-dev glutg3-dev libgl1-mesa-dev libglu1-mesa libglut3 libglut3-dev

GTK libraries: 

sudo aptitude install libgtk2.0-0 libgtk2.0-bin libgtk2.0-cil libgtk2.0-common libgtk2.0-dev libgtkgl2.0-1 libgtkgl2.0-dev libgtkglext1 libgtkglext1-dev

Installing ICE

What's ICE?

ICE (or Internet Communications Engine) is a modern object-oriented middleware with support for C++, .NET, Java, Python, Objective-C, Ruby, and PHP. ICE's most important new concepts are: Slice, IceGrid and IceStorm. We'll see all details.

Slice

It's the Specification Language for ICE. 

$ sudo apt-get install ice33-slice

ICE translators

You must install Slice translators. It lets you get translation: [Slice definitions->Your desired language]. 

$ sudo apt-get install ice33-translators

ICE Services

ICEGrid

It basically decouples clients from their servers. For example: if you're gonna use some ICE camera server component you don't need to care about its IP address.

IceStorm

It's an efficient publish/subscribe service for ICE applications.

Installation 
$ sudo apt-get install ice33-services

Installing JDErobot 5.0 on Linux Ubuntu 9.04

This chapter consolidates JDErobot 5.0 installation process on a Linux Ubuntu 9.04 operating system. The system used had already installed previous JDErobot version, 4.3.

Installing ICE middleware

The new version of JDErobot requieres this GNU component as a feature for communicating different JDErobot components and make them work together in a distributed system environment.

ICE, stands for the Internet Communications Engine, is a middleware for the practical programmer developed by ZeroC Inc. A high-performance Internet communications platform, Ice includes a wealth of layered services and plug-ins.

Ice is built on concepts which will be familiar to CORBA programmers, and supports a wide variety of programming languages and runtime platforms. Slice is the interface description language used in Ice.

First, ice33-slice component has to be installed (ice*-slice). This package installs the Slice language definitions of standard Ice services on /usr/share/slice. You will find further information in the ZeroC home page (http://www.zeroc.com/ice.html) and in the non-free package zeroc-ice-manual. 

$ sudo apt-get install ice33-slice
[sudo] password for jvazquez: 
Reading package lists... Done
Building dependency tree       
Reading state information... Done
The following NEW packages will be installed:
  ice33-slice
0 upgraded, 1 newly installed, 0 to remove and 193 not upgraded.
Need to get 181kB of archives.
After this operation, 2,966kB of additional disk space will be used.
Get:1 http://us.archive.ubuntu.com karmic/universe ice33-slice 3.3.1-6 [181kB]
Fetched 181kB in 1s (142kB/s)      
Selecting previously deselected package ice33-slice.
(Reading database ... 176692 files and directories currently installed.)
Unpacking ice33-slice (from .../ice33-slice_3.3.1-6_all.deb) ...
Setting up ice33-slice (3.3.1-6) ...

At [file:///usr/share/doc/ice33-slice/reference/index.html] directory, a reference guide is available after installation.

It's also neccesary to install ICE translator module, ice33-translators (ice*-translators), by executing the following command: 

$ sudo apt-get install ice33-translators
Reading package lists... Done
Building dependency tree       
Reading state information... Done
The following extra packages will be installed:
  libiceutil33 libmcpp0 libslice33
The following NEW packages will be installed:
  ice33-translators libiceutil33 libmcpp0 libslice33
0 upgraded, 4 newly installed, 0 to remove and 193 not upgraded.
Need to get 1,440kB of archives.

...

Processing triggers for libc-bin ...
ldconfig deferred processing now taking place

For a developing environment, it's also requiered the installation of libzeroc-ice33-dev package with any dependency. 

$ sudo apt-get install libzeroc-ice33-dev
[sudo] password for jvazquez: 
Reading package lists... Done
Building dependency tree       
Reading state information... Done
The following extra packages will be installed:
  libdb4.6++ libfreeze33 libglacier2-33 libicebox33 libicegrid33 libicepatch2-33 libicessl33 libicestorm33 libicexml33 libzeroc-ice33 libzeroc-ice33-dbg
The following NEW packages will be installed:
  libdb4.6++ libfreeze33 libglacier2-33 libicebox33 libicegrid33 libicepatch2-33 libicessl33 libicestorm33 libicexml33 libzeroc-ice33 libzeroc-ice33-dbg
  libzeroc-ice33-dev
0 upgraded, 12 newly installed, 0 to remove and 193 not upgraded.
Need to get 36.7MB of archives.

...

Processing triggers for libc-bin ...
ldconfig deferred processing now taking place

Finally, if any ICE service, such us, icegrid or icestorm, is goning to be used, ice33-services (ice*-services) is requiered.

ICE Documentation

You can find an extended on-line manual at http://www.zeroc.com/doc/Ice-3.3.1/manual/toc.html


Installing GStreamer development framework

GStreamer is a streaming media framework, based on graphs of filters which operate on media data. Applications using this library can do anything from real-time sound processing to playing videos, and just about anything else media-related. Its plugin-based architecture means that new data types or processing capabilities can be added simply by installing new plug-ins.

This framework is used for Camera component interface impletentations. JDErobot 5.0 Components, such us cameraserver requieres this libraries and development packages.

First, install libgstreamer0.10-dev package for developing environment. 

>$ sudo apt-get install libgstreamer0.10-dev
Reading package lists... Done
Building dependency tree       
Reading state information... Done
The following packages were automatically installed and are no longer required:
  libsigc++-2.0-dev libxml++2.6-dev libgstreamermm-0.10-2 libglibmm-2.4-dev
Use 'apt-get autoremove' to remove them.
Suggested packages:
  gstreamer0.10-doc
The following NEW packages will be installed:
  libgstreamer0.10-dev
0 upgraded, 1 newly installed, 0 to remove and 192 not upgraded.
Need to get 0B/873kB of archives.
After this operation, 4,047kB of additional disk space will be used.
Selecting previously deselected package libgstreamer0.10-dev.
(Reading database ... 177838 files and directories currently installed.)
Unpacking libgstreamer0.10-dev (from .../libgstreamer0.10-dev_0.10.25-2_i386.deb) ...
Processing triggers for man-db ...
Setting up libgstreamer0.10-dev (0.10.25-2) ...

Then, install libgstreamer-plugins-base0.10-dev as well 

>$ sudo apt-get install libgstreamer-plugins-base0.10-dev
Reading package lists... Done
Building dependency tree       
Reading state information... Done
The following packages were automatically installed and are no longer required:
  libsigc++-2.0-dev libxml++2.6-dev libgstreamermm-0.10-2 libglibmm-2.4-dev
Use 'apt-get autoremove' to remove them.
The following NEW packages will be installed:
  libgstreamer-plugins-base0.10-dev
0 upgraded, 1 newly installed, 0 to remove and 192 not upgraded.
Need to get 0B/138kB of archives.
After this operation, 1,450kB of additional disk space will be used.
Selecting previously deselected package libgstreamer-plugins-base0.10-dev.
(Reading database ... 177967 files and directories currently installed.)
Unpacking libgstreamer-plugins-base0.10-dev (from .../libgstreamer-plugins-base0.10-dev_0.10.25-2ubuntu1.2_i386.deb) ...
Setting up libgstreamer-plugins-base0.10-dev (0.10.25-2ubuntu1.2) ...

Installing GearBox development package

GearBox has to be also installed. At the moment of this documentation, there isn't a Debian package yet. Installation instructions can be read at http://gearbox.sourceforge.net/gbx_doc_getting.html 

sudo apt-get install cmake
  • Follow the rest of configuration, compilation and installation steps for Debian/Ubuntu [1]

Include GearBox libraries path to LD_LIBRARY_PATH environment variable. It'll be required for later references during compilation. Type or include to $HOME/.profile, the following line: 

echo "export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib/gearbox/" >> ${HOME}/.profile && . ${HOME}/.profile

Installing OpenCV 2.0.0

OpenCV (Open Source Computer Vision) is a library of programming functions for real time computer vision. It is released under a BSD license, it is free for both academic and commercial use. The library has >500 optimized algorithms (see figure below). It is used around the world, has >2M downloads and >40K people in the user group.

Refer to http://opencv.willowgarage.com/wiki/InstallGuide in order to download and install the component on Linux.

Installing Gtkmm 2.4

Gtkmm is a C++ interface for the popular GUI library GTK+. Gtkmm provides a convenient interface for C++ programmers to create graphical user interfaces with GTK+'s flexible OO framework. Highlights include type safe callbacks, widgets extensible using inheritance and over 180 classes that can be freely combined to quickly create complex user interfaces.

Install libgtkmm-2.4-dev Debian package: 

sudo apt-get install libgtkmm-2.4-dev

Installing Libglade 2.4

Libglade is a library which enables an application to build its graphical interface from an XML file (generated by Glade) at runtime. libglademm is the C++ wrapper for libglade.

Install libglademm-2.4-dev Debian package: 

sudo apt-get install libglademm-2.4-dev

Installing JDErobot 5.0

After JDErobot 5.0 download, you must execute the following steps: 

cd $JDEproject_dir
aclocal
autoconf
autoheader
automake -a
./configure --prefix=$JDErobot_install_dir --disable-component-recordingserver
make
sudo make install

Running JDErobot 5.0

Running components

Each component requires an input configuration file with the format: 

...
...
myComponent.X.Y = Z
...
...

This format is better defined in ICE middleware documentation.

Thus, the component execution syntax is: 

$> jdeComponent --Ice.Config=jdeComponent.cfg

Some entries are required, like the ones defining the component address, if we are connecting our components directly or the locator service if we are using IceGrid. And others are optional, that can define the behavior of our component in some cases. Each component have a set of configuration entries to set its specific parts. A common configuration file may be like this: 

CameraSrv.Endpoints=default -h 127.0.0.1 -p 9999

#cameras configuration
CameraSrv.NCameras=2

#camera 0
CameraSrv.Camera.0.Name=cameraA
CameraSrv.Camera.0.ShortDescription=Camera pluged to /dev/video0
CameraSrv.Camera.0.Uri=v4l2:///dev/video0
...
...

Here we can see the component's name CameraSrv and the define endpoints, that are the network addresses where our component will tie. The syntax to describe an endpoint is explained in the ICE manual. If we are using a locator service we don't need to define an specific address since we won't connect directly to it but with the indirect proxy that the locator will give us. In this case the configuration would be something like this: 

CameraSrv.Endpoints=default
CameraSrv.AdapterId=CameraSrv1
Ice.Default.Locator=IceGrid/Locator:tcp -h localhost -p 12000

#cameras configuration
CameraSrv.NCameras=2

#camera 0
CameraSrv.Camera.0.Name=cameraA
CameraSrv.Camera.0.ShortDescription=Camera pluged to /dev/video0
CameraSrv.Camera.0.Uri=v4l2:///dev/video0
...

In this last case, we have to define an unique AdapterId that will be used to ask to the locator service, since may exists more than one instance of our server.

The rest of the configuration is used by the component implementation, in this case to set the video sources.

Programming a component for JDErobot 5.0

Programming style

JDErobot code is documented using doxygen. You can find more information here.

Interfaces

ImageProvider

Slice definition

Camera

Slice definition

RecordingManager

Slice definition

Motors

Slice definition

Laser

Slice definition

Encoders

Slice definition

PTMotors

Slice definition

PTEncoders

Slice definition

Sonars

Slice definition

Components

In this section, we describe the main components distributed with JDErobot 5.0. They go from simple components to access hardware, to other more complex that process data and produce derived data, like motion detection from images. They are a valuable examples to create new components as well, so we will describe how to use them and how they work.

cameraserver

Cameraserver is a component to serve N cameras, either real or simulated from a video file. It uses gstreamer internally to handle and to process the video sources.

Provided Interfaces

Required Interfaces

Using cameraserver

To use cameraserver we just have to edit the component's configuration to set the video sources and to set the served formats of our cameras. We also have to set the network address where our component will be listening to for new connections or to choose the locator service.

A configuration file example may be like this: 

#network configuration
CameraSrv.Endpoints=default -h 127.0.0.1 -p 9999

#cameras configuration
CameraSrv.NCameras=1

#camera 0
CameraSrv.Camera.0.Name=cameraA
CameraSrv.Camera.0.ShortDescription=Camera pluged to /dev/video0
CameraSrv.Camera.0.Uri=v4l2:///dev/video0
CameraSrv.Camera.0.FramerateN=15
CameraSrv.Camera.0.FramerateD=1
CameraSrv.Camera.0.ImageWidth=320
CameraSrv.Camera.0.ImageHeight=240
CameraSrv.Camera.0.Format=RGB888

The first paragraph define the network configuration, that is the address where our server will be listening to request. Next paragraph define the number of cameras our server will provide. And following it, we have the configuration for the cameras. Notice that each camera will have its parameters after the prefix CameraSrv.Camera.X., with X in the interval [0..NCameras). In this example we have only one camera. A camera has several parameters:

  • Name: Name use to serve this camera. The interface for this camera will have this name.
  • ShortDescription: A short description of this camera taht may be used by the client to retrieve more information about the camera than only a name.
  • Uri: String that define the video source.
  • FramerateN: Frame rate numerator.
  • FramerateD: Frame rate denominator.
  • ImageWidth: Size of the served image.
  • ImageHeight: Size of the served image.
  • Format: A string defining the format of the served image. Cameraserver use libcolorspacesmm to manage the image formats. Currently accepted formats are RGB888 for RGB 24bits and YUY2.

Cameraserver can serve several types of sources. Each of them are named using the parameter uri with a syntax like:

type-of-source://source-descriptor

where type of source can be one of this:

  • v4l or v4l2: For V4l and V4l2 cameras respectively. Source descriptor will name the device name, e.g. v4l2:///dev/video0
  • file: For video files. Source descriptor will name the file, e.g file:///home/user/file.avi
  • http or https: For files located in a web server. Source descriptor will name the remote resource, e.g http://webserver.com/file.avi
  • videotest: For a test video signal with pure colors and noise. Source descriptor will name the video test pattern from 0 to 12 (may differ with gstreamer version), e.g videotest://0
  • others: Gstreamer support a big variety of urls to name resources as rtsp, cd, dvd, but not all of them have been fully tested yet.

Inside cameraserver

cameraview

motiondetection

gazeboserver

gazeboserver is a component to communicate with gazebo using JDErobot platform. It's possible to retrieve information from several sensor devices, such us: laser, encoders, cameraand ptencoders sonar, ptencoders. It's also possible to control robot's behaviour by sending control signals to motors and ptmotors.

In the initial version, it's assumed gazebo robot just supports one sensor/actuator of each type.

Provided Interfaces


Required Interfaces

gazeboserver bases its capabilities on gazebo platform comunication. Any gazeboserver provided interface requieres a equivalent service in gazebo. As mentioned above, for the time beign, the gazebo robot reference is fixed at code level and it maps "robot1" sensors and actuators.

Example: 

...

 <model:Pioneer2DX>
    <id>robot1</id>
    <xyz>2. 2. 0.200</xyz>
     <rpy>0.0 0.0 0.0</rpy>	
    <model:SickLMS200>
      <id>laser1</id>
      <xyz>0.0 0.0 0.00</xyz>	
     <model:SonyVID30>
        <id>camera1</id>
        <xyz>0 0 0.2</xyz>
	<renderMethod>xlib</renderMethod>
      </model:SonyVID30>
      <rayCount>180</rayCount>
      <rangeCount>180</rangeCount>
    </model:SickLMS200>

  </model:Pioneer2DX>


...

Using gazeboserver

To use gazeboserver we just have to edit the component's configuration to set ICE communication channel plus the video source and and format. On this initial version, the reference paths to gazebo robot is hardcoded yet. It'll be one of the coming changes, to support gazebo robot's name as well as available devices in the same configuration file.

A configuration file example may be like this: 

#network configuration
CameraSrv.Endpoints=default -h 127.0.0.1 -p 9999

#cameras configuration
CameraSrv.NCameras=1

#camera 1
GazeboServer.Camera.0.Name=cameraA
GazeboServer.Camera.0.ImageWidth=320
GazeboServer.Camera.0.ImageHeight=240
GazeboServer.Camera.0.Format=RGB888

The first paragraph define the network configuration, that is the address where our server will be listening to request. Next paragraph define the number of cameras our server will provide. Although, this format is open to support several cameras description, it's just only one recognized by the code during gazebo communication. It's an identified improvement to work with a second camera. And following it, we have the configuration for the cameras. Notice that each camera will have its parameters after the prefix CameraSrv.Camera.X., with X in the interval [0..NCameras). In this example we have only one camera. Refer to cameraserver description, in order to know more about the meaning of each field. Gaseboserver and cameraserver provides the same camera interface and, therefore, use a common configuration format on this file.

introrob

introrob is a component to visualize robot sensor information and to control its actuators. It's implemented with a GUI that facilitates the usage of these capabilities. The initial version was develop for working with gazeboserver component though it's possible to adapt its configuration file to refer to different data signals.

As it was supported the previous version of JDERobot 4.3,

to communicate with gazebo using JDErobot platform. It's possible to retrieve information from several sensor devices, such us: laser, encoders, cameraand ptencoders sonar, ptencoders. It's also possible to control robot's behaviour by sending control signals to motors and ptmotors.

In the initial version, it's assumed gazebo robot just supports one sensor/actuator of each type.

Provided Interfaces

Nothing but GUI for introbot user. It's also posible to encapsulate a different navigation code in an specific class, with all sensor data available and actuators interfactes, in order to change robots behaviour when "Your code" mode is selected. It's very useful to test different navigation algorithms on different gazebo worlds. See below, more information about how to adaptate navigation logic for automatic mode.

Required Interfaces

Note: All of them are served by gazeboserver altough they can be individually redirect to different providers (i.e: camera coming from cameraserver and not from gazeboserver).

Configuring introrob

To use introrob we just have to edit the component's configuration to set the sensor and actuator pointers. This current specification will be improved during the next months:

A configuration file example may be like this: 

Introrob.Camera.Proxy=cameraA:tcp -h 127.0.0.1 -p 9999
Introrob.Motors.Proxy=motors1:tcp -h 127.0.0.1 -p 9999
Introrob.Laser.Proxy=laser1:tcp -h 127.0.0.1 -p 9999
Introrob.Encoders.Proxy=encoders1:tcp -h 127.0.0.1 -p 9999

With the format "Introrob.X.Proxy=Y:Z", it is possible to specify the individual services to be used. X corresponds to sensor or actuator name: Motors, PTMotors, Encoders, PTEncoders, Sonars, Camera, Laser. Y refers to service name (how it has been denominated at ICE interface). The example shows the default name given by gazeboserver. Finally, Z means the network connection path (protocol, IP address and TCP port).

Using introrob

Introrob provides the following interface by default:

In the left side of the window, a scrolled canvas area is shown for representing robot's map, and laser and sonar measurements. It's also a zoom bar which can be used to increase or decrease the pizel per unit factor on cavas rectangle.

On the right side, from top to bottom, we find first a radio button menu which allows the user to chose between manual navigation and automatic one (base on your code behind). If manual navigation is pressed, two scrolled bars are displayed, one to select V (linear speed) value and the other to do the same with W (angular speed). Both have a reset button bellow, in order to change the value to 0 (stop linear or radial speed).

In both modes (automatic or manual), it's possible to pause the navigation by clicking "stop" button. It's a toggled button type, so it can be pressed twice to enable again the navigation.

Finally, camera display is represented in the righ-bottom corner. It's also provides frame-per-second (fps) figure.

Changing introrob automatic navigation logic

Introrob has the following classes distribution: 


  ICE API <----> introrob ------> introrobgui ---> introrobcanvas
                     |            
                     |
                     v
                  navega

introrob class is the main class, responsable for communicating with ICE services, open graphical interface and feed it with sensor data, cath menu events and implement a reaction and and coordinate navigation changes.

introrobgui is accountable for any GUI update and manual navigation event catch. It uses introrobcanvas to represent canvas area information.

navega embbeds automatic mode navigation logic. All this logic is located at navegacion method, inside navega class. From this method, it's possible to access to any sensor information and save V, W values robot behaviour update.

Libs

Colorspacesmm

JDErobot 5.0 SVN

Download and access to 5.0 development sources

Version 5.0 is available in one development branch of JDErobot SVN repository. Once you download this repository by running the following command: 

svn co http://svn.jderobot.org/jderobot

version 5.0 is available at "./jderobot/branches/5.0"

JDErobot 5.0 SVN folder organization

Under 5.0 repository, the following folders are available:

Retrieved from "http://www.jderobot.org/index.php/Manual-5"
Personal tools