main.tex

\documentclass[]{article}

\usepackage{amsmath}
\usepackage{graphicx}
\usepackage{wrapfig}
\usepackage[utf8]{inputenc}
\usepackage{a4wide}
\usepackage{multicol}
\usepackage{url}
\usepackage{xcolor}
\usepackage{framed}
\usepackage{wrapfig}

\definecolor{shadecolor}{rgb}{0.9,0.9,0.9}

%opening
\title{Documentation of the QGroundControl WiMA-Extension}
\author{Valentin Platzgummer}

\begin{document}

\maketitle
\section{Introduction} 
WiMA is a abbreviation for \textbf{Wi}reless \textbf{M}easurement \textbf{A}pplication.

This document was created to explain the functionality of the WiMA-Extension at one hand and to encourage the reader to find bugs inside the program. Hence the document is split in two parts. The first part contains instructions on how to use WiMA and the second part gives some suggestions for testing. As the extension is still being developed the contents demonstrated inside this document may differ from those ones in the program.

The folder "deploy" in the QGroundControl root directory (can be cloned from Gitlab) contains a AppImage of the program. QGroundControl can be launched by double-clicking the AppImage. Currently only a Linux version is available.
 

\section{Documentation}
\subsection{Structure of QGroundControl with WiMA-Extension}
Figure \ref{fig:QGCMainButtonExplain} shows a detail view of the QGC main window. Relevant for this documentation are the flight view, the plan view and the WiMA main window. Their function will now be briefly summarized.

The \textbf{plan view window} is used to create flight plans. They can be stored as .plan files or directly be uploaded to a vehicle (either a real one or a simulated one). Flight plans consist of waypoints. Each waypoint stores, among others, a coordinate (latitude, longitude, altitude) and a command (take off, land, wait for x seconds, etc.). To define a sensible flight plan a sequence of waypoints should begin with a take off command and end with a land command. Besides waypoints more complex patterns can be defined, which is done by inserting a Survey, a Circular Survey, a Structure Scan or a Corridor Scan. Just try them out! Using the simulator can be very helpful.

The \textbf{flight view window} comes in necessary as soon as you want a vehicle to get in action. Once the vehicle established a connection (serial, TCP, UDP, etc.) QGroundControl starts to communicate automatically with it automatically  in most cases. If not, check the settings menu of QGroundControl. A red arrow will appear on the map showing the vehicles position and orientation. On the top indicator strip telemetry data will be published. At the left edge a tool strip will be activated, which can be used to command the vehicle.

The \textbf{WiMA main window} is used to automatically generate flight paths on the base of minimal user input. The user can define a Measurement Area, a Service Area (for take off, land, supply tasks, etc.) and a Corridor, which connects the previous two areas. Below the WiMA main window will be described in more detail.

\begin{figure}[h!]
	\includegraphics[width=\textwidth]{pics/QGCMainWindowCroppedRect}
	\centering
	\caption{Detail view of the QGC window, which appears after start-up. Marked in red is the button for switching to the plan view window, green indicates the flight view button (current window) and marked in magenta is the button for switching to the WiMA main window.}
	\label{fig:QGCMainButtonExplain}
\end{figure}


\subsection{WiMA Main Window}
\subsubsection{WiMA Tool Strip}
\label{sec:wimaToolStrip}
By clicking the wave symbol (see fig. \ref{fig:QGCMainButtonExplain}; magenta square) the WiMA main window appears. After entering, at the left edge, the WiMA tool strip will appear (depicted in fig. \ref{fig:WimaToolstrip}). 

\begin{wrapfigure}{r}{0.3\textwidth}
	\centering
	\includegraphics[width=0.3\textwidth]{pics/WiMAToolstrip}
	\caption{WiMA Toolstrip inside WiMA Main Window.}
	\label{fig:WimaToolstrip}
\end{wrapfigure}
Pressing the \textbf{File} button opens a menu which offers saving and loading operations. At one hand all WiMA areas and mission items can be saved using the \verb|.wima| file extension, at the other hand the mission items only can be stored using the \verb|.plan| file extension. The Open button can be used to load previously stored files. Pressing the New button deletes all contents within the WiMA Main Window. Additionally with the Upload, Download and Clear Vehicle Mission button the mission items (if present) can be uploaded, downloaded or be deleted from the vehicle respectively.

The \textbf{Measure}, \textbf{Service} and \textbf{Corridor} buttons are used to insert a measurement, service and corridor area, respectively. At the time only one of each areas can be inserted. To automatically generate a flight plan at least a measurement and a service area must be defined. Both must be overlapping.

To auto generate a flight plan the \textbf{Calculate} button must be pressed. Further information about how to display the generated flight plan will follow below. In the future this button might be removed and be replaced by a routine which automatically triggers recalculation after any modification. However as the flight plan generation can be time consuming on older devices, this button will remain in the near future, up to the point, underlying routines get optimized. 

As flight generation is manually triggered the flight plans might look wrong (for e.g. after user modification), pressing the \textbf{Calculate} button often will remove errors. If not, please report any bugs. 

The last three buttons, \textbf{Center}, \textbf{In} and \textbf{Out} are used to center the view and for zooming respectively.

\subsubsection{WiMA Areas}
As all ready mention the three areas, namely the Measurement Area, the Service Area and the Corridor can be defined using the corresponding buttons of the WiMA Tool Strip (see \ref{sec:wimaToolStrip}).

\begin{figure}[h!]
	\begin{minipage}{0.3\textwidth}
		\centering
		\includegraphics[width=\textwidth]{pics/WiMAItemEditor}
		\caption{WiMA Item Editor at the right edge of the WiMA Main Window.}
		\label{fig:WimaItemEditor}
	\end{minipage}
    \hfill
	\begin{minipage}{0.3\textwidth}
		\centering
		\includegraphics[width=\textwidth]{pics/optimPath}
		\caption{Flight path of a real world vehicle (the red line).}
		\label{fig:optimPaht}
	\end{minipage} 
\end{figure}



\begin{figure}
	\begin{minipage}{0.3\textwidth}
		\centering
		\includegraphics[width=0.75\textwidth]{pics/VertexHandle}
		\caption{Adjust the vertex by dragging it's handle.}
		\label{fig:vertexHandle}
	\end{minipage}
    \hfill
	\begin{minipage}{0.3\textwidth}
		\centering
		\includegraphics[width=0.75\textwidth]{pics/VertexPlus}
		\caption{Add vertices by hitting the plus sign.}
		\label{fig:vertexPlus}
	\end{minipage}
	\hfill
	\begin{minipage}{0.3\textwidth}
		\centering
		\includegraphics[width=0.75\textwidth]{pics/MoveArea}
		\caption{Move any area by dragging its drag handle.}
		\label{fig:moveArea}
	\end{minipage}
\end{figure}





The \textbf{WiMA Measurement Area} defines, as the name indicates, the area of interest within which any measurements should be performed. The area will be displayed as a green shaded rectangle surrounded by a white line, after pressing the Measure button. The area will be listed at the right side within the WiMA Item Editor, after creation (see fig. \ref{fig:WimaItemEditor}). The WiMA Item Editor can be used to modify area parameters.

% area parameter description here
The Offset parameter (see fig. \ref{fig:WimaItemEditor}) changes the distance between the measurement area and its surrounding polygon. The surrounding polygon is a helper to provide sufficient clearance between the measurement area and surrounding obstacles like trees or buildings.

% remove later
All other parameters shown in fig. \ref{fig:WimaItemEditor} don't yet have any impact (intended for future use).

The \textbf{WiMA Service Area} is meant to be the area were takeoff and landing happens as well as battery exchange or (hopefully no) repair work is done, hence the name. 


The \textbf{WiMA Corridor} connects the two previous areas and defines a corridor which the vehicles uses to travel between Service and Measurement Area. 

The flight plan will be generated such that all waypoints are within or at least at the edge of the above mentioned areas. However it should be taken in account, that the vehicle could still leave the save area, even under fully functional operation. Depending on software implementation of the vehicles flight stack (firmware) the flight controller could decide to perform any kind of path optimization. Additionally drifts caused by wind gusts could happen. An example can be seen in fig. \ref{fig:optimPaht}.
The vehicles flight controller indeed has no information about any WiMA Areas, they exist exclusively within the QGroundControl application.


All WiMA areas can be shaped by dragging the vertex handles (see fig. \ref{fig:vertexHandle}). New vertices can be created  by hitting the plus signs at the edges (see fig. \ref{fig:vertexPlus}). The whole area can be moved by dragging its drag handle (see fig. \ref{fig:moveArea}).



A valid configuration including Measurement, Service Area and Corridor could look like shown in fig. 
\begin{figure}
	\includegraphics[width=0.8\textwidth]{pics/validAreas}
	\centering
	\caption{A valid configuration of Measurement, Service Area and Corridor.}
\end{figure} 

\subsubsection{The generated Flight Path}

\subsubsection{Circular Survey}






\newpage
\subsection{ArduPilot Simulator}
For tasks like debugging, program verification or flight plan testing a simulated vehicle can be very useful. It can save time, money and prevent you from any excessive sunburns, if you forgot that you are actually outside, starring on your screen, exposed to the hot summer sun.

For this task the ArduPilot simulator can be used. It simulates a vehicle runnig the ArduPilot flight stack (firmware) on your local machine. Data is beeing published by the simulator via UDP and should ideally connect to QGroundControl without any further tweaks.

The simulator is part of the ArduPilot project, which can be downloaded from Github: \url{https://github.com/ArduPilot/ardupilot}.
It is recommanded to fork the repository. After cloning the repository, the submodules must be initialized and updated. Execute the following code to do this.
\begin{shaded*}
	\begin{verbatim}
		git clone https://github.com/ArduPilot/ardupilot
		cd ardupilot
		git submodule init
		git submodule update
	\end{verbatim}	
\end{shaded*}
The simulator is launched by a Python script, thus Python must be installed on your machine. The simulator is now ready to run, it can be launched from your ArduPilot root directory with the following command.
\begin{shaded*}
	\begin{verbatim}
		./Tools/autotest/sim_vehicle.py -v ArduCopter
	\end{verbatim}
	
\end{shaded*}
Thereby the \verb|-v| option specifies the vehicle type. The \verb|-l| option can be used to define a custom start location. See the \verb|sim_vehicle.py --help| option for further information.
After launching, the vehicle should appear inside QGC.

 




\end{document}