root/documentation/ossie/user-guide-0.8.2/UserGuide.tex @ 10692

% ------------------------------------------------------------------
%
%   TITLE: OSSIE Installation and User Guide 0.8.2
% AUTHORS: Matt Carrick, Drew Cormier, Christopher Covington,
%          Carl B. Dietrich, Mike Ekoniak, Joseph Gaeddert, Benjamin Hilburn, 
%          C. Ian Phelps, Shereef Sayed, Jason Snyder, Haris Volos
% CREATED: 
% REVISED: 
%     URL: http://ossie.wireless.vt.edu/
%
% ------------------------------------------------------------------

\documentclass[11pt]{article}

\setlength{\textwidth}{6.5in}
\setlength{\textheight}{8.2in}
\setlength{\evensidemargin}{0in}
\setlength{\oddsidemargin}{0in}
\setlength{\topmargin}{0in}
\setlength{\parindent}{0pt}
\setlength{\parskip}{0.1in}

\newcommand{\describeossiedemo}{The demonstration waveform simulates a very
basic QPSK communication system. It consists of three components: a transmitter,
a channel, and a receiver. The transmitter generates bursts of 512 QPSK symbols
that are sent through an AWGN channel and decoded by the receiver. The number of
errors per burst will be printed out on the screen while the waveform runs.}

\newcommand{\ossieversion}{0.8.2}

%@usepackage{html}
%@usepackage{verbatim}

%@begin{comment}
\usepackage{listings}
\usepackage{amssymb}
%@end{comment}

\usepackage{appendix}
\usepackage[pdftex]{graphicx}
\usepackage{url}

% ------------------- BIBLIOGRAPHY STYLE -------------------
\usepackage[sort]{natbib}
\bibliographystyle{plain} % note the change here
%\bibliographystyle{IEEEtran}
\bibpunct{[}{]}{,}{n}{}{;}  % define bibliography punctuation
% The six mandatory arguments for \bibpunct are:
%   1. opening bracket: '(', '[', '{', or '<'
%   2. closing bracket: ')', ']', '}', or '>'
%   3. separator between multiple citations: ';' or ','
%   4. citation style: 'n' for numerical style, 's' for numerical superscript style, or 'a' for authorÐyear style
%   5. punctuation between the author names and the year
%   6. punctuation between years or numbers when common author lists are suppressed: ',' or ';' 

%@begin{comment}
% due to magic hacks, hyperref must be right before document begin
\usepackage[pdftex]{hyperref}
\usepackage{wrapfig}
\hypersetup{colorlinks,
           citecolor=blue,
           filecolor=blue,
           linkcolor=blue,
           urlcolor=blue,
           pdftex}
%@end{comment}

% ------------------- MAIN DOCUMENT -------------------
\begin{document}
\thispagestyle{empty}
\pagenumbering{roman}

%@begin{comment}
\definecolor{MyCommentColor}{rgb}{0.1,0.4,0.1}
\definecolor{MyCodeBackgroundColor}{rgb}{0.95,0.95,0.95}
%\definecolor{MyCodeFrameRuleColor}{rgb}{0.9,0.9,0.9}
\definecolor{MyStringColor}{rgb}{0.6,0.1,0.1}
\definecolor{MyKeywordColor}{rgb}{0.6,0.1,0.1}

% define lstlistings style
% (see http://tug.ctan.org/tex-archive/macros/latex/contrib/listings/)
\lstloadlanguages{[GNU]C++,Python,[CORBA]IDL,sh}

\lstset{% general command to set parameter(s)
    basicstyle=\small\ttfamily,          % print whole listing small
    keywordstyle=\color{MyKeywordColor}\bfseries,
    identifierstyle=\color{black},
    commentstyle=\color{MyCommentColor}, % define color and sytle of comments
    stringstyle=\ttfamily\color{MyStringColor},      % typewriter type for strings
    %showstringspaces=false,     % no special string spaces
    backgroundcolor=\color{MyCodeBackgroundColor},
    frame=none,
    %framerule=0.5pt,
    %framexleftmargin=2pt,
    %framexrightmargin=2pt,
    %framexbottommargin=2pt,
    %framextopmargin=2pt,
    %rulecolor=\color{MyCodeFrameRuleColor},
    nolol=true,     % suppress listoflistings entry
    tabsize=4,
    linewidth=\linewidth,
    breaklines=false,
    xleftmargin=6pt,
    xrightmargin=6pt
}
%@end{comment}

{\huge OSSIE \ossieversion\ Installation and User Guide\\}

%\vfill

{\sf Matt Carrick, Drew Cormier, Christopher Covington, Carl B. Dietrich, \\
Joseph Gaeddert, Benjamin Hilburn, C. Ian Phelps, Shereef Sayed, \\ 
Deepan Seeralan, Jason Snyder, Haris Volos}

\vfill

April, 2011


\vfill

\begin{figure*}[!ht]
\centering
\includegraphics[width=6in]{figures/alf_screenshot_00.png}
\end{figure*}

\vfill

OSSIE is an open source Software Defined Radio (SDR) development effort based
at Virginia Tech. OSSIE is primarily intended to enable research and education
in SDR and wireless communications. The software package includes an SDR core
framework based on the JTRS Software Communications Architecture, tools
for rapid development of SDR components and waveforms (applications), and an
evolving library of pre-built components and waveforms. In addition, free
laboratory exercises for SDR education and training are being developed in
cooperation with the Naval Postgraduate School.\\

\begin{center}
{\sf\small OSSIE is the Open Source SCA Implementation::Embedded}
\end{center}

\pagebreak
\tableofcontents
%@begin{comment}
\lstlistoflistings
%@end{comment}

\pagebreak
\pagenumbering{arabic}

% ------------------- Quick Start Guide -------------------
\newpage
\input{QuickStartGuide} 

% ------------------- Introduction -------------------
\newpage
\input{Introduction} 

% ------------------- Installation Guide -------------------
\newpage
\input{Installation} 

% ------------------- Running Waveforms -------------------
\newpage
\input{RunningWaveforms} 

% ------------------- Waveform Workshop -------------------
\newpage
\input{WaveformWorkshop} 

% ------------------- OEF Guide -------------------
\newpage
\include{OEFGuide} 

% ------------------- OWD Guide -------------------
\newpage
\include{OWDGuide} 

% ------------------- ALF Guide -------------------
\newpage
\include{ALFGuide} 

% ------------------- WaveDash Guide -------------------
\newpage
\include{WaveDash} 

% ------------------- wavecli.py Guide -----------------
\newpage
\include{wavecli}

%-------------------- Uninstallation -------------------
\newpage
\include{Uninstallation}

% ------------------- Helping With Development -------------------
\newpage
\input{HelpingWithDevelopment} 

% ------------------- Troubleshooting -------------------
\newpage
\input{Troubleshooting}

% ------------------- NoCites -------------------
\nocite{vmware:web}
\nocite{irctutorial:web}
\nocite{writingbugreports:web}
\nocite{Bard:2007}
\nocite{Buracchini:2000}
\nocite{Reed:2002}
\nocite{jtrssca:web}

% ------------------------------------------------------------------
%
%             APPENDICES
%
% ------------------------------------------------------------------
\pagebreak
\appendix
\appendixpage
\addappheadtotoc

% -------------------- managing services --------------------------
\section{Managing Services on Fedora Core 9}
\label{appendix:services}
Controlling which services are currently running on your computer and which
start up with your computer is very easy with Fedora Core's Service
Configuration interface. From the GNOME taskbar, click
System$\to$Administration$\to$Services. You will need to enter your root (system
administrator) password to use the dialog.  The window that pops up shows you
all of the available services on your computer.  Services that have a check in
the box next to them are currently running.  To turn a service on or off,
simply click the box, or select it and press the `Start' or `Stop' button at
the top of the list.

In order to edit which services start with your computer when it boots, you need
to know a little about runlevels.  You computer has several different
runlevels. The one you are most concerned with is runlevel 5.  Runlevel 5 means
multiuser X-server mode.  Generally speaking, if you are using a graphical
interface then you are in runlevel 5.

To have omniNames start with your computer, select it in the services list,
click `Edit Runlevel' on the top menubar, and select runlevel 5.  Click
the save button to save your configuration.

That's it!  The next time you start your computer, omniNames will start running
automatically.

% ------------------- omniNames.sh -------------------
\section{Creating {\tt omniNames.sh}}
\label{appendix:omninamessh}
Installing omniORB from RPM automatically starts the naming service when the
system boots.
If omniORB was {\it not} installed using RPM, the naming service will
probably need to be started manually.
To do so, create a file called {\tt omniNames.sh} containing the following
\begin{lstlisting}[caption={{\tt omniNames.sh} file}, nolol=false]
 #!/bin/sh
 
 killall omniNames
 rm /sdr/logs/omninames*
 
 omniNames -start -logdir /sdr/logs &
\end{lstlisting}

Once this file is created, the file must be given executable permissions:
\begin{lstlisting}[]
 $ chmod 755 omniNames.sh
 # cp omniNames.sh /usr/local/bin
\end{lstlisting}

Create a directory for the logs:
\begin{lstlisting}[]
 $ mkdir /sdr/logs
\end{lstlisting}

The script can now be run by executing {\tt omniNames.sh} in any terminal.
You can check to see if {\tt omniNames} is running by executing:
\begin{lstlisting}[]
 $ nameclt list
\end{lstlisting}
If the naming service is {\it not} running you will see an error like:
\begin{lstlisting}[]
  Unexpected error when trying to narrow the NamingContext.
\end{lstlisting}

% ------------------- ossie.pth -------------------
\newpage
\section{Configuring {\tt ossie.pth}}
\label{appendix:ossiepth}
In order for the Python tools to link properly, a Python path file must be
created to point to the shared modules.
The default {\tt ossie.pth} file is located under \\
{\tt ossie-\ossieversion/src/system/ossie/idl/python/} and is installed by default in \\
{\tt /usr/lib/pythonX.X/site-packages} when you install the ossie core
framework libraries.

If you did {\it not} install omniORBpy using an RPM, you might need to add \\
{\tt /usr/local/lib/pythonX.X/site-packages} to {\tt ossie.pth}, where
{\it X.X} corresponds to the specific version of Python installed on your
system.
Now reinstall by running {\tt python setup.py install} as root within the \\
{\tt ossie-\ossieversion/system/ossie/idl/python/} directory:
\begin{lstlisting}[]
 # cd ossie-0.8.1/system/ossie/idl/python/
 # python setup.py install
\end{lstlisting}

% ----------- source component creation ----------
\newpage
\section{Data Source Component Creation}
\label{appendix:datasourcecreation}
The component TxDemo will be used as an example on how to create a data source.
When creating a component which is not a data source, typically only the function 
{\tt ProcessData} needs to be modified to include the desired operation. This is 
not the case for a source component, however. The code that needs to be updated in 
this example resides in the {\tt start}, {\tt stop}, and {\tt ProcessData} functions. 
Locate the directory {\tt components/TxDemo} and open the files TxDemo.h and TxDemo.cpp. 

In TxDemo.h, near the end of the file the following code will be listed:
\begin{lstlisting}[]
  bool continue_processing(void); 
  volatile bool thread_started;
\end{lstlisting}
The flag {\tt thread\_started} holds the state of the component; whether or not the 
component should continue sending data. A function {\tt continue\_processing} is also 
declared which will be used to check {\tt thread\_started} and determine if the component 
should continue sending packets.

In TxDemo.cpp, locate the {\tt start} function and the following code will be listed:
\begin{lstlisting}[]
  omni_mutex_lock l(processing_mutex);
  if (false == thread_started){
    thread_started = true;    //initialize
    //Create the thread for the writer's processing function
    processing_thread = new omni_thread(Run, (void *) this);

    //Start the thread containing the writer's processing function
    processing_thread->start();
    }
\end{lstlisting}
This code creates a new thread and starts processing when the {\tt thread\_started} 
variable is set to true.

Now locate the {\tt stop} function, and the following code will be listed:
\begin{lstlisting}[]
  omni_mutex_lock l(processing_mutex);
  thread_started=false;
\end{lstlisting}
This code stops the processing on the thread by setting {\tt thread\_started} to false.

Now locate the {\tt ProcessData} function, and the following code will be listed:
\begin{lstlisting}[]
  while(continue_processing()) {
    // push data to output
    dataOutPort->pushPacket(I_out, Q_out);

    // wait
    usleep(packet_delay*1000);
    }
\end{lstlisting}
This code checks the function {\tt continue\_processing} to determine if packets should 
continue to be sent using {\tt pushPacket}. The {\tt usleep} function call is specific 
to TxDemo, and is not necessarily required in other data sources.

The last section of code that must be created is the {\tt continue\_processing} function. 
The code for the function is listed as the following:
\begin{lstlisting}[]
  bool TxDemo_i::continue_processing(void)
  {
    omni_mutex_lock l(processing_mutex);
    return thread_started;
  } 
\end{lstlisting}

All of the code listings provided above are not created by default when a new component is 
generated, since the code is only required for source components. Instead, all of the 
code must be added by hand. The addition of the code will create the appropriate environment 
for the data source, and afterwards only the data creation must be added to the {\tt ProcessData} 
function.

% ------------------- Known Bugs -------------------
\include{Bugs}


% ------------------- Abbreviations -------------------
\input{Abbreviations}

% ------------------------------------------------------------------
%
%             BIBLIOGRAPHY
%
% ------------------------------------------------------------------
\newpage
\bibliography{UserGuide}

% ------------------- Change Log -------------------
\newpage
\section{Change Log}
\label{appendix:changelog}

\subsection {OSSIE 0.8.2}
All changes in 0.8.2 involve the tools
\begin{enumerate}
\item ALF tries to find a domain manager using a local naming service when ALF is first started.  If a domain manager is not found using the local naming service, ALF pops up a dialog box.  The user can then specify an IP address for a remote naming service or start a domain manager locally using icons in the ALF toolbar.
\item The nodeBooter can now be started from either ALF or WaveDash by clicking on the right most icon in the tool bar (monitor with triangle/arrow).  This allows the user to choose a domain manager and a device manager.  The domain manager is optional and can be deselected.
\item OEF 1.1.7 supports multiple instances of a component in a waveform, on the same node or on different nodes.  In previous versions multiple instances were all assigned the same instantiation ID.
\item OSSIE preferences file allows users the option to replace the default GPP license text with a license of their choice.  From Eclipse menu bar:  {\tt Window -> Preferences -> OSSIE -> License}, then paste in new license text.
\item OEF now supports creating python components that use long, bool, and string properties.
\item WaveDash now includes two new views:  a command line interface and an HTTP server
\item WaveDash backend now can run without X11. (wasn't included in 0.8.1 tarball, need to fix makefile)
\end{enumerate}

\subsection {OSSIE 0.8.1}
\begin{enumerate}
\item Components and Devices now accept standard command line parameters.
\item ALF and WaveDash now use the CF::FileSystem to query for available components and applications.
\item Distribution of components across multiple nodes is significantly simpler.
\item Core Framework now supports boolean, char, and octal component property
types. 
\item OEF 1.1.5 now supports node generation.
\item WaveDash now supports updating property values immediately or on a
per-component or per-waveform basis.
%\item Wavedash backend now can run without X11. (wasn't included in 0.8.1 tarball, need to fix makefile)
\end{enumerate}

\subsection {OSSIE 0.8.0}
\begin{enumerate}
\item CF::FileSystem now encapsulates the Boost file system library
\item Xerces has been replaced by TinyXML
\item The install directory structure has changed to separate Domain management from Device management
\item The nodeBooter and c\_wavLoader utilities support '-debug' level flag and any compatible ORB flags (i.e. -ORBInitRef)
\end{enumerate}

\subsection {OSSIE 0.7.4}
\begin{enumerate}
\item Addition of new waveform: Lab 5 example AM application.
\item AutomaticGainControl component will output ones when threshold is not met.
\item ALF ConnectTool has improved support for port connections.
\item WaveDash can now control single-component waveforms created and launched
in ALF.
\item ALF allows user to specify IP address for CORBA naming service.
\end{enumerate}

\subsection {OSSIE 0.7.3}
\begin{enumerate}
\item Introduction of Waveform Dashboard (WaveDash).
\item Addition of new waveforms: OSSIETalkLoopBack, OSSIETalkUSRP.
\item Addition of new components: Channel, Conv\_Dec, Conv\_Enc, DigitalModem, FrameAssembler, OSSIETalk, PacketResizer, SymbolSyncPoly.
\item Decimator has the ability to use either IIR or FIR.
\item OWD provides generation of custom license headers.
\item More removal of vestigial project files.
\end{enumerate}

\subsection {OSSIE 0.7.2}
\begin{enumerate}
\item Improved start/stop capability within TxDemo component.
\item Corrected XML Template files for OWDC component generation.
\item Removal of incorrect entry point tags in default\_GPP\_node SPD.
\item Deletion of vestigial project files.
\item Addition of Interpolator component.
\end{enumerate}

\subsection {OSSIE 0.7.1}
\begin{enumerate}
\item Removal of duplicate profile templates.
\item Added start, stop capability to TxDemo component.
\item Fixed USRP\_Commander rx\_freq property typo.
\item Fixed capability of components being run as waveforms.
\end{enumerate}

\subsection {OSSIE 0.7.0}
\begin{enumerate}
\item Start of change log.
\item Allows for non /sdr install.
\item Installation through RPMs.
\item ALF can start and stop waveforms.
\item Reduced plot tool's refresh rate.
\item Removed ``sample waveform'' option in OWD.
\item Removed duplicate DOCTYPE descriptors in generated XML files.
\item Fixed path in USRP's SCD file.
\item Fixed soundCardCapture device name to prevent OWD error.
\item Added Ubuntu 8.04 as supported platform.
\item OWD default save directory is now home directory.
\item ALF's plot tool has normalized frequency axis.
\item Debug statements use DEBUG macro instead of std::cout.
\item Tools now installed to site-packages.
\item ALF, OWD, and OWD Component Editor can be run from any directory.
\item More than two nodes can be run through a single domain manager.
\item Added webcam components.
\item Installation from source broken into two steps.
\end{enumerate}

\end{document}