workflow_for_students.md 14.6 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
       3. Compile the source code running `catkin_make`
19

phfriedl's avatar
phfriedl committed
20
---
21

22
### Start the student's GUI
phfriedl's avatar
phfriedl committed
23

24
  * Once all the prerequisites have been fulfilled, you can start the student's
25
    GUI by going to a terminal and typing:
26
    `roslaunch dfall_pkg agent.launch`
27

28
    *Note: for this to work, the teacher's computer has to be connected to the
29
    network and the `teacher.launch` GUI has to be started before. Please wait until
30
    your teacher has already set up everything.*
31

roangel's avatar
roangel committed
32
33
34
35
  * Once started, you will see something like this: <br>

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

36
37
  * Connect to/Disconnect from Crazyflie: this connects/disconnects your computer to
  the assigned Crazyflie using the Crazyradio USB dongle.<br><br>
roangel's avatar
roangel committed
38
    * Crazyradio status: can take the values "Connected!", "Disconnected" or
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
      "Connecting...", and the icon changes to display the current status.<br><br>
    * The title at the top contains information about your AgentID number, and the Crazyflie that is allocated to you. This is the only Crazyflie you can connect to.<br><br>

  * The voltage displays the instantaneous voltage of the battery of the Crazyflie, in Volts.<br><br>
    * The battery icon displays this relative to the voltages for full and empty.<br><br>
    * Because flying requires a high current draw from the battery, the full and empty voltages levels automatically adjust depending on whether your Crazyflie is flying or has the motors turned off.<br><br>
    * If the battery voltage falls below the empty level, then a low battery warning is raise and your Crazyflie will be forced to land.<br><br>
    * You must change the battery if the low battery warning occurs because continuing to drain the battery further will cause permanent damage to the battery.<br><br>

  * There are 3 buttons to control the flying state of your Crazyflie: **"Take-off", "Land", and "Motors-OFF"**<br><br>
    * The icon displays the current flying state. **It is important to know that you can only "Take-off" when the state is "Motors
  OFF", and you can only "Land" if the state is NOT "Motors OFF".**<br><br>
    * **IMPORTANT: YOU CAN PRESS SPACE-BAR AT ANYTIME AS A SHORT-CUT TO THE "MOTORS-OFF" BUTTON.**<br><br>

  * In the lower part of the GUI there are two tabs: **"Default" and "Student" controller**<br><br>
    * These tabs allow you to interact with the respective controller.<br><br>
    * In these tabs, the first column of numbers provides information about the current position of the Crazyflie, the second column of numbers is computed as the difference between the current position and the current setpoint, and the third column of number is the current setpoint. This information is useful for keeping track of the error of your controller.<br><br>
    * The next column of boxes can be edited and allows you to type in a new setpoint. When you press the button "Set
  setpoint" (or the enter key on the keyboard), we change the current setpoint with the information filled.<br><br>
roangel's avatar
roangel committed
58
59
60
61
62
    * 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
63

64

65
66
  * 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
67

68
    *Note: there are different parameters in the file called
69
    `SafeController.yaml`, in the folder param (use `roscd dfall_pkg/param` in a
roangel's avatar
roangel committed
70
71
    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,
72
    since may have to write your own for the student controller.*
73

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

#### Files of interest:

81
* In `dfall_pkg/src`
82

83
  * _StudentControllerService.cpp_ <br>
84
85
  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.

86
* In `dfall_pkg/param`
87

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

      *Usage:*

94
      *`studentController: "SERVICENAME/TOPICNAME"`*
95

96
      *where SERVICENAME is the name of the cpp-file that contains the student controller (e.g. the provided template StudentControllerService) and
97
98
99
100
101
102
      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
103
      your student controller from assuming certain angles before the safe controller
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
      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.***

119
* In `dfall_pkg/`
120
121
122
123
124
125
126
127
128
129
130

  * 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: -->
131
<!-- in `dfall_ws/src/dfall_pkg/scripts` -->
132
133
134
135
136
137
138
139
140
141
142
143
<!-- -\-> 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: -->
144
<!-- in `dfall_ws/src/dfall_pkg/param` -->
145
146
147
<!-- * _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. -->

148
<!-- in `dfall_ws/scr/dfall_pkg/launch` <br> -->
149
150
151
152
153
154
155
156
157
158
159
160
161
162
<!-- 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. -->

163
164
#### Steps to create a student controller
1. Open the file `StudentControllerService.cpp` and go through it. You should see
165
166
167
   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
168
169
170
   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>
171

roangel's avatar
roangel committed
172
     In the template you can also see an example of how to use the
173
     `StudentController.yaml` to load parameters that you may want to change
roangel's avatar
roangel committed
174
175
176
     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>
177
2. Go to `cd ~/work/D-FaLL-System/dfall_ws` and write `catkin_make`.
178
179

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

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

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
188
finish taking off, if the student controller was enabled, we automatically switch
189
190
191
192
193
194
195
196
197
198
199
200
201
202
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.*

203
204
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
205
206
207
   the GUI. This way, you can try and see the effect of changing some parameters
   on the fly.

roangel's avatar
roangel committed
208

209
#### Steps to plot debug variables from Student Controller in a graph
roangel's avatar
roangel committed
210
211

1. Choose the variables that we want to see in a plot from the file
212
   `StudentControllerService.cpp`. Inside the function `calculateControlOutput`,
roangel's avatar
roangel committed
213
214
215
216
217
   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>
218
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
219
220
221
222
223
224
225
226
227
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
228
   `/<student_id>/StudentControllerService/DebugTopic/vicon_z`. You can see an
roangel's avatar
roangel committed
229
230
   autocompletion of the
   list of all the topics available when you start typing in the field "Topic". <br><br>
231
5. Start the Student node following the steps mentioned before (`roslaunch dfall_pkg Student.launch`) and enable the Student Controller.<br><br>
232
6. Once we are using the Student Controller, we will be seeing how the data
roangel's avatar
roangel committed
233
234
   selected gets plotted in the rqt plots.

235
236
237
238
239
240
241
<!-- --- -->


<!-- ## 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. -->
242
<!-- 3.  Use `roscd dfall_pkg/launch` in a terminal as well as `roscd dfall_pkg/scripts` in another terminal -->
243
244
245
246

<!-- <br> -->
<!-- **Working** -->
<!-- 1.  Adjust your custom controller -->
247
<!-- 2.  Use `catkin_make` in the dfall_ws directory to compile your controller implementation -->
248
249
250
251
252
253
254
255
256
257
258
259
260
261
<!-- 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. -->