root/documentation/ossie/user-guide-0.7.0/QuickStartGuide.tex @ 8154

% ------------------------------------------------------------------
%
%   TITLE: OSSIE Quick Start Guide
% AUTHORS: Matt Carrick
% CREATED: 
% REVISED: 
%     URL: http://ossie.wireless.vt.edu/
%
% ------------------------------------------------------------------

\section{Quick Start Guide}
\label{section:quickstartguide}
The following is a quick start guide. It is meant to be a concise introduction
to OSSIE. While it assumes general computer
knowledge, it tries not to assume extensive knowledge of or familiarity with Linux or
OSSIE. The quick start guide is a compact version of much of the rest of
the guide. If you are interested in more in-depth coverage, we recommend you
fully read the pertinent sections of the guide.
The rest of this document should be able answer more of the questions that may arise 
during installation and provide deeper insight into OSSIE. That
said, here is a short walkthrough to get you experimenting with
OSSIE in short order.

\subsection{Using the OSSIE VMware Player Image}
The VMware Player application is needed to run the OSSIE demonstration waveform
using our VMware image.

Unless VMware Player is already installed on your system, download it from \\
\href{http://www.vmware.com/download/player/}{http://www.vmware.com/download/player/}
and install it. For detailed instructions, consult the VMWare Player User Guide~\cite{vmware:web}.

Next, download the OSSIE VMware image at \\
\href{http://ossie.wireless.vt.edu/trac/wiki/Downloads}{http://ossie.wireless.vt.edu/trac/wiki/Downloads}.
When the download is complete, unzip the image to another directory. We
recommend you keep the original zip file. It can serve as a useful backup
should you want or need to start from a fresh install and might save
time and bandwidth.

Once the image is unpacked, boot it up in VMware Player. This quick start guide
will walk you though the process of running OSSIE and our demonstration
waveform. \describeossiedemo

\subsection{Running the OSSIE Demonstration Waveform}
\label{section:quickstartguide:ossiedemo}
Once the OSSIE VMware image has booted up, open a
terminal window by navigating to Applications $\to$System
Tools$\to$Terminal. The first thing that needs to be started is the
naming service. Type as root:
%TODO: instructions on logging in as root
\begin{lstlisting}[]
 # omniNames.sh
\end{lstlisting}

%TODO: fix image to automagically start naming service

The terminal should look like this:
\begin{center}
\includegraphics[scale=0.4]{figures/quickstart/omniNames.png}
\end{center}

The next service that needs to be started is the Node Booter. Open a new tab or
a completely new terminal and type the commands in the listing below. You can
press tab after the first couple of letters of a command, directory or
filename to have it automatically completed, saving time and perhaps avoiding
typos.
\begin{lstlisting}[]
 $ cd /sdr/
 $ nodeBooter -D -d nodes/default_GPP_node/DeviceManager.dcd.xml
\end{lstlisting}

The terminal should look like this:
\begin{center}
\includegraphics[scale=0.4]{figures/quickstart/nodeBooter.png}
\end{center}

Now load the waveform using wavLoader. In a third tab or terminal, type in:
\begin{lstlisting}[]
 $ cd /sdr/waveforms/ossie_demo
 $ wavLoader.py ossie_demo_DAS.xml
\end{lstlisting}

The terminal should look similar to the following:
\begin{center}
\includegraphics[scale=0.4]{figures/quickstart/wavLoader.png}
\end{center}

Select the first listing of the OSSIE demonstration waveform,\\
{\tt //waveforms/ossie\_demo/ossie\_demo.sad.xml}
\begin{lstlisting}[]
 Selection: 1
\end{lstlisting}

The tab or terminal window in which nodeBooter was started should now contain
the output of the demonstration waveform. The lines will update with output
similar to this:
\begin{verbatim}
 RxDemo errors:  X  / 1024
\end{verbatim}
The X denotes the number of QPSK bit errors out of 1024 that have been detected
by the RxDemo component.
Here is an example output:
\begin{center}
\includegraphics[scale=0.4]{figures/quickstart/RxDemo.png}
\end{center}

Congratulations! You have just run the QPSK demonstration waveform for OSSIE
version 0.7.0. From here you may be interested in learning how to create
your own waveforms using the OSSIE Waveform Developer (OWD) described in
Section~\ref{section:owd}.