whole-body-controllers

Warning! This repository contains reseach material and therefore is under active development. In future releases, master branch may break compatibility with older versions of WBC. If you are interested in retrieving a stable version of this repo, fork the repository or refer to the following releases:

• WBC v2.5
• WBC v2.0
• WBC v1.5
• WBC v1.0

Overview

The repository contains Simulink-based whole-body controllers developed to control the iCub humanoid robot. It can be imagined as a starting point and a support repository for a user that intends to develop a new Simulink controller (not necessarily for the iCub robot) in within the framework of the robotology organization. It is worth noting that:

• The controllers stored in this repository are an overview of the possibile control frameworks that can be implemented using the robotology software infrastructure. Also, the repository contains a library of configuration and utility Matlab functions to design simulations with Gazebo simulator and on the real robot iCub. With the dependency matlab-whole-body-simulator installed, you can also design simulations with a full MATLAB/Simulink simulator and robot visualizer, accessible through the Simulink Library Browser entry Matlab Whole-body Simulator (refer to this README).

• The robot dynamics and kinematics is computed run-time by means of WBToolbox, a Simulink library that wraps iDyntree. For more information on iDyntree library, see also this README.

• The Simulink models implement different control strategies both for fixed-base and for floating-base robots. They space from momentum-based torque control to inverse-kinematics-based position control. Have a look at the controllers folder for more details.

Dependencies

This repository depends upon the following Software:

• CMake, at least version 3.5.
• Matlab/Simulink, default version R2019b.
• WB-Toolbox and blockfactory.
• matlab-whole-body-simulator, at least version 2.0.0.
• Gazebo Simulator, default version 9.0.
• gazebo-yarp-plugins.
• icub-gazebo, icub-gazebo-wholebody and icub-models to access iCub models.
• whole-body-estimators (Optional, for using wholeBodyDynamics device).
• YARP and icub-main.

Installation and usage

The repository is usually tested and developed on Ubuntu and macOS operating systems. Some functionalities may not work properly on Windows.

• It is suggested to install whole-body-controllers and most of its dependencies (namely, YARP, icub-main, whole-body-estimators,icub-gazebo,icub-gazebo-wholebody, icub-models, gazebo-yarp-plugins, matlab-whole-body-simulator, blockfactory and WB-Toolbox and their dependencies) using the robotology-superbuild (enable ROBOTOLOGY_ENABLE_DYNAMICS option). Warning: the superbuild can download and compile the repository also without having Matlab, Simulink and Gazebo installed in the PC, but the functionalities of the repo will be considerably reduced! To access all the features of the repo, install all the dependencies. Also, in the superbuild you have to enable the ROBOTOLOGY_USES_GAZEBO and ROBOTOLOGY_USES_MATLAB options.

• Otherwise, after installing all the dependencies, clone the repository on your pc by running on a terminal git clone https://github.com/robotology/whole-body-controllers, or download the repository. Then (on Ubuntu), open a terminal from the folder where you downloaded whole-body-controllers and run:

  mkdir build
  cd build
  ccmake ..
  

  in the GUI that it will open, set the CMAKE_PREFIX_PATH as your desired installation folder. Then, run make install.

• Set the environmental variable YARP_ROBOT_NAME in your .bashrc file (or equivalent) to be the name of the robot you want to control. List of supported robot names:

  Robot Names	Associated URDF Model
  iCubGenova02	model.urdf
  iCubGenova04	model.urdf
  iCubGazeboV2_5	model.urdf
  icubGazeboSim	model.urdf

• IMPORTANT! to use the WBC Simulink controllers, it is required to add the installed +wbc and +wbc/simulink folders (copied from +wbc) to the Matlab path. There are two possible ways to add the folder to the Matlab path:

  1a. manually and permanently add the parent folder of the installed +wbc (${CMAKE_INSTALL_PREFIX}/mex), and its sub-folder +wbc/simulink to the Matlab path;

  1b. run only once the startup_WBC.m script, which is installed in your ${BUILD} folder. In this case, path is not permanently added to Matlab, and it is required to always start Matlab from the folder where your pathdef.m file is (usually ~/Documents/MATLAB). To facilitate the reaching of the WBC working folder from the folder containing the pathdef.m, a goToWholeBodyController.m script can be automatically created in that folder. Run it to jump to the WBC folder. For further information on the installation procedure see also the WBToolbox documentation. WARNING: if the repository is installed through the robotology-superbuild, DO NOT run the startup_WBC.m file but instead run the startup_robotology_superbuild file that comes along with robotology-superbuild installation.

  • Note: to use any function inside the package matlab-wbc/+wbc, add the wbc prefix to the function name when the function is invoked, i.e. [outputs] = wbc.myFunction(inputs). More information on packages can be found in the Matlab documentation.

• The folder ${CMAKE_INSTALL_PREFIX}/mex having been already added to the Matlab path, there are no other requirements for using the simulation library from matla-whole-body-simulator.

• There are some functionalities of the repo such as the automatic generation of c++ code from Simulink that require to enable not-default cmake options. Check the available options by running ccmake . in your build directory.

Troubleshooting

Please refer to the WBToolbox troubleshooting documentation.

Relevant folders of the repo

• config: a collection of scripts to correctly configure this repo. [README]

• controllers: Simulink whole-body position and torque controllers for balancing of humanoid robots. [README]

• doc: guidelines on how to create/use Simulink models for control. [README]

• library: a library of functions/scripts used by the controllers. [README]

• utilities: Simulink models for debugging sensors on the real robot. [README]

Available controllers

• fixed-base-joints-torque-control
• floating-base-balancing-position-control
• floating-base-balancing-torque-control
• floating-base-balancing-torque-control-with-simulator
• floating-base-jerk-control

Matlab functions library

• matlab WBC library

Additional features

Automatic generation of c++ code from Simulink

There is the possibility to generate c++ code from the Simulink models using Simulink coder (available only for the floating-base-balancing-torque-control). The repositiory that contains the generated c++ code is named autogenerated-whole-body-controllers. Documentation on how to generate the code is available in the repository wiki.

Static GUI for Simulink

When used for controlling real platforms, heavy Simulink models may violate the user-defined simulation time step, see also this issue. It seems a source of delay is the run-time update of the Simulink interface. For this reason, a static GUI for running the models has been developed. If you want to run Simulink with the static GUI, run the startModelWithStaticGui script.

Home positions for yarpmotorgui

The repo contains a set of predefined home positions to be used with the yarpmotorgui. By default, if the repo is installed through robotology-superbuild, the home positions are installed in the robotology-superbuild/build/install directory. Otherwise add the path to the homePositions folder to the YARP_DATA_DIRS environmental variable in your .bashrc file . The command to use the home positions with the yarpmotorgui is yarpmotorgui --from myHomePosFileName.ini.

Where do I find legacy materials?

Official legacy repositories are: mex-wholebodymodel and WBI-Toolbox-controllers. Note: these legacy repos contain undocumented/outdated code, and duplicated or not tested matlab functions. They also contain original code that has been tested on the robot in the past and then never used again, or code that will be ported in the main repository in the future.

• exploit friction controller
• walking controller
• seesaw controller
• automatic gain tuning and automatic gain tuning-matlab
• elastic joints control
• walkman control and walkman control-matlab
• joint-space control and centroidal transformation
• stand-up control 4 contacts

You can also find other legacy controllers/simultors in this repository whole-body-controllers in specific commits:

• simulink-balancing-simulator@c217f051.

Citing this work

If you are using this code for your research activity and you're willing to cite it, you may add the following references to your bibliography:

  @INPROCEEDINGS{Nava_etal2016,
  author={G. Nava and F. Romano and F. Nori and D. Pucci}, 
  booktitle={2016 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)}, 
  title={Stability analysis and design of momentum-based controllers for humanoid robots}, 
  year={2016}, 
  pages={680-687}, 
  doi={10.1109/IROS.2016.7759126}, 
  month={Oct},
  }

  @article{Nori_etal2015,
  author="Nori, F. and Traversaro, S. and Eljaik, J. and Romano, F. and Del Prete, A. and Pucci, D.",
  title="iCub whole-body control through force regulation on rigid non-coplanar contacts",
  year="2015",
  journal="Frontiers in {R}obotics and {A}{I}",
  volume="1",
  }

Mantainers

Main: Gabriele Nava (@gabrielenava)

Auxiliary: Giuseppe L'Erario (@giulero)