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. In particular, the robotology-superbuild is divided in different "profiles",
that specify the specific subset of robotology packages to build.
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. gym-ignition if the ROBOTOLOGY_USES_IGNITION 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, matioCpp, YARP_telemetry. Furthermore, osqp-matlab and matlab-whole-body-simulator if ROBOTOLOGY_USES_MATLAB option is enabled. |
OFF |
Documentation on Dynamics profile. |
ROBOTOLOGY_ENABLE_DYNAMICS_FULL_DEPS |
bipedal-locomotion-framework and its dependencies. |
bipedal-locomotion-framework, manif, qhull, casadi. CppAD. |
OFF |
Documentation on Dynamics full deps 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. |
ROBOTOLOGY_ENABLE_EVENT_DRIVEN |
The robotology software packages related to event-driven. | event-driven |
OFF |
Documentation on event-driven 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.
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 Classic simulator. | ON on Linux and macOS, OFF on Windows |
Documentation on Gazebo Classic dependency. |
ROBOTOLOGY_USES_IGNITION |
Include software that depends on Ignition. | OFF |
Documentation on Ignition 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_PYTHON |
Include software that depends on Python. | OFF |
Documentation on Python 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 |
Not all options are supported on all platforms. The following table provides a recap of which options are supported on each platform.
| Option | Ubuntu/Debian, dependencies: apt | macOS, dependencies: Homebrew | Windows, dependencies: vcpkg | conda on Linux, dependencies: conda-forge | conda on macOS, dependencies: conda-forge | conda on Windows, dependencies: conda-forge |
|---|---|---|---|---|---|---|
ROBOTOLOGY_ENABLE_CORE |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_ENABLE_ROBOT_TESTING2! |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_ENABLE_DYNAMICS |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_ENABLE_DYNAMICS_FULL_DEPS1! |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_ENABLE_ICUB_HEAD |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_ENABLE_ICUB_BASIC_DEMOS |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_ENABLE_TELEOPERATION |
✔️ | ✔️ | ❌ | ✔️ | ✔️ | ❌ |
ROBOTOLOGY_ENABLE_HUMAN_DYNAMICS |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_ENABLE_EVENT_DRIVEN |
✔️ | ✔️ | ❌ | ✔️ | ✔️ | ❌ |
ROBOTOLOGY_USES_GAZEBO |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_USES_IGNITION |
❌ | ❌ | ❌ | ✔️ | ❌ | ❌ |
ROBOTOLOGY_USES_MATLAB |
✔️ | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_USES_OCTAVE |
✔️ | ✔️ | ❌ | ❌ | ❌ | ❌ |
ROBOTOLOGY_USES_PYTHON3! |
✔️ | ❌ | ❌ | ✔️ | ✔️ | ✔️ |
ROBOTOLOGY_USES_OCULUS_SDK |
❌ | ❌ | ✔️ | ❌ | ❌ | ❌ |
ROBOTOLOGY_USES_CYBERITH_SDK |
❌ | ❌ | ✔️ | ❌ | ❌ | ✔️ |
ROBOTOLOGY_USES_CFW2CAN |
✔️ | ❌ | ❌ | ✔️ | ❌ | ❌ |
ROBOTOLOGY_USES_XSENS_MVN_SDK |
❌ | ❌ | ✔️ | ❌ | ❌ | ❌ |
ROBOTOLOGY_USES_ESDCAN |
❌ | ❌ | ✔️ | ❌ | ❌ | ✔️ |
1!:Since 2021.05, ROBOTOLOGY_ENABLE_DYNAMICS_FULL_DEPS does not support building with apt dependencies on Ubuntu 18.04 .
2!:Since 2021.11, ROBOTOLOGY_ENABLE_ROBOT_TESTING does not support building with apt dependencies on Ubuntu 18.04 .
3!:Since 2021.11, ROBOTOLOGY_USES_PYTHON does not support building with apt dependencies on Ubuntu 18.04 .
This profile is enabled by the ROBOTOLOGY_ENABLE_CORE CMake option.
The steps necessary to install the system dependencies of the Core profile are provided in operating system-specific installation documentation.
Follow the steps in http://wiki.icub.org/wiki/Check_your_installation to verify if your installation was successful.
This profile is enabled by the ROBOTOLOGY_ENABLE_ROBOT_TESTING CMake option.
On Windows, this profile creates some long paths during the build process. If you enable it, it is recommended to keep the total path length of the robotology-superbuild build directory below 50 characters, or to enable the support for long path in Windows following the instructions in the official Windows documentation.
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.
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.
This profile is enabled by the ROBOTOLOGY_ENABLE_DYNAMICS CMake option.
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.
This profile is enabled by the ROBOTOLOGY_ENABLE_DYNAMICS_FULL_DEPS CMake option.
The steps necessary to install the system dependencies of the Dynamics full deps profile are provided in operating system-specific installation documentation, and no additional required system dependency is required.
Since 2021.05, ROBOTOLOGY_ENABLE_DYNAMICS_FULL_DEPS is not supported with apt dependencies on Ubuntu 18.04.
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 robotology#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 the official iCub documentation.
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.
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.
This profile is enabled by the ROBOTOLOGY_ENABLE_ICUB_BASIC_DEMOS CMake option.
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.
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.
This profile is enabled by the ROBOTOLOGY_ENABLE_TELEOPERATION CMake option.
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.
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:
- Windows: Oculus.
- Linux/macOS: walking controller.
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:
- Windows: Oculus, Cyberith.
- Linux/macOS: walking controller.
This profile is enabled by the ROBOTOLOGY_ENABLE_HUMAN_DYNAMICS CMake option.
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.
This profile is enabled by the ROBOTOLOGY_ENABLE_EVENT_DRIVEN CMake option. For the moment, Windows is not a supported platform.
The steps necessary to install the system dependencies of the Event-driven profile are provided in operating system-specific installation documentation.
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.
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.
On macOS with Homebrew dependencies, due to an incompatibility of Gazebo with the latest version of tbb (gazebosim/gazebo-classic#2867), to correctly compiled robotology-superbuild with the ROBOTOLOGY_USES_GAZEBO option enabled,
it is necessary to define the following environment variables:
export CMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH}:/usr/local/opt/tbb@2020_u3
export CPATH=${CPATH}:/usr/local/opt/tbb@2020_u3/include
export LIBRARY_PATH=${LIBRARY_PATH}:/usr/local/opt/tbb@2020_u3/lib
See osrf/homebrew-simulation#1486 for more info.
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.
Support for this dependency is enabled by the ROBOTOLOGY_USES_IGNITION CMake option.
This option is set to OFF on all platforms as it is still experimental.
Different Ignition distributions can be installed alongside. The projects included in the superbuild might require different distributions. From the superbuild point of view, we currently do not allow enabling projects that only support a specific Ignition distribution, therefore all required distributions have to be found in the system.
Follow the source installation with conda-forge provided dependencies and, after creating and environment and installing the default dependencies, execute:
conda install -c conda-forge libignition-gazebo4Follow the official instructions to install Ignition on your platform, available at https://ignitionrobotics.org/docs.
Note: this installation method is not currently tested in Continuous Integration.
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.
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.
If MATLAB is installed on your computer, the robotology-superbuild can install some projects that depend on MATLAB, among the others:
- the MATLAB bindings of the iDynTree library,
- the native MATLAB bindings of YARP, contained in the yarp-matlab-bindings repository,
- The WB-Toolbox Simulink toolbox,
- The whole-body-controllers Simulink-based balancing controllers. Note that whole-body-controllers can be installed and compiled also without MATLAB, but its functionalities are reduced.
- The matlab-whole-body-simulator Simulink-based whole-body dynamics simulator with contacts handling.
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/mexdirectory, - the
$ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX/share/WBToolboxdirectory and all its subdirectories (except the packages which are folder names starting with "+"), - the library
$ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX/mex/+wbc/simulink, - the controller model examples
$ROBOTOLOGY_SUPERBUILD_INSTALL_PREFIX/mex/+wbc/examples.
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>' '/mex/+wbc/examples'])
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.
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.
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.resize(3);
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.
Support for this dependency is enabled by the ROBOTOLOGY_USES_OCTAVE CMake option.
Install octave and the necessary development files using the following command:
sudo apt-get install liboctave-dev
Install octave using the following command:
brew install octave
The ROBOTOLOGY_USES_OCTAVE option is not supported on Windows, see robotology#139 for more info.
Add the $ROBOTOLOGY_SUPERBUILD_SOURCE_DIR/build/install/octave directory to your Octave path.
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.resize(3);
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.
Support for this dependency is enabled by the ROBOTOLOGY_USES_PYTHON CMake option.
Install Python and the necessary development files using the following command:
sudo apt-get install python3-dev python3-numpy python3-pybind11 pybind11-dev
To install python and the other required dependencies when using conda-forge provided dependencies, use:
conda install -c conda-forge python numpy swig pybind11
Open a python interpreter and try to import modules, for example verify that import yarp works.
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.
To check and install the Oculus SDK please follow the steps for Oculus SDK mentioned here.
To configure the Oculus SDK follow the steps for Oculus SDK mentioned here.
Support for this dependency is enabled by the ROBOTOLOGY_USES_CYBERITH_SDK CMake option.
Warning: at the moment the Cyberith SDK does not support macOS and Linux, so this option is only supported on Windows.
To check and install the Cyberith SDK, please follow the steps for Cyberith SDK mentioned in here.
To configure the Cyberith SDK please follow the steps for Cyberith SDK mentioned in here.
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.
To check and install the Xsens MVN SDK, please follow the steps for Xsens MVN SDK mentioned in here.
To configure the Xsens MVN SDK please follow the steps for Xsens MVN SDK mentioned in here.
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 .
To compile the software enabled by the ROBOTOLOGY_USES_ESDCAN option (such as the icub-main's ecan YARP driver) you need to install the esd CAN C library.
To install this library in conda, just run mamba install -c conda-forge -c robotology esdcan inside your conda environment. If you installed icub-main from conda binary packages, the ecan YARP driver enabled by the ROBOTOLOGY_USES_ESDCAN option is already included.
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.
No additional configuration is required to use the software installed by the ROBOTOLOGY_USES_ESDCAN
Open a terminal, and check that amoung the device listed by yarpdev --list the ecan YARP device is listed.