How to install the software on your machine (Ubuntu 16)

Follow these guidelines for the installation on Ubuntu 16.04

0) Environment variables (bashrc file)

During the installation, you will need to add many environment variables, this is typically done in the bashrc file. However, you will end up with many new environment variables. For this reason, we strongly suggest you to write them in a separate file called from within the original bashrc. So, in order to maintain things organized and avoid messing up with the original bashrc, we will create the file bashrc_icub.

This also allows new users to debug more easily =)

Create an empty bashrc_icub file in /home/$USER/icub/software

Now, open the original bashrc file with your preferred text editor (here, we use gedit):

gedit ~/.bashrc

Then add these lines into bashrc at the beginning of the file just before the "running interactively" comment:

# iCub software
  if [ -f /home/$USER/icub/software/bashrc_icub ]; then
      . /home/$USER/icub/software/bashrc_icub
  fi

1) Dependencies

Prepare the machine by installing the libraries that you need to compile the systems. You can do it either automatically (not advised) or manually (advised).

Automatically

The dependencies for yarp and icub-main can be retrieved automatically by doing apt-get of the debian package icub-common:

sudo apt-get install icub-common

For further instructions on http://wiki.icub.org/wiki/Linux:Installation_from_sources

Manually

The list of dependencies is in the script file used to build icub-common: https://github.com/robotology/icub-packaging/blob/master/linux/config.sh#L22

We advise you to manually update your dependencies following the list on the script, by using the instructions below:

sudo apt-get install subversion git cmake cmake-curses-gui
sudo apt-get install wget unzip openssh-server
sudo apt-get install sphinx-common python-dev python-numpy python-tk

sudo apt-get install libc6 libncurses5-dev
sudo apt-get install libace-dev
sudo apt-get install libgsl0-dev
sudo apt-get install libcv-dev libhighgui-dev libcvaux-dev libopencv-dev
sudo apt-get install libsdl1.2-dev
sudo apt-get install gfortran
sudo apt-get install libxmu-dev
sudo apt-get install libode4 libode-dev
sudo apt-get install qtbase5-dev qtdeclarative5-dev qtmultimedia5-dev libqt5svg5
sudo apt-get install freeglut3-dev
sudo apt-get install libtinyxml-dev
sudo apt-get install libgoocanvasmm-2.0-dev
sudo apt-get install swig
sudo apt-get install libeigen3-dev

At some point, YARP and iCub ask for the name of the robot. This is a variable that is used to identify in priority the configuration files of your robot. Our robot is iCubNancy01. To automatize the compilation, you will need to add your first line to bashrc_icub. Just insert the following line:

export YARP_ROBOT_NAME=iCubNancy01

2) IPOPT

IPOPT is an optimization library used in many icub modules, such as the kinematics and Cartesian modules.

sudo apt-get install coinor-libipopt-dev

3) Install YARP

The project github repository is here: https://github.com/robotology/yarp The detailed instructions for the installations are described here: http://www.yarp.it/install_yarp_linux.html Quick instructions:

cd /home/$USER/icub/software/src
git clone https://github.com/robotology/yarp
cd yarp
mkdir build
cd build
ccmake ..

The first time you open cmake to configure your project, a "empty cache" message will appear. Just press c to configure cmake the first time, and the cmake variables will be available.

When you configure cmake, you can choose to specify a specific location for the installation by changing the variable CMAKE_INSTALL_PREFIX (see below).

You should also set some flags CREATE_GUIS=on to enable the graphical user interfaces (GUI) and CREATE_LIB_MATH=on to enable the mathematical library.

If you are going to use CODYCO modules please set the flag BUILD_SHARED_LIBS=on (toggle to see it).

If you are not sure what other flags do, don't change the default values.

We advise to either:

1. NOT install - keep a local copy of your binary and add the /bin folder to your PATH

2. install locally in a folder that you can easily access with your account and not as root: for example, /icub/software, and not the default /usr/local. This can be done by changing the flag CMAKE_INSTALL_PREFIX when you do ccmake. If you keep /usr/local, then you will have to install by doing sudo make install. If you change into **/icub/software** (or any path in your home), then you can install with a simple make install (without sudo). The advantage of having installed binaries is that you can test compiled versions without overwriting a functioning binary (useful for debugging). Once done configuring, press c until g becomes an option, then press g to generate and exit.

You can now compile:

make
<OPTIONAL> make install

If you choose /home/$USER/icub/software as installation prefix, once you do make install you will have the following folders:

/home/$USER/icub/software/bin => to be added to PATH
/home/$USER/icub/software/lib => to be added to LD_LIBRARY_PATH

In your bashrc, you should now have the following variables:

export YARP_ROBOT_NAME=iCubNancy01
export YARP_DIR=/home/$USER/icub/software/src/yarp/build
export YARP_DATA_DIRS=$YARP_DATA_DIRS:/home/$USER/icub/software/share/yarp
export PATH=$PATH:/home/$USER/icub/software/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/$USER/icub/software/lib

Note that if you choose not to do make install, then you have to add the /bin and /lib folders inside your /build.

Before proceeding run:

source /home/$USER/icub/software/bashrc_icub

To load the required environment variables

4) Install ICUB

The project github repository is here: https://github.com/robotology/icub-main Detailed instructions for the installation are here: http://wiki.icub.org/wiki/Linux:Installation_from_sources Quick instructions:

cd /home/$USER/icub/software/src
git clone https://github.com/robotology/icub-main
cd icub-main
mkdir build
cd build
ccmake ..

Again, there are some flags to be set. If you choose the local installation, change CMAKE_INSTALL_PREFIX to ~/icub/software or to the location of your choice. For the flags, set:

ENABLE_icubmod_cartesiancontrollerclient ON
ENABLE_icubmod_cartesiancontrollerserver ON
ENABLE_icubmod_gazecontrollerclient      ON
ICUB_SHARED_LIBRARY ON

ICUB_SHARED_LIBRARY is found in advanced mode. Press t to toggle ccmake to advanced mode.

Now you can compile:

make
<OPTIONAL> make install

Remember to do make install only if you choose to install on a local folder.

Now you should have the following environmental variables in your bashrc:

export ICUB_DIR=/home/$USER/icub/software/src/icub-main/build/
export YARP_DATA_DIRS=$YARP_DATA_DIRS:/home/$USER/icub/software/share/yarp:/home/$USER/icub/software/share/iCub

If you installed everything in /home/$USER/icub/software, then PATH and LD_LIBRARY_PATH are already ok:

export PATH=$PATH:/home/$USER/icub/software/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/$USER/icub/software/lib:/home/$USER/icub/software/src/Ipopt/build/lib

5) Test your installation

The best way to test your installation is to run one of the tutorials. Download the project here: https://github.com/robotology/icub-tutorials

cd /home/$USER/icub/software/src
git clone https://github.com/robotology/icub-tutorials

motorControlBasic

We start by trying motorControlBasic:

cd icub-tutorials/src/motorControlBasic
mkdir build
cd build
ccmake ..
make

This will create an executable tutorial_arm. To test it, you need to launch yarp and the iCub simulator first.

=> on terminal tab 1:

yarpserver

=> on terminal tab 2:

iCub_SIM

You need to check the name of your robot now. => on terminal tab 3:

yarp name list

There should be several ports starting with the name of your robot, for example: /icubSim/torso/state:o , which means icubSim = name of the robot, torso = body part, state = joint encoders position, o=output (it means that we can read the output streaming from this port).

You can now launch tutorial_arm with the correct name of the robot: => on terminal tab 4:

./tutorial_arm --robot icubSim

The robot should move its right arm. If so, congratulations! You can move the arm sending joint positions. Press CTRL+C to stop moving the arm by closing the thread.

motorControlAdvanced

Now let's verify if we can control the Cartesian position of the end-effector. We need to try the tutorial named motorControlAdvanced.

cd motorControlAdvanced
mkdir build
cd build
ccmake ..
make

Check the instructions on tutorial_cartesian_interface.cpp to discover why we need to launch two more modules. In short, do:

=> on terminal tab 4:

yarprobotinterface --context simCartesianControl

Note: If yarprobotinterface.ini is not found do:

export YARP_DATA_DIRS=$YARP_DATA_DIRS:/home/$USER/icub/software/share/iCub/contexts/simCartesianControl

=> on terminal tab 5:

iKinCartesianSolver --context simCartesianControl --part left_arm

If you get an error in launching this module, for example it attempts to open a port with icub and not icubSim, then look for the file cartesianSolver.ini (in my case it is in /home/icub/software/share/iCub/robots/iCubNancy01) and then change the robot name inside into icubSim.

Now you can launch the tutorial:

=> on terminal tab 6:

./tutorial_cartesian_interface

You should see the iCub arm moving making a circle. Congratulations! Your system is set up and you can start coding.

The tutorial documentation is here: http://wiki.icub.org/iCub/main/dox/html/icub_tutorials.html Please read these pages to get more information about YARP and iCub libraries!!!

We strongly recommend to read all tutorials (especially the code), in this order:

misc/relay => shows how to read from a YARP port and write on a YARP port
rateThread => shows how to play with Threads
motorControlBasic => joint position control
motorControlAdvanced => cartesian control of the hands
motorControlImpedance => compliant control

These are the basics for starting to control the robot (simulated or real).

6) Install Gazebo simulator for iCub

The default simulator coming with icub-main, iCub_SIM, is based on ODE. It is very practical if you want to test some robot movements (e.g., hand gestures, gaze) and also the camera view from the robot eyes. However, if you are interested in whole-body movements, leg movements, forces etc, then you need a better simulator, like Gazebo.

a) Gazebo

Note:
The installation tutorials for Gazebo are in its official page: http://gazebosim.org/tutorials?cat=install
The installation notes for Ubuntu are here: http://gazebosim.org/tutorials?tut=install_ubuntu&cat=install

Very quick instructions:

sudo apt-get install curl
curl -ssL http://get.gazebosim.org | sh

To test if gazebo is installed, now type:

gazebo

b) gazebo_yarp_plugins

Now you can proceed with installing the yarp plugin for gazebo. The project is here: https://github.com/robotology/gazebo-yarp-plugins To install, follow the instructions on the README page on github. Quick instructions:

git clone https://github.com/robotology/gazebo-yarp-plugins.git
cd gazebo-yarp-plugins
mkdir build
cd build
ccmake ..
make install

Note that while doing ccmake you can set the installation folder for the plugin files. We highly recommend an handy place for that, for example /home/icub/software, since you have to add to the environmental variable GAZEBO_PLUGIN_PATH in your bashrc the path containing the library files libgazebo_yarp_controlboard.so etc, that should be in your install folder + /lib :

export GAZEBO_PLUGIN_PATH=$GAZEBO_PLUGIN_PATH:/home/icub/software/lib

c) icub-gazebo

To import iCub in gazebo, now you need to download its simulation files. The project is here: https://github.com/robotology/icub-gazebo Follow the readme in the github project for the installations instructions. Quick instructions:

git clone https://github.com/robotology-playground/icub-gazebo.git

Then simply add some lines to the bashrc.

At the end of this process, you should have the following lines in the bashrc related to gazebo:

#GAZEBO VARIABLES
#----------------------------------------
export GAZEBO_PLUGIN_PATH=$GAZEBO_PLUGIN_PATH:/home/icub/software/lib

if [ -z "$GAZEBO_MODEL_PATH" ]; then
    export GAZEBO_MODEL_PATH=/home/$USER/icub/software/src/icub-gazebo
else
    export GAZEBO_MODEL_PATH=$GAZEBO_MODEL_PATH:/home/$USER/icub/software/src/icub-gazebo
fi

To start gazebo with iCub, just launch: => on terminal 1:

yarpserver

=> on terminal 2:

gazebo

Then select one of the iCubs in the model list. For example, iCub with hands. You can start moving the robot joints using the motor-gui interface: => on terminal 3:

yarpmotorgui --robot icubSim

7) Install CODYCO

If you want to install the Matlab and Simulink interface for iCub, then you need to install also the CODYCO project modules. The project repository is here: https://github.com/robotology/codyco-superbuild You can follow the github readme for installations instructions, but we suggest you to follow these following instructions.

First check that your system meets all the dependencies (you should have already most of them) :

sudo apt-get install libeigen3-dev build-essential cmake cmake-curses-gui libboost-system-dev libboost-filesystem-dev libboost-thread-dev libboost-iostreams-dev libtinyxml-dev libace-dev libgtkmm-2.4-dev libglademm-2.4-dev libgsl0-dev libcv-dev libhighgui-dev libcvaux-dev libode-dev liblua5.1-dev lua5.1 git swig

Quick instructions:

cd /home/$USER/icub/software/src
git clone https://github.com/robotology/codyco-superbuild.git
cd codyco-superbuild
mkdir build
cd build
ccmake ../

Now setting the cmake flags can be a little tricky. Please refer to the installations instructions (https://github.com/robotology/codyco-superbuild) to have more details. In our case we suggest:

CMAKE_INSTALL_PREFIX=/home/$USER/icub/software => even if for the moment, the superbuild does not support global installation, i.e., there is no make install
CODYCO_USES_MATLAB=on => Required if you want to use the Simulink controllers and the WBI
COYCO_USES_WBI_TOOLBOX=on => Useful for the motor friction identification
CODYCO_USES_WBI_TOOLBOX_CONTROLLERS=on => Contains the codyco controllers in Simulink
CODYCO_USES_MEX_WHOLEBODYMODEL => Matlab MEX interface to the wholeBodyModel C++ interface, 

Don't worry about the missing folders/projects as the superbuild will download them automatically. Just pay attention that cmake finds the projects that you have already installed (yarp, icub-main etc). When the cmake is configured, just do

make

Note:
Without doing make install as for the moment the global install is not supported.

You also have to add the path of this project in some variables. In bashrc_icub add:

# CODYCO
#----------------------------------------
export CODYCO_SUPERBUILD_ROOT=/home/$USER/icub/software/src/codyco-superbuild

# Modify YARP_DATA_DIRS with:
export YARP_DATA_DIRS=$YARP_DATA_DIRS:$CODYCO_SUPERBUILD_ROOT/build/install/share/codyco

# Modify your paths with:
export PATH=$PATH:$CODYCO_SUPERBUILD_ROOT/build/install/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CODYCO_SUPERBUILD_ROOT/build/install/lib/

After updating the library path configuration (source ~/.bashrc), you should also run ldconfig:

 sudo ldconfig

Finally, you have to configure paths in Matlab:

The easiest way to do it is to run from within MATLAB the startup_codyco_superbuild.m script located at ~/icub/software/src/codyco-superbuild/build/. Note that you only need to run it once to configure your MATLAB paths.

You can test your code by following this link or the following lines.

First, in bashrc_icub change the robot name:

export YARP_ROBOT_NAME=icubGazeboSim Terminal 1:

yarpserver

Terminal 2: (Add the icub WITHOUT hands in gazebo. Right now, the model with hands causes the simulation to fail)

gazebo -slibgazebo_yarp_clock.so

Terminal 3: (click on the home all button. I think it is normal if there is the warning "no head_zeros" since with the choosed .ini file we don't care how the head is initialized.)

yarpmotorgui --from homePoseBalancingLegsZero.ini --robot icubSim

Note:
As of now, the initial configuration from homePoseBalancingLegsZero.ini doesn't seem to be working.

Terminal 4:

wholeBodyDynamicsTree --autoconnect --robot icubGazeboSim

Terminal 5:

./twoFeetStandingIdleAndCalib.sh

Terminal 6:

matlab

In Matlab, you need to launch torqueBalancing.mdl (or its respective Matlab version) in /home/$USER/icub/software/src/codyco-superbuild/main/WBIToolboxControllers/controllers/torqueBalancing. Open Simulink, hit the run button and you should be good to go and see your simulated iCub performing some yoga movements =).

Note:
As of now, the full simulation leads the robot to fall at the very end of its Yoga presentation.

Troubleshoot!

• Problems with libstdc++

It is common for Matlab to use its own version of a library that it is already provided by the system. This may cause some (or many!) runtime errors. This is further discussed in WB-Toolbox and in this issue. As a quick fix to the problem, we preload the system variables (before Matlab has the chance to load its own).

For instance, you can use the same Matlab alias we used. Just add the following line to bashrc_icub:

alias matlab_codyco="cd ~/Documents/MATLAB && LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6 matlab"

Just remember to run matlab_codyco from now on, instead of matlab. Note, that you can also use:

alias matlab="cd ~/Documents/MATLAB && LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6 matlab"

If you don't mind matlab to always preload libstdc++ .

8) Install other iCub projects' code.

There are many projects around with code that can be used for iCub. Here's a list:

https://github.com/robotology/icub-contrib-common

<<< more instructions to come >>>