Skip to content

Installation

Jump to bottom
Heiko Renz edited this page Dec 19, 2023 · 3 revisions

We provide two options for using the robot motion planner, and it's environmental consideration:

  • Simplified use: Use our prepared Dockerfile (recommended for checking out the general functionalities of the provided system)
  • Manual Installation: A step-by-step installation guide for a customized setup (recommended for an improved version with the option for further features and own customizations)

At the end of this page we provide information about our systems and possible limitations due to various hardware.

Simplified Use: Docker

Please be sure that you have a running docker version on your PC.

Note, that the Docker installation automatically executes commands for various dependencies. Therefore, please check the dependencies on our Dependencies page.

Tested with docker version 24.0.2

  1. Manually download the Dockerfile from the docker folder in the repository

  2. Build the docker image (navigate into the folder where the Dockerfile is located or add the path of the Dockerfile):

    docker build -t mhp . -f Dockerfile

    This command builds a docker image named mhp, which is ready to use

    Note that several third-party dependencies are directly built by using this command. See also Dependencies

Alternative: Instead of running step 1. and step 2. you can directly build the docker file from our GitHub:

docker build -t mhp https://github.com/rst-tu-dortmund/mhp4hri.git#melodic-devel-github:docker

  1. You have to permit access to your display.

    Ubuntu: xhost + (Note, this deactivates the access control) or add only the root user xhost local:root

  2. Run the docker image mhp:

    docker run -it --rm --privileged --net=host --env=NVIDIA_VISIBLE_DEVICES=all --env=NVIDIA_DRIVER_CAPABILITIES=all --env=DISPLAY --env=QT_X11_NO_MITSHM=1 -v /tmp/.X11-unix:/tmp/.X11-unix --gpus all mhp:latest

    The additional arguments allow the docker container to use the graphic card of the host system.

    Note that these commands are for an NVIDIA graphic card. If you have a different manufacturer, you must adapt these arguments. In case you run into erros regarding the graphic card with a message like "could not select driver" check the following links for further information: https://askubuntu.com/questions/1400476/docker-error-response-from-daemon-could-not-select-device-driver-with-capab and https://github.com/NVIDIA/nvidia-docker/issues/1034. It could be possible that the nvidia-toolkit is missing on your system to support graphic outputs of docker containers.

    This command enters the docker container directly in the ROS Workspace (_catkin_ws), already prepared for testing our planer.

    If you want to attach another terminal to the same docker container use:

    docker exec -it <containerName> /bin/bash

  3. Start the motion planner and a default environment:

    roslaunch ur_launch ur10_simulation.launch

    For further steps on how to use the planner, please refer to Usage.

Manual Installation

This installation is recommended if you want to install different linear solvers for Ipopt or explore and customize the code to your needs. Please check the Dependencies for further information and licensing.

Prerequisites

  • Ubuntu 18.04
  • ROS Melodic (we recommend the desktop-full installation)
  • (optional) STFC account and license to download HSL (Harwell Subroutine Library) (Coin-HSL)

Installation

  1. Install dependencies

    sudo apt install gcc g++ gfortran git patch wget pkg-config libmetis-dev checkinstall zip

  2. Variant 1 Intel MKL → Recommended

    Install Intel MKL (Math Kernel Library) → Optional but recommended for faster calculations (in case you don't use an Intel CPU, check different optimizers, e.g. OpenBLAS):

    Installation steps

    1. Download the Intel MKL from the Intel oneAPI Toolkits website

    2. Click Download for Intel oneAPI Base Toolkit

    3. Select Linux (Select Operating System), Online Installer (Select distribution) and 2023.2.0 (Select version)

      Other versions may work as well but are not tested.

    4. Follow the steps of the Command Line Download to download the installer:

      Installer steps

      1. Download installer (the link here is just an example; please use the link from the Intel website):

        wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/xxx/l_BaseKit_p_xxxx.x.x.xxxxx.sh

      2. Make the installer executable:

        chmod +x l_BaseKit_p_xxxx.x.x.xxxxx.sh

      3. Run the installer:

        sudo sh ./l_BaseKit_p_xxxx.x.x.xxxxx.sh

    5. Source the environment settings:

      source /opt/intel/oneapi/setvars.sh

      Note: You have to source the environment settings every time you want to use the Intel MKL and in each terminal. To avoid this, you can add the command to your .bashrc file:

      echo "source /opt/intel/oneapi/setvars.sh" >> ~/.bashrc

    Variant 2 LAPACK

    Install Lapack:

    Installation steps 
    sudo apt install liblapack-dev

  3. Prepare Ipopt

    1. Enter your home directory: 
      cd ~
    2. Create a folder for the Ipopt installation: 
      mkdir ipopt_ws

  4. Install linear solvers (you can install both or only one option)

    1. HSL (Harwell Subroutine Library)→ recommended

      Installation steps

      1. Enter the Ipopt workspace:

        cd ~/ipopt_ws

      2. Clone the Third-Party HSL Repository and enter the folder:

        git clone https://github.com/coin-or-tools/ThirdParty-HSL.git
cd ThirdParty-HSL

      3. Download the coinHSL solvers (as a zip) at the coin-HSL website (you need a STFC account and license to download the solvers)

      4. Unzip the downloaded folder into the ThirdParty-HSL folder and link to the general name:

        unzip <pathToDownloadedZip> -d <pathToThirdParty-HSL>
ln -s coinhsl-x.y.z coinhsl

      5. Resolve dependencies:

        ./configure

        Check the output whether the solvers are found (MA27, MA28, MA57 .....) and if the Optimizer is found:

        checking for LAPACK... yes: Intel MKL (-lmkl_intel_lp64 -lmkl_sequential -lmkl_core -lm)

        In case you are using Lapack, it might say generic-module

      6. Build the solvers (-j for using multiple cores):

        make -j

      7. Install the solvers (checkinstall is recommended to create a .deb file for easy maintenance):

        sudo checkinstall

        Answer the questions for package docs with y:

        Should I create a default set of package docs?  [y]: y

        Change the summary, name, and version (by following the GitHub link) of the package to install:

        1 -  Summary: [ coinhsl ]
2 -  Name:    [ coinhsl ]
3 -  Version: [ 2.2.1 ]

        The package should install automatically.

    2. MUMPS (MUltifrontal Massively Parallel sparse direct Solver)

      Installation steps

      1. Enter the Ipopt workspace:

        cd ~/ipopt_ws

      2. Clone the Third-Party MUMPS Repository and enter the folder:

        git clone https://github.com/coin-or-tools/ThirdParty-Mumps.git
cd ThirdParty-Mumps

      3. Apply patches:

        ./get.Mumps

      4. Resolve dependencies:

        ./configure

        Check the output whether the Optimizer is found:

        checking for LAPACK... yes: Intel MKL (-lmkl_intel_lp64 -lmkl_sequential -lmkl_core -lm)

        In case you are using Lapack, it might say generic-module

      5. Build the solvers (-j for using multiple cores):

        make -j

      6. Check the version for installation:

        cat MUMPS/VERSION | grep MUMPS

      7. Install the solvers (checkinstall is recommended to create a .deb file for easy maintenance):

        sudo checkinstall

        Answer the questions for package docs with y:

        Should I create a default set of package docs?  [y]: y

        Change the summary, name, and version (from step 6) of the package to install:

        1 -  Summary: [ mumps ]
2 -  Name:    [ mumps ]
3 -  Version: [ 5.6.0 ]

        The package should install automatically.

  5. Install Ipopt

    1. Enter the Ipopt workspace:

      cd ~/ipopt_ws

    2. Clone the Ipopt repository and enter the folder:

      git clone https://github.com/coin-or/Ipopt.git
cd Ipopt

    3. Create and enter the build folder:

      mkdir build
cd build

    4. Configure Ipopt:

      ../configure

      Check the output whether the optimizer and the desired solver packages are found:

      checking for LAPACK... yes: Intel MKL (-lmkl_intel_lp64 -lmkl_sequential -lmkl_core -lm)
...
checking for package Mumps... yes
...
checking for package HSL... yes

      In case you are using Lapack, it might say generic-module.

    5. Build Ipopt:

      make -j

    6. Run tests and check if they are passed:

      make test

    7. Install Ipopt (checkinstall is recommended to create a .deb file for easy maintenance):

      sudo checkinstall

      Answer the questions for package docs with y:

      Should I create a default set of package docs?  [y]: y

      Change the summary, name, and version (from the ChangeLog.md in the Ipopt folder) of the package to install:

      1 -  Summary: [ ipopt ]
2 -  Name:    [ ipopt ]
3 -  Version: [ 3.14.13 ]

      Answer the question about showing extra files with n:

      Do you want me to list them?  [n]: n

      Answer the question for excluding them with y:

      Should I exclude them from the package? (Saying yes is a good idea)  [n]: y

      The package should install automatically.

  6. Install planner

    1. Initialize ROS workspace: 
      mkdir -p ~/mhp_ws/src
cd ~/mhp_ws/src
catkin_init_workspace
cd ~/mhp_ws
catkin_make
    2. Clone the repository into the src folder: 
      cd ~/mhp_ws/src
git clone https://github.com/rst-tu-dortmund/mhp4hri.git
    3. Install dependencies: 
      cd ~/mhp_ws
rosdep update --include-eol-distros # in case you are using ROS melodic
rosdep install --from-paths src --ignore-src -y
    4. Build the workspace 
      cd ~/mhp_ws
catkin_make -ADDITIONAL_ARGUMENTS
      Possible additional arguments define the usage of further dependencies, e.g. (the given values are the default values): 
      -DUSE_ARMADILLO=ON
-DUSE_DKM=ON
-DUSE_SAVITZKY_GOLAY=OFF
-DUSE_SPL=OFF
-DUSE_NATNET=OFF
      Further information about these packages can be found in the Dependencies section.

  7. Start the planner. For further instructions on how to use the planner, please refer to Usage.

    roslaunch ur_launch ur10_simulation.launch

Tested Systems (Requirements)

Depending on your hardware it is possible that the planner requires a higher time to solve the problem, which may affect the real-time capability of the planner. Therefore, we can not define fixed system requirements for the planner, but in the following two systems are listed which are used to run the planner (sometimes also the execution time extends on these systems, but nevertheless a non-optimal solution can be used then).

System 1:

  • Intel Core i5-12600KF CPU @ 3.70GHz
  • 32 GB RAM
  • NVIDIA GeForce RTX 3060 with 12 GB VRAM
  • Ubuntu 18.04 & ROS Melodic

System 2:

  • Intel Core i7-8700 CPU @ 3.20GHz
  • 32 GB RAM
  • NVIDIA GeForce GTX 1050 Ti with 4 GB VRAM
  • Ubuntu 18.04 & ROS Melodic

Furthermore, our lab provides access to a real robot and a Motion Capture System for testing purposes. Nevertheless, the planner can be adapted to various robots and Mocap systems (or other tracking options providing obstacle poses in ROS)

  • Robot: Universal Robot UR10 CB-Series (10kg Payload)
  • Motion Capture System: OptiTrack System with 12 Flex 13 Cameras and Motive 2
Clone this wiki locally