Installation of the robotic tools

The robotic tools should be installed on any system that hosts components of the software architecture for the Robotic platform. This section details the installation process.

Note

For all the guidelines gathered here, we will assume that you are using Ubuntu GNU/Linux as it is the supported distribution for ROS (though any other UNIX platform should be suited to the GenoM3 tools). Many commands given here are intended for the bash shell. If you use a different shell, you should adapt the bash-related commands accordingly.

Install ROS

The ROS distribution you can install will depend on your Ubuntu version:

Install the GenoM3 tools through robotpkg

This section will guide you through the installation of the GenoM3 tools. GenoM3 is open-source software (available at https://git.openrobots.org/) and can be compiled from source, but the common installation uses robotpkg, a compilation framework and packaging system for robotics software (more information at http://robotpkg.openrobots.org/).

Get robotpkg on your system

Note

The following instructions invite you to download two git repositories. If the given URLs using git:// protocol fail, try https:// protocol as instructed here and there. If you need an introduction to git have a look at Git for beginners.

First, get the robotpkg repository in your home folder (you can choose another location, but we recommend this one):

cd
git clone git://git.openrobots.org/robots/robotpkg

You will also need the wip subset of robotpkg, it contains some work in progress that is not officially released, but already available:

cd ~/robotpkg
git clone git://git.openrobots.org/robots/robotpkg/robotpkg-wip wip

Next, set the installation path. The tools that you will soon install will be placed in your home folder under a dedicated folder named openrobots. Installing robotic components in your home folder ensures that you do not need root privileges for the installation (you can choose another location with a different prefix, but we recommend this one):

cd ~/robotpkg/bootstrap
./bootstrap --prefix $HOME/openrobots

To finish, update your environment variables to include the installation folder:

Note

In the following commands, note the use of an environment variable ROBOTPKG_BASE to indicate your installation path, set to $HOME/openrobots. If you have selected a different location at the previous step, you should modify the corresponding command accordingly.

echo >> ~/.bashrc
echo '# ROBOTPKG' >> ~/.bashrc
echo 'export ROBOTPKG_BASE=$HOME/openrobots' >> ~/.bashrc
echo 'export PATH=$PATH:$ROBOTPKG_BASE/bin:$ROBOTPKG_BASE/sbin' \
     >> ~/.bashrc
echo 'export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:\
     $ROBOTPKG_BASE/lib/pkgconfig' >> ~/.bashrc
echo 'export ROS_PACKAGE_PATH=$ROS_PACKAGE_PATH:\
     $ROBOTPKG_BASE/src/ros-nodes:$ROBOTPKG_BASE/share' >> ~/.bashrc
echo 'export PYTHONPATH=$PYTHONPATH:\
     $ROBOTPKG_BASE/lib/python2.7/site-packages:\
     $ROBOTPKG_BASE/lib/python3.2/site-packages' >> ~/.bashrc
echo '# ROBOTPKG END' >> ~/.bashrc
source ~/.bashrc

How to install a robotpkg package

Your ~/robotpkg directory contains a tree of packages, grouped into main categories. In the next part, we will invite you to install some of those packages. Here, we expose you the guidelines to follow for each package.

  1. Add options to the package

    If you are asked to add options option-1 option-2 ... to the package pkg-name, edit the file ~/openrobots/etc/robotpkg.conf and add a line (near the beginning for instance) looking like:

    PKG_OPTIONS.pkg-name+= option-1 option-2 ...
    

    You will get a better idea about this step with an actual example in the next part.

  2. Move to the package’s directory

    You will be given the path to the package, such as robotpkg/category/pkg-name. Change to this directory:

    cd ~/robotpkg/category/pkg-name
    
  3. Install possibly missing system dependencies

    Run the following command to list the dependencies for the package you are about to install:

    make show-depends
    

    At the end of the command’s output, the dependencies are separated into Robotpkg dependencies and System dependencies. If any robotpkg dependency is missing, it will be automatically installed. If any system dependency is missing, you need to install it (commonly with apt-get under Ubuntu). Iterate this step until no system dependency is missing.

    You may skip this step, but if a system dependency is missing, the package installation will stop at some point and you will be asked to install it.

  4. Install the package

    Run the following command:

    make update
    

    This will download the sources, compile them locally on your system, and install the output files in the ~/openrobots directory.

Install packages for GenoM3

  • Install the package demo-genom3 from robotpkg/doc/demo-genom3 with options codels ros-server ros-client-ros ros-client-c.

    This package will install the demo component. It is a sample component distributed with GenoM3, serving as an example, simply controlling the motion of a fictional robot. The aim of installing the demo component is twofold: first, it automatically installs all the dependencies for using GenoM3 (the provided options specifying that we will use the ROS templates); second, you get a GenoM3 component ready to be run to start using the robotic tools.

    For your convenience, here is how applying the above steps could look like:

    # 1. Add options to the package
    echo 'PKG_OPTIONS.demo-genom3+= codels ros-server ros-client-ros ros-client-c'\
          >> ~/openrobots/etc/robotpkg.conf
    # or better, edit the file manually and add the line near the beginning
    
    # 2. Change to the package's directory
    cd ~/robotpkg/doc/demo-genom3
    
    # 3. Install missing system dependencies
    make show-depends
    # Let's say that `make show-depends` revealed two missing system
    # dependencies named 'bison' and 'flex'. Next step would be:
    sudo apt-get install bison flex
    make show-depends
    # No missing system dependency left
    
    # 4. Install the package
    make update
    
  • Then, install the packages genomix from robotpkg/net/genomix and rosix from robotpkg/net/rosix.

    genomix and rosix are HTTP servers providing an interface for some clients to control GenoM3 components and generic ROS nodes respectively.

  • Then, install the packages tcl-genomix from robotpkg/supervision/tcl-genomix and matlab-genomix from robotpkg/supervision/matlab-genomix.

    These are clients of genomix and rosix servers. The tcl-genomix client allows to control components using the Tcl language. Its installation is not mandatory (we will rather use the matlab-genomix client), but recommended as a common package distributed with GenoM3. The matlab-genomix client allows to control components from Matlab.

    Note

    You need a Matlab installation on your system in order to install the matlab-genomix package. If you encounter a missing dependency for mex (the MEX compiler from Matlab), you need to add the path to Matlab executables to the PATH environment variable. For example, with Matlab R2013a installed in /usr/local/MATLAB/R2013a, it would be done with:

    export PATH=$PATH:/usr/local/MATLAB/R2013a/bin
    

The GenoM3 tools are now installed on your system. If you want to try the Matlab bridge, you can follow the official tutorial using the demo component. You can also follow the instructions below to install BASS, an audio streaming server component and later on follow the tutorial Stream binaural signals from BASS to Matlab.

Note

The Matlab bridge is installed in ~/openrobots/lib/matlab. To follow the tutorials using matlab-genomix, you need to add this path to the Matlab path.

Install a GenoM3 component from the sources

Instructions

The software part of the Two!Ears robotic architecture includes several GenoM3 components. You may have to install them from their source files. Each GenoM3 component has its own folder, containing a description file named after the component with the .gen extension (something like component.gen). These steps will install the component in your ~/openrobots folder:

cd path/to/component/folder
genom3 skeleton -i component.gen
./bootstrap.sh
mkdir build && cd build
../configure --prefix=$ROBOTPKG_BASE --with-templates=ros/server,ros/client/c
make install

Example: installing the BASS component

BASS is a component for binaural audio streaming. The folder for this component is named bass-genom3, under the RoboticPlateform folder of the software repository (see the installation guide). Applying the above commands to install BASS gives:

# assuming that you are in the software repository
cd RoboticPlateform/bass-genom3
genom3 skeleton -i bass.gen
./bootstrap.sh
mkdir build && cd build
../configure --prefix=$ROBOTPKG_BASE --with-templates=ros/server,ros/client/c
make install

Note

You might need additional ALSA libraries, like libasound-dev or libasound2-dev, to install the BASS component (commonly with apt-get under Ubuntu).