Skip to content

Latest commit

 

History

History
696 lines (525 loc) · 50.7 KB

README.md

File metadata and controls

696 lines (525 loc) · 50.7 KB
Raw

robotology-superbuild

This is a meta repository (so-called "superbuild") that uses CMake and YCM to automatically download and compile software developed in the robotology GitHub organization, such as the YARP middleware or software used to run the iCub humanoid robot.

CMake is an open-source, cross-platform family of tools designed to build, test and package software. A YCM Superbuild is a CMake project whose only goal is to download and build several other projects. If you are familiar with ROS, it is something similar to catkin or colcon workspace, but using pure CMake for portability reasons and for customizing the build via CMake options. You can read more about the superbuild concept in YCM documentation or in the related IRC paper.

System Continuous Integration Status
Linux/macOS/Windows GitHub Actions Status

Table of Contents

Superbuild structure

robotology-superbuild will download and build a number of software. For each project, the repository will be downloaded in the robotology/<package_name> subdirectory of the superbuild root. The build directory for a given project will be instead the robotology/<package_name> subdirectory of the superbuild build directory. All the software packages are installed using the install directory of the build as installation prefix. If there is any non-robotology dependency handled by the superbuild as it is not easily in the system, it will located in the external directory instead of the robotology one.

Superbuild CMake options

As a huge number of software projects are developed in the robotology organization, and a tipical user is only interested in some of them, there are several options to instruct the superbuild on which packages should be built and which one should not be built.

Profile CMake options

The profile CMake options specify which subset of the robotology packages will be built by the superbuild. Note that any dependencies of the included packages that is not available in the system will be downloaded, compiled and installed as well. All these options are named ROBOTOLOGY_ENABLE_<profile> .

CMake Option Description Main packages included Default Value Profile-specific documentation
ROBOTOLOGY_ENABLE_CORE The core robotology software packages, necessary for most users. YARP, ICUB, ICUBcontrib, icub-models and robots-configurations. GazeboYARPPlugins and icub-gazebo if the ROBOTOLOGY_USES_GAZEBO option is enabled. ON Documentation on Core profile.
ROBOTOLOGY_ENABLE_ROBOT_TESTING The robotology software packages related to robot testing. RobotTestingFramework, icub-tests, blocktest and blocktest-yarp-plugins OFF Documentation on Robot Testing profile.
ROBOTOLOGY_ENABLE_DYNAMICS The robotology software packages related to balancing, walking and force control. iDynTree, blockfactory, wb-Toolbox, whole-body-controllers, walking-controllers. icub-gazebo-wholebody if the ROBOTOLOGY_USES_GAZEBO option is enabled. OFF Documentation on Dynamics profile.
ROBOTOLOGY_ENABLE_ICUB_HEAD The robotology software packages needed on the system that is running on the head of the iCub robot, or in general to communicate directly with iCub low-level devices. icub-firmware, icub-firmware-shared, diagnostic-daemon. Furthermore, several additional devices are compiled in YARP and ICUB if this option is enabled. OFF Documentation on iCub Head profile.
ROBOTOLOGY_ENABLE_ICUB_BASIC_DEMOS The robotology software packages needed to run basic demonstrations with the iCub robot. icub-basic-demos, speech, funny-things. OFF Documentation on iCub Basic Demos profile.
ROBOTOLOGY_ENABLE_TELEOPERATION The robotology software packages related to teleoperation. walking-teleoperation. To use Oculus or Cyberith Omnidirectional Treadmill enable ROBOTOLOGY_USES_OCULUS_SDK and ROBOTOLOGY_USES_CYBERITH_SDK options. OFF Documentation on teleoperation profile.
ROBOTOLOGY_ENABLE_HUMAN_DYNAMICS The robotology software packages related to human dynamics estimation. human-dynamics-estimation, wearables, forcetorque-yarp-devices. For options check the profile documentation. OFF Documentation on human dynamics profile.

If any of the packages required by the selected profiles is already available in the system (i.e. it can be found by the find_package CMake command ), it will be neither downloaded, nor compiled, nor installed. In robotology-superbuild, this check is done by the find_or_build_package YCM command in the main CMakeLists.txt of the superbuild.

By default, the superbuild will use the package already available in the system. If the user wants to ignore those packages and have two different versions of them, then he/she should set the CMake variable USE_SYSTEM_<PACKAGE> to FALSE. For further details, please refer to YCM Superbuild Manual for Developers.

Dependencies CMake options

The dependencies CMake options specify if the packages dependending on something installed in the system should be installed or not. All these options are named ROBOTOLOGY_USES_<dependency>.

CMake Option Description Default Value Dependency-specific documentation
ROBOTOLOGY_USES_GAZEBO Include software and plugins that depend on the Gazebo simulator. ON on Linux and macOS, OFF on Windows Documentation on Gazebo dependency.
ROBOTOLOGY_USES_MATLAB Include software and plugins that depend on the Matlab. OFF Documentation on MATLAB dependency.
ROBOTOLOGY_USES_OCTAVE Include software and plugins that depend on Octave. OFF Documentation on Octave dependency.
ROBOTOLOGY_USES_OCULUS_SDK Include software and plugins that depend on Oculus. OFF Documentation on Oculus dependency.
ROBOTOLOGY_USES_CYBERITH_SDK Include software and plugins that depend on Cyberith. OFF Documentation on Cyberith dependency.
ROBOTOLOGY_USES_CFW2CAN Include software and plugins that depend on CFW2 CAN custom board. OFF No specific documentation is available for this option, as it is just used with the iCub Head profile, in which the related documentation can be found.
ROBOTOLOGY_USES_XSENS_MVN_SDK Include software and plugins that depend on Xsens MVN SDK. OFF Documentation on Xsens MVN dependency
ROBOTOLOGY_USES_ESDCAN Include software and plugins that depend on Esd Can bus. OFF Documentation on ESDCAN dependency

Installation

We provide different instructions on how to install robotology-superbuild, depending on your operating system:

The exact versions of the operating systems supported by the robotology-superbuild follow the one supported by the YARP library, that are documented in https://github.com/robotology/yarp/blob/master/.github/CONTRIBUTING.md#supported-systems . Complete documentation on how to use a YCM-based superbuild is available in the YCM documentation.

Linux

System Dependencies

On Debian based systems (as Ubuntu) you can install the C++ toolchain, Git, CMake and Eigen (and other dependencies necessary for the software include in robotology-superbuild) using apt-get:

sudo apt-get install libeigen3-dev build-essential cmake cmake-curses-gui coinor-libipopt-dev freeglut3-dev libboost-system-dev libboost-filesystem-dev libboost-thread-dev libtinyxml-dev libedit-dev libace-dev libgsl0-dev libopencv-dev libode-dev liblua5.1-dev lua5.1 git swig qtbase5-dev qtdeclarative5-dev qtmultimedia5-dev qml-module-qtquick2 qml-module-qtquick-window2 qml-module-qtmultimedia qml-module-qtquick-dialogs qml-module-qtquick-controls qml-module-qt-labs-folderlistmodel qml-module-qt-labs-settings libsdl1.2-dev libxml2-dev libv4l-dev

For what regards CMake, the robotology-superbuild requires CMake 3.12 . If you are using a recent Debian-based system such as Debian 10 or Ubuntu 20.04, the default CMake is recent enough and you do not need to do further steps.

If instead you use an older distro in which the default version of CMake is older, you can easily install a newer CMake version in several ways. For the following distributions, we recommend the following methods:

  • Ubuntu 18.04 : use the latest CMake release in the Kitware APT repository. You can find the full instructions for the installation on the website.
  • Debian 9 : use the CMake in the stretch-backports repository, following the instructions to install from backports available in Debian documentation. More details can be found at robotology/community#364 .

If you enabled any profile or dependency specific CMake option you may need to install additional system dependencies, following the dependency-specific documentation (in particular, the ROBOTOLOGY_USES_GAZEBO option is enabled by default, so you should install Gazebo unless you plan to disable this option):

Superbuild

If you didn't already configured your git, you have to set your name and email to sign your commits:

git config --global user.name FirstName LastName
git config --global user.email [email protected]

Finally it is possible to install robotology software using the YCM superbuild:

git clone https://github.com/robotology/robotology-superbuild.git
cd robotology-superbuild
mkdir build
cd build
ccmake ../
make

You can configure the ccmake environment if you know you will use some particular set of software (put them in "ON"). See Superbuild CMake options for a list of available options.

Configure your environment

Currently the YCM superbuild does not support building a global install target, so all binaries are installed in robotology-superbuild/build/install/bin and all libraries in robotology-superbuild/build/install/lib.

To use the binaries and libraries installed by the robotology-superbuild, you should update the enviroment variables of your process such as PATH and CMAKE_PREFIX_PATH.

The superbuild provides an automatically generated setup.sh sh script that will set all the necessary enviromental variables. To do so automatically for any new terminal that you open, append the following line to the .bashrc file:

source <directory-where-you-downloaded-robotology-superbuild>/build/install/share/robotology-superbuild/setup.sh

To use the updated .bashrc in your terminal you should run the following command:

user@host:~$ source ~/.bashrc

If may also be necessary to updates the cache of the dynamic linker:

user@host:~$ sudo ldconfig

If for any reason you do not want to use the provided setup.sh script and you want to manage your enviroment variables manually, please refer to the documentation available at doc/environment-variables-configuration.md .

macOS

System Dependencies

To install the system dependencies, it is possible to use Homebrew:

brew install ace boost cmake eigen gsl ipopt jpeg libedit opencv pkg-config qt5 sqlite swig tinyxml

Since Qt5 is not symlinked in /usr/local by default in the homebrew formula, Qt5_DIR needs to be properly set to make sure that CMake-based projects are able to find Qt5.

export Qt5_DIR=/usr/local/opt/qt5/lib/cmake/Qt5

If you want to enable a profile or a dependency specific CMake option, you may need to install additional system dependencies following the dependency-specific documentation (in particular, the ROBOTOLOGY_USES_GAZEBO option is enabled by default, so you should install Gazebo unless you plan to disable this option):

Superbuild

If you didn't already configured your git, you have to set your name and email to sign your commits:

git config --global user.name FirstName LastName
git config --global user.email [email protected]

Finally it is possible to install robotology software using the superbuild:

git clone https://github.com/robotology/robotology-superbuild.git
cd robotology-superbuild
mkdir build
cd build

To use GNU Makefile generators:

cmake ../
make

To use Xcode project generators

cmake ../ -G Xcode
xcodebuild [-configuration Release|Debug] [-jobs <n>] [-list | -target <target_name>]

-list gives the list of available targets.

Configure your environment

Currently the YCM superbuild does not support building a global install target, so all binaries are installed in robotology-superbuild/build/install/bin and all libraries in robotology-superbuild/build/install/lib.

To use the binaries and libraries installed by the robotology-superbuild, you should update the enviroment variables of your process such as PATH and CMAKE_PREFIX_PATH.

The superbuild provides an automatically generated setup.sh sh script that will set all the necessary enviromental variables. To do so automatically for any new terminal that you open, append the following line to the .bash_profile file:

source <directory-where-you-downloaded-robotology-superbuild>/build/install/share/robotology-superbuild/setup.sh

To use the updated .bash_profile in your terminal you should run the following command:

user@host:~$ source ~/.bash_profile

or simply open a new terminal.

If for any reason you do not want to use the provided setup.sh script and you want to manage your enviroment variables manually, please refer to the documentation available at doc/environment-variables-configuration.md .

Windows

Disclaimer

While the robotology software is tested to be fully compatible with Windows, the Gazebo simulator that is widely used for simulation with robotology software does not support Windows.

For this reason if you plan to do use the robotology software with the Gazebo simulator on Windows, for the time being it is easier for you to use the Windows Subsystem for Linux.

System Dependencies

As Windows does not have a widely used system package manager such as the one that are available on Linux or macOS, installing the system dependencies is slightly more compliated. However, we try to document every step necessary for the installation, but you find something that you don't understand in the documentation, please open an issue.

Visual Studio

Most of the robotology software is developed using the C/C++ language. For this reason, you should have Visual Studio, the official Microsoft compiler for Windows, installed on your computer to compile the software in the superbuild. Only Visual Studio 2019 targeting the 64 bit platform is currently supported by the robotology-superbuild. Pay attention to enable the C++ support (https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation) when first installing the Visual Studio compiler, as by default C++ support is not installed.

Git

Most of the robotology software is hosted on Git repositories, so you will need Git to download them. You can download the Git installer at http://msysgit.github.io/ .

CMake

To install CMake you can use the official installer available at http://www.cmake.org/cmake/resources/software.html . It is recommended to install the latest version of CMake.

Rapid Enviroment Editor

While this tool is not strictly required, it is convenient to install the Rapid Environment Editor to easily modify the value of the environment variables in Windows.

System Libraries

The software in the superbuild depends on several C++ libraries: to install the required dependencies on your machine, we suggest to use vcpkg, the C++ library manager mantained by Microsoft. As vcpkg compiles from sources all its libraries, this can be quite time intensive for some libraries such as qt5 or opencv.

For this reason, we provide a ready to use vcpkg workspace at https://github.com/robotology/robotology-superbuild-dependencies-vcpkg/releases, that you can download and unzip in C:/ and use directly from there, for example executing the following commands from the Git Bash shell:

cd C:/
wget https://github.com/robotology/robotology-superbuild-dependencies-vcpkg/releases/download/v0.3.0/vcpkg-robotology.zip
unzip vcpkg-robotology.zip -d C:/
rm vcpkg-robotology.zip

or creating the directories and extracting the archive through the File Explorer. If you prefer to use your own vcpkg to install the dependencies of the superbuild, please refer to the documentation available at doc/vcpkg-dependencies.md.

If you want to enable the ROBOTOLOGY_USES_GAZEBO option, you will need to download and extract the vcpkg-robotology-with-gazebo.zip archive. For instructions on how to correctly use this archives, please refer to documentation of the robotology-superbuild-dependencies-vcpkg) repo.

If you want to enable a profile or a dependency specific CMake option, you may need to install additional system dependencies following the dependency-specific documentation:

Superbuild

If you didn't already configured your git, you have to set your name and email to sign your commits:

git config --global user.name FirstName LastName
git config --global user.email [email protected]

After that you can clone the superbuild repository as any other git repository, i.e. if you use terminal you can write:

git clone https://github.com/robotology/robotology-superbuild

or you can use your preferred Git GUI.

Once you cloned the repository, you can generate the Visual Studio solution using the CMake GUI, by using as a generator the appropriate Visual Studio version, and the 64 bit as a platform, and specifying the vcpkg CMake toolchain as discussed in the previous section. In particular, see the nicely written CGold documentation if you do not know how to generate a Visual Studio solution from a CMake project.

You can then open the generated solution with Visual Studio and build the target all.

Visual Studio will then download, build and install in a local directory all the robotology software and its dependencies. If you prefer to work from the command line, you can also compile the all target using the following command (if you are in the robotology-superbuild/build directory, and the directory of the cmake.exe exectuable is in the PATH :

cmake --build . --config Release

Configure your environment

Currently the YCM superbuild does not support building a global install target, so all binaries are installed in robotology-superbuild/build/install/bin and all libraries in robotology-superbuild/build/install/lib.

To use the binaries and libraries installed by the robotology-superbuild, you should update the enviroment variables of your process such as PATH and CMAKE_PREFIX_PATH.

If you are an heavy user of the software installed by the robotology-superbuild, you may want to update your user enviroment variables to permit you to use the robotology-superbuild software from any Windows process. To automatically update the user enviroment variables, the robotology-superbuild provides the addPathsToUserEnvVariables.ps1 and removePathsFromUserEnvVariables.ps1 available at <directory-where-you-downloaded-robotology-superbuild>/build/install/share/robotology-superbuild/. As indicated by their name, addPathsToUserEnvVariables.ps1 is used to setup the enviroment variables used by the robotology-superbuild, while removePathsFromUserEnvVariables.ps1 permits to cleanly remove them. To configure the robotology-superbuild, just run the addPathsToUserEnvVariables.ps1 script once in a Powershell terminal.

To check the values of the enviroment variables modified by the powershell scripts provided by the superbuild, you can use a program such as Rapid Enviroment Editor.

If you do not want to modify the user enviroment variables permanently, the superbuild provides an automatically generated setup.bat batch script in <directory-where-you-downloaded-robotology-superbuild>/build/install/share/robotology-superbuild/setup.bat. This script will set all the necessary enviromental variables to use the software installed by the robotology-superbuild. However, as in Windows there is no .bashrc file-equivalent, you will need to call this script every time you open a batch terminal in which you want to run the software installed by the robotology-superbuild.

Another option if you do not want to to modify the user enviroment variables permanently and you use the Git Bash as your main terminal, is to use the automatically generated setup.sh script, available in <directory-where-you-downloaded-robotology-superbuild>/build/install/share/robotology-superbuild/setup.sh. You can source automatically this script for any new Git Bash instance by creating a .bash_profile file in your C:/Users/<UserName> directory, and by adding in it the file:

source <directory-where-you-downloaded-robotology-superbuild>/build/install/share/robotology-superbuild/setup.sh

If for any reason you do not want to use the provided scripts and you want to manage your enviroment variables manually, for example because you want to cleanup the enviroment variables modified by addPathsToUserEnvVariables.ps1 and you delete the corresponding removePathsFromUserEnvVariables.ps1, please refer to the documentation available at doc/environment-variables-configuration.md .

If you have problems in Windows in launching executables or using libraries installed by superbuild, it is possible that due to some existing software on your machine your executables are not loading the correct dll for some of the dependencies. This is the so-called DLL Hell, and for example it can happen if you are using the Anaconda Python distribution on your Windows installation. To troubleshoot this kind of problems, you can open the library or executable that is not working correctly using the Dependencies software. This software will show you which DLL your executable or library is loading. If you have any issue of this kind and need help, feel free to open an issue in our issue tracker.

Windows Subsystem for Linux

The Windows Subsystem for Linux (wsl) lets developers run a GNU/Linux environment -- including most command-line tools, utilities, and applications -- directly on Windows, unmodified, without the overhead of a virtual machine.

As all the software running on Linux distributions can run unmodified on Windows via WSL, to install the robotology-superbuild in WSL you can just install a Debian-based distribution for WSL, and then follow the instructions on how to install the robotology-superbuild on Linux. As the WSL enviroment is nevertheless different, there are few things you need to care before using the robotology-superbuild on WSL, that are listed in the following.

Run graphical applications on WSL

To run graphical applications on WSL, you need to install a X Server for Windows, that will be able to visualize the windows WSL-based applications, see https://www.howtogeek.com/261575/how-to-run-graphical-linux-desktop-applications-from-windows-10s-bash-shell/ for more info. For information of X Servers that can be installed on Windows, follow the docs in https://github.com/sirredbeard/Awesome-WSL#10-gui-apps .

Sanitize enviroment variables for WSL

By default, the PATH enviroment variable in WSL will contain the path of the host Windows system, see microsoft/WSL#1640 and microsoft/WSL#1493. This can create problems, as the CMake in WSL may find (incompatible) Windows CMake packages and try to use them, creating errors due to the compilation. To avoid that, you can add the following line in the WSL .bashrc that filters all the Windows paths from the WSL's enviromental variables:

for var in $(env | awk {'FS="="} /\/mnt\//{print $1}'); do export ${var}=\"$(echo ${!var} | awk -v RS=: -v ORS=: '/\/mnt\// {next} {print $1}')\" ; done

Update

For updating the robotology-superbuild repository it is possible to just fetch the last changes using the usual git command:

git pull

However, for running the equivalent of git pull on all the repositories managed by the robotology-superbuild, you have to run in your build system the appropriate target. To do this, make sure to be in the build directory of the robotology-superbuild and run:

make update-all
make

using make on Linux or macOS or

cmake --build . --target UPDATE_ALL
cmake --build .

using Visual Studio on Windows or

cmake --build . --target ALL_UPDATE
cmake --build .

using Xcode on macOS.

Note that the update will try to update all the software in the robotology-superbuild, and it will complain if the repository is not in the expected branch. For this reason, if you are activly developing on a repository managed by the robotology-superbuild, remember to switch the YCM_EP_DEVEL_MODE_<package_name> option to TRUE. This option will ensure that the superbuild will not try to automatically update the <package_name> repository. See https://robotology.github.io/ycm/gh-pages/git-master/manual/ycm-superbuild.7.html#developer-mode for more details on this options.

By default, the robotology-superbuild uses the latest "stable" branches of the robotology repositories, but in some cases it may be necessary to use the "unstable" active development branches, or use some fixed tags. For this advanced functionalities, please refer to the documentation on changing the default project tags, available at doc/change-project-tags.md.

Profile-specific documentation

Core

This profile is enabled by the ROBOTOLOGY_ENABLE_CORE CMake option.

System Dependencies

The steps necessary to install the system dependencies of the Core profile are provided in operating system-specific installation documentation.

Check the installation

Follow the steps in http://wiki.icub.org/wiki/Check_your_installation to verify if your installation was successful.

Robot Testing

This profile is enabled by the ROBOTOLOGY_ENABLE_ROBOT_TESTING CMake option.

System Dependencies

The steps necessary to install the system dependencies of the Robot Testing profile are provided in operating system-specific installation documentation, and no additional required system dependency is required.

Check the installation

If the profile has been correctly enabled and compiled, you should be able to run the robottestingframework-testrunner and blocktestrunner executable from the command line.

Dynamics

This profile is enabled by the ROBOTOLOGY_ENABLE_DYNAMICS CMake option.

System Dependencies

The steps necessary to install the system dependencies of the Dynamics profile are provided in operating system-specific installation documentation, and no additional required system dependency is required.

The only optional system dependency of wb-toolbox, project part of this profile, is tbeu/matio.

Linux

Install matio using the following command:

sudo apt install libmatio-dev

macOS

Install matio from homebrew/core using the following command:

brew install libmatio

Windows

Install matio following the installation instructions present in the repository.

iCub Head

This profile is enabled by the ROBOTOLOGY_ENABLE_ICUB_HEAD CMake option. It is used in the system installed on iCub head, or if you are a developer that needs to access iCub hardware devices directly without passing through the iCub head.

Warning: the migration of existing iCub setups to use the robotology-superbuild is an ongoing process, and it is possible that your iCub still needs to be migrated. For any doubt, please get in contact with icub-support.

The configuration and compilation of this profile is supported on Linux, macOS and Windows systems.

On Linux all the software necessary to communicate with boards contained in the robot, including CAN devices via esd's CAN USB bridges, is already included.

On Windows to communicate with CAN devices via esd's CAN USB bridges you need to set to ON the Windows-only CMake option ROBOTOLOGY_ENABLE_ESDCAN.

On macOS, communication with esd's CAN USB bridges is not supported and diagnosticdaemon is not available because of #439.

This section documents the iCub Head profile as any other profile, in a way agnostic of the specific machine in which it is installed. To get information on how to use the robotology-superbuild to install software on the machine mounted in the head of physical iCub robots, please check the documentation in doc/use-on-icub-head.md.

System Dependencies

The steps necessary to install the system dependencies of the iCub Head profile are provided in operating system-specific installation documentation, and no additional required system dependency is required.

On old iCub systems equipped with the CFW2 CAN board, it may be necessary to have the cfw2can driver installed on the iCub head (it is tipically already pre-installed in the OS image installed in the system in the iCub head). In that case, you also need to enable the ROBOTOLOGY_USES_CFW2CAN option to compile the software that depends on cfw2can. In case of doubt, please always get in contact with icub-support.

Check the installation

The ROBOTOLOGY_ENABLE_ICUB_HEAD installs several YARP devices for communicating directly with embedded boards of the iCub. To check if the installation was correct, you can list all the available YARP devices using the yarpdev --list command, and check if devices whose name is starting with embObj are present in the list. If those devices are present, then the installation should be working correctly. Furthermore, if the profile has been correctly enabled and compiled, you should be able to run the diagnosticdaemon executable from the command line.

iCub Basic Demos

This profile is enabled by the ROBOTOLOGY_ENABLE_BASIC_DEMOS CMake option.

System Dependencies

The steps necessary to install the system dependencies of the iCub Basic Demos profile are provided in operating system-specific installation documentation, and no additional required system dependency is required.

Check the installation

If the iCub Basic Demos profile have been correctly installed, you should be able to find in your PATH and execute the demoYoga or demoRedBall executables.

Teleoperation

This profile is enabled by the ROBOTOLOGY_ENABLE_TELEOPERATION CMake option.

System Dependencies

To run a teleoperation scenario, with real robot or in simulation, at least we need a Windows machine and Linux/macOS machine. If you are using iCub, the linux/macOS source code can be placed on the robot head. The teleoperation dependencies are also related to the teleoperation scenario you want to perform.

Teleoperation without Cyberith treadmill

In this scenario, we only use Oculus for teleoperation, and we do not use Cyberith treadmill. In this case, the user can give the command for robot walking through the Oculus joypads. The dependencies for this scenario are as following:

Teleoperation with Cyberith treadmill

In this scenario, we use both Oculus and cyberith treadmill for teleopration. In this case, the user can give the command for robot walking through walking on cyberith treadmill. The dependencies for this scenario are as follwoing:

Human Dynamics

This profile is enabled by the ROBOTOLOGY_ENABLE_HUMAN_DYNAMICS CMake option.

System Dependencies

To run a human dynamics estimation scenario, we need a Windows machine to install the Xsens suit SDK for getting the sensory information of the human motions from Xsens and ESD USB CAN driver to get the FTShoes/FTSkShoes sensory information. Refer to Xsens and ESDCAN for more information about the dependencies.

Dependencies-specific documentation

Gazebo

Support for this dependency is enabled by the ROBOTOLOGY_USES_GAZEBO CMake option. This option is still set to OFF on Windows as it is still experimental.

System Dependencies

On Linux or macOS, install Gazebo following the instructions available at http://gazebosim.org/tutorials?cat=install . Make sure to install also the development files, i.e. libgazebo*-dev on Debian/Ubuntu.

On Windows, make sure that you install the Windows dependencies using the vcpkg-robotology-with-gazebo.zip archive and you set the correct enviroment variables as documented in robotology-superbuild-dependencies-vcpkg documentation.

Check the installation

Follow the steps in https://github.com/robotology/icub-gazebo#usage and/or https://github.com/robotology/icub-models#use-the-models-with-gazebo to check if the Gazebo-based iCub simulation works fine.

MATLAB

Support for this dependency is enabled by the ROBOTOLOGY_USES_MATLAB CMake option.

Warning: differently from other optional dependencies, MATLAB is a commercial product that requires a license to be used.

System Dependencies

If MATLAB is not installed on your computer, install it following the instruction in https://mathworks.com/help/install/ . Once you installed it, make sure that the directory containing the matlab executable is present in the PATH of your system, as CMake's FindMatlab module relies on this to find MATLAB.

Note: tipically we assume that a user that selects the ROBOTOLOGY_USES_MATLAB also has Simulink installed in his computer. If this is not the case, you can enable the advanced CMake option ROBOTOLOGY_NOT_USE_SIMULINK to compile all the subprojects that depend on MATLAB, but disable the subprojecs that depend on Simulink (i.e. the wb-toolbox Simulink Library) if you have enabled the ROBOTOLOGY_ENABLE_DYNAMICS CMake options.

Configuration

If MATLAB is installed on your computer, the robotology-superbuild can install some projects that depend on MATLAB, in particular:

To use this software, you can simply enable its compilation using the ROBOTOLOGY_USES_MATLAB CMake option. Once this software has been compiled by the superbuild, you just need to add some directories of the robotology-superbuild install (typically $ROBOTOLOGY_SUPERBUILD_SOURCE_DIR/build/install) to the MATLAB path. In particular you need to add to the MATLAB path the $ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX/mex directory and all the subdirectories $ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX/share/WBToolbox.

Start MATLAB from the launcher or the application menu

You could add this line to your MATLAB script that uses the robotology-superbuild matlab software, substituting <ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX> with the install folder inside the build directory of the superbuild:

    addpath(['<ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX>' '/mex'])
    addpath(['<ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX>' '/mex/+wbc/simulink'])
    addpath(['<ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX>' '/share/WBToolbox'])
    addpath(['<ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX>' '/share/WBToolbox/images'])

Another way is to run (only once) the script startup_robotology_superbuild.m in the $ROBOTOLOGY_SUPERBUILD_SOURCE_DIR/build folder. This should be enough to permanently add the required paths for all the toolbox that use MATLAB.

Start MATLAB from the terminal

You can add the folders by modifying the startup.m or the MATLABPATH environmental variable as described in official MATLAB documentation. If you are using the setup.sh or setup.bat script for configuring your environment, MATLABPATH is automatically populated with these directories.

For more info on configuring MATLAB software with the robotology-superbuild, please check the wb-toolbox README.

Check the installation

To verify that the compilation of ROBOTOLOGY_USES_MATLAB option was successful, try to run a script that uses the Matlab bindings of yarp and see if it executes without any error, for example:

yarpVec = yarp.Vector();
yarpVec.fromMatlab([1;2;3]);
yarpVec.toMatlab()

This scripts should print a 1 2 3 vector, but only if the yarp bindings are working correctly.

Octave

Support for this dependency is enabled by the ROBOTOLOGY_USES_OCTAVE CMake option.

System Dependencies

Linux

Install octave and the necessary development files using the following command:

sudo apt-get install liboctave-dev

macOS

Install octave using the following command:

brew install octave

Windows

The ROBOTOLOGY_USES_OCTAVE option is not supported on Windows, see #139 for more info.

Configuration

Add the $ROBOTOLOGY_SUPERBUILD_SOURCE_DIR/build/install/octave directory to your Octave path.

Check the installation

To verify that the compilation of ROBOTOLOGY_USES_OCTAVE option was successful, try to run a script that uses the Octave bindings of yarp and see if it executes without any error, for example:

yarpVec = yarp.Vector();
yarpVec.fromMatlab([1;2;3]);
yarpVec.toMatlab()

This scripts should print a 1 2 3 vector, but only if the yarp bindings are working correctly.

Python

Support for this dependency is enabled by the ROBOTOLOGY_USES_PYTHON CMake option.

Check the installation

Open a python interpreter and try to import modules, for example verify that import yarp works.

Oculus

Support for this dependency is enabled by the ROBOTOLOGY_USES_OCULUS_SDK CMake option.

Warning: at the moment the Oculus SDK does not support macOS and Linux, so this option is only supported on Windows.

System Dependencies

To check and install the Oculus SDK please follow the steps for Oculus SDK mentioned here.

Configuration

To configure the Oculus SDK follow the steps for Oculus SDK mentioned here.

Cyberith

Support for this dependency is enabled by the ROBOTOLOGY_USES_CYBERITH_SDK CMake option.

Warning: at the moment the Oculus SDK does not support macOS and Linux, so this option is only supported on Windows.

System Dependencies

To check and install the Cyberith SDK, please follow the steps for Cyberith SDK mentioned in here.

Configuration

To configure the Cyberith SDK please follow the steps for Cyberith SDK mentioned in here.

Xsens

Support for ROBOTOLOGY_USES_XSENS_MVN_SDK option is only enabled when the ROBOTOLOGY_ENABLE_HUMAN_DYNAMICS CMake option is set to ON.

Warning: at the moment the Xsens MVN SDK does not support macOS and Linux, so this option is only supported on Windows.

System Dependencies

To check and install the Xsens MVN SDK, please follow the steps for Xsens MVN SDK mentioned in here.

Configuration

To configure the Xsens MVN SDK please follow the steps for Xsens MVN SDK mentioned in here.

ESDCAN

The ROBOTOLOGY_USES_ESDCAN option is used to enable support for interacting with esd CAN devices on Windows. On Linux no special option is necessary, as the interconnection with esd CAN device is supported using the default SocketCAN Linux driver. Use of esd CAN devices is not supported in macOS .

System Dependencies

To compile the software enabled by the ROBOTOLOGY_USES_ESDCAN option (such as the icub-main's esdcan YARP driver) you need to install the esd CAN C library. This library is already contained in the vcpkg installation installed by the robotology-superbuild dependencies installer. If you use a custom vcpkg installation, you can install the esdcan-binary custom port from the robotology-vcpkg-binary-ports repo.

To actually run the software that uses the esd CAN devices, you also need to install the esd CAN Driver for your specific esd CAN device. The installers for the esd CAN Driver should have been provided by esd, so ask for them to who provided you with the esd CAN device you want to use.

Configuration

No additional configuration is required to use the software installed by the ROBOTOLOGY_USES_ESDCAN

Check the installation

Open a terminal, and check that amoung the device listed by yarpdev --list the esdcan YARP device is listed.

FAQs

See also YCM documentation for YCM's FAQs. For questions related to how to modify the rootology-superbuild itself, such as how to add a new package, how to do a release, check the Developers' FAQs document at doc/developers-faqs.md.

Which are the differences between the robotology-superbuild and the codyco-superbuild ?

The CoDyCo European project that funded the development and the mantainance of the codyco-superbuild ended in 2017 . The robotology-superbuild is the successor of the codyco-superbuild, but it is not limited to software developed in the CoDyCo project, but more in general software developed in the robotology GitHub organization.

Technically speaking, there are a few differences:

  • Projects in the codyco-superbuild were saved in the external, libraries or main directories subdirectories of the source and of the build directories. For the sake of simplicity, the robotology-superbuild just save robotology projects in the robotology directory and all external projects in the external directory.
  • Support for software that depends on Gazebo (gazebo-yarp-plugins, icub-gazebo, ...) is enabled by default in Linux and macOS .
  • In the robotology-superbuild the compilation for dynamics-related software (iDynTree, balancing and walking controllers) needs to be explicity enabled using the ROBOTOLOGY_ENABLE_DYNAMICS that is OFF by default.

I successfully used the robotology-superbuild for my project, how do I cite it in my publication?

The robotology-superbuild is based on YCM, you can cite one of these papers:

  • A Build System for Software Development in Robotic Academic Collaborative Environments, D.E. Domenichelli, S. Traversaro, L. Muratore, A. Rocchi, F. Nori, L. Natale, Second IEEE International Conference on Robotic Computing (IRC), 2018, https://doi.org/10.1109/IRC.2018.00014

  • A Build System for Software Development in Robotic Academic Collaborative Environments, D.E. Domenichelli, S. Traversaro, L. Muratore, A. Rocchi, F. Nori, L. Natale, IN PRESS International Journal of Semantic Computing (IJSC), Vol. 13, No. 02, 2019

Mantainers

Profile Maintainer
Core, Dynamics, iCub Head, iCub Basic Demos Silvio Traversaro @traversaro
Teleoperation Kourosh Darvish @kouroshD
Human Dynamics Yeshasvi Tirupachuri @Yeshasvitvs