Project

General

Profile

Wiki » History » Version 60

Gianluca Corsini, 2022-10-12 14:11

1 23 Gianluca Corsini
h1. Wiki
2
3 20 Gianluca Corsini
{{toc}}
4
5 8 Martin Jacquet
*TODO*:
6 24 Gianluca Corsini
* provide an alternative for joystick
7 1 Martin Jacquet
8 23 Gianluca Corsini
h2. Prerequisites
9 18 Gianluca Corsini
>
10 27 Gianluca Corsini
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 guaranteet
11 1 Martin Jacquet
The installation on a non-Linux OS has to be handled by the user.
12 2 Martin Jacquet
>
13 18 Gianluca Corsini
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.
14 1 Martin Jacquet
>
15 41 Martin Jacquet
In order to use our launcher, it is required to use a USB joystick (such a Microsoft XBox joystick for PC or any equivalent one).
16 1 Martin Jacquet
>
17
18 23 Gianluca Corsini
h2. I - Software Overview
19 22 Gianluca Corsini
>
20 23 Gianluca Corsini
21
h3. I.1. Openrobots
22 1 Martin Jacquet
>
23 2 Martin Jacquet
Collections of all the open-source software used at LAAS. You can find more details in "Openrobots Wiki-Homepage":https://www.openrobots.org/wiki
24
>
25 22 Gianluca Corsini
26 23 Gianluca Corsini
h3. I-2. Robotpkg
27 1 Martin Jacquet
>
28 2 Martin Jacquet
"Robotpkg":http://robotpkg.openrobots.org/ is a packaging system for installing robotics software developed by the robotic community.
29
We will use robotpkg to install the required modules for the simulations (state estimation, gazebo interface...) as well as third-party dependencies (qpOases).
30
>
31
32 23 Gianluca Corsini
h3. I-3. GenoM
33 2 Martin Jacquet
>
34 18 Gianluca Corsini
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.
35
This allows a great code re-usability and to abstracts the user from any specific choice of a middleware.
36 1 Martin Jacquet
Originally GenoM has been developed tightly with Pocolibs, then from version 3, aka GenoM3, ROS templates have been provided.
37 18 Gianluca Corsini
>
38 2 Martin Jacquet
Another specificity of GenoM is the interaction with and between components.
39 18 Gianluca Corsini
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. 
40 2 Martin Jacquet
>
41 1 Martin Jacquet
42 23 Gianluca Corsini
h3. I-4. Pocolibs
43 18 Gianluca Corsini
>
44 2 Martin Jacquet
"Pocolibs":https://www.openrobots.org/wiki/pocolibs/ is a middleware, like ROS.
45 18 Gianluca Corsini
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.
46 2 Martin Jacquet
>
47
48 23 Gianluca Corsini
h3. I-5. TeleKyb
49 18 Gianluca Corsini
>
50
The "TeleKyb":https://git.openrobots.org/projects/telekyb3 software platform provides the aerial-robotic oriented software developed at LAAS-CNRS.
51 2 Martin Jacquet
In particular, we will use:
52 1 Martin Jacquet
* "pom":https://git.openrobots.org/projects/pom-genom3, a UKF-based state estimator merging state feedback for different sources (e.g. mocap + IMU)
53 18 Gianluca Corsini
* "optitrack":https://git.openrobots.org/projects/optitrack-genom3, to export the motion capture data to the genom software stack
54 2 Martin Jacquet
* "rotorcraft":https://git.openrobots.org/projects/rotorcraft-genom3, the low-level interface, with either the simulated or real platform
55 59 Martin Jacquet
* "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.
56 18 Gianluca Corsini
* "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).
57 11 Martin Jacquet
* "joystick":https://git.openrobots.org/projects/joystick-genom3, a component to read the joystick inputs.
58 2 Martin Jacquet
>
59 22 Gianluca Corsini
60 23 Gianluca Corsini
h3. I-6. Gazebo
61 18 Gianluca Corsini
>
62 2 Martin Jacquet
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:
63 18 Gianluca Corsini
* "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.
64
* "optitrack-gazebo":https://git.openrobots.org/projects/optitrack-gazebo emulates the optitrack network interface to publish the model poses.
65 2 Martin Jacquet
>
66 1 Martin Jacquet
The installation procedure for Gazebo can be found at http://www.gazebosim.org/tutorials?cat=install&tut=install_ubuntu&ver=9.0
67 16 Martin Jacquet
>
68 22 Gianluca Corsini
69 23 Gianluca Corsini
h3. I-7. TCL
70 1 Martin Jacquet
>
71 16 Martin Jacquet
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.
72
There are two available language interfaces: "matlab":https://git.openrobots.org/projects/matlab-genomix and "tcl":https://git.openrobots.org/projects/tcl-genomix.
73 18 Gianluca Corsini
"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.
74
>
75 2 Martin Jacquet
76 23 Gianluca Corsini
h2. II - Installation procedure
77 18 Gianluca Corsini
>
78 2 Martin Jacquet
This section is a tutorial on how to install the software architecture to run the simulations.
79
>
80
81 23 Gianluca Corsini
h3. II-0. Clone the Visual and Physical Control Architecture for Flying End-Effector repository
82 18 Gianluca Corsini
>
83 4 Martin Jacquet
Clone the repo associated to this project, using the git daemon. Its root will act as the devel folder for the following.
84 2 Martin Jacquet
<pre><code class="shell">
85 1 Martin Jacquet
git git://redmine.laas.fr/laas/visual-physical-control-architecture.git
86 4 Martin Jacquet
cd ./visual-physical-control-architecture/
87 2 Martin Jacquet
</code></pre>
88 1 Martin Jacquet
>
89 21 Gianluca Corsini
To simplify the installation, we provide a @env.sh@ script that exports all the required variables.
90 24 Gianluca Corsini
In order to run all the installed executables, we need to set up the path to the newly created folders.
91 2 Martin Jacquet
*/!\* the source has to be called in the repository root since it uses the @pwd@ command to export the paths.
92
<pre><code class="shell">
93 1 Martin Jacquet
source env.sh
94
</code></pre>
95 2 Martin Jacquet
>
96 22 Gianluca Corsini
97 24 Gianluca Corsini
h3. II-1. Set up robotpkg
98 1 Martin Jacquet
>
99 2 Martin Jacquet
(Steps taken from http://robotpkg.openrobots.org/install.html)
100 18 Gianluca Corsini
>
101 30 Gianluca Corsini
*1. Clone the robotpkg lastest release*
102 2 Martin Jacquet
103
<pre><code class="shell">
104 1 Martin Jacquet
git clone git://git.openrobots.org/robots/robotpkg
105 2 Martin Jacquet
</code></pre>
106
107 30 Gianluca Corsini
*2. Check that the @openrobots/@ folder exists in the repository root, and update the environment variables accordingly if you didn't source the @env.sh@ file*
108 2 Martin Jacquet
109
<pre><code class="shell">
110
export ROBOTPKG_BASE=`pwd`/openrobots
111
</code></pre>
112
113 30 Gianluca Corsini
*3. Install robotpkg*
114 2 Martin Jacquet
115
<pre><code class="shell">
116
cd robotpkg/bootstrap
117
./bootstrap --prefix=$ROBOTPKG_BASE
118
</code></pre>
119
120 30 Gianluca Corsini
*4. Install the required components and their dependencies*
121 18 Gianluca Corsini
>
122 2 Martin Jacquet
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_.
123
To do so, we need to edit the config file: @$ROBOTPKG_BASE/etc/robotpkg.conf@. Add the following at the end of the file:
124 18 Gianluca Corsini
125 2 Martin Jacquet
<pre><code class="shell">
126
PKG_OPTIONS.%-genom3 = \
127
        codels \
128
        pocolibs-server \
129
        pocolibs-client-c
130
131 28 Gianluca Corsini
PKGSET.myset = \
132 1 Martin Jacquet
    middleware/pocolibs \
133
    architecture/genom3 \
134 2 Martin Jacquet
    architecture/genom3-pocolibs \
135 1 Martin Jacquet
    robots/rotorcraft-genom3 \
136
    localization/pom-genom3 \
137 2 Martin Jacquet
    localization/optitrack-genom3 \
138
    net/genomix \
139
    supervision/tcl-genomix \
140 1 Martin Jacquet
    shell/eltclsh \
141
    simulation/mrsim-gazebo \
142
    simulation/libmrsim \
143 2 Martin Jacquet
    simulation/optitrack-gazebo \
144 1 Martin Jacquet
    joystick-genom3
145
146
PREFER.lapack = robotpkg
147
PREFIX.matlab = <path/to/Matlab>
148
</code></pre>
149 2 Martin Jacquet
150 22 Gianluca Corsini
The last line needs to point to the Matlab root folder in the system (e.g. @/opt/Matlab@).
151
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).
152 2 Martin Jacquet
If Matlab is not installed on the system, remove the lines @supervision/matlab-genomix \@ and @PREFIX.matlab = <path/to/Matlab>@ from the above list.
153 1 Martin Jacquet
Also, all the above is meant for using Pocolibs, not ROS. Futur version of this tutorial might come to use the ROS install.
154
>
155 2 Martin Jacquet
Now return to the robotpkg folder and install all the set:
156
<pre><code class="shell">
157
cd robotpkg
158 28 Gianluca Corsini
make update-myset
159 1 Martin Jacquet
</code></pre>
160 22 Gianluca Corsini
>
161 1 Martin Jacquet
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.
162 2 Martin Jacquet
>
163
164 23 Gianluca Corsini
h3. II-2. Install custom components
165 2 Martin Jacquet
>
166 30 Gianluca Corsini
*List of the components*
167 18 Gianluca Corsini
>
168 2 Martin Jacquet
The @src/@ folder contains some additional components, in particular:
169 33 Gianluca Corsini
* *vision-idl*: provides the type declarations regarding the camera modules.
170
* *camgazebo-genom3*: reads the data from the gazebo innate camera, via the gazebo API.
171
* *camviz-genom3*: records and/or displays the images from a camera.
172
* *arucotag-genom3*: detects and filters (EKF-based) the ArUco markers/tags.
173
* *phynt-genom3*: handles the physical interaction (wrench observer and admittance filter).
174
* *uavatt-genom3*: is the attitude controller for fully-actuated UAVs.
175
* *uavpos-genom3*: is the position controller for fully-actuated UAVs.
176
* *visualservoing-genom3*: implements the state machine for the pick-n-place experiment and provides the reference trajectory (either based on visual-servoing, or based on waypoints for takeoff/exploration).
177
* *dynamixel-genom3*: reads and sends data to Dynamixel devices (e.g. motors) that adopt Dynamixel protocols.
178
* *libdynamixel*: provides the type and function declarations used by magdynamixel-gazebo.
179
* *magdynamixel-gazebo*: is a gazebo plugin that emulates a magnetic gripper and adopts the Dynamixel Protocol 2.0.
180 1 Martin Jacquet
>
181 30 Gianluca Corsini
*Install the extra components*
182 1 Martin Jacquet
>
183 22 Gianluca Corsini
Since the extra necessary components are not considered 'stable' as the one provided in robotpkg, we rather install them in a devel folder.
184 18 Gianluca Corsini
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:
185 2 Martin Jacquet
186
<pre><code class="shell">
187 1 Martin Jacquet
export DEVEL_BASE=`pwd`/devel
188 2 Martin Jacquet
cd src/
189 1 Martin Jacquet
</code></pre>
190 2 Martin Jacquet
191 1 Martin Jacquet
For the manual installation, @asciidoctor@ is needed. It can be installed using @apt@ or any package manager.
192 22 Gianluca Corsini
Each component here has to be installed manually, using @autoconf@. To do so, proceed as follow:
193 1 Martin Jacquet
194 2 Martin Jacquet
<pre><code class="shell">
195 1 Martin Jacquet
cd src/<component>/
196 2 Martin Jacquet
./bootstrap.sh
197
mkdir build
198
cd build
199
../configure --prefix=$DEVEL_BASE --with-templates=pocolibs/client/c,pocolibs/server
200 22 Gianluca Corsini
make install
201 2 Martin Jacquet
</code></pre>
202 1 Martin Jacquet
203 60 Gianluca Corsini
*NB*
204
* The component @vision-idl@ has to be installed first since it defines some type headers used by others.
205
* The component @libdynamixel@ must be installed before @magdynamixel-gazebo* since it defines some variable types and the necessary functions for the other module. To install @libdynamixel@, please follow these instructions:
206
207
<pre><code class="shell">
208
cd src/libdynamixel
209
autoreconf -if
210
./configure --prefix=$DEVEL_BASE
211
make install
212
</code></pre>
213
214 1 Martin Jacquet
>
215 2 Martin Jacquet
216 23 Gianluca Corsini
h3. II-3. Set up the environment
217 18 Gianluca Corsini
>
218 2 Martin Jacquet
In order to run all the installed executables, we need to set up the path to the newly created folders.
219 47 Martin Jacquet
All the required variables are exported in the @env.sh@ file, so nothing more has to be done here.
220
However, remember to source the @env.sh@ each time that you want to run simulations from a new terminal.
221 1 Martin Jacquet
222 49 Martin Jacquet
>Remember that the @env.sh@ have to be sourced from the repository root!
223 2 Martin Jacquet
>
224 23 Gianluca Corsini
225 18 Gianluca Corsini
h2. III - Running the simulation
226 2 Martin Jacquet
>
227 18 Gianluca Corsini
>
228 2 Martin Jacquet
229 23 Gianluca Corsini
h3. III-1. GInterface
230 18 Gianluca Corsini
>
231 24 Gianluca Corsini
In order to start all the required software, connect the components together and store the parameters, we use a TCL-based interface.
232
The folder called @ginterface@ contains all the necessary scripts.
233 1 Martin Jacquet
For convenience, we provide as many generic scripts as possible.
234 24 Gianluca Corsini
The next section explains how to set up the GInterface, then how to use it to run the proposed simulation.
235
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.
236 1 Martin Jacquet
>
237 15 Martin Jacquet
238 24 Gianluca Corsini
h3. III-2. Set up the GInterface
239 44 Martin Jacquet
240 58 Martin Jacquet
h4. 1. Install dependencies
241 44 Martin Jacquet
242 1 Martin Jacquet
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@.
243
>
244 26 Gianluca Corsini
245 58 Martin Jacquet
h4. 2. Configuration
246 25 Gianluca Corsini
247 44 Martin Jacquet
In order to configure it, it is necessary to modify the content of the file user file. This file is located in the GInterface repository inside the folder @users@.
248
For convenience, we provide a generic @airpharo_user.tcl@ file that is pre-filled with environment variables exported from the @env.sh@ file.
249
>
250 1 Martin Jacquet
251 44 Martin Jacquet
> Remember that the @env.sh@ have to be sourced from the repository root!
252 1 Martin Jacquet
253 45 Martin Jacquet
Nothing needs to be modified in this file the sourced has been done correctly.
254 44 Martin Jacquet
For who is interested, the variables listed in the user file are defined as below, and must be modified according to your system setup: 
255 32 Gianluca Corsini
* *pc_name*: refers to the name of your machine, when running simulations, otherwise it should be set to the name of the aerial platform's machine when running experiments. Since these instructions will cover only how to run simulations, set this variable to the name of your machine.
256
* *ground_station_hostname*: refers to the name of your machine, when accessing it through the network (e.g. through @ssh@).
257
* *path_tcl*: is the path to @tcl-genomix@, where the software in robotpkg has been installed. If you followed these instructions it should be set to @<path-to-ginterface>/ginterface/openrobots/lib/tcl-genomix@.
258
* *path_rep*: is the path to the @ginterface@ folder of this repository in your machine.
259
* *path_sup*: is the path to the @ginterface@ folder in the aerial platform's machine. This path is not required for running the provided simulation, thus it can be left unchanged.
260
* *path_log*: is the path where the logs are saved during experiments (precisely in the machine specified at @pc_name@).
261
* *path_log_sim*: is the path where the logs are saved during simulations (precisely in the machine specified at @ground_station_hostname@).
262
* *path_launch*: is the path to the @ginterface/launchers@ folder of this repository in your machine.
263
* *path_devel*: is the path to the @devel@ folder where the extra necessary components have been installed in your machine. If you followed these instructions it should be set to @<path-to-ginterface>/ginterface/devel@.
264
* *path_openrobots*: is the path where the software in robotpkg has been installed in your machine. If you followed these instructions it should be set to @<path-to-ginterface>/ginterface/openrobots@.
265
* *path_gazebo_world*: is the path to the folder @ginterface/gazebo/worlds@ of this repository, where the world files for Gazebo are located. If you followed these instructions it should be set to @<path-to-ginterface>/ginterface/gazebo/worlds@.
266 29 Gianluca Corsini
>
267 1 Martin Jacquet
268 58 Martin Jacquet
h4. 3. About the joystick
269 50 Martin Jacquet
270
As explained previously, a joytick is required to run the simulation, because this interface is primarily used to run real experiments on a remote UAV, hence control is made through a joystick.
271 51 Martin Jacquet
If the joystick is actually plugged and @no joystick found@ appears in the terminal during the simulation bootstrap, it means that it is not detected by Linux drivers and probably does not comply with the standards, so cannot be used to play the simulation.
272
>
273 50 Martin Jacquet
274 1 Martin Jacquet
h2. III-3. Run the simulation
275
>
276
277 53 Martin Jacquet
First of all, remember to source the @env.sh@ file in the terminal to export the paths correctly,and connect a USB joystick to your pc, prior to running the simulation.
278
Navigate to ginterface folder and run the @GInterface.tcl@ script:
279 25 Gianluca Corsini
<pre>
280 53 Martin Jacquet
$ cd ./ginterface/
281 1 Martin Jacquet
$ ./GInterface.tcl
282 25 Gianluca Corsini
</pre>
283 1 Martin Jacquet
284
At this point, the window in the next figure should appear. 
285
>
286 37 Gianluca Corsini
!{width:30%}main_window_ginterface.png!
287 1 Martin Jacquet
>
288 34 Gianluca Corsini
Click on @File@ (pointed by the red arrow in the figure above), then on @Missions@ and select @sim_fiberthex_airpharo@, to run the proposed simulation.
289
After that, @Gazebo@ should be launched, and right after a @XTerm@ console should appear.
290
If everything worked correctly, you will have the situation depicted in the next figure.
291 26 Gianluca Corsini
>
292 38 Gianluca Corsini
!{width:80%}windows-ginterface.png!
293 25 Gianluca Corsini
>
294 54 Martin Jacquet
295
Here is a picture of the buttons numbers on the joystick. Below, we will refer them by these numbers.
296 55 Martin Jacquet
!{width:(50%}gamepad.png!
297 54 Martin Jacquet
>
298
When 
299
> UAV1 is Ready to FLY ...
300
is displayed in the terminal, press and hold down for 3s the central button (button 8) of your joypad until the propellers start to run the message @Armed!@ appears in the @Xterm@ console. 
301 56 Martin Jacquet
As soon as the central button of the joypad is pressed the message @Arming...@ should appear in the @Xterm@ console and, while holding it down, a countdown should be initialized. The countdown will be reset if the central button is released before its end. If so, you have to restart the arming sequence (by pressing button 0).
302 54 Martin Jacquet
If everything is well configured, the propellers should spin.
303
>
304
305 1 Martin Jacquet
When the propeller started spinning and the platform slightly took off, press the button 3 to start the pick-n-place mission. The sequence from this point on will be entirely autonomous.
306 57 Martin Jacquet
One can move the bricks and the ground tag in the gazebo workspace to see the searching phase before the brick is detected by the onboard camera.