part2_manual_flight_with_paparazzi.tex

\chapter{Manual Flight with Paparazzi}
\label{ch:manual_flight}
In this part you will learn how to start Paparazzi, compile and upload your autopilot and perform your first manual flight.

\section{Safety rules}
To keep the practical safe and to prevent damage to the materials, there are some safety rules.
Last year we had no incidents and managed to break zero drones, let's keep it that way :).
\textbf{Carefully read and follow the rules below!}

\subsubsection*{CyberZoo rules}
\begin{itemize}
	\item No access after 18:00.
	\item Persons inside the flying area:
	\begin{itemize}
		\item Try to avoid having people inside the flight area when drones are flying.
		\item If there are people inside the flight area, notify them before you start flying.
		\item If you are inside the flight area while other drones are flying, we recommend you to wear safety glasses. These hang on the poles next to the entrances. Pay constant attention to the drones that are flying in the zoo, as unexpected errors can cause them to make abrupt movements.
	\end{itemize}
	\item When leaving the CyberZoo:
	\begin{itemize}
		\item Clear up the desks.
		\item Remove all obstacles and other materials from the CyberZoo.
		\item Shut down Motive on the Optitrack PC.
		\item Turn off the lights and open the curtain on the left side of the CyberZoo (as seen from the desks).
	\end{itemize}
	\item Do not borrow any materials from the desks behind the CyberZoo (around the press). Do not use the desks, power sockets or ethernet cables there either.
\end{itemize}

\subsubsection*{Handling the drone}
\begin{itemize}
	\item If you damage or break anything, report this to the TA's so we can fix or replace it.
	\item Demonstrate your flying skills -- including nose-in flight -- in simulation to one of the TA's before flying the real drone. You should be able the safely land the drone when it does not behave as expected. Your team should have at least one safety pilot.
	\item Prevent common problems:
	\begin{itemize}
		\item The example flight plan contains safety rules (`exceptions') that land the drone in case of problems. Do not disable these.
		\item GPS (Optitrack) loss. The drone needs position and velocity feedback for navigation, without this feedback the drone cannot maintain its position. This feedback is provided through Optitrack (more in this in \Cref{ch:autonomous_flight}). The Optitrack system can fail when you did not initialize your drone's rigid body correctly, when you forget to plug in the ethernet cable, when your drone gets confused with another team's drone, etc. Therefore:
		\begin{itemize}
			\item Before taking off, \textbf{always} verify that the drone's position and heading in the Ground Control Station are correct.
			\item During flight, be ready to take over if the GPS fix is lost.
			\item The flight plan should automatically trigger a landing when the GPS fix is lost.
		\end{itemize}
		\item WiFi loss. The GCS communicates with the Bebop over WiFi. Without a WiFi connection, you are no longer able to control the drone. Therefore:
		\begin{itemize}
			\item Do not remove the datalink loss exception from the flight plan. This exception will land the drone automatically when the connection is lost.
		\end{itemize}
		\item Connecting to the wrong drone. Before uploading your code, make sure that you are connected to the right drone. Other teams will not appreciate it if you upload new code to their drone while in flight -- this will lead to a crash. Also make sure you are connected to the right drone before taking off, letting another team's drone take off instead can cause dangerous situations.
		\item Joystick issues. Make sure the joystick is calibrated and working correctly before flying. Before takeoff, check in the GCS that the mode switch is working.
		\item Bad code. Bad code can cause a variety of problems, from missing an obstacle and crashing into it, to segmentation faults that kill the autopilot altogether, often with the motors still running. Therefore:
		\begin{itemize}
			\item Test your code in simulation before testing it on the real drone.
			\item When possible, test your vision code on a dataset you collected beforehand or with an in-hand test on the real drone, before testing it in-flight.
			\item If your drone crashed because of unexpected behavior, try to find out what went wrong before flying again. Do not keep testing the same code in the hopes that it will work the next time. Logging (part 5) will help you find out what went wrong.
		\end{itemize}
	\end{itemize}
	\item Regarding batteries:
	\begin{itemize}
		\item{LiPo batteries, as used in the Bebop, become permanently damaged when the battery voltage drops too low. This will result in a lower battery capacity and shorter flight time. The Bebop battery has a voltage of 12.4~V when full, and 11.1~V when empty. \textbf{You should land when the battery level drops to 11.1~V or below}. The Ground Control Station will give an audible warning when this happens (`BAT LOW'), make sure to turn your sound on. If you hear `BAT CRITICAL', you are too late. The drone also consumes power while it is stationary (e.g. during debugging), make sure to check the battery voltage from time to time.
		
		If you suspect your battery is damaged (BAT LOW at takeoff, exceptionally short flight times or physical damage), contact one of the TA's.}
		
		\item{LiPo batteries are a fire hazard, \textbf{do not leave the batteries unattended while charging!}}
	\end{itemize}
\end{itemize}

\section{Pre-flight preparation}
Before you begin your preparation, charge your battery if you have not already done so. Charging can take a significant amount of time, so you should do this beforehand or during your preparation.

\subsubsection*{Start Paparazzi Center}
Start Paparazzi: go to your terminal and navigate to the paparazzi directory, then run \texttt{paparazzi}:

\begin{lstlisting}[style=Bash]
cd ~/paparazzi
./paparazzi
\end{lstlisting}

The Paparazzi Center performs the following functions: it manages aircraft, airframes and flightplans, it is used to compile and upload your code and it is used to start flight- or simulation sessions.

The top left corner shows the current aircraft (A/C). Use the drop-down menu to select `bebop\_orange\_avoid'.
Below the A/C there are fields to select your airframe and flight plan and other options. Leave these as they are for now; later in the course you may want to modify your flight plan or airframe.

The buttons in the top center (Target, Flash mode, Clean, Build, Upload) are used to compile and upload your code.

Finally, the top right allows you to execute a `Session': a collection of programs that help you perform your flight. Examples of these programs are the communications server and datalink, the Ground Control Station and your joystick.

Saving a custom session is useful in case you are, for example, using a different joystick, flying with a different flight plan than the default, or if you always want to launch an additional process like the Log Plotter or the Messages (found in Tools).

\subsubsection*{Connect and calibrate your joystick}
Before you can fly, you need to connect and calibrate your joystick.
Connect the joystick to your computer\footnote{On some systems, a bug in Ubuntu 18.04 can cause the screen to rotate when the joystick is used. If this happens to you, open a terminal and enter the following commands to (permanently) fix this: \fbox{xrandr -o normal}, followed by \fbox{gsettings set org.gnome.settings-daemon.peripherals.touchscreen orientation-lock true}}.

Joystick calibration should be repeated every time you connect a joystick to your computer, as the center positions may vary slightly per device and the trim sliders may have shifted. It is also a good test to verify that your joystick is working correctly.

\textit{SM600 joystick example}

Ensure that the trim sliders to the right and below the two sticks are in the center position. Check that the bottom mode selector next to the name (SM600) is in the second position, G3-G4.5. Before plugging in the USB of the joystick make sure that all sticks are centered, including the throttle.

Open a terminal (Ctrl+Alt+T), type \fbox{jstest-gtk} and press enter to start the joystick calibration program. Find your joystick in the list. If your device is not \verb"/dev/input/js0", write down the number after `js', you will need this later. Double-click on your joystick to start the test and calibration program.

Click the `Calibration' button, then `Start Calibration'. Move both sticks in circles through their extreme positions, then return them to the center position (the throttle should also be centered). Switch the autopilot mode switch on the top left between the two positions. Move the tuning knob on the top right fully clockwise and counterclockwise. With the control sticks centered, click on the `Ok' and `Close' buttons. It's important to check that the throttle (Axis 2) can reach the minimum value after calibration, as the drone will not arm otherwise.

\textit{Other joysticks}

A similar process using \fbox{jstest-gtk} needs to be repeated if another joystick or radio is being used. However, by default the Paparazzi Center will load the presets for the SM600 joystick. Other radios may use a different number of input channels, or the mapping of the channels will be different, and therefore another preset must be selected.

In order to select another joystick preset, start a session in the Paparazzi Center. If you plan to fly in simulation, select Simulation: Gazebo + Joystick, or Flight UDP when flying with a real drone. The joystick textbox should now have appeared, visible amongst the other programs of the session at the top of the Paparazzi Center. Replace the XML filename at the end of the textbox with the filename of the joystick you are planning to use. A number of XMLs have already been created for a variety of joysticks, you can check the available ones in the \texttt{conf/joystick} directory. To avoid having to repeat this process every time the simulation is launched, click Session $\to$ Save at the top of the window. The newly save session will now appear in the dropdown menu next to the Execute button.

\textit{Creating joystick XML files}

In case the joystick you are planning to use does not have a corresponding XML it may be necessary to create a new, custom joystick XML. There is a comprehensive tutorial explaining all there is to know on how to do this in the \texttt{doc/sphinx/source/tutorials/intermediate/create\_joystick.rst}.

If you succeed in creating a new joystick XML for a device you think others may have at home or want to use, do not hesitate to create a pull request to the \coursebranch{} branch to share your work!

\section{Flying in simulation}
Before you fly with the real drone, you will first practice in the simulator.
This allows you to practice without the risk of breaking your drone. It also allows you to practice somewhere else than the CyberZoo as long as you have access to a joystick.

\medskip

The simulation is started as follows:
\begin{enumerate}
	\item In the Paparazzi Center, go to the Target drop-down menu and select the `nps' target. NPS is the \emph{New Paparazzi Simulator}; by setting nps as the target your autopilot is compiled to run on your own pc instead of on the Bebop.
	\item Click `Clean', then `Build'. Paparazzi will now compile your autopilot.
	\item In the Session drop-down menu, select `Simulation - Gazebo + Joystick' (\emph{not} `Simulation'). Press execute to start the simulation.
	
	If your joystick device was not \verb"/dev/input/js0" the following error will appear in the Paparazzi center: \verb|Invalid_argument("index out of bounds")|. Fix this as follows: the command in the `Joystick' textbox ends with \verb"-d 0"; replace the 0 with the number of your joystick device (e.g. if your joystick was \verb"/dev/input/js1", change the command to \verb"... -d 1"). Click the `Stop' button next to the Joystick textbox, then click `Redo'. In the top menu of the Paparazzi Center, click `Session $\rightarrow$ Save' and overwrite the `Simulation - Gazebo + Joystick' session. Paparazzi will now remember your joystick number. You may have to repeat these steps for the `Flight UDP' session.
	* On Ubuntu 20.04 and 22.04, there is a bug with the joystick device number. If your jstest-gtk shows js0 but you do not get the radio connection in the GCS, try with \verb"... -d 1" instead of \verb"... -d 0".
	
	Sometimes a `Speech dispatcher' error may appear. As long as you can still hear the messages from the GCS, this error can be ignored.
\end{enumerate}

After these steps, two new windows will have appeared: `GCS' and `Gazebo'.
GCS is the \emph{Ground Control Station}, from here you can control and monitor your drone.
The top left of this screen shows the status of your drone. Pay extra attention to the following fields:

\begin{itemize}
	\item Bat: this shows the battery level of your drone. Stop flying when the voltage drops to 11.1 or below, otherwise you will damage the battery. This is of course not a problem in the simulator.
	\item Link: indicates that the drone and GCS are connected. This should be green.
	\item Status:
	\begin{itemize}
		\item Autopilot mode (ATT or NAV): this is the current mode of the autopilot. In ATT mode you are in control of the drone, in NAV mode the drone will follow the flight plan. Check that the mode switch on the top left of the joystick toggles the autopilot mode, then set it to ATT.
		\item RC/Joystick status (OK): this indicates that your joystick is operating correctly.
		\item GPS status (3D): this indicates that the drone has a position fix. This field should be green and at `3D' for autonomous flight.
	\end{itemize}
	\item Throttle (red, 0\%): this shows the current throttle level. The indicator is red when the motors are killed and orange/green when the motors are armed (running).
\end{itemize}

The right part of the GCS window shows a map of your drone and flight plan (top), and the flight plan itself (bottom). The autonomous flight exercise will show how to use the flight plan. The GCS map may not be centered on the drone when you launch it. Click the map and press F to recenter it

The Gazebo window provides a view of your simulation. Navigate around the CyberZoo by panning (click-and-drag the left mouse button), zooming (scroll) and rotating (click-and-drag the middle mouse button).
You can reduce the clutter by going to the `Layers' tab (top left) and unchecking the checkboxes. (Note: the CyberZoo and environment will remain visible to the drone's camera).

\section{Flying in simulation}

Now that you are familiar with the GCS and Gazebo, it is time for your first flight.
Open the GCS and make sure that the autopilot is in ATT mode (use the top left switch of the joystick). Then, move the throttle/yaw stick (left) fully to the bottom-right position until the throttle indicator turns orange: you have now started the motors.

Should you be using a different joystick (a stick joystick for example), the arming procedure may be different. For stick joystick you must move the throttle to zero and twist the stick counter-clockwise. This way you will be sending the same signal to the drone (no throttle, max yaw to the left), which by default arms/disarms the motors.

Switch to the Gazebo window. Slowly advance the throttle until the drone takes off.
You can now use the simulator to practice your manual flying skills. It is very important to test if you can fly a drone nose-in (with its nose pointing towards you). When you can do this perfectly you can consider yourself good enough to serve as a safety pilot during this course.

When you are finished, you can stop the simulation by going to the Paparazzi Center (not the GCS) and clicking the `Stop/Remove All Processes' button.

\section{Flying the real drone}
Once you have mastered flying in the simulator, it is time to transition to the real drone.
If this is your first flight, first demonstrate your flying skills in the simulator to one of the TA's.
Then:

\begin{enumerate}
	\item Place the Bebop inside the CyberZoo. Connect the battery and turn the drone on using the power button on the rear side. When the light stops blinking, press the power button four times. (This allows custom code to be uploaded).
	\item Return to your computer and connect to your Bebop's WiFi access point. (Note: disable and re-enable the WiFi in Ubuntu if the Bebop takes too long to appear in the list of available networks.)
	Make sure that you have connected to the right Bebop, it is a good idea to write down its number somewhere.
	\item In the Paparazzi Center, select the `ap' target and click `Clean' and `Build'. Check that you are connected to the right Bebop, then click the `Upload' button. You should get a message that the autopilot has been started successfully.
	\item Select the `Flight UDP' session and click `Execute'.
\end{enumerate}

After these steps, the GCS window should appear.
Ensure that the battery level is sufficient, the Link indicator is green, the RC status indicator is `OK' and that the autopilot is in ATT mode. Since you will fly manually, it is ok if the GPS fix indicator is red.
If everything is in order, start the engines by moving the yaw/throttle stick to the bottom-right. Slowly increase the throttle to take off, then enter a stable hover. Congratulations, you are now flying with Paparazzi!