Fixed the READMEs

ami-iit · May 17, 2021 · 17597b2 · 17597b2
1 parent 0b425d0
commit 17597b2
Show file tree

Hide file tree

Showing 4 changed files with 57 additions and 39 deletions.
diff --git a/README.md b/README.md
@@ -16,7 +16,7 @@ In the simulator the ground is assumed to be flat and the contact forces are com
 
 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/).
+- either use a [one line installer](https://github.com/robotology/robotology-superbuild/blob/master/doc/matlab-one-line-install.md#one-line-installation-of-robotology-matlabsimulink-packages), meant for users not familiar with the `conda` package manager nor [Git](https://git-scm.com/).
 
 ### One Line Installation
 
@@ -29,17 +29,13 @@ websave('install_robotology_packages.m', 'https://raw.githubusercontent.com/robo
 install_robotology_packages
 robotology_setup
 ```
-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 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
-```
+For testing the installation, run the example as described in [this section](#eyes-checking-the-installation).
 
-### Installation from the Conda Robotology Channel
+### Binary 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.
+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
@@ -62,6 +58,8 @@ 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">
 
+For testing the installation, run the example as described in [this section](#eyes-checking-the-installation).
+
 ### :cloud: One Line Installation in MATLAB Online Session
 
 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.
@@ -72,6 +70,8 @@ The procedure is similar to the [One Line Installation](#one-line-installation)
 
 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).
 
+For testing the installation, run the example as described in [this section](#eyes-checking-the-installation).
+
 ## :floppy_disk: Source Installation
 
 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.
@@ -80,9 +80,23 @@ It is recommended to follow one of the two procedures using the [robotology-supe
 - 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 full superbuild installation from source](doc/source-installation-using-the-full-superbuild-installation-from-source.md).
+
+### [Source Installation using the robotology conda packages](doc/source-installation-using-the-robotology-conda-packages.md).
+
+For testing the installation, run the example as described in [this section](#eyes-checking-the-installation).
 
-### [Source Installation using the robotology conda packages](docs/source-installation-using-the-robotology-conda-packages).
+
+## :eyes: Checking The Installation
+
+A [Simulink model example](https://github.com/robotology/whole-body-controllers/tree/master/controllers/%2BfloatingBaseBalancingTorqueControlWithSimulator), 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](doc/getting-whole-body-controllers.md).
+
+You can then run the model from the MATLAB command line, from any directory, as follows:
+```
+floatingBaseBalancingTorqueControlWithSimulator.torqueControlBalancingWithSimu
+```
 
 
 ## :runner: How to use the simulator

diff --git a/doc/getting-whole-body-controllers.md b/doc/getting-whole-body-controllers.md
@@ -0,0 +1,20 @@
+# Getting the `whole-body-controllers` repository
+
+## Local and Online One Line Installation
+With the [local one line installation](../README.md#one-line-installation) and [one line installation in MATLAB Online](../README.md#one-line-installation-in-matlab-online-session), 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 also the package `whole-body-controllers`, which includes the Simulink model example mentioned above.
+
+## Binary Installation Using Conda
+If you followed the guide [Binary Installation from the Conda Robotology Channel](../README.md#binary-installation-from-the-conda-robotology-channel), install the repository `whole-body-controllers` as follows:
+```
+mamba install -c robotology whole-body-controllers
+```
+An additional library folder, `+wbc`, appears in `<user-home-dir>/miniforge3/envs/robotologyenv/mex`, and the MATLABPATH environment variable was appended with...
+```
+<user-home-dir>/miniforge3/envs/robotologyenv/mex/+wbc/simulink: <user-home-dir>/miniforge3/envs/robotologyenv/mex/+wbc/examples:
+```
+
+## Source Installation using the full Superbuild Installation from Source
+The `whole-body-controllers` project was installed along.
+
+## Source Installation using the Dependencies from the Conda Robotology Channel
+Refer to section [Binary Installation Using Conda](#binary-installation-using-conda).
diff --git a/doc/source-installation-using-the-full-superbuild-installation-from-source.md b/doc/source-installation-using-the-full-superbuild-installation-from-source.md
@@ -1,10 +1,9 @@
 # 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`.
+1. Clone and build the robotology-superbuild following the steps in https://github.com/robotology/robotology-superbuild/blob/master/README.md.
+2. For cloning `icub-models`, `YARP` (dependency of `yarp-matlab-bindings`): set the profile option `ROBOTOLOGY_ENABLE_CORE`.
+3. For cloning `iDynTree`, `WBToolbox`, `qpOASES`, `yarp-matlab-bindings` and `matlab-whole-body-simulator`(*): set the profile option `ROBOTOLOGY_ENABLE_DYNAMICS` and CMake option  `ROBOTOLOGY_USES_MATLAB`. The repository `matlab-whole-body-simulator` is cloned in `<ROBOTOLOGY_SUPERBUILD_SOURCE_DIR>/src/matlab-whole-body-simulator`.
+4. Open MATLAB and Add the path `<ROBOTOLOGY_SUPERBUILD_SOURCE_DIR>/src/matlab-whole-body-simulator/lib` to the top of the MATLAB path. This allows MATLAB to find the source library instead of the installed one.
 
 **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.

diff --git a/doc/source-installation-using-the-robotology-conda-packages.md b/doc/source-installation-using-the-robotology-conda-packages.md
@@ -1,11 +1,6 @@
 # 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.
+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
@@ -18,27 +13,17 @@ It is recommended to install these dependencies using the [robotology-superbuild
     ```
     <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:
+    Check the mex and Simulink libraries in the folder `<user-home-dir>/miniforge3/envs/robotologyenv/mex`. It should contain:
     ```
-    +iDynTree
-    +iDynTreeWrappers
-    +wbc
-    BlockFactory.mexmaci64
-    BlockFactory.tlc
-    SwigGet.m
-    SwigMem.m
-    SwigRef.m
-    iDynTreeMEX.mexmaci64
-    mesh2tri.m
+    +iDynTree               BlockFactory.mexmaci64      mwbs_lib.slx
+    +iDynTreeWrappers       BlockFactory.tlc            mwbs_robotDynamicsWithContacts_lib.slx
+    +yarp                   iDynTreeMEX.mexmaci64       mwbs_robotSensors_lib.slx
+                            yarpMEX.mexmaci64           mwbs_visualizers_lib.slx
     ```
 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`.
+5. Open MATLAB and Add the path `<matlab-whole-body-simulators-dir>/lib` to the top of the MATLAB path (done automatically after you open and compile the test model `test_matlab_system_2020b.mdl`).
+6. The `Matla Whole Body Simulator` library, along with the sub-libraries **robotDynamicsWithContacts**, **robotSensors** and **visualizers** should be visible in the Simulink Library Browser (press F5 to refresh the Library Browser if otherwise). 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">