FAQ

The very beggining

What is this FAQ for?

This FAQ aims to solve some questions about:

• using the tools around Jderobot project like Svn, Trac, MediaWiki, Blog, etc
• using third-party software like Gazebo, Player, OpenGL, etc..
• it also explains some good community conventions and good practices.

For a detailed description about using JDE software or programming applications with Jderobot, better check the Manual page.

What is Jderobot?

This is better explained at the Manual page.

How can I download and compile Jderobot?

This is better explained at the Manual page.

Player and Stage

Stage is a multiple robot 2D simulator Player provides a network interface to a variety of robot and sensor hardware. It has become a de facto standard in robotics. They all belongs to the same open source project, check their official web page for further details and downloads.

If you are going to work only with Player and Stage, the releases Player 3.2.2 and Stage 4.0.0 and known to work fine with JDE-4.3, but they are not compatible with Gazebo-0.7.

How to install Player 3.2.2 and Stage 4.0.0

If you can't install the oldest version of Player and Stage then you can follow this steps to install the latest released version of those tools.

Installing Player

Installing Stage 4.0.0

3. Pioneer Configuration File

We can find the pioneer configuration file on this path /usr/local/share/player/config/pioneer.cfg. The default configuration is:

driver
(
  name "p2os"
  provides ["odometry:::position2d:0"
            "compass:::position2d:1"
            "gyro:::position2d:2"
            "sonar:0"
            "aio:0"
            "dio:0"
            "power:0"
            "bumper:0"
            "gripper:::gripper:0"
            "blobfinder:0"
            "sound:0"
           ]
  port "/dev/ttyS0"
)

driver
(
  name "sicklms200"
  provides ["laser:0"]
  port "/dev/ttyS2"
)

But now, because of we use a new scanning laser (Hokuyo), the configuration file must be like this:

driver
(
  name "p2os"
  provides ["odometry:::position2d:0"
	    "power:0"
	    "bumper:0"
           ]
  port "/dev/ttyS0"
)

driver
(
  name "urglaser"
  provides ["laser:0"]
  port "/dev/ttyACM0"
  pose [0.0 0.0 0.0]
  baud "19200"
  min_angle -90.0
  max_angle 90.0
  alwayson 1
)

The Pioneer platform is connected by serial port (S0) and the new Hokuyo laser by USB (ACM0). Sometimes we'll have to change it by ACM1 (thanks to Ubuntu features...). And we don't recommended to change the rest of parameters (baud, min_angle, max_angle and alwayson); the device can stop working.

Executing Stage and Player

After it you can test your installation typing:

>> robot-player /usr/share/stage/worlds/simple.cfg

* Part of the Player/Stage/Gazebo Project [http://playerstage.sourceforge.net].
* Copyright (C) 2000 - 2006 Brian Gerkey, Richard Vaughan, Andrew Howard,
* Nate Koenig, and contributors. Released under the GNU General Public License.
* Player comes with ABSOLUTELY NO WARRANTY.  This is free software, and you
* are welcome to redistribute it under certain conditions; see COPYING
* for details.

trying to load /usr/share/stage/worlds/libstageplugin...
trying to load /usr/lib/libstageplugin...
success
invoking player_driver_init()...
 Stage driver plugin init

 ** Stage plugin v2.0.3 **
 * Part of the Player/Stage Project [http://playerstage.sourceforge.net]
 * Copyright 2000-2006 Richard Vaughan, Andrew Howard, Brian Gerkey
 * and contributors. Released under the GNU General Public License v2.
success
  Stage driver creating 1 device
   6665.31.0 is a Stage world [Loading /usr/share/stage/worlds/simple.world][Include pioneer.inc][Include map.inc][Include sick.inc]

  Stage driver creating 1 device
   6665.42.0 is "cave"
  Stage driver creating 2 devices
   6665.4.0 is "robot1"
   6665.6.0 is "robot1.laser:0"
Listening on ports: 6665 

Jderobot Wiki's FAQ

How do I show video in the wiki?

This wiki can show videos with flv format and youtube format.

Youtube videos

The syntax is:

{{#ev:youtube|id_youtube}}

FLV Videos

The syntax is:

<video [width=XX height=YY image=src] > path_to_video </video>

The parameters width, height and image are optionals:

• width: set the video's width (default: 320)
• heigth: set the video's height (default: 240).
• image: set the image that appears at the beginning of the video ( by default appears "peloto"). This value can be show through an extern url ()

path_to_video is the path where the video is saved in flv format. The path may be local ( in DocumentRoot of mediawiki ) or external as http://server/video.flv

Example 1: Only specify the video's path. Others parameters are taken by default.

<video>http://gsyc.es/jmplaza/multimedia/multiwatcher.flv</video>

Example 2: Specify all the values

<video width=400 height=320 image=http://gsyc.es/jmplaza/pioneer.png> http://gsyc.es/jmplaza/multimedia/atencion3d2006.flv </video>

All videos must be in flv format. This not a problem because mencoder can convert to this format.

How do I convert OGG to FLV video

ffmpeg -i videoOGG.ogg videoFLV.flv

If you want to add some features; for example bitrate, aspect ratio,... You must write something like this:

ffmpeg -i videoOGG.ogg -b 163840 -s 512x288 -ar 44100 videoFLV.flv

How do I convert AVI to FLV video

You can use mencoder tool

mencoder video.avi -o video.flv -noskip -mc 0 -of lavf -oac mp3lame -lameopts abr:br=56 -ovc lavc -lavcopts 
 vcodec=flv:vbitrate=500:mbd=2:mv0:trell:v4mv:cbp:last_pred=3 -srate 22050

How do I upload a file?

If you have an active user account at jderobot.org, you can upload files using "scp" or "sftp" utilities.

It's possible to establish a secured ftp connection to jderobot in order to upload/download files to/from your account directory (/users/${USERNAME}). See below one example, where not only a video file is uploaded but also some directories are created by using standard ftp commands:

jvazquez@ubuntu:~/ROBOTICS/SVN/users/jvazquez/tfm/trunk/practica1_introrob$ sftp jvazquez@jderobot.org
Connecting to jderobot.org...
The authenticity of host 'jderobot.org (193.147.71.110)' can't be established.
RSA key fingerprint is be:23:2d:19:6b:49:d2:13:ac:3c:49:3f:35:79:d0:0d.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'jderobot.org' (RSA) to the list of known hosts.
jvazquez@jderobot.org's password: 
sftp> pwd
Remote working directory: /users/jvazquez
sftp>
sftp> mkdir videos
sftp> cd videos
sftp> put vff_obstacles_v2.ogv
Uploading vff_obstacles_v2.ogv to /users/jvazquez/videos/vff_obstacles_v2.ogv
vff_obstacles_v2.ogv                                                                        100% 5142KB  32.8KB/s   02:37    
sftp> 

You could access to "/user/${USERNAME}" contents with a HTTP URL like http://jderobot.org/users/${USERNAME}.

As an alternative to "sftp" command, secured copy is also available.

jvazquez@ubuntu:~/ROBOTICS/SVN/users/jvazquez/tfm/trunk/practica1_introrob$ scp vff_obstacles_v1.ogv  jvazquez@jderobot.org:/users/jvazquez/videos/
jvazquez@jderobot.org's password: 
vff_obstacles_v1.ogv     
jvazquez@ubuntu:~/ROBOTICS/SVN/users/jvazquez/tfm/trunk/practica1_introrob$ 

Jderobot Blog's FAQ

How do I register to the blog?

• First, you must register here.

• Later, you send an e-mail to jde-developers [at] gsyc [point] es commenting your register to elevate your role on the blog.

How do I add content to the blog?

It's easy. You must go to this link: http://blog.jderobot.org/wp-admin. And then, log in with your username and password. Now, you can go to "Write" tab. When you have finished to write it, click on the "Publish" button.

How do I show video in the blog?

You can insert youtube video and flash video in this blog. When you write a post, you can see the buttons “YT Video” and “FLV” (see image). Use this buttons to insert videos in your post

How to collaborate with the Jderobot community

How do I notify a bug?

If you found a bug, the first step that you should do is update ot last version of subversion, and check that bug may be reproduced. If you can reproduce the bug and you haven't permits in trac tool, you can send an e-mail to jde-developers [at] gsyc.es with subject [BUG] - little description, tell us:

• The steps to reproduce the bug.
• Jde's version.
• Operative System and version.
• Traces of bug ( if is possible ).

If you want to get traces of bug, you can do it this way:

$ gdb ./jde 
(gdb) run [put here the options that you use for this execution]

When the execution crash, write:

(gdb) bt

Attach the result in your mail.

How do I notify a bug through Jderobot trac?

If you want to notify a bug and you have permits on trac tool, you should create a new ticket in order to developers can solve it. Before creating the ticket, you should check that the bug hasn't been notificated previously. The first step to create a ticket is logging in the trac tool as you log in your project svn. After that, you have to push 'New Ticket' button in the menu:

Then, you have to fill some information about the bug in this form:

You should write a short summary that explains the bug quickly. In the box below, you should write a full description including the same information mentioned in the previous section:

• The steps to reproduce the bug.
• Jderobot's version.
• Operative System and version.
• Traces of bug ( if is possible ).

In the ticket properties, you should fill some fields, most important are:

• Component: specify type of component that has the bug.
• Milestone: select 'improving' by defect.
• Version: select 'trunk' by defect.
• Assing to: you don't need to fill it.
• Cc: if you want to receive news about the ticket state, you can put your e-mail here.

Finally, you have to push 'Submit ticket' button.

How do I send a patch or new feature?

If you are able to find the solution of a bug or you have added a new feature, send:

• An e-mail to jde [at] gsyc.es with subject [FIX-BUG - little description] or [FEATURE - little description]
• Attach the patch generate with this command (execute this command in work local copy of subversion):

$ svn diff > path_[date]_[versionJDE].patch

It's very important that you say us the version of JDE you used to create the patch. The more recent the jde version at svn, the easier is to integrate into the development release of Jde.

Ideally, in order to solve a given bug:

1. first, download the latest release,
2. second, modify the source code to solve the bug
3. third, generate the patch,
4. and fourth, send the patch to the email list, as mentioned before.

Removing gearbox

At this moment we have to compile JdeRobot with Gearbox. This dependency is uncomfortable. If you follow the next steps, you can delete the dependency from yours components.

First at all, delete the next includes:

#include <gbxsickacfr/gbxiceutilacfr/safethread.h>
#include <jderobotice/component.h>
#include <jderobotice/application.h>

Now change the inheritance of the ReplyTask class. Remove:

class ReplyTask: public gbxiceutilacfr::SafeThread 

Replace for:

class ReplyTask: public IceUtil::Thread

Rename the method who execute the thread "walk()" for "run()"

Remove the component Class. And create the server in the main thread. Here you can see some source code of the inicializacion of the cameraServer

    Ice::CommunicatorPtr ic;
    try{
        ic = Ice::initialize(argc, argv);

        Ice::PropertiesPtr prop = ic->getProperties();

        std::string Endpoints = prop->getProperty("CameraSrv.Endpoints");

      ...

          Ice::ObjectAdapterPtr adapter =
                  ic->createObjectAdapterWithEndpoints(cameraName, Endpoints);

          Ice::ObjectPtr object = new cameraserver::CameraI(objPrefix, ic);

          adapter->add(object, ic->stringToIdentity(cameraName));

          adapter->activate();
        }
        ic->waitForShutdown();

Programming style

Documenting the code

We use doxygen as code documentation system, so we can easily generate an online version of the API documentation. Adding doxygen comments to your code is as easy as adding regular comments, you just have to follow some rules and learn a small set of tags. You can find a complete manual here.

This is a documented code snippet with some examples of doxygen documentation:

/**
 *  A test class. A more elaborate class description.
 */

class Test
{
  public:

    /** 
     * An enum.
     * More detailed enum description.
     */

    enum TEnum { 
          TVal1, /**< enum value TVal1. */  
          TVal2, /**< enum value TVal2. */  
          TVal3  /**< enum value TVal3. */  
         } 
       *enumPtr, /**< enum pointer. Details. */
       enumVar;  /**< enum variable. Details. */
       
      /**
       * A constructor.
       * A more elaborate description of the constructor.
       */
      Test();

      /**
       * A destructor.
       * A more elaborate description of the destructor.
       */
     ~Test();
    
      /**
       * a normal member taking two arguments and returning an integer value.
       * @param a an integer argument.
       * @param s a constant character pointer.
       * @see Test()
       * @see ~Test()
       * @see testMeToo()
       * @see publicVar()
       * @return The test results
       */
       int testMe(int a,const char *s);
       
      /**
       * A pure virtual member.
       * @see testMe()
       * @param c1 the first argument.
       * @param c2 the second argument.
       */
       virtual void testMeToo(char c1,char c2) = 0;
   
      /** 
       * a public variable.
       * Details.
       */
       int publicVar;
       
      /**
       * a function variable.
       * Details.
       */
       int (*handler)(int a,int b);
};

And here you can see the html generated documentation.

Raspberry Pi

Some of the Jderobot components are supported for Raspberry and others are in development. To simplify the use of this single board computer here you can find a SD image with all you need to start developing jderobot for ARM:

• Jderobot 5.0
• OpenCV 2.3.1
• Ice 3.4
• Gearbox 9.11
• OpenNI 2

To drop the image to the SD card: $ if=jderobot-raspberry.img of=/dev/sdX (where sdX is your SD)

How to create debian packages

As you can see in this section, you can install JdeRobot easily by packages. If you want to create a debian package for your code, the best and more automated way to do that is following these steps:

• First, create a directory called <package>-<version>. In this example we are going to package the component cameraserver, so the created directory is going to be at jderobot/trunk/src/components and its name will be jderobot-cameraserver-5.1.1. In this directory you have to put the code, config and cmake files, etc. of cameraserver; but we have to modify the CMakeLists.txt to make this packaging easier. Now, this directory has the following files: cameraserver.cpp, cameraserver.cfg and CMakeLists.txt.

• Modify the CMakeLists.txt file to do all the necessary stuff in one file, like this:

project ( JDEROBOT_CAMERASERVER )

cmake_minimum_required ( VERSION 2.8 )

SET( THESE_SOURCE_FILES cameraserver.cpp)

SET( INTERFACES_CPP_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../../interfaces/cpp) # Directorio con las interfaces ICE en C++
SET( LIBS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../../libs) # Directorio donde se encuentran las librerias propias de jderobot
SET( DEPS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../../../Deps) # Directorio donde se encuentran las dependencias

SET( CMAKE_CXX_FLAGS "-lIce -lIceUtil" ) # Opciones para el compilador

####################
#                  #
#   CHECK SYSTEM   #
#                  #
####################

  # FIND AND CHECK OTHER DEPENDENCES
include(${DEPS_DIR}/gearbox/CMakeLists.txt)
include(${DEPS_DIR}/ice/CMakeLists.txt)
include(${DEPS_DIR}/opencv/CMakeLists.txt)

# START RECURSIVE
add_subdirectory (${CMAKE_CURRENT_SOURCE_DIR}/../.. ${CMAKE_CURRENT_SOURCE_DIR}/../..)

include_directories(
	${INTERFACES_CPP_DIR}
	${LIBS_DIR}
	${CMAKE_CURRENT_SOURCE_DIR}
)

add_executable (../cameraserver ${THESE_SOURCE_FILES})

find_package(OpenCV REQUIRED)

TARGET_LINK_LIBRARIES(../cameraserver 
	${OpenCV_LIBRARIES}        
	${LIBS_DIR}/jderobotice/libjderobotice.so
	${LIBS_DIR}/colorspaces/libcolorspacesmm.so
	${INTERFACES_CPP_DIR}/jderobot/libJderobotInterfaces.so
	${Gearbox_LIBRARIES}
	${ZeroCIce_LIBRARIES}
)

###############
#             #
#   INSTALL   #
#             #
###############
# Install Executables
FILE(GLOB_RECURSE BIN_FILES ${CMAKE_CURRENT_SOURCE_DIR}/*cfg)
    string(REGEX REPLACE ".*/(.*).cfg" "\\1" new_source1 ${BIN_FILES})
INSTALL (FILES ${new_source1}  DESTINATION /usr/local/bin PERMISSIONS OWNER_EXECUTE GROUP_EXECUTE WORLD_EXECUTE)

# Install CONF
FILE(GLOB_RECURSE CONF_FILES  ${CMAKE_CURRENT_SOURCE_DIR}/*cfg)
INSTALL (FILES ${CONF_FILES} DESTINATION /usr/local/share/jderobot/conf)

• In the created directory jderobot-cameraserver-5.1.1, type:

dh_make --createorig

This sentence allows you to automatically create a "debian" directory inside of your directory, This new directory is very important: it contains all the files necessary to create the debian package. Now, you are going to edit two files, the "control" and "rules". The "control" file will be like this:

Source: jderobot-cameraserver
Section: devel
Priority: extra
Maintainer: Your Name <your_e-mail>
Build-Depends: debhelper (>= 8.0.0), cmake
Standards-Version: 3.9.2
Homepage: <insert the upstream URL, if relevant>

Package: jderobot-cameraserver
Architecture: i386
Depends: ${shlibs:Depends}, ${misc:Depends}, jderobot-gearbox, jderobot-opencv, libc6 (>= 2.4), libdc1394-22, libgcc1 (>= 1:4.1.1), libglib2.0-0 (>= 2.12.0), libicebox34, libicegrid34, libicepatch2-34, libicessl34, libicestorm34, libiceutil34, libicexml34, libraw1394-11, libstdc++6 (>= 4.1.1), libxml2 (>= 2.6.27), libzeroc-ice34, jderobotinterfaces, jderobotlib-jderobotice, jderobotlib-jderobotutil, libraw1394-dev, libdc1394-22-dev
Description: <insert up to 60 chars description>
 <insert long description, indented with spaces>

The important thing is "Depends". In this line you have to put all the libraries that your component depends on. Next, you have to edit the "rules" file:

#!/usr/bin/make -f
# -*- makefile -*-
# Sample debian/rules that uses debhelper.
# This file was originally written by Joey Hess and Craig Small.
# As a special exception, when this file is copied by dh-make into a
# dh-make output file, you may use that output file without restriction.
# This special exception was added by Craig Small in version 0.37 of dh-make.

# Uncomment this to turn on verbose mode.
#export DH_VERBOSE=1

%:
	dh $@ --buildsystem=cmake

override_dh_usrlocal:

The only difference with the original "rules" file is the sentences "--buildsystem=cmake" and "override_dh_usrlocal:". The first sentence allows you to use cmake instead of autotools, so is very powerful; the second sentence allows you to override the usr/local of your new "debian" directory (this is important because in other way the packaging will not end satisfactory).

• Now you are able to create the .deb packages. You just have to type:

dpkg-buildpackage -rfakeroot

And the code will be compiled and your debian package created at jderobot/trunk/src/components. So, now, you are able to install it with:

sudo dpkg -i jderobot-cameraserver_5.1.1-1_i386.deb

Important notes

• If you don't have dh_make installed, just type:

sudo apt-get install dh-make 

• Pay attention on the "Install" of your CMakeLists.txt and don't allow cmake to install files that are already installed: then the installation will crash.

• If you have a message similar to "failed to remove debian/blablabla" Directory not empty, please, follow this mini-guide.

• If you have any problem and you want to start again creating your packages, you have to remove all files in "/tmp" and all files starting as "jderobot-cameraserver-5.1.1_" (that are in the same folder as your jderobot-cameraserver-5.1.1 directory).