NMPC for Human Aerial Handover

h1. NMPC for Human Aerial Handover WIKI

{{toc}}

h2. Foreword

In case of questions, queries, comments, or bug reports, feel free to use the @ISSUES@ system or contact the corresponding authors (contact details in the project's "@OVERVIEW@ panel":https://redmine.laas.fr/projects/nmpc-handover).

h2. Prerequisites

The framework has been written and tested using @Ubuntu 18.04@ since it is the OS used by the LAAS-CNRS robotic platform. It should work seamlessly on a recent Linux version, but there is no guarantee.

Some issues have been found while installing the software on @Ubuntu 16.04@ because of version incompatibility with @Protoc@ and @Protobuf@.

The installation on a non-Linux OS has to be handled by the user.

The installation assumes the use of a package manager (e.g. @apt@) to install some dependencies, as well as the @Gazebo@ simulator. Everything provided in this repository or by the LAAS-CNRS robotic platform aims to be installed locally in the repository folder to avoid polluting the user's system.

h2. I. Software Overview

h3. I.A. Openrobots

Collections of all the open-source software used at LAAS. You can find more details in "Openrobots Wiki-Homepage":https://www.openrobots.org/wiki.

h3. I.B. Robotpkg

"@Robotpkg@":http://robotpkg.openrobots.org/ is a packaging system for installing robotics software developed by the robotics community.

We will use @robotpkg@ to install the required modules for the simulations (state estimation, @Gazebo@ interface...) as well as third-party dependencies (@qpOases@).

h3. I.C. GenoM

@GenoM@ is a generator of modules, designed to be middleware independent, i.e. the same module can be compiled for, e.g., ROS, YARP, or Pocolibs, without any modification.

This allows a great code re-usability and abstracts the user from any specific choice of middleware.

Originally @GenoM@ has been developed tightly with @Pocolibs@, then from version 3, aka @GenoM3@, @ROS@ templates have been provided.

Another specificity of GenoM is the interaction with and between components.

Each component is started independently like a Linux executable (within a @roscore@, for @ROS@, or an @h2@ instance, for @Pocolibs@), then the connection between ports (or topics) is made using a supervisor, "@Genomix@":https://git.openrobots.org/projects/genomix, either with "@MATLAB@":https://git.openrobots.org/projects/matlab-genomix or "@TCL@":https://git.openrobots.org/projects/tcl-genomix.

h3. I.D. Pocolibs

@Pocolibs@ is a middleware, like @ROS@.

It aims at being lighter and faster than ROS, when running on a single machine, thanks to the exploitation of shared memory. @ROS@, on the other hand, uses a network layer for sending messages between nodes, which leads to greater delays and loss of performance.

h3. I.E. TeleKyb

The "@TeleKyb@":https://git.openrobots.org/projects/telekyb3 software platform provides the aerial-robotic oriented software developed at LAAS-CNRS.

In particular, we will use:

* @mrsim@, a Multi-Robot SIMulator. It is designed to be a transparent interface w.r.t. the real aerial vehicles used in LAAS-CNRS. It makes the transition between simulation and experiments seamless, from the software point of view.

* @pom@, a UKF-based state estimator merging state-feedback measurements of different sources (e.g. Motion Capture + IMU).

* @optitrack@, to export the motion capture data to the @genom@ software stack.

* @rotorcraft@, the low-level interface, with either the simulated or real platform.

* @nhfc@, near-hovering flight controller, used for unmodeled take-off and landing.

* @maneuver@, a trajectory planner, providing position and attitude (as quaternions) as well as first- and second-order derivatives. It implements waypoint-to-waypoint trajectory generation.

h3. I.F. Gazebo

To simulate the platform, we use the @Gazebo@ simulator. To interface it with the @genom@ software stack, we use two dedicated components:

* @mrsim-gazebo@ a plugin to interface the simulated multi-rotor with the @genom@ components (in place of @mrsim@).

* @optitrack-gazebo@ emulates the optitrack network interface to publish the model poses.

The installation procedure for @Gazebo@ can be found in the official documentation "Install Gazebo using Ubuntu packages -- ver. 9":http://www.gazebosim.org/tutorials?cat=install&tut=install_ubuntu&ver=9.0.

h2. II. Installation Procedure

This section is a tutorial on how to install the software architecture to run the simulations.

h3. II.A. Clone the Perceptive and torque-control NMPC repository

Clone the repo associated with this project. Its root will act as the @devel@ folder for the following.

<pre><code class="shell">

git clone git://redmine.laas.fr/laas/nmpc-handover.git

cd ./nmpc-handover

</code></pre>

To simplify the installation, we provide some environment variables in the @env.sh@ file.

In order to run all the installed executables, we need to set up the path to the newly created folders.

We provide an @env.sh@ script that exports all the required variables.

*/!\ :* the @source@ command has to be called within this repository's root since it uses the @pwd@ command to export the paths.

<pre><code class="shell">

source env.sh

</code></pre>

h3. II.B. Setup robotpkg

> These steps are taken from the official documentation "Install":http://robotpkg.openrobots.org/install.html.

# Clone the robotpkg latest release.

<pre><code class="shell">

git clone git://git.openrobots.org/robots/robotpkg

</code></pre>

# Check that the @openrobots/@ folder exists in the repository root, and update the environement variables accordingly, if you haven't already sourced the @env.sh@ file.

<pre><code class="shell">

export ROBOTPKG_BASE=`pwd`/openrobots

</code></pre>

# Install @robotpkg@.

<pre><code class="shell">

cd robotpkg/bootstrap

./bootstrap --prefix=$ROBOTPKG_BASE

</code></pre>

# Install the required components and their dependencies

The installation can be done 'manually' by navigating to the desired folder in @./robotpkg/@ and install with @make update@. +Anyway, we will simplify the process using a set+.

To do so, we need to edit the config file: @$ROBOTPKG_BASE/etc/robotpkg.conf@. Add the following lines at the end of the file:

<pre><code class="shell">

PKG_OPTIONS.%-genom3 = \

        codels \

        pocolibs-server \

        pocolibs-client-c

PKGSET.mpcset = \

    architecture/genom3 \

    architecture/genom3-pocolibs \

    localization/pom-genom3 \

    localization/optitrack-genom3 \

    hardware/joystick-genom3 \

    motion/nhfc-genom3 \

    net/genomix \

    optimization/qpoases \

    path/maneuver-genom3 \

    simulation/mrsim-gazebo \

    simulation/optitrack-gazebo \

    supervision/matlab-genomix \

    supervision/tcl-genomix \

    robots/rotorcraft-genom3

PREFER.lapack = robotpkg

PREFIX.matlab = <path/to/MATLAB>

</code></pre>

The last line (<path/to/MATLAB>) needs to point to the @MATLAB@ root folder in the system (e.g. @/opt/Matlab@).

It is recommended to use @MATLAB@ for the proposed simulations since the syntax is more intuitive and comprehensible for an end-user who will modify them.

If @MATLAB@ is not installed on the system, please install it, since the provided interface to the @GenoM@ components is provided only in @MATLAB@.

Also, all the above is meant for using Pocolibs, not @ROS@. Future versions of this tutorial might come to use the @ROS@ install.

Now return to the @robotpkg@ folder and install the custom set by typing:

<pre><code class="shell">

cd robotpkg

make update-mpcset

</code></pre>