root/ossiedev/branches/mcarrick/user-guide-0.8.3/Installation.tex @ 11063

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

\newpage
\section{Installation}
\label{section:installation}
For users that do not have access to a Linux system, or are unfamiliar with Linux, we recommend
that you use our pre-built VMWare images.  These images have OSSIE pre-installed on them, and are
ready to use out-of-the-box. Using an OSSIE VMware image is described in
Section~\ref{section:installation:vmware}.

Although we do not yet provide and support binary installation packages for more Linux
distributions, compiling OSSIE from source on them should be possible.

To install OSSIE from source, follow the below instructions to install the OSSIE dependencies,
and then compile and install the source code. 

\subsection{Installing OSSIE from Source}
\label{section:installation:source}

This section assumes that the user is familiar with basic
Linux commands such as {\tt cd} and {\tt ls} and has sudo 
access or root access.

If you have an older version of OSSIE installed, then you will need to delete the contents of {\tt /sdr/}.
\begin{lstlisting}[]
 $ rm -rf /sdr/*
\end{lstlisting}

Ubuntu is the main supported operating system for OSSIE and the dependencies 
for Ubuntu 11.10 are listed below. After following the instructions, jump to 
Section~\ref{section:installation:source:dependencies:configomni} to continue the install.

\subsubsection{Installing Dependencies on Ubuntu 11.10}
\begin{lstlisting}[]
 $ sudo apt-get -y install libtool automake g++ omniorb libomniorb4-dev omniidl \
        libboost-all-dev libgnuradio-usrp-dev libgnuradio-usrp2-dev libpulse-dev \
        libsndfile-dev python-omniorb omniidl-python
\end{lstlisting}

\subsubsection{Configure omniORB}
\label{section:installation:source:dependencies:configomni}
All of the dependencies have been installed and one of the dependencies, 
omniORB, needs to be configured. This configuration is done through the
modification of a file, either {\tt /etc/omniORB.cfg} or 
{\tt /etc/omniORB4.cfg}, depending on the version of the omniORB dependency. 

Open the file as root, and search for the following line:
\begin{lstlisting}[]
 InitRef = NameService=corbaname::my.host.name
\end{lstlisting}
Uncomment the line by deleting the pound or hash character `\#' and change
it to:
\begin{lstlisting}[]
 InitRef = NameService=corbaname::127.0.0.1
\end{lstlisting}
Before running the framework you will need to start the naming service. If you
installed omniORB from source, you have to follow the instructions in
Appendix~\ref{appendix:omninamessh}. When installing from yum
{\tt omniNames} will automatically start when you restart your machine. Refer
to Appendix~\ref{appendix:services} for instructions on how to start the
omniNames service without restarting your machine or set whether the service
starts automatically at boot.
\footnote{You may also manually start a source-compiled tarball package of
omniNames {\tt omniNames} with the script described in
Appendix~\ref{appendix:omninamessh}}

\label{section:installation:source:dependencies:gnuradio}
OSSIE uses a small subset of GNU Radio to communicate with and configure the USRP. The
following steps will walk through configuring portions the USRP and USRP2 drivers:

To setup the proper permissions for the USRP, as root, create a group which will have access
to the USRP:

\begin{lstlisting}[]
 $ sudo /usr/sbin/groupadd usrp
\end{lstlisting}

Add users to the group which need access to the USRP:

\begin{lstlisting}[]
 $ sudo /usr/sbin/usermod -G usrp -a USERNAME
\end{lstlisting}

Now that users will have access to the USRP, read and write access to the device
must be created. As root, create the file {\tt /etc/udev/rules.d/10-usrp.rules} in
a text editor:

\begin{lstlisting}[]
 $ sudo gedit /etc/udev/rules.d/10-usrp.rules
\end{lstlisting}

Add the following text to the file:

\begin{lstlisting}[]
 ACTION=="add", BUS=="usb", SYSFS{idVendor}=="fffe", \
 SYSFS{idProduct}=="0002", GROUP:="usrp", MODE:="0660"
\end{lstlisting}

The text above is displayed on two lines due to the contraints on page size, however
the text must appear on a single line, without the backslash, in the file for the
access to the USRP to work properly. You may also add the following comment lines to
the file for future reference:

\begin{lstlisting}[]
 # rule to grant read/write access on USRP to group named usrp.
 # to use, install this file in /etc/udev/rules.d/ as
 # 10-usrp.rules
\end{lstlisting}

The USRP interface has now been created. As an optional test, connect the USRP
to the computer and run the following command:

\begin{lstlisting}[]
 $ ls -lR /dev/bus/usb
\end{lstlisting}

The users root and usrp should now be listed under the user groups.

If you are using the USRP2, it is necessary to have a gigabit ethernet interface and 
intruct the kernel to allow raw socket access to the ethernet port:
\begin{lstlisting}[]
 $ sudo chmod u+s /usr/local/bin/usrp2_socket_opener
\end{lstlisting}

This step is necessary every time you reinstall GNU Radio.

\subsubsection{Install OSSIE}
\label{section:installation:source:ossiecf}
You are now ready to build and install OSSIE.  
Note that installing by hand requires some knowledge of OSSIE, Linux, and software development.

Download the latest tarball from
\href{http://ossie.wireless.vt.edu/download/tarballs/\ossieversion/}{http://ossie.wireless.vt.edu/download/tarballs/\ossieversion/}
\\ and unpack {\tt ossie-\ossieversion.tar.gz}.
\begin{lstlisting}[]
 $ wget http://ossie.wireless.vt.edu/download/tarballs/0.8.3/ \ 
   ossie-0.8.3.tar.gz
 $ tar -xvf ossie-0.8.3.tar.gz
\end{lstlisting}

By default, the installation directory of the OSSIE platform is {\tt /sdr}. In order to install new
source code and binaries into this directory without root permissions, you need to create and change
the ownership of {\tt /sdr}.
\begin{lstlisting}[]
 $ sudo mkdir /sdr
 $ sudo chown -R username.username /sdr
\end{lstlisting}
where {\tt username} is your user name.

\subsubsection{Using Autoconf}
\label{section:installation:source:ossiecf:autoconf}

\begin{lstlisting}[]
 $ cd ossie-0.8.3
 $ ./configure --prefix=/sdr --libdir=/usr/local/lib/ \
   --includedir=/usr/local/include/ --with-boost --with-boost-filesystem
 $ make
 $ sudo make install
\end{lstlisting}

If successful, the prompt should say:
\begin{lstlisting}[]
*********************************************************

  Complete installation of OSSIE 0.8.3 finished!

*********************************************************
\end{lstlisting}

If you prefer, or require, a different root directory, then change the 
'--prefix' flag to your appropriate absolute path. If you require the OSSIE 
libraries to be installed to a different location, then change the '--libdir' 
flag to your appropriate absolute path. For further 'configure' options, 
use {\tt configure --help}. 

If configure fails, use {\tt aptitude search <dependency name>} to find any missing packages.

\subsubsection{Updating System Libraries}
\label{section:installation:source:ossiecf:ldconfig}
Once the OSSIE libraries are installed, they need to be linked.
As root edit the file {\tt /etc/ld.so.conf}, adding the line
\begin{lstlisting}[]
 /usr/local/lib
\end{lstlisting}
Now run:
\begin{lstlisting}[]
 $ sudo /sbin/ldconfig
\end{lstlisting}

OSSIE should now be successfully installed on your system. You can skip to
Section~\ref{section:runningwaveforms} to learn how to run waveforms.

\subsection{Installation of OSSIE Eclipse Feature}
\label{section:installation:alloefinstall}
Installation of the OSSIE Eclipse Feature (OEF) requires the installation of OSSIE, Java, and Eclipse.

\subsubsection{Installing Java}
\label{section:installation:javainstall}
Eclipse is written in Java, so you must have it installed to run Eclipse and OEF. 
We recommend using Sun's Java Development Kit. As of this writing, the GNU Compiler 
for Java (GCJ) will not work. 

\subsubsection{Installing Java on Ubuntu}
\label{section:installation:javaubuntu}

Open /etc/apt/sources.list in an editor and add the following lines to the end of the file:
\begin{lstlisting}[]
 deb http://archive.canonical.com/ubuntu lucid partner
 deb-src http://archive.canonical.com/ubuntu lucid partner
\end{lstlisting}

In a terminal, enter the following lines:
\begin{lstlisting}[]
 $ sudo apt-get update
 $ sudo apt-get install sun-java6-jdk 
\end{lstlisting}

\subsubsection{Installing Eclipse}
\label{section:installation:eclipseinstall}
Install the Eclipse IDE for Java Developers. Go to 
the \href{http://www.eclipse.org/downloads/}{Eclipse Download Center} 
and download an Eclipse distribution for your platform.

Eclipse is distributed as a tarball archive that you can unpack to location 
of your choice. Pick a location that is appropriate for your platform and 
simply unpack the contents. There is no self-installer, just unpack the distribution. 
Do not install Eclipse in a directory that has spaces anywhere in its full path name.

\subsubsection{Installing OEF}
\label{section:installation:oefinstall}
Now that the dependencies have been installed, OEF can be installed.

Move into the unpacked eclipse directory, and start eclipse:
\begin{lstlisting}[]
$ cd /path/to/eclipse
$ ./eclipse
\end{lstlisting}

After Eclipse starts, on the toolbar select {\tt Help}, {\tt Install New Software}.
In the new window, select the ``Work with'' textbox and enter the URL: {\tt http://ossie.wireless.vt.edu/eclipse/}
and select Add. Give a name, e.g., ``OEF''.

The window will then add the URL, OSSIE, OSSIE Waveform Developer
Feature to the list of available software. Place a check in the box next to OSSIE
Waveform Developer Feature and click Next. Eclipse will show a window with more details, select Finish to complete the installation process.

%Eclipse will bring up a window which will
%resolve any dependencies and then start the install guide.

%When the install window opens, make sure OSSIE Waveform Developer Feature is selected and click Next. 

%Accept the GNU license agreement and select Next. Eclipse will then begin to download the necessary files, which may take a few minutes. 
Allow Eclipse to restart when it prompts to do so. After it restarts, the OSSIE Eclipse Feature will be installed.

Select the OSSIE perspective within Eclipse. On the toolbar, select {\tt Window}, 
{\tt Open Perspective}, {\tt Other}. In the new window, select OSSIE which will then
open the OSSIE perspective. On the toolbar, select {\tt File}, {\tt New}, {\tt OSSIE Waveform},
or {\tt OSSIE Component} to start developing.

These same instructions used for installing OEF can be used later to update it to newer versions. 

\subsection{Using a VMware Image on Any Platform}
\label{section:installation:vmware}
A VMware image of OSSIE \ossieversion\ pre-installed on a Linux operating system is available at \\
\href{http://ossie.wireless.vt.edu/trac/wiki/Downloads}{http://ossie.wireless.vt.edu/trac/wiki/Downloads}. 
All that is needed to run the virtual image is the VM­Ware Player, available
for free from \href{http://www.vmware.com/download/player/}{http://www.vmware.com/download/player/}.
Versions of the player are available for both Windows and Linux.

Install VMware Player on your system, unzip the virtual image and open it.
For full instructions on installing and using VMware player, please
consult the VMWare Player User Guide~\cite{vmware:web}.

It is recommended that you keep a copy of the zipped virtual image so that you do
not need to download the image a second time to start with a fresh copy. Changes
that you make from within the image will alter it, and in the event of drastic
unwanted changes, starting afresh is easy if you have an extra copy of the image
on your hard drive.

% \subsection{Via Ebuild on Gentoo Linux}
% Support for installation via Gentoo's Portage package management system has not
% yet been thoroughly tested but ebuilds do exist.
% 
% To access the ebuilds, install and configure layman if you haven't already:
% \begin{figure}
% \begin{lstlisting}[]
% # emerge layman
% # echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf
% \end{lstlisting}
% \end{figure}
% 
% Then, add ossie-overlay to your locally-stored overlays:
% \begin{figure}
% \begin{lstlisting}[]
% # layman -a -o https://ossie.wireless.vt.edu/repos/ossie/experimental/scripts/gentoo/ossie-overlay.xml
% \end{lstlisting}
% \end{figure}
% 
% You can then proceed with installing OSSIE:
% \begin{figure}
% \begin{lstlisting}[]
% # emerge -av ossie
% \end{lstlisting}
% \end{figure}
% 
% After sucessful compiliation of the OSSIE framework and its dependencies, skip
% to section X.

%\subsection{Embedded Platforms}
%While installation on embedded platforms is not officially supported in the
%0.6.2 release, work has been done (MENTION WORK) on porting OSSIE to embedded
%platforms and we are interested in promoting more work in this area.