root/documentation/ossie/user-guide-0.7.0/UserGuide.tex @ 8277

% ------------------------------------------------------------------
%
%   TITLE: OSSIE User Guide 0.7.0
% AUTHORS: Matt Carrick, Drew Cormier, Christopher Covington,
%          Carl B. Dietrich, 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.}

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

%@begin{comment}
\usepackage{listings}
%@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}
\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 0.7.0 User Guide\\}

%\vfill

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

\vfill

September, 2008


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


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

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

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

% ------------------- 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 something 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-0.7.0/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-0.7.0/src/system/ossie/idl/python/} directory:
\begin{lstlisting}[]
 # cd ossie-0.7.0/src/system/ossie/idl/python/
 # python setup.py install
\end{lstlisting}

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


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

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

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

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