matlab-whole-body-simulator is a simulator for the humanoid robots. It has been designed to work in Simulink. In the simulator the ground is assumed to be flat and the contact forces are computed using the Maximum dissipation principle and under the linear approximation of the friction cones assumption.
- Matlab/Simulink 2019b
- yarp-matlab-bindings: Yarp Resource Finder.
- WBToolbox: WB-Toolbox library Simulink blocks.
- iDynTree: Dynamic computations (through bindings) and WB-Toolbox library dependency.
- qpOASES: QP solver for estimating the contact wrenches.
- icub-models: access to the iCub models.
This section is for users wishing to run an example showcase of the library or integrate the library in a wider Simulink model they are implementing., it is recommended to:
- either use the Conda package manager for installing directly the
conda
packagematlab-whole-body-simulator
, available since theconda
build number 8 of theconda
binaries hosted in the robotology conda channel, - either use a one line installer, meant for users not familiar with the
conda
package manager nor Git.
For users not familiar with the conda
package manager nor Git version control system, a one line installer is available, that can be downloaded and run from the Matlab command line, without any access to a terminal:
- Run Matlab.
- In the Matlab command line change the current folder to a directory where you wish to download the one installer script and install all the packages.
- Run the following commands:
websave('install_robotology_packages.m', 'https://raw.githubusercontent.com/robotology/robotology-superbuild/master/scripts/install_robotology_packages.m')
install_robotology_packages
robotology_setup
For testing the installation, run the example as described in this section.
If you're familiar with running shell commands in a terminal, handling environment variables, and have a home directory where you can freely install a package manager, you can run the following steps:
- If you are not already using the
conda
package manager, install theconda
miniforge distribution following https://github.com/robotology/robotology-superbuild/blob/master/doc/install-miniforge.md#linux. Remember to restart your shell session or runsource ~/.bashrc
(~/.bash_profile
on MacOS) for theconda init
command to take effect. - Install Mamba, create a new environment and install the robotology dependency binaries:
To read more about installing
conda install mamba conda create -n robotologyenv conda activate robotologyenv mamba install -c robotology matlab-whole-body-simulator
robotology
package binaries refer to https://github.com/robotology/robotology-superbuild/blob/master/doc/conda-forge.md#binary-installation. - Check the MATLABPATH environment variable. It should now have...
Check the mex and Simulink libraries in the folder
<user-home-dir>/miniforge3/envs/robotologyenv/mex: <user-home-dir>/miniforge3/envs/robotologyenv/share/WBToolbox: <user-home-dir>/miniforge3/envs/robotologyenv/share/WBToolbox/images
<user-home-dir>/miniforge3/envs/robotologyenv/mex
. It should contain:+iDynTree BlockFactory.mexmaci64 mwbs_lib.slx +iDynTreeWrappers BlockFactory.tlc mwbs_robotDynamicsWithContacts_lib.slx +mwbs iDynTreeMEX.mexmaci64 mwbs_robotSensors_lib.slx +yarp. yarpMEX.mexmaci64 mwbs_visualizers_lib.slx
- The
Matla Whole Body Simulator
library, along with the sub-libraries robotDynamicsWithContacts, robotSensors and visualizers should be visible in the Simulink Library Browser. They can be drag and dropped into any open Simulink model.
For testing the installation, run the example as described in this section.
This use case is very convenient if a local host with installed MATLAB application and license is not available, or simply if the user wishes to leave his usual working environment unchanged by the package dependencies of this simulator framework.
With a MATLAB account, one can sign in and access to MATLAB online, an online workspace that provides MATLAB and Simulink from any standard web browser. The GUI is practically identical to the one provided by the desktop application.
The procedure is similar to the One Line Installation one, except that you run it in the MATLAB online session and the command set is slightly different (refer to robotology-superbuild/doc/matlab-one-line-install.md).
The same example integrating the "YOGA++" controller and the Matlab Whole-body Simulator simulator library blocks can be run in MATLAB Online in the same way as described in section One Line Installation.
For testing the installation, run the example as described in this section.
This section is for developers wishing to implement new features or fixes in the library Matlab Whole Body Simulator. This repository has to be cloned and the modules listed in the dependencies section need to be installed.
It is recommended to follow one of the two procedures using the robotology-superbuild resources:
- Get the
matlab-whole-body-simulators
repository and the dependencies by installing the full superbuild from source. - clone the
matlab-whole-body-simulators
repository, then install the dependency binary packages from the conda robotology channelusing the miniforge conda distribution package manager.
For testing the installation, run the example as described in this section.
A Simulink model example, from the repository whole-body-controllers
, integrates a controller model with the simulator library RobotDynWithContacts from this repository. The controller (labelled "YOGA++") controls a humanoid robot (iCub) in performing a dynamic trajectory while balancing.
For getting the whole-body-controllers
repository, follow this guide.
You can then run the model from the MATLAB command line, from any directory, as follows:
floatingBaseBalancingTorqueControlWithSimulator.torqueControlBalancingWithSimu
-
Connect your controller to the RobotDynWithContacts block. This block takes as imput the joints torque, motor inertia and an eventual generalized external wrench. It outputs the robot state, the contact wrenches wrench_LFoot and wrench_RFoot, respectively applied to the left and right foot (sole frames), and kinDynOut, an output bus exposing all the computed dynamics quantities relevant for debugging or the extension of dynamics computations in external blocks (emulation of an IMU sensor, of pressure sensors on the feet, etc).
-
Select the robot model by setting the environment variable
YARP_ROBOT_NAME
(e.g.setenv('YARP_ROBOT_NAME','iCubGenova04')
). The available models are:Model description iCub robot (iCubGenova04) RRBot from Gazebo Preview $YARP_ROBOT_NAME 'iCubGenova04'
'RRbot1'
-
Set the configuration parameters
robot_config
,contact_config
andphysics_config
.
Details:
Structure | Field name | Size/Type | Description | ||
---|---|---|---|---|---|
robot_config | jointOrder | [1×N_DOF] / cell | List of N_DOF "controlled" joints (matches dimension of joint torques input) | ||
meshFilePrefix | char | Prefix to be concatenated to the mesh file path specified in the URDF model file (*) | |||
fileName | char | File name of the URDF model (typically: model.urdf) | |||
N_DOF | [1x1] double | Robot degrees of freedom | |||
N_DOF_MATRIX | [23×23] double] | eye(robot_config.N_DOF) |
|||
initialConditions | [1×1] struct | Base pose and velocity. Joint positions and velocities | |||
SIMULATE_MOTOR_REFLECTED_INERTIA | [1x1] logical | Activate motor reflected inertia emulation | |||
robotFrames | [1×1] struct | Selected reference frames (base, left/right sole) | |||
contact_config | foot_print | [3×4] double | 4 Contact points on one of the feet soles | ||
total_num_vertices | [1x1] double | Total number of contact points (Nv=8) | |||
friction_coefficient | [1x1] double | Ground/feet Coulomb friction coefficient |
|||
physics_config | GRAVITY_ACC | [1x3] double | Gravity vector (gz = -9.81) | ||
TIME_STEP | [1x1] double | Simulator sampling time (recommended 1e-03) |
(*) Since iDynTree 3.0.0, if meshFilePrefix='', the standard iDynTree workflow of locating the mesh via the ExternalMesh.getFileLocationOnLocalFileSystem
method is used. The iCub model meshes file tree is compatible with this workflow.
- Set to
vector
ormatrix
the parameter "input motor reflected inertia format" from the pop-up pick-list. The selected format should match the format of the input signalmotorInertias
and respective definition as follows:
parameter value |
motorInertias format |
represented quantity |
---|---|---|
vector | [NDOFx1] | Column vector composed of the diagonal terms of |
matrix | [NDOFxNDOF] | Matrix defined by |
The motor inertia reflected on the mass matrix of the articulated system is given by
- To run and example open and launch
test_matlab_system.mdl
. It also contains a callback to theinit
file that retrieves the needed information.