diff --git a/pps_wiki/workflow_for_students.md b/pps_wiki/workflow_for_students.md index cc2a5884290bf5f33511b5318458bbe8daff0349..588ce6e0a3afca53eebe0830478cb73d7afd456f 100644 --- a/pps_wiki/workflow_for_students.md +++ b/pps_wiki/workflow_for_students.md @@ -1,92 +1,215 @@ # Workflow for students. In development right now! -### Prerequisite: -* 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 -* The Crazyflie must be started on a flat surface, as the gyrosensor needs to initialize -* The Crazyflie atennas had to face the right direction (antenna facing positive x-axis) upon defining the object in ViconTracker! +### 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, +ask your teacher. The Crazyflie must be started on a flat surface, as the gyrosensor needs to initialize. +<!-- * The Crazyflie atennas had to face the right direction (antenna facing --> +<!-- positive x-axis) upon defining the object in ViconTracker! --> + +### 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: + 1. Go to the next folder: `cd ~/work/D-FaLL-System/pps_ws` + 2. Checkout master branch of the repository and pull: + + `` + git checkout master + `` + + `` + git pull origin master + `` + + *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 + have an active account in gitlab: [https://gitlab.ethz.ch/](https://gitlab.ethz.ch/)* + + 3. Compile the source code running `catkin_make` --- -### Files of interest: - -##### -- Changeable files: -in `pps_ws/src/d_fall_pps/src` -* _CustomControllerService.cpp_ <br> -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. - -in `pps_ws/src/d_fall_pps/param` -* _ClientConfig.yaml_ <br> -This file needs to be changed to define names for the custom controller. **The safeController property shouldn't be changed!** <br> -Usage: <br> -`customController: "SERVICENAME/TOPICNAME"` <br> -where SERVICENAME is the name of the cpp-file that contains the custom controller (e.g. the provided template CustomControllerService) and <br> -where TOPICNAME is the defined name for the topic which is defined insided the controller's code. -<br><br> -There are two additional values. By setting _strictSafety_ to true you limit your custom controller from assuming certain angles before the safe controller takes over. Set it to false and the safe controller only takes over when the crazyflie flies out of its defined range. <br> -The _angleMargin_ 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. - - -in `pps_ws/src/d_fall_pps/` -* _CMakeLists.txt_ <br> -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. -Easiest way is to search for a file that exists and just add all the same things for your new file. <br> - -##### -- Useful files: -in `pps_ws/src/d_fall_pps/scripts` ---> 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: -in `pps_ws/src/d_fall_pps/param` -* _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. - -in `pps_ws/scr/d_fall_pps/launch` <br> -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. ---- +### Start the student's GUI + <!-- * Maybe add here some instructions to check if we are in the last version of --> + <!-- the repository? --> + * Once all the prerequisites have been fulfilled, we can start the student's + GUI by going to a terminal and typing: + `roslaunch d_fall_pps Student.launch` -## 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. -3. Use `roscd d_fall_pps/launch` in a terminal as well as `roscd d_fall_pps/scripts` in another terminal + *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.* -<br> -**Working** -1. Adjust your custom controller -2. Use `catkin_make` in the pps_ws directory to compile your controller implementation -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 + * Once started, you will see something like this: + <!-- insert image of student GUI with numbers in the buttons, so we can + explain every button --> + * You can now play with the landing, take off and change of setpoint using the + safe controller to get familiar with the system. ---- -**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. + *Note: there are different parameters in the file called + `SafeController.yaml`, in the folder param (use `roscd d_fall_pps/param` in a + 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, + since may have to write your own for the custom controller.* + +### Creating your own custom controller! +In this part, we will learn how to design our own custom controller and actually +deploy it and see it working in our Crazyflie. For this, there are a set of +files of interest: + +#### Files of interest: + +* in `d_fall_pps/src` + + * _CustomControllerService.cpp_ <br> + 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. + +* in `d_fall_pps/param` + + * _ClientConfig.yaml_ <br> + This file needs to be changed to define names for the custom controller. **The safeController property shouldn't be changed!** <br> + + *Usage:* + + *`customController: "SERVICENAME/TOPICNAME"`* + + *where SERVICENAME is the name of the cpp-file that contains the custom controller (e.g. the provided template CustomControllerService) and + 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 + your custom controller from assuming certain angles before the safe controller + 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.*** + +* in `d_fall_pps/` + + * 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: --> +<!-- in `pps_ws/src/d_fall_pps/scripts` --> +<!-- -\-> 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: --> +<!-- in `pps_ws/src/d_fall_pps/param` --> +<!-- * _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. --> + +<!-- in `pps_ws/scr/d_fall_pps/launch` <br> --> +<!-- 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. --> + +#### Steps to create a custom controller +1. Open the file `CustomControllerService.cpp` and go through it. You should see + 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 + algorithm. + + In the template you can also see an example of how to use the + `CustomController.yaml` to load parameters that you may want to change + without having to compile or restart the system. + +2. Go to `cd ~/work/D-FaLL-System/pps_ws` and write `catkin_make`. + +3. Once everything has compiled without errors, run the next launch file: + `roslaunch d_fall_pps Student.launch`. This will run the student's GUI. + +4. Make sure that your Crazyflie is turned ON and connect to it. Choose the tab + called *Custom Controller* and click on the button *Enable Custom Controller* + +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 +finish taking off, if the custom controller was enabled, we automatically switch +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.* + +7. If you decided to put some parameter in the `CustomController.yaml` file, you + can now change it and press the *Load CustomController YAML file* button in + the GUI. This way, you can try and see the effect of changing some parameters + on the fly. + +<!-- --- --> + + +<!-- ## 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. --> +<!-- 3. Use `roscd d_fall_pps/launch` in a terminal as well as `roscd d_fall_pps/scripts` in another terminal --> + +<!-- <br> --> +<!-- **Working** --> +<!-- 1. Adjust your custom controller --> +<!-- 2. Use `catkin_make` in the pps_ws directory to compile your controller implementation --> +<!-- 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. --> diff --git a/pps_ws/src/d_fall_pps/GUI_Qt/studentGUI/studentGUI.pro.user b/pps_ws/src/d_fall_pps/GUI_Qt/studentGUI/studentGUI.pro.user index 3b9189a59781de2bd7cd38561179dd4a0515eb34..df4ea05454ef8dead59e8a6ae534ae953ea36b65 100644 --- a/pps_ws/src/d_fall_pps/GUI_Qt/studentGUI/studentGUI.pro.user +++ b/pps_ws/src/d_fall_pps/GUI_Qt/studentGUI/studentGUI.pro.user @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE QtCreatorProject> -<!-- Written by QtCreator 3.5.1, 2017-09-26T18:03:04. --> +<!-- Written by QtCreator 3.5.1, 2017-10-09T12:05:56. --> <qtcreator> <data> <variable>EnvironmentId</variable>