% ------------------------------------------------------------------ % % 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 \ omniorb-nameserver python-numpy python-wxgtk2.8 \end{lstlisting} A bug in Ubuntu 11.10 causes some of the OSSIE tools to print the following warning: \begin{lstlisting}[] (eclipse:18548): Gtk-WARNING **: Unable to locate theme engine in module_path: "pixmap" \end{lstlisting} Installing the \texttt{gtk2-engines-pixbuf} package will remove the warning, though it is not explicity necessary for OSSIE. \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/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 apt-cache search } 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. In a terminal, enter the following lines: \begin{lstlisting}[] $ sudo apt-get install openjdk-7-jre \end{lstlisting} to install the Java runtime environment. To install the entire Java Development Kit if you wish to do Java development, enter the following: \begin{lstlisting}[] $ sudo apt-get install openjdk-7-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.