Skip to content

Commit

Permalink
Refactor README. Add first installation section "binary Installation"
Browse files Browse the repository at this point in the history 
- This section includes the one line installer and the procedure describing the installation
  of conda robotology package matlab-whole-body-simulator.
  • Loading branch information
@nunoguedelha
nunoguedelha committed May 17, 2021
1 parent 006cd80 commit e3c83a1
Showing 1 changed file with 63 additions and 15 deletions.
78 changes: 63 additions & 15 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,55 @@ In the simulator the ground is assumed to be flat and the contact forces are com
- [qpOASES](https://github.com/robotology-dependencies/qpOASES): QP solver for estimating the contact wrenches.
- [icub-models](https://github.com/robotology/icub-models): access to the iCub models.

It is recommended to install these dependencies using the [robotology-superbuild](https://github.com/robotology/robotology-superbuild) resources:
- Either installing the full superbuild from source.
- Either installing the required binary packages derived from the above listed dependencies, using the [miniforge conda distribution](https://github.com/conda-forge/miniforge) package manager, from the robotology channel.
## :floppy_disk: Binary Installation

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](https://anaconda.org) for installing directly the `conda` package [`matlab-whole-body-simulator`](https://anaconda.org/robotology/matlab-whole-body-simulator), available since the `conda` build number 8 of the `conda` binaries hosted in the [robotology conda channel](https://anaconda.org/robotology),
- either use the [one line installer described in the respective section](#one-line-installer), meant for user not familiar with the `conda` package manager nor [Git](https://git-scm.com/).

### One Line Installer

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:
1. Run Matlab.
1. 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.
1. 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
```
The `websave` command downloads the installer `install_robotology_packages` to the current folder. The second line installs it. The script `robotology_setup` sets the environment variables. You can run it again every time you wish to reset the environment variables.

Currently, the script `install_robotology_packages` installs the `conda` package `matlab-whole-body-simulator` and all its dependencies, as well as other packages, like `whole-body-controllers`, which includes a Simulink model example integrating 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. You can run the model from the Matlab command line, from any directory, as follows:
```
floatingBaseBalancingTorqueControlWithSimulator.torqueControlBalancingWithSimu
```

### Installation from the Conda Robotology Channel

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:
1. If you are not already using the conda package manager, install the `conda` miniforge distribution following https://github.com/robotology/robotology-superbuild/blob/master/doc/install-miniforge.md#linux. Remember to restart your shell session or run `source ~/.bashrc` (`~/.bash_profile` on MacOS) for the `conda init` command to take effect.
2. Install Mamba, create a new environment and install the robotology dependency binaries:
```
conda install mamba
conda create -n robotologyenv
conda activate robotologyenv
mamba install -c robotology matlab-whole-body-simulator
```
To read more about installing `robotology` package binaries refer to https://github.com/robotology/robotology-superbuild/blob/master/doc/conda-forge.md#binary-installation.
3. Check the MATLABPATH environment variable. It should now have...
```
<user-home-dir>/miniforge3/envs/robotologyenv/mex: <user-home-dir>/miniforge3/envs/robotologyenv/share/WBToolbox: <user-home-dir>/miniforge3/envs/robotologyenv/share/WBToolbox/images
```
Check the mex and Simulink libraries in the folder `<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
```
4. 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.
<img width="963" alt="image" src="https://user-images.githubusercontent.com/6848872/116485698-1ff57580-a88c-11eb-8856-c4527e00b401.png">
## :floppy_disk: Installing the dependencies through the robotology superbuild source
Expand All @@ -28,23 +74,25 @@ It is recommended to install these dependencies using the [robotology-superbuild
## :floppy_disk: Installing the dependencies from the conda robotology channel
1. Install the conda miniforge distribution following https://github.com/robotology/robotology-superbuild/blob/master/doc/install-miniforge.md#linux. Remember to restart your shell session or run `source ~/.bashrc` (`~/.bash_profile` on MacOS) for the `conda init` command to take effect.
1. Install the `conda` miniforge distribution following https://github.com/robotology/robotology-superbuild/blob/master/doc/install-miniforge.md#linux. Remember to restart your shell session or run `source ~/.bashrc` (`~/.bash_profile` on MacOS) for the `conda init` command to take effect.
2. Install Mamba, create a new environment and install the robotology dependency binaries:
```
$ conda install mamba
$ conda create -n robotologyenv
$ conda activate robotologyenv
$ mamba install -c robotology yarp-matlab-bindings idyntree qpoases icub-models wb-toolbox
conda install mamba
conda create -n robotologyenv
conda activate robotologyenv
mamba install -c robotology yarp-matlab-bindings idyntree qpoases icub-models wb-toolbox
```
To read more about installing robotology-superbuild package binaries refer to https://github.com/robotology/robotology-superbuild/blob/master/doc/conda-forge.md#binary-installation.
3. Check the MATLABPATH environment variable. It should now have:
3. Check the MATLABPATH environment variable. It should now have...
```
<user-home-dir>/miniforge3/envs/robotologyenv/mex: <user-home-dir>/miniforge3/envs/robotologyenv/share/WBToolbox: <user-home-dir>/miniforge3/envs/robotologyenv/share/WBToolbox/images
```
Mex libraries:
Check the mex libraries...
```
ls <user-home-dir>/miniforge3/envs/robotologyenv/mex/
```
Should return:
```
$ ls <user-home-dir>/miniforge3/envs/robotologyenv/mex/
+iDynTree
+iDynTreeWrappers
+wbc
Expand All @@ -58,9 +106,9 @@ It is recommended to install these dependencies using the [robotology-superbuild
```
4. Clone the repository `matlab-whole-body-simulators`
```
$ git clone https://github.com/dic-iit/matlab-whole-body-simulator.git
git clone https://github.com/dic-iit/matlab-whole-body-simulator.git
```
5. Run matlab in the same conda environment.
5. Run matlab in the same `conda` environment.
6. Change working directory to the root path of repository `matlab-whole-body-simulators`.
7. Open and run the model `test_matlab_system_2020b.mdl`.
Expand All @@ -70,7 +118,7 @@ This use case is very convenient if a local host with installed MATLAB applicati
With a MATLAB account, one can sign in and access to [MATLAB online](https://www.mathworks.com/products/matlab-online.html#connect-to-the-cloud), 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.
Once connected, the goal is to follow a procedure similar to the one from [the previous section](https://github.com/dic-iit/matlab-whole-body-simulator/tree/devel#floppy_disk-installing-the-dependencies-from-the-conda-robotology-channel) extensively using the [Robotology](https://anaconda.org/robotology) and the [conda-forge](https://anaconda.org/conda-forge) conda channels.
Once connected, the goal is to follow a procedure similar to the one from [the previous section](https://github.com/dic-iit/matlab-whole-body-simulator/tree/devel#floppy_disk-installing-the-dependencies-from-the-conda-robotology-channel) extensively using the [Robotology](https://anaconda.org/robotology) and the [conda-forge](https://anaconda.org/conda-forge) `conda` channels.
The steps will slightly differ from the ones in the referenced procedure because of the limitations of the bash provided by the MATLAB online session, as listed below:
- The session `~/.bashrc` cannot be sourced (or sourcing it won't have any effect), so the **PATH** environment variable shall be set directly.
Expand Down

0 comments on commit e3c83a1

Please sign in to comment.