workflow_for_students.md 14 KB
Newer Older
roangel's avatar
roangel committed
1
# Workflow for students.
2

3
4
5
6
### Hardware prerequisites:
* Make sure you are connected to the network (cable inserted and check if connected to Vicon in the settings).
* Insert a CrazyRadio into one of your USB-ports on your Laptop.
* Start your crazyflie. To know which one is the one you have been linked to,
roangel's avatar
roangel committed
7
8
ask your teacher. The Crazyflie must be started on a flat surface, as the
gyrosensor needs to initialize.
9
10
11
12
13

### Software prerequisites:
  * In the software side, everything has already been set up for the course, but
    it would be helpful to check if the repository is in the last version, and
    if the source code has been properly compiled. To do this, follow the next steps:
14
       1. Go to the next folder: `cd ~/work/D-FaLL-System/dfall_ws`
roangel's avatar
roangel committed
15
16
17
       2. Checkout master branch of the repository and pull:<br />
         ``git checkout master``<br />
         ``git pull origin master``<br />
18
19
       *Note: to do this step, you will be asked a username and a password. Use
       the same credentials you use for your ETH account. Also, make sure you
roangel's avatar
roangel committed
20
       have an active account in gitlab: [https://gitlab.ethz.ch/](https://gitlab.ethz.ch/)*<br />
21
       3. Compile the source code running `catkin_make`
22

phfriedl's avatar
phfriedl committed
23
---
24

25
### Start the student's GUI
phfriedl's avatar
phfriedl committed
26

27
28
  * Once all the prerequisites have been fulfilled, we can start the student's
    GUI by going to a terminal and typing:
29
    `roslaunch dfall_pkg Student.launch`
30

31
32
33
    *Note: for this to work, the teacher's computer has to be connected to the
    network and the teacher's GUI has to be started before. Please wait until
    your teacher has already set up everything.*
34

roangel's avatar
roangel committed
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
  * Once started, you will see something like this: <br>

    <img src="./pics/student_gui.png" style="width: 800px;"/> <br><br>

  * Connect to/Disconnect from Crazyflie: physically connects/disconnects our computer to
  the assigned crazyflie using the Crazyradio dongle.<br><br>
    * Crazyradio status: can take the values "Connected!", "Disconnected" or
      "Connecting..." <br><br>
    * Below the disconnect button we see two lines of text. The first one
  contains information about our StudentID number, and the Crazyflie we are
  linked to. This is the Crazyflie we must connect to. <br><br>
  Below that, we can also see the Raw voltage line, which contains the instantaneous voltage of the
  battery of the Crazyflie, in Volts.<br><br>
    * In the right part, there are 3 buttons to control the flying state of our
  Crazyflie, and a text label containing the current flying state. **It is
  important to know that we can only take off when we are in the state "Motors
  OFF", and we can only land if we are NOT in the state "Motors OFF"**<br><br>
52
    * In the middle-bottom part of the GUI there are two tabs: Safe and Student
roangel's avatar
roangel committed
53
54
55
56
57
58
59
60
61
62
63
64
65
  controller. <br><br>
  In the left part of these tabs, there is information about the
  current position of the Crazyflie, and also the difference between the current
  position and the current setpoint, useful for keeping track of the error of
  our controller.<br><br>
  In the right part of the tabs, there is information about the current
  setpoint, and boxes to edit the new setpoint. When we press the button "Set
  setpoint", we change the current setpoint with the information filled.<br><br>
    * The button called "Enable <controller> Controller" enables the selected
  controller. The current enabled controller is the one which is highlighted in
  green in the tab name.<br><br>
    * The button "Load <filename> YAML file" loads and refreshes the parameters
  that are in the corresponding YAML file.<br><br>
roangel's avatar
roangel committed
66

67

68
69
  * You can now play with the landing, take off and change of setpoint using the
    safe controller to get familiar with the system.
phfriedlHome's avatar
phfriedlHome committed
70

71
    *Note: there are different parameters in the file called
72
    `SafeController.yaml`, in the folder param (use `roscd dfall_pkg/param` in a
roangel's avatar
roangel committed
73
74
    terminal to go there).* **These are the safe controller parameters and should NOT be
    changed.** *Take a look at the file and get familiar with the format used,
75
    since may have to write your own for the student controller.*
76

77
78
### Creating your own controller!
In this part, we will learn how to design our own controller and actually
79
deploy it and see it working in our Crazyflie. For this, there are a set of
roangel's avatar
roangel committed
80
important files that should be taken into account.
81
82
83

#### Files of interest:

84
* In `dfall_pkg/src`
85

86
  * _StudentControllerService.cpp_ <br>
87
88
  The file where students can implement their own controller. It provides already the ros service with the teacher. It can be used as a template.

89
* In `dfall_pkg/param`
90

roangel's avatar
roangel committed
91
92
  * _ClientConfig.yaml_ <br><br>
          <img src="./pics/client_config_yaml.png" style="width: 400px;"/> <br><br>
93
  This file needs to be changed to define names for the student controller. **The safeController property should not be changed!** <br>
94
95
96

      *Usage:*

97
      *`studentController: "SERVICENAME/TOPICNAME"`*
98

99
      *where SERVICENAME is the name of the cpp-file that contains the student controller (e.g. the provided template StudentControllerService) and
100
101
102
103
104
105
      where TOPICNAME is the defined name for the topic which is defined insided
      the controller's code.*

      *`strictSafety: <bool>`*

      *By setting _strictSafety_ to true you limit
106
      your student controller from assuming certain angles before the safe controller
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
      takes over. Set it to false and the safe controller only takes over when the
      crazyflie flies out of its defined range.*

      *`angleMargin: <float>`*

      *This value can be used to change the acceptable angles for pitch
      and roll. angleMargin=1 means that your crazyflie could flip 90°. The safe
      controller might not recover from such angles. Therefore you should use values
      in the range of 0.4 to 0.7.*

      *`battery_threshold_while....`*

      *Sets the low battery thresholds at which the crazyflie will automatically
      land. **Do not change these values.***

122
* In `dfall_pkg/`
123
124
125
126
127
128
129
130
131
132
133

  * CMakeLists.txt

      *This file defines all important things that are needed for build process.
      You need this file, if you for example choose to add a new controller with a new name. You then need to add several lines in this file.
      The easiest way is to search for a file that exists and just add all the
      same things for your new file.*



<!-- ##### -- Useful files: -->
134
<!-- in `dfall_ws/src/dfall_pkg/scripts` -->
135
136
137
138
139
140
141
142
143
144
145
146
<!-- -\-> call scripts in terminal by going to the above path and then typing -->
<!-- ./SCRIPTNAME, e.g.: `./enable_crazyflie` -->

<!--   * *disable_crazyflie* -->
<!--   * *enable_crazyflie* -->
<!--   * *load_custom_controller* -->
<!--   * *load_safe_controller* -->
<!--   * *safe_controller_setpoint* <br> -->
<!--   This one needs 4 parameters for x,y,z and yaw. The setpoint of the crazyflie is then set to those values. -->


<!-- ##### -- Files to look at: -->
147
<!-- in `dfall_ws/src/dfall_pkg/param` -->
148
149
150
<!-- * _SafeController.yaml_ <br> -->
<!-- This file contains the control parameters that the SafeControllerService uses. The SafeControllerService loads this file when it starts. You might want to use a similar approach and can try to copy some functionality from  SafeControllerService.cpp. -->

151
<!-- in `dfall_ws/scr/dfall_pkg/launch` <br> -->
152
153
154
155
156
157
158
159
160
161
162
163
164
165
<!-- The launch files contained in this directory are used to launch several nodes and some parameter files to be launched simultaneously. It is best, that you take a look at them yourself, but here is a brief explanation what the different launch files are for.<br> -->
<!-- To start the whole thing type the following in a terminal whilst being in the launch directory.<br> -->
<!-- `roslaunch filename.launch` -->

<!--   * _Teacher.launch_<br> -->
<!--   This doesn't concern the students, nor will it work. This launches the GUI for the teacher and the services he needs. -->
<!--   * _Student.launch_<br> -->
<!--   This launches the nodes for the CrazyRadio, the PPSClient, SafeController and CustomController. Make sure that __ClientConfig__ is correctly set up. -->
<!--   <br><br> -->
<!--   * _StudentCirlce.launch_ : as an example<br> -->
<!--   This launches CircleControllerService instead of the normal CustomControllerService. Therefore the ClientConfig has to be adjusted. This should show a way of how to work with the CustomControllerService. -->
<!--   * _StudentFollow.launch_ : as an example<br> -->
<!--   As the circle launcher, this starts another service that enables one crazyflie to _copy_ the behavior of another crazyflie. For this to work, two student groups have to collaborate because some things have to manipulated manually in the cpp files of the Circle and Follow code. -->

166
167
#### Steps to create a student controller
1. Open the file `StudentControllerService.cpp` and go through it. You should see
168
169
170
   that the file is already filled with some code. This code is a simple LQR
   controller that is offered as a template for the student to start developing
   their own controller. Change the file as you wish with your own controller
roangel's avatar
roangel committed
171
172
173
   algorithm. The function partially shown below is the most important part of
   our this file:<br><br>
        <img src="./pics/custom_controller_src.png" style="width: 700px;"/> <br><br>
174

roangel's avatar
roangel committed
175
     In the template you can also see an example of how to use the
176
     `StudentController.yaml` to load parameters that you may want to change
roangel's avatar
roangel committed
177
178
179
     without having to compile or restart the system. Here, as an example, we
     pass some parameters that can be seen below:<br><br>
        <img src="./pics/custom_controller_yaml.png" style="width: 400px;"/> <br><br>
180
2. Go to `cd ~/work/D-FaLL-System/dfall_ws` and write `catkin_make`.
181
182

3. Once everything has compiled without errors, run the next launch file:
183
   `roslaunch dfall_pkg Student.launch`. This will run the student's GUI.
184
185

4. Make sure that your Crazyflie is turned ON and connect to it. Choose the tab
186
   called *Student Controller* and click on the button *Enable Student Controller*
187
188
189
190

5. Press the *Take Off* button and you should see your crazyflie taking OFF.

      *Note: for take off and landing, the crazyflie uses the safe controller. Once we
191
finish taking off, if the student controller was enabled, we automatically switch
192
193
194
195
196
197
198
199
200
201
202
203
204
205
to it*

6. If everything went correctly, now your Crazyflie is using your own
   controller!

      *Note: if your controller is unstable, or it does not compute a valid
   output, your crazyflie will start moving in a wrong way. Please be careful
   and take care, since the crazyflie can unexpectedly go and hit the ceiling,
   the wall, or other student. If your crazyflie
   goes out of the assigned zone, or if the pitch or roll go out of the safety
   margin (when strict safety is enabled), the safe controller will be
   automatically enabled to try to recover the crazyflie and bring it to the
   center of your zone.*

206
207
7. If you decided to put some parameter in the `StudentController.yaml` file, you
   can now change it and press the *Load StudentController YAML file* button in
208
209
210
   the GUI. This way, you can try and see the effect of changing some parameters
   on the fly.

roangel's avatar
roangel committed
211

212
#### Steps to plot debug variables from Student Controller in a graph
roangel's avatar
roangel committed
213
214

1. Choose the variables that we want to see in a plot from the file
215
   `StudentControllerService.cpp`. Inside the function `calculateControlOutput`,
roangel's avatar
roangel committed
216
217
218
219
220
   a part where we fill a DebugMsg with data has been written (lines 133-145 in
   previous figure). Vicon data has already been filled in (vicon\_x,
   vicon\_y,...). Additionally, there are up to 10 general purpose variables
   that can be filled with any data we may be interested in plotting (value\_1,
   value\_2,...., value\_10). <br><br>
221
2. Once chosen the variables, save the file and go to `cd ~/work/D-FaLL-System/dfall_ws` and write `catkin_make`.<br><br>
roangel's avatar
roangel committed
222
223
224
225
226
227
228
229
230
3. Open another terminal and type `rqt`. Then, in the top bar, go to
   Plugins->Visualization->Plot. A new plot will be added to the screen. If you
   want more than one plot, just add several ones doing the same thing. You will
   be seeing something like this:<br><br>

    <img src="./pics/rqt_window_subplots.png" style="width: 400px;"/> <br><br>
4. In each subplot, to add data to plot, write the name of the topic you want to
   plot in the field "Topic", e.g., if we want to plot the Z position of our
   crazyflie, we would have to write here
231
   `/<student_id>/StudentControllerService/DebugTopic/vicon_z`. You can see an
roangel's avatar
roangel committed
232
233
   autocompletion of the
   list of all the topics available when you start typing in the field "Topic". <br><br>
234
5. Start the Student node following the steps mentioned before (`roslaunch dfall_pkg Student.launch`) and enable the Student Controller.<br><br>
235
6. Once we are using the Student Controller, we will be seeing how the data
roangel's avatar
roangel committed
236
237
   selected gets plotted in the rqt plots.

238
239
240
241
242
243
244
<!-- --- -->


<!-- ## Workflow: -->
<!-- **Setup** -->
<!-- 1.  Teacher must run his part, that publishes ViconData for students and hosts the roscore. -->
<!-- 2.  Each student/group has a CrazyFlie and a laptop. -->
245
<!-- 3.  Use `roscd dfall_pkg/launch` in a terminal as well as `roscd dfall_pkg/scripts` in another terminal -->
246
247
248
249

<!-- <br> -->
<!-- **Working** -->
<!-- 1.  Adjust your custom controller -->
250
<!-- 2.  Use `catkin_make` in the dfall_ws directory to compile your controller implementation -->
251
252
253
254
255
256
257
258
259
260
261
262
263
264
<!-- 3.  Start your crazyflie -->
<!-- 4.  Launch the correct file in the launch directory as described above. ClientConfig.yaml has to be correct. -->
<!-- 5. Use the scripts to change from the safe to your custom controller. -->
<!-- 6. When your done, you can turn of your crazyflie by using the script `disable_crazyflie`. -->
<!-- 7. Repeat -->


<!-- --- -->
<!-- **Troubleshooting** -->
<!-- - _SafeController is not working_ <br> -->
<!-- Was the antenna of the crazyflie facing in the *opposite* direction of the defined Vicon x-axis? -\-> Define it again! <br> -->
<!-- The crazyflie has to lie on the table when you turn it on because the gyro sensor is initialized upon start-up. <br> -->
<!-- Is the crazyflie still properly showing in the ViconTracker software? -\-> Define it again and check that the markers don't move! -->
<!-- - If you have added a new controller. Don't forget to adjust the CMakeList.txt file and use catkin_make again. -->