Skip to content

Commit

Permalink
Update README: refactor Source Installation section
Browse files Browse the repository at this point in the history
  • Loading branch information
@nunoguedelha
nunoguedelha committed May 17, 2021
1 parent e3c83a1 commit 0b425d0
Show file tree
Hide file tree
Showing 3 changed files with 73 additions and 71 deletions.
89 changes: 18 additions & 71 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@ This section is for users wishing to run an example showcase of the library or i
- 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
### One Line Installation

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:
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:
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:
Expand All @@ -29,9 +29,9 @@ websave('install_robotology_packages.m', 'https://raw.githubusercontent.com/robo
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.
Refer to [robotology-superbuild/doc/matlab-one-line-install.md](https://github.com/robotology/robotology-superbuild/blob/master/doc/matlab-one-line-install.md#one-line-installation-of-robotology-matlabsimulink-packages) for a more detailed description.

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:
Currently, the script `install_robotology_packages` installs all the Simulink/Matlab packages available in the [robotology-superbuild](https://github.com/robotology/robotology-superbuild) resources. This includes the package `matlab-whole-body-simulator` and all its dependencies, and the package `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
```
Expand Down Expand Up @@ -62,81 +62,28 @@ If you're familiar with running shell commands in a terminal, handling environme
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
### :cloud: One Line Installation in MATLAB Online Session
- Clone and build the robotology-superbuild following the steps in https://github.com/robotology/robotology-superbuild/blob/master/README.md.
- `icub-models`, `YARP` (dependency of `yarp-matlab-bindings`): set the profile option `ROBOTOLOGY_ENABLE_CORE`.
- `iDynTree`, `WBToolbox`, `qpOASES` and `yarp-matlab-bindings`: set the profile option `ROBOTOLOGY_ENABLE_DYNAMICS` and CMake option `ROBOTOLOGY_USES_MATLAB`.
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.
**Note 1:** In general, for selecting the profile CMake options according to the sub-projects to install, refer to the table in the section [Profile CMake Options](https://github.com/robotology/robotology-superbuild/blob/master/doc/profiles.md#profile-cmake-options).
**Note 2:** By setting the profile `ROBOTOLOGY_ENABLE_DYNAMICS`in the superbuild cmake options. The `qpOASES` library will then be installed along with `iDynTree` as an external dependency.
**Note 3:** Previously, two other optional QP solvers were available: OSQP and the native MATLAB solver `quadprog`. OSQP bindings and `quadprog` are not supported by the Simulink code generation build option in the `step_block` MATLAB System block. For this reason, the `step_block` MATLAB System block uses the qpOASES WBT block through a Simulink function call, and this choice is hardcoded in the class `Contacts`. As soon as the OSQP WBT block is created, it will replace the qpOASES Solver block.
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.
## :floppy_disk: Installing the dependencies from the conda robotology channel
The procedure is similar to the [One Line Installation](#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](https://github.com/robotology/robotology-superbuild/blob/master/doc/matlab-one-line-install.md#installation-on-matlab-online)).
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
```
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...
```
<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 libraries...
```
ls <user-home-dir>/miniforge3/envs/robotologyenv/mex/
```
Should return:
```
+iDynTree
+iDynTreeWrappers
+wbc
BlockFactory.mexmaci64
BlockFactory.tlc
SwigGet.m
SwigMem.m
SwigRef.m
iDynTreeMEX.mexmaci64
mesh2tri.m
```
4. Clone the repository `matlab-whole-body-simulators`
```
git clone https://github.com/dic-iit/matlab-whole-body-simulator.git
```
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`.
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](#one-line-installation).
## :floppy_disk: Installing the framework in MATLAB Online environment
## :floppy_disk: Source Installation
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.
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](#hammer-dependencies) need to be installed.
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.
It is recommended to follow one of the two procedures using the [robotology-superbuild](https://github.com/robotology/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 channel](https://anaconda.org/robotology)using the [miniforge conda distribution](https://github.com/conda-forge/miniforge) package manager.
### [Source Installation using the full superbuild installation from source](docs/source-installation-using-the-full-superbuild-installation-from-source).
### [Source Installation using the robotology conda packages](docs/source-installation-using-the-robotology-conda-packages).
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.
- No **Git** tool is available by default, so it has to be installed through **mamba**.
- any command run on terminal in the original procedure shall be run through the `system` instruction (refer to https://github.com/robotology/robotology-superbuild/pull/652#issuecomment-794027294).
- Any prompt resulting from those commands is not accessible from MATLAB, so we have to use the automatic "yes" user input (command option `-y`).
The required commands have been sequenced in a MATLAB script, `app/tools/matlabOnlineInstaller.m`. Follow the below steps once logged in the MATLAB Online session.
1. Download and run the installer:
```
system('curl -LO https://raw.githubusercontent.com/dic-iit/matlab-whole-body-simulator/featue/install-matlab-online/app/tools/matlabOnlineInstaller.m');
run matlabOnlineInstaller.
```
2. After step 1, you find the `matlab-whole-body-simulator` repository has been downloaded to `/MATLAB Drive/dev/matlab-whole-body-simulator`, further designated as <MATLAB_WB_SIM_SRC>, and its dependencies installed in `$HOME/miniforge3`. Select the robot model among the available ones in `<MATLAB_WB_SIM_SRC>/app/robots` and as described in the next section. For instance, selecting `iCubGenova04` would be done as follows:
```
setenv('YARP_ROBOT_NAME','iCubGenova04');
```
3. Open the test model `<MATLAB_WB_SIM_SRC>/test_matlab_system_2020b.mdl`, and run it. After the compilation is complete, a figure will appear, displaying the robot performing the task driven by the controller used in the test model.
## :runner: How to use the simulator
Expand Down
11 changes: 11 additions & 0 deletions doc/source-installation-using-the-full-superbuild-installation-from-source.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Source Installation using the full Superbuild Installation from Source

- Clone and build the robotology-superbuild following the steps in https://github.com/robotology/robotology-superbuild/blob/master/README.md.
- `icub-models`, `YARP` (dependency of `yarp-matlab-bindings`): set the profile option `ROBOTOLOGY_ENABLE_CORE`.
- `iDynTree`, `WBToolbox`, `qpOASES`, `yarp-matlab-bindings` and `matlab-whole-body-simulator`: set the profile option `ROBOTOLOGY_ENABLE_DYNAMICS` and CMake option `ROBOTOLOGY_USES_MATLAB`.

After these steps, the repository `matlab-whole-body-simulator` has been cloned in `<ROBOTOLOGY_SUPERBUILD_SOURCE_DIR>/src/matlab-whole-body-simulator`.

**Note 1:** In general, for selecting the profile CMake options according to the sub-projects to install, refer to the table in the section [Profile CMake Options](https://github.com/robotology/robotology-superbuild/blob/master/doc/profiles.md#profile-cmake-options).
**Note 2:** By setting the profile `ROBOTOLOGY_ENABLE_DYNAMICS`in the superbuild cmake options, the `qpOASES` library will then be installed along with `iDynTree` as an external dependency.
**Note 3:** Previously, two other optional QP solvers were available: OSQP and the native MATLAB solver `quadprog`. OSQP bindings and `quadprog` are not supported by the Simulink code generation build option in the `step_block` MATLAB System block. For this reason, the `step_block` MATLAB System block uses the qpOASES WBT block through a Simulink function call, and this choice is hardcoded in the class `Contacts`. As soon as the OSQP WBT block is created, it will replace the qpOASES Solver block.
44 changes: 44 additions & 0 deletions doc/source-installation-using-the-robotology-conda-packages.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Source Installation using the Dependencies from the Conda Robotology Channel

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.


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
```
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...
```
<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 libraries...
```
ls <user-home-dir>/miniforge3/envs/robotologyenv/mex/
```
Should return:
```
+iDynTree
+iDynTreeWrappers
+wbc
BlockFactory.mexmaci64
BlockFactory.tlc
SwigGet.m
SwigMem.m
SwigRef.m
iDynTreeMEX.mexmaci64
mesh2tri.m
```
4. Clone the repository `matlab-whole-body-simulators`
```
git clone https://github.com/dic-iit/matlab-whole-body-simulator.git
```
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`.

0 comments on commit 0b425d0

Please sign in to comment.