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.

Finally, to run the simulations and interface with the middleware, it is assumed to have @MATLAB@ installed.

The provided code has been tested with @MATLAB >= r2019b@; other releases could be compatible but they have not been tested. If you run another version and notice any issue or that the code is compatible, please do not hesitate to contact the authors to point that out, so that this wiki can be updated.

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>