main.tex

\documentclass[]{scrartcl}

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

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

%opening
\subtitle{WiMA-Extension}
\title{User Guide}
\author{Valentin Platzgummer}

 \input{macros.tex}

\begin{document}

\maketitle
\newpage
\tableofcontents
\newpage
\section{Introduction} 
\subsection{Purpose}
The purpose of this document is to introduce the user to \wima (\textbf{Wi}reless \textbf{M}easurement \textbf{A}pplication) integrated in \qgc. \qgc is a ground control station software intended for the remote control of UAVs (\uav). A Documentation of the \qgc program can be found under \qgcdocurl. The WiMA extends the functionality of \qgc to simplify mobile UAV based coverage measurements. 
\subsection{Scope}
The current goal of the \wima is to provide software able to generate flight plans form minimal user input. This guide contains information about how to use \wima.



 

\section{System Description}

\subsection{Key Features}
The extension can generate flight plans based on minimal user input. This is done by defining different areas on a world map. Additionally \wima offers to partition generated flight plans, which gives more flexibility. Partitioning makes it possibly to execute a subset of a flight plan, which makes it less tedious to cover large areas. As a security feature \wima offers a smart return to launch routine. Most return to launch implementations choose the direct path for return, which can be blocked. \wima can automatically calculate a save return path, based on user defined save areas. \wima also offers fast adaption of flight altitude and speed.   

\subsection{Inventory}
The source code can be cloned from the git repository \gitrepourl. The root directory of the project contains the folder "deploy" inside which a \verb|.AppImage| of the program can be found. Under Linux \qgc can be launched from console or by double-clicking the \verb|.AppImage|. It is also possible to build versions for Microsoft Windows, Android or Mac. For this purpose refer to the  \qgc documentation under \qgcdocurl. 


\section{Menus and Instructions}

\subsection{Brief Summary}
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 view. Their function will now be briefly summarized.

The \textbf{plan view} is used to create flight plans and is part of standard \qgc. Flight plans can be stored as \verb|.plan| files or directly be uploaded to a vehicle (either a real one or a simulated one). Flight plans consist of way-points. Each way-point 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 way-points should begin with a take off command and end with a land command. Besides way-points more complex patterns can be defined, which is done by inserting a Survey, a Circular Survey, a Structure Scan or a Corridor Scan.

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

The \textbf{\wima view} is used to generate flight paths from 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 other two areas. Furhter the \wima view and flight view will be described. 

\begin{figure}
	\includegraphics[width=0.2\textwidth]{pics/flightViewToolStrip}
	\centering
	\caption{Flight view tool strip. Used to command the vehicle.}
	\label{fig:flightViewToolStrip}
\end{figure}
\begin{figure}[h!]
	\includegraphics[width=0.5\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}
\begin{figure}[h!]
	\includegraphics[width=0.8\textwidth]{pics/flightViewTopIndicatorStrip}
	\centering
	\caption{Flight view top indicator strip. Show's data about a connected vehicle. Among others satellite count, telemetry quality, battery level \etc are displayed.}
	\label{fig:flightViewTopIndicatorStrip}
\end{figure}


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

\begin{wrapfigure}{r}{0.3\textwidth}
	\centering
	\includegraphics[width=0.18\textwidth]{pics/WiMAToolstrip}
	\caption{WiMA Toolstrip inside WiMA Main Window.}
	\label{fig:WimaToolstrip}
\end{wrapfigure}
The \wima tool strip is used for load/ save operations as well as editing tasks. The file button can be used to load, save and clear missions. Measurement and service area as well as corridor can be added by clicking the corresponding buttons. The calculate button can be used to regenerate the current mission. However with the current version regeneration is done automatically. The center and zoom buttons are used to navigate the map.

\subsubsection{WiMA Areas}
\label{sec:wimaAreas}
The three areas, namely the measurement area, the service area and the corridor, can be defined using the corresponding buttons (see \ref{sec:insertAreas}). In the default mode the areas will be displayed as a half transparent polygon surrounded by a white lines. The polygon shape can be altered by using the drag and split handles shown in fig. \ref{fig:vertexHandle}, \ref{fig:vertexPlus} and \ref{fig:moveArea}. All areas will be listed at the right side within the WiMA Item Editor (see fig. \ref{fig:WimaItemEditor}). The WiMA Item Editor can be used to modify area parameters.
The Parameters \verb|Altitude|, \verb|Layers|, and \verb|Layer Dist.| are reserved for future use and don't yet have any impact. The \verb|Offset| parameter changes the distance between the area and its border polygon. The border polygon is a helper to provide sufficient clearance between the area and nearby obstacles, like trees or buildings. The border polygon can be deactivated by unchecking the \verb|Border Polygon| check box. This can be use full for service area and corridor. 
Additionally the \wima item editor shows some statistics about the polygon, like area and number of nodes.

The three areas have the following purpose.  The \wima measurement area defines, as the name indicates, the area of interest within which any measurements are performed. See \ref{sec:wimaAreas} for more information about \wima areas. The \wima service area is meant to be the place were takeoff and landing happens as well as battery exchange or repair work. See \ref{sec:wimaAreas} for more information about \wima areas. The \wima corridor connects the measurement area and the service areas and defines a path which the vehicles uses to travel between Service and Measurement Area. 

A minimal configuration of areas consists of measurement and service area. In that case the two areas must be overlapping. The corridor can additionally be used to connect measurement and service area if overlapping of those two is not desired. A valid configuration including measurement, service area and corridor could look like in figure \ref{fig:validConfig}. The sum of all three areas is further refereed to as the joined area. 

\begin{figure}[h!]
	\includegraphics[width=0.4\textwidth]{pics/wimaArea}
	\centering
	\caption{\wima area with border polygon. Shown is a measurement area (green).}
	\label{fig:wimaArea}
\end{figure}
\begin{figure}
	\centering
	\includegraphics[width=0.3\textwidth]{pics/WiMAItemEditor}
	\caption{WiMA Item Editor at the right edge of the WiMA Main Window.}
	\label{fig:WimaItemEditor}
\end{figure}
\begin{figure}
	\centering
	\includegraphics[width=0.3\textwidth]{pics/optimPath}
	\caption{Flight path of a real vehicle (red line).}
	\label{fig:optimPaht}
\end{figure} 
\begin{figure}
	\begin{minipage}{0.3\textwidth}
		\centering
		\includegraphics[width=0.5\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.5\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.5\textwidth]{pics/MoveArea}
		\caption{Move any area by dragging its drag handle.}
		\label{fig:moveArea}
	\end{minipage}
\end{figure}
\begin{figure}
\includegraphics[width=0.8\textwidth]{pics/validAreas}
\centering
\caption{A valid configuration of Measurement, Service Area and Corridor.}
\label{fig:validConfig}
\end{figure} 

\subsubsection{Saving and Loading \wima Missions}
\label{sec:savingLoadingWima}
Pressing the \verb|File| button (see fig. \ref{fig:wimaViewSaveLoad}) of \wima tool strip (see \ref{sec:wimaToolStrip}) opens a menu offering 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 \verb|Open| button can be used to load previously stored files. 
\begin{figure}
	\includegraphics[width=0.3\textwidth]{pics/wimaViewSaveLoad}
	\centering
	\caption{\wima tool strip save/load dialog.}
	\label{fig:wimaViewSaveLoad}
\end{figure}

\subsubsection{Clearing \wima Missions}
\label{sec:clearingWima}
Press the \verb|File| button (see fig. \ref{fig:wimaViewSaveLoad}) of \wima tool strip (see \ref{sec:wimaToolStrip}) to open the dialog window. Pressing the \verb|New| button deletes all contents within the WiMA Main Window. 

\subsubsection{Uploading, Downloading and Clearing vehicle Missions}
\label{sec:uploadDownloadVehicle}
Press \verb|File| button (see fig. \ref{fig:wimaViewSaveLoad}) of \wima tool strip (see \ref{sec:wimaToolStrip}) to open the dialog window. With the \verb|Upload|, \verb|Download| and \verb|Clear Vehicle Mission| button, the mission items (if present) can be uploaded, downloaded or deleted from the vehicle.


\subsubsection{Inserting \wima Areas}
\label{sec:insertAreas}
The \verb|Measure|, \verb|Service| and \verb|Corridor| buttons of the \wima tool strip (see \ref{sec:wimaToolStrip}) are used to insert a measurement, service and corridor area, respectively. Only one of each can be inserted. To generate a flight plan, at least a measurement and a service area must be defined. In that case both must be overlapping.

\subsubsection{Generating a \wima flight plan}
\label{sec:generatingFlightPlan}
The current version of \wima automatically updates the flight plan, after terminated user interaction. However using the \verb|Calculate| button (see fig. \ref{fig:wimaViewSaveLoad}) of the \wima tool strip (see \ref{sec:wimaToolStrip}), manual regeneration can be triggered. The flight plan will be generated such that all way-points are within or at least at the edge of the joined\footnote{The joined area is the sum of measurement, service area and corridor (see \ref{sec:wimaAreas}).} area. However it should be taken in account, that the vehicle could still leave the save area, even under fully functional operation. Depending on the software implementation of the vehicles flight stack (firmware), the flight controller could perform a path change. Additionally drifts caused by wind gusts could occur. An example can be seen in fig. \ref{fig:optimPaht}. The vehicles flight controller has no information about any \wima Areas, they exist exclusively within the \qgc application.
\begin{figure}
	\includegraphics[width=0.3\textwidth]{pics/wimaRadioButtons}
	\centering
	\caption{Checking the Mission radio button, on the right hand side, displays the mission items.}
	\label{fig:wimaRadioButtons}
\end{figure}
\begin{figure}
	\includegraphics[width=0.6\textwidth]{pics/flightPath2}
	\centering	
	\caption{The flight path generated from the areas depicted in fig. \ref{fig:validConfig}.}
	\label{fig:flightPath}
\end{figure}

\subsubsection{Navigating the Map}
\label{sec:navigatingMap}
The three buttons  \verb|Center|, \verb|In| and \verb|Out| (see fig. \ref{fig:wimaViewSaveLoad}) of the \wima tool strip (see \ref{sec:wimaToolStrip}) can be used to center the view to a object of interest, and for zooming. The Map can be navigated by dragging the mouse pointer or touch screen.

\subsubsection{How to display the generated flight plan}
The flight plan can be displayed by checking the \verb|Mission| radio button above the \wima item editor (see. fig. \ref{fig:wimaRadioButtons}), as depicted in fig \ref{fig:wimaRadioButtons}. An example of a generated flight path can be seen in figure \ref{fig:flightPath}. Within the green measurement area the program has generated a circular survey (see \ref{sec:circularSurvey} ). The survey has an entry and an exit point. The program has routed paths from the take off point to the surveys entry point and from the surveys exit point to the landing point. The paths have been chosen to be within the joined area and to be as short as possible. 

\subsubsection{Circular Survey}
\label{sec:circularSurvey}
\begin{figure}
	\includegraphics[width=0.25\textwidth]{pics/circularSurveyItemEditor}
	\centering
	\caption{The circular survey item editor. Can be found at the right edge of the screen.}
	\label{fig:circularSurveyItemEditor}
\end{figure} 

The Circular Survey (green area in fig. \ref{fig:flightPath}, containing circular tracks) is a flight pattern provided by \wima. It is similar to the Survey pattern of the standard \qgc application. The Circular Survey was adapted for mobile coverage measurements. It consists of circle segments refereed to as transects. Ideally, the transects are connected with each other such that the path between entry and exit point is as short as possible. Currently this goal is approximated by a heuristics. The solution might not always be the global optimum. The \verb|Reference| point (Circle with R symbol and Reference tag, see fig. \ref{fig:flightPath}) defines the center of the circle segments. It is supposed to be placed on the base stations position.
  
Circular survey parameters can be edited with the circular survey editor (see \ref{fig:circularSurveyItemEditor}). The \verb|Altitude| input box adjusts the altitude of the survey's way-points. The distance between adjacent circle segments can be modified by changing the \verb|Delta R| value. The circle segments are approximated by polygonal structures, consisting of way-points. Two arbitrary adjacent way-points of a circle segment have a maximum angle between them. This angle can be adjusted by editing the \verb|Delta Alpha| input box. The \verb|Delta Alpha| value can assume everything between 0.3$^{\circ}$ and 90$^{\circ}$. The higher the value the rougher the circle appears. The survey will contain the less way-points the higher the \verb|Delta R| and the \verb|Delta Alpha| values are. The number of way-points impacts the recreation and upload time. In general the following holds. The less way-points the better. Use only as many way-point as you really need.
 
Short transects are often undesired, to remove them, the minimal transect length can be specified by the \verb|Min. Length| value. 

If it is desired that the UAV flies with the same direction for all transects the \verb|Fixed Direction| check box can be activated. The \verb|Relative Altitude| check box enables relative height. With the \verb|Reverse Path| check box path reversal can be obtained. The \verb|Reset Reference| button the reference handle can be set to the survey area center. This can be helpful if the reference handle is hidden.

To reduce calculation effort, the maximum number of way-points can be set using the \verb|Max Waypoints| input box. Transects are hidden and calculations aborted, if the number of way-points exceeds \verb|Max Waypoints|.

\subsubsection{How to synchronize the Data with Flight View}



\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 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 \qgc 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 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}