Visual and Physical Control Architecture for Flying End-Effector

h1. Wiki

{{toc}}

*TODO*:

* provide an alternative for joystick

* adapt paths in airpharo_user as much as possible

* use default paths of the EEPROMs in gazebo world (for plugin)

* explain libdynamixel and dynamixel-gazebo (section II-2)

* how to use GInterface (section III)

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.

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.

>

In order to use our launcher, it is required to use a USB joystick.

>

h2. I - Software Overview

>

h3. I.1. 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-2. Robotpkg

>

"Robotpkg":http://robotpkg.openrobots.org/ is a packaging system for installing robotics software developed by the robotic 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-3. 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 to abstracts the user from any specific choice of a 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 a h2 intance, 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-4. Pocolibs

>

"Pocolibs":https://www.openrobots.org/wiki/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, this leads to greater delays and loss of performance.

>

h3. I-5. 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:

* "pom":https://git.openrobots.org/projects/pom-genom3, a UKF-based state estimator merging state feedback for different sources (e.g. mocap + IMU)

* "optitrack":https://git.openrobots.org/projects/optitrack-genom3, to export the motion capture data to the genom software stack

* "rotorcraft":https://git.openrobots.org/projects/rotorcraft-genom3, the low-level interface, with either the simulated or real platform

* "maneuver":https://git.openrobots.org/projects/maneuver-genom3, a global trajectory planner, providing position and attitude (as quaternions) as well as first and second derivatives. It implements take-off and waypoint-to-waypoint motions. A joystick-based velocity control is implemented, but not used in this project.

* "dynamixel":https://git.openrobots.org/projects/dynamixel-genom3, an interface to control the Dynamixel motors. It is used since the gazebo gripper plugin used for the simulation (presented below) adopts the same interface protocol as the Dynamixel motors (precisely Dynamixel Protocol 2.0).

* "joystick":https://git.openrobots.org/projects/joystick-genom3, a component to read the joystick inputs.

>

h3. I-6. Gazebo

>

To simulate the platform, we use the "Gazebo":http://gazebosim.org/ simulator. To interface it with the genom software stack, we use two dedicated components:

* "mrsim-gazebo":https://git.openrobots.org/projects/mrsim-gazebo a plugin to interface the simulated multi-rotor with the genom components. It uses "libmrsim":https://git.openrobots.org/projects/libmrsim, a Multi-Robot SIMulator interface, 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 transparent, from the software point of view.

* "optitrack-gazebo":https://git.openrobots.org/projects/optitrack-gazebo emulates the optitrack network interface to publish the model poses.

>

The installation procedure for Gazebo can be found at http://www.gazebosim.org/tutorials?cat=install&tut=install_ubuntu&ver=9.0

>

h3. I-7. TCL

>

The interaction with the GenoM components is handled using a scripting language, implementing the communication through the "genomix":https://git.openrobots.org/projects/genomix HTTP server.

There are two available language interfaces: "matlab":https://git.openrobots.org/projects/matlab-genomix and "tcl":https://git.openrobots.org/projects/tcl-genomix.

"eltclsh":https://git.openrobots.org/projects/eltclsh is an in-terminal TCL shell to interact with the components. However, in the following, we provide a TCL-based software that is all-embedded to avoid the use of the inline interaction through eltclsh.

>

h2. II - Installation procedure

>

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

>

h3. II-0. Clone the Visual and Physical Control Architecture for Flying End-Effector repository

>

Clone the repo associated to this project, using the git daemon. Its root will act as the devel folder for the following.

<pre><code class="shell">

git git://redmine.laas.fr/laas/visual-physical-control-architecture.git

cd ./visual-physical-control-architecture/

</code></pre>

>

To simplify the installation, we provide a @env.sh@ script that exports all the required variables.

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

*/!\* the source has to be called in the repository root since it uses the @pwd@ command to export the paths.

<pre><code class="shell">

source env.sh

</code></pre>

>

h3. II-1. Set up robotpkg

>

(Steps taken from http://robotpkg.openrobots.org/install.html)

>

h4. 1. Clone the robotpkg lastest release:

<pre><code class="shell">

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

</code></pre>

h4. 2. Check that the @openrobots/@ folder exists in the repository root, and update the environement variables accordingly if you didn't source the @env.sh@ file:

<pre><code class="shell">

export ROBOTPKG_BASE=`pwd`/openrobots

</code></pre>

h4. 3. Install robotpkg

<pre><code class="shell">

cd robotpkg/bootstrap

./bootstrap --prefix=$ROBOTPKG_BASE

</code></pre>

h4. 4. 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@; but 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 at the end of the file:

<pre><code class="shell">

PKG_OPTIONS.%-genom3 = \

        codels \

        pocolibs-server \

        pocolibs-client-c

PKGSET.mpcset = \

    middleware/pocolibs \

    architecture/genom3 \

    architecture/genom3-pocolibs \

    robots/rotorcraft-genom3 \

    localization/pom-genom3 \

    localization/optitrack-genom3 \

    net/genomix \

    supervision/tcl-genomix \

    shell/eltclsh \

    simulation/mrsim-gazebo \

    simulation/libmrsim \

    simulation/optitrack-gazebo \

    hardware/dynamixel-genom3 \

    joystick-genom3

PREFER.lapack = robotpkg

PREFIX.matlab = <path/to/Matlab>

</code></pre>

The last line 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 the user to modify them. However, we also provide all the launch files in tcl, as well as the environment to run them (@shell/eltclsh@ in the above list is a custom tcl script shell).

If Matlab is not installed on the system, remove the lines @supervision/matlab-genomix \@ and @PREFIX.matlab = <path/to/Matlab>@ from the above list.

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

>

Now return to the robotpkg folder and install all the set:

<pre><code class="shell">

cd robotpkg

make update-mpcset

</code></pre>

>

During the installation, some required dependencies need to be installed with the usual package manager (e.g. @apt@ on Ubuntu). When the install stops, install the required packages and rerun the command above.

>

h3. II-2. Install custom components

>

h4. List of the components

>

The @src/@ folder contains some additional components, in particular:

* *vision-idl*: provide the type declarations regarding the camera modules.

* *camgazebo-genom3*: read the data from the gazebo innate camera, via the gazebo API.

* *camviz-genom3*: record and/or display the images from a camera.

* *arucotag-genom3*: detect and filter (EKF-based) the ArUco markers/tags.

* *phynt-genom3*: handle physical interaction (wrench observer and admittance filter).

* *uavatt-genom3*: attitude controller for fully-actuated UAVs.

* *uavpos-genom3*: position controler for fully-actuated UAVs.

* *visualservoing-genom3*: implement the state machine for the pick-n-place experiment and provide the reference trajectory (either based on visual-servoing, or based on waypoints for takeoff/exploration).

* *libdynamixel*: provide the type and function declarations used by magdynamixel-gazebo.

* *magdynamixel-gazebo*: gazebo plugin that emulates a magnetic gripper and adopts the Dynamixel Protocol 2.0.

>

h4. Install the extra components

>

Since the extra necessary components are not considered 'stable' as the one provided in robotpkg, we rather install them in a devel folder.

Go to the project root, check that the devel folder exists, export the path if you didn't source the @env.sh@. Then go to the sources folder:

<pre><code class="shell">

export DEVEL_BASE=`pwd`/devel

cd src/

</code></pre>

For the manual installation, @asciidoctor@ is needed. It can be installed using @apt@ or any package manager.

Each component here has to be installed manually, using @autoconf@. To do so, proceed as follow:

<pre><code class="shell">

cd src/<component>/

./bootstrap.sh

mkdir build

cd build

../configure --prefix=$DEVEL_BASE --with-templates=pocolibs/client/c,pocolibs/server

make install

</code></pre>

The component @vision-idl@ has to be installed first since it defines some type headers used by others.

>

h3. II-3. Set up the environment

>

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

All the required variables are exported in the @env.sh@ file.

>

h2. III - Running the simulation

>

*The part is going to be filled soon.*

>

h3. III-1. GInterface

>

In order to start all the required software, connect the components together and store the parameters, we use a TCL-based interface.

The folder called @ginterface@ contains all the necessary scripts.

For convenience, we provide as many generic scripts as possible.

The next section explains how to set up the GInterface, then how to use it to run the proposed simulation.

We also provide the "mission" script used in the experiment presented in the paper, so that the reader can have a glance at the parameters used in this experiment.

h3. III-2. Set up the GInterface

>

h4. Install dependencies

>

Before being able to run @GInterface@, the following packages might be required to be installed with the usual package manager (e.g. @apt@ on Ubuntu): @tcllib@, @rsync@, @grsync@, @rpcbind@, @python-pandas@, @python-qt4@.

>

h4. Configuration

>

Navigate inside the @GInterface@ repository and then in the folder @users@.

Here open the file @airpharo_user.tcl@, whose content is reported below for convenience.

<pre>

#!/bin/sh

# -*-Tcl-*- \

exec tclsh "$0" ${1+"$@"}

set user [dict create \

nickname "airpharo_user" \

pc_name "pandartin" \

ground_station_hostname "pandartin-wifi" \

path_tcl "/opt/openrobots/lib/tcl-genomix" \

path_rep "/home/mjacquet/RIS/work/ginterface" \

path_sup "/home/mjacquet/ginterface" \

path_log "/tmp" \

path_log_sim "/tmp" \

path_launch "/home/mjacquet/RIS/work/ginterface/launchers" \

path_devel "/home/mjacquet/RIS/genom_devel" \

path_openrobots "/opt/openrobots" \

path_gazebo_world "/home/mjacquet/RIS/work/ginterface/gazebo/worlds" \

modules {rotorcraft pom optitrack dynamixel joystick uavatt uavpos maneuver phynt arduio t265 arucotag camgazebo visualservoing camviz} \

]

</pre>

Modify the paths and other user configurations according to your system setup. Below more details regarding these parameters are reported: 

* *pc_name*: the name of your machine, when running simulations, otherwise it is the name of the machine on the aerial platform when running experiments.

* *ground_station_hostname*: the name of your machine when accessing it through the network (e.g. through @ssh@).

* *path_tcl*: path to @tcl-genomix@ where the software in @robotpkg@ has been installed. If you followed the instructions of this wiki it should be @<path-to-ginterface>/ginterface/openrobots/lib/tcl-genomix@.

* *path_rep*: path to the @GInterface@ repository.

* *path_sup*: path to the @GInterface@ repository in the machine mounted in the aerial platform. This path is not required for running the provided simulation.

* *path_log*: path where the logs are saved during experiments (in the machine specified at @pc_name@).

* *path_log_sim*: path where the logs are saved during simulations (in the machine specified at @ground_station_hostname@).

* *path_launch*: path to the @launchers@ folder of the @GInterface@ repository in your machine.

* *path_devel*: path to the @devel@ folder where the extra necessary components have been installed. If you follow the instructions of this wiki it should be @<path-to-ginterface>/ginterface/devel@.

* *path_openrobots*: path where the  software in robotpkg has been installed. If you followed the instructions of this wiki it should be @<path-to-ginterface>/ginterface/openrobots@.

* *path_gazebo_world*: path where the world files for Gazebo are located. If you followed the instructions of this wiki it should be @<path-to-ginterface>/ginterface/gazebo/worlds@.

h2. III-3. Run the simulation

>

First of all, source the @env.sh@ file. Then, connect a USB joystick to your pc, prior to running the simulation.

Open a terminal and navigate to the repository root and run the following command:

<pre>

$ ./GInterface.tcl

</pre>

At this point, a window should appear. Click on @File@, then on @Missions@ and select @sim_fiberthex@.

After that, @Gazebo@ should be launched, and right after a @XTerm@ console should appear.

** Then other two graphical interfaces should appear.

** You should have something similar to what depicted in the next picture.

!{width:80%}sim_fiberthex.png!

** Press the central button of the joypad until the propellers start to run. If everything went well, the propellers should spin.

** Then, on the graphical interface with the labels @POM@, @IMU@ and @OPTITRACK@, click on @Options@ and then on @Command Waypoint@.

** Press the button @Take Off@. The drone now should have taken off.

** Insert a desired z in the related field and press @send@. The drone now should fly at the commanded altitude.

Now some configurations steps are necessary, in order to run correctly @GInterface@.

To test that the configuration is correct, a simple demo will be launched.

* Open your @.bashrc@ and add the following line:

<pre>

export GAZEBO_MODEL_PATH=${GAZEBO_MODEL_PATH}:$<somewhere>/ginterface/gazebo/models

</pre>

this will allow Gazebo to see all the models contained in @GInterface@ repository.

Replace @<somewhere>@ in order to match the location in which you cloned the @GInterface@ repository.

*NB:* If you have already an SDF model for Gazebo, which is contained in a folder with the same name of those contained into @ginterface/gazebo/models@ but at a different path, then the world files, which include these models, may include the wrong version. 

*Please verify to do +not+ have model folders with same names of those contained in @ginterface/gazebo/models@, at other locations which are added to @$GAZEBO_MODEL_PATH@!*