Project

General

Profile

Wiki » History » Version 2

Martin Jacquet, 2021-09-10 04:46

1 2 Martin Jacquet
h1. Perceptive and torque-control NMPC wiki
2 1 Martin Jacquet
3 2 Martin Jacquet
h2. Prerequisite
4
5
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.
6
Some issues has been found while installing the software on Ubuntu 16.04 because of version incompatibility with Protoc and Protobuf.
7
The installation on a non-Linux OS has to be handled by the user.
8
>
9
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 repo or by the LAAS-CNRS robotic platform aims to be installed locally in the repository folder to avoid polluting the user's system.
10
>
11
12
h2. I - Software Overview
13
14
h3. I.1. Openrobots
15
16
Collections of all the open-source software used at LAAS. You can find more details in "Openrobots Wiki-Homepage":https://www.openrobots.org/wiki
17
>
18
19
20
h3. I-2. Robotpkg
21
22
"Robotpkg":http://robotpkg.openrobots.org/ is a packaging system for installing robotics software developed by the robotic community.
23
We will use robotpkg to install the required modules for the simulations (state estimation, gazebo interface...) as well as third-party dependencies (qpOases).
24
>
25
26
27
h3. I-3. GenoM
28
29
GenoM is a generator of modules, designed to be middleware independant, i.e. the same module can be compiled for, e.g., ROS, YARP, or Pocolibs, without any modification.
30
This allows a great code re-usability and to abstract the user from any specific choice of a middleware.
31
Originally GenoM has been developed tightly with Pocolibs, then from version 3, aka GenoM3, ROS templates has been provided.
32
>
33
Another specificity of GenoM is the interaction with and between components.
34
Each component is started independantly 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. 
35
>
36
37
h3. I-4. Pocolibs
38
39
"Pocolibs":https://www.openrobots.org/wiki/pocolibs/ is a middleware, like ROS.
40
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 performances.
41
>
42
43
h3. I-5. TeleKyb
44
45
The "TeleKyb":https://git.openrobots.org/projects/telekyb3 software platform provides the aerial-robotic oriented softwares developped at LAAS-CNRS.
46
In particular, we will use:
47
* "mrsim":https://git.openrobots.org/projects/mrsim-genom3, a Multi-Robot SIMulator. It is design to be a transparent interface w.r.t. the real aerial vehicles used in LAAS-CNRS. It makes the transition between simulation and experiment transparent, from the software point of view.
48
* "pom":https://git.openrobots.org/projects/pom-genom3, a UKF-based state estimator merging state feedback for different sources (e.g. mocap + IMU)
49
* "optitrack":https://git.openrobots.org/projects/optitrack-genom3,, to export the motion capture data to the genom software stack
50
* "rotorcraft":https://git.openrobots.org/projects/rotorcraft-genom3, the low-level interface, with either the simulated or real platform
51
* "nhfc":https://git.openrobots.org/projects/nhfc-genom3, near-hovering flight controller, used for unmodeled take-off and post-failure recoverues
52
* "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 implement take-off and waypoint-to-waypoint motions.
53
>
54
55
h3. I-6. Gazebo
56
57
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:
58
* "mrsim-gazebo":https://git.openrobots.org/projects/mrsim-gazebo a plugin to interface the simulated multi-rotor with the genom components (in place of mrsim)
59
* "optitrack-gazebo":https://git.openrobots.org/projects/optitrack-gazebo emulates the optitrack network interface to publish the model poses
60
>
61
The installation procedure for Gazebo can be found at http://www.gazebosim.org/tutorials?cat=install&tut=install_ubuntu&ver=9.0
62
63
64
h2. II - Installation procedure
65
66
This section is a tutorial on how to install the software architecture to run the simulations.
67
>
68
69
h3. II-0. Clone the Perceptive and torque-control NMPC repository
70
71
Clone the repo associated to this project. Its root will act as the devel folder for the following.
72
<pre><code class="shell">
73
git clone git://redmine.laas.fr/laas/perceptive-torque-nmpc.git
74
cd ./perceptive-torque-nmpc/
75
</code></pre>
76
>
77
To simplify the installation, we provide some environment variables in the @env.sh@ file.
78
In order to run all the installed executables, we need to setup the path to the newly created folders.
79
We provide a @env.sh@ script that exports all the required variables.
80
*/!\* the source has to be called in the repository root since it uses the @pwd@ command to export the paths.
81
<pre><code class="shell">
82
source env.sh
83
</code></pre>
84
>
85
86
h3. II-1. Setup robotpkg
87
88
(Steps taken from http://robotpkg.openrobots.org/install.html)
89
90
h4. 1. Clone the robotpkg lastest release:
91
92
<pre><code class="shell">
93
git clone git://git.openrobots.org/robots/robotpkg
94
</code></pre>
95
96
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:
97
98
<pre><code class="shell">
99
export ROBOTPKG_BASE=`pwd`/openrobots
100
</code></pre>
101
102
h4. 3. Install robotpkg
103
104
<pre><code class="shell">
105
cd robotpkg/bootstrap
106
./bootstrap --prefix=$ROBOTPKG_BASE
107
</code></pre>
108
109
h4. 4. Install the required components and their dependencies
110
111
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_.
112
To do so, we need to edit the config file: @$ROBOTPKG_BASE/etc/robotpkg.conf@. Add the following at the end of the file:
113
<pre><code class="shell">
114
PKG_OPTIONS.%-genom3 = \
115
        codels \
116
        pocolibs-server \
117
        pocolibs-client-c
118
119
PKGSET.mpcset = \
120
    sysutils/arduio-genom3 \
121
    architecture/genom3 \
122
    architecture/genom3-pocolibs \
123
    robots/rotorcraft-genom3 \
124
    localization/pom-genom3 \
125
    localization/optitrack-genom3 \
126
    motion/nhfc-genom3 \
127
    path/libkdtp \
128
    optimization/qpoases \
129
    net/genomix \
130
    supervision/matlab-genomix \
131
    supervision/tcl-genomix \
132
    shell/eltclsh \
133
    simulation/mrsim-genom3 \
134
    simulation/mrsim-gazebo \
135
    simulation/libmrsim \
136
    simulation/optitrack-gazebo
137
138
PREFER.lapack = robotpkg
139
PREFIX.matlab = <path/to/Matlab>
140
</code></pre>
141
The last line need to point to the Matlab root folder in the system (e.g. @/opt/Matlab@).
142
It is recommanded 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).
143
If Matlab is not installed on the system, remove the lines @supervision/matlab-genomix \@ and @PREFIX.matlab = <path/to/Matlab>@ from the above list.
144
Also, all the above is meant for using Pocolibs, not ROS. Futur version of this tutorial might come to use the ROS install.
145
>
146
Now return to the robotpkg folder and install all the set:
147
<pre><code class="shell">
148
cd robotpkg
149
make update-mpcset
150
</code></pre>
151
>
152
During the installation, some required dependencies need to be install with the usual package manager (e.g. @apt@ on Ubuntu). When the install stops, install the required packages and rerun the above command.
153
>
154
155
h4. 5. Matlab configuration
156
157
The last step is to update Matlab path to use the custom libraries, if relevant.
158
Add the following paths in the Matlab path window:
159
<pre><code class="shell">
160
</path/to/openrobots>/lib/matlab
161
</path/to/openrobots>/lib/matlab/simulink
162
</path/to/openrobots>/lib/matlab/simulink/genomix
163
</code></pre>
164
(change </path/to/openrobots> to the value of @$ROBOTPKG_BASE@)
165
166
h3. II-2. Install custom components
167
168
h4. List of the components
169
170
The @src/@ folder contains some additional components, in particular:
171
* *vision-idl*: the type declaration regarding the camera modules
172
* *camgazebo-genom3*: read the data from the gazebo inate cameras, via the gazebo API
173
* *camviz-genom3*: record and/or display the images from a camera
174
* *arucotag-genom3*: detect and filter (EKF-based) the ArUco markers/tags
175
* *maneuver-genom3*: custom version of maneuver (already mentionned) that publishes the reference trajectory for a specified receding horizon
176
* *uavmpc-genom3*: the NMPC controller presented in the paper
177
178
h4. Install the extra components
179
180
Since it they are not considered 'stable' as the one provided in robotpkg, we rather install them in a devel folder.
181
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:
182
<pre><code class="shell">
183
export DEVEL_BASE=`pwd`/devel
184
cd src/
185
</code></pre>
186
>
187
For the manual installation, @asciidoctor@ is needed. It can be installed using @apt@ or any package manager.
188
Each component here has to be installed manually, using @autoconf@. To do so, proceed as follow:
189
<pre><code class="shell">
190
cd src/<component>/
191
./bootstrap.sh
192
mkdir build
193
cd build
194
../configure --prefix=$DEVEL_BASE --with-templates=pocolibs/client/c,pocolibs/server
195
make install
196
</code></pre>
197
>
198
The component @vision-idl@ has to be installed first since it defines some type headers used by others.
199
The installation of the main component, @uavmpc-genom3@, is described in the next subection.
200
>
201
202
h4. Install the MPC controller
203
204
Before installing the MPC controller, we have to generate the @C@ sources corresponding to the desired model.
205
To do so, go to the @model_generation/@ folder:
206
<pre><code class="shell">
207
cd src/uavmpc-genom3/model_generation
208
</code></pre>
209
>
210
There is a README.md file there, explaining the requirements.
211
In short, the model sources are exported to @C@ using @CasADi@ in @python3@.
212
@python3@ along with @NumPy@, @SciPy@ and @CasADi@  are required, and easily installable on most Linux distributions (e.g. with @apt@ and @pip3@).
213
Then, the sources are generated using:
214
<pre><code class="shell">
215
python3 gen_model.py <quad or hexa>
216
</code></pre>
217
Then install the component as explained before, but add the following flags to the @configure@ command:
218
<pre><code class="shell">
219
configure --prefix=$GENOM_DEVEL --with-templates=pocolibs/client/c,pocolibs/server CPPFLAGS="-Wall -march=native -mfpmath=sse -I$ROBOTPKG_BASE/include" CXXFLAGS="-O3" CFLAGS="-O3" LDFLAGS="-L$ROBOTPKG_BASE/lib -Wl,-R$ROBOTPKG_BASE/lib"
220
</code></pre>
221
>
222
223
h3. II-3. Setup the environment
224
225
In order to run all the installed executables, we need to setup the path to the newly created folders.
226
All the required variables are exported in the @env.sh@ file.
227
228
h2. III - Running the simulation
229
230
We @ws/@ folder contains all the material to run a basic simulation with the NMPC.
231
In a terminal, launch the @launch.sh@ script. It starts all the genom components, in background. It is used as a console since it displays warnings or error during runtime.
232
In another terminal, start gazebo with one of the world file provided.
233
Finally, run @matlab@ or @eltclsh@ and go to the relevant subsection below.
234
>
235
236
237
h3. III.1. Running the simulations with Matlab
238
239
Change the flag at the top of the script to use either the quadrotor or the hexarotor.
240
>
241
The provided scripts are organised as follow
242
* The two @param_*.m@ scripts provide the parameters for either a standard colinear quadrotor (denoted *qr*) and a tilted-propeller hexarotor (denoted *hr*).
243
* The @init.m@ script that connects all the components together and call the initialization services for all provided components.
244
* The @traj_*.m@ that runs the specific trajectories for a specific scenario.
245
>
246
Run the init script and wait until it stops displaying in the console.
247
If no error occured, run any traj script then press enter between each step to proceed to the next one. The evolution can be watched in gazebo and in the console terminal in parallel.
248
>
249
250
251
h3. III.2. Running the simulations with tcl
252
253
The tcl scripts are called from the @eltclsh@ shell environment. In a terminal, run:
254
<pre><code class="tcl">
255
eltclsh
256
</code></pre>
257
>
258
In order to run the script and keep the variables in the environment, use the @source@ command.
259
The script architecture is the same as the matlab one. Change the flags init.tcl script, then:
260
<pre><code class="tcl">
261
source init.tcl
262
source traj_<name_name>.tcl
263
</code></pre>
264
>
265
266
h3. III.3. List of the provided trajectories
267
268
* @traj_mpc@ runs a flight using the nmpc without any perceptive constraint, reaching successive waypoints.
269
* @traj_track@ runs a flight using the nmpc with a couple of perceptive constraints, again reaching successive waypoints.
270
It corresponds to the experiment presented in section *V-B* in the paper.
271
* @traj_follow@ runs a flight where we follow a _target_ quadrotor equipped with a marker. The NMPC-controlled UAV needs to stay on top of it, while the _target_ quadrotor is given successive waypoints.
272
It corresponds to the experiment presented in Section *V-C* in the paper.
273
>
274
275
h3. III.4. Comments on how to use the simulator
276
277
* In order to perform the exact simulation performed in Section *V-E* of the paper, one need first to generate the @model_hexa3.py@ file and recompile @uavmpc-genom3@.
278
Then, modify the parameters in the @init@ script: @ground_tag = 1;@, @z_desired = 2;@ and @target_compliant = 0;@
279
* In the experiment presented in the paper, the wall target was 1m high while it is 2m high in the gazebo simulation.
280
* In order to recover from a failed simulation, reset the positions in Gazebo and rerun the scripts.
281
* The waypoints in the traj trajectories can be changed freely to change the scenarios. Of course, in the markers have to be visible when calling the @track@ or @follow@ services from the MPC.
282
* In order to "manually" control the UAV through the MPC software, one can run any @traj@ file up to the _MPC_ section. Then, waypoints can be provided to the maneuver trajectory planner.
283
** go to position _(x,y,z)_ rotated of _yaw_ radians, in _t_ seconds (t=0 means minimum time). (nb: is the trajectory is not feasible in _t_, nothing happens.)
284
** in tcl, use @maneuver::goto -f "x y z yaw t" &@ ; the @&@ runs the command in background to let the user call other waypoints of actions while the UAV moves.
285
** in matlab, use @maneuver.goto('-a', x, y, z, yaw, t);@ ; the @'-a'@ is equivalent to the @&@ above