Index: /documentation/ossie/user-guide-0.8.1/ALFGuide.tex =================================================================== --- /documentation/ossie/user-guide-0.8.1/ALFGuide.tex (revision 9972) +++ /documentation/ossie/user-guide-0.8.1/ALFGuide.tex (revision 9972) @@ -0,0 +1,174 @@ +% ------------------------------------------------------------------ +% +% TITLE: ALF Graphical Debugging Environment Guide +% AUTHORS: A. Cormier, C. Dietrich, J. Gaeddert +% CREATED: +% REVISED: +% URL: +% +% ------------------------------------------------------------------ + +\section{ALF Graphical Debugging Environment} +\label{section:alf} +Our waveform application visualization and debugging environment, ALF, provides a graphical user interface for +waveform management and debugging. Not only is it useful for installing and starting +waveforms, but it also provides a selection of debugging tools. When a +waveform is running, the developer is able to monitor the throughput of components, plot +data in real time, and input or output data to components in a +waveform. ALF also gives the user the ability to run components that are not part of a host +waveform in the framework. + +\subsection{Running ALF} +To start ALF, nodeBooter must be started as usual. In one tab or terminal type: +\begin{lstlisting}[] + $ nodeBooter -D -d dev/nodes/default_GPP_node/DeviceManager.dcd.xml +\end{lstlisting} +{\tt default\_GPP\_node} can be changed if your waveform requires it. + +Once {\tt nodeBooter} is running, open a second tab or terminal and type: +\begin{lstlisting}[] + $ ALF +\end{lstlisting} +This should open the ALF main window without errors or warnings. You will be presented with a dialog box to select the IP address hosting the NameService. If you are running the NameService locally (i.e. 127.0.0.1), then select 'OK' and continue using ALF. You can also point ALF to a different IP address that is hosting the NameService, for example, an embedded platform. +\begin{center} +\includegraphics[scale=0.35]{figures/alf/alf_main.png} +\end{center} + +\subsection{Running Waveforms} +\label{alf:runningwaveforms} +The top left pane, Launch Waveform Applications, displays a list of installed waveforms. +To install and run an instance of the waveform, simply double-click on the +waveform name.% +\footnote{Note that for a waveform to run, you must have started the correct +node for that particular waveform in nodeBooter. For a resource to run, you +must have started one of the default nodes in {\tt nodeBooter}} +% +The terminal in which {\tt nodeBooter} was started should display the output +of the OSSIE frameworks ApplicationFactory as it installs +the waveform. You may easily run multiple waveforms, or multiple instances of the same +waveform in this manner. + +It is also possible to install a waveform and start it manually. In the Launch Waveform Applications window, right click on a waveform to select Install or Install and Start. If Install is selected, the waveform will be installed and will be visible in the Manage Applications window. To start the installed waveform, right click and select start. To stop the waveform, right click on stop. + +\subsection{Managing Running Waveforms} +\label{alf:managewaveforms} +The Manage Applications pane in the lower-left corner of the main ALF +window displays a lists of all instances of running waveforms. +Try running the {\tt ossie\_demo} waveform using the instructions above. +You should see {\sf--OSSIE::ossie\_demo\_1} listed in the Manage +Waveforms pane. +Double-click on {\sf--OSSIE::ossie\_demo\_1} to display the waveform's components +in the main window: +\begin{center} +\includegraphics[scale=0.35]{figures/alf/alf_ossie_demo_display.png} +\end{center} +Notice that {\bf\sf --OSSIE::ossie\_demo\_1} is now in bold face to indicate +that this waveform instance is the one currently being displayed. + +%\subsection{Launch Components as Waveforms} +%\label{alf:launchcomponentsaswaveforms} +%The middle-left pane displays a list... + +\subsection{ALF Tools} +\label{alf:tools} +ALF uses a set of tools (or plugins) to assist in waveform and component +development. +To see a list of available tools, display a waveform and right-click on one +of the ports: +\begin{center} +\includegraphics[scale=0.35]{figures/alf/alf_ossie_demo_tools_list.png} +\end{center} + +\subsubsection{The Plot Tool} +\label{alf:tools:plot} +Right click on an existing {\it uses} port on the graphical interface and select +``Plot'' in order to plot data. The data must be either of type +{\tt complexShort} or type {\tt complexFloat} for this tool. +\begin{center} +\includegraphics[width=6cm]{figures/alf/alf_channel_demo_plot_spectrum.png}\,\, +\includegraphics[width=6cm]{figures/alf/alf_channel_demo_plot_IQ.png} +\end{center} + +\subsubsection{The write\_to\_file Tool} +\label{alf:tools:writetofile} +In order to write data to a file, right click on an existing {\it uses} port and +select ``write\_to\_file.'' In the write to file window you may specify where +the data will be written. Click on the ``Write Packet'' button to write the +last incoming packet to file. + +\subsubsection{The Arbitrary Waveform Generator} +\label{alf:tools:awg} +To activate the Arbitrary Waveform Generator (AWG), click on an existing +provides port and select ``AWG.'' Either select a pre-existing signal type from the drop +down menu (e.g., ``random''), or select ``File'' in order to specify a file to +read data from. The data will be sent when the ``Push Packet'' button is +pressed. The data being sent will be of type {\tt complexShort}. + +\subsubsection{The Speaker Tool} +\label{alf:tools:speaker} +To activate the speaker tool, click on an existing {\it uses} port and select +``speaker.'' Audio should start playing automatically. The input to +this tool must be of type {\tt complexShort}. + +\subsubsection{The Timing Tool} +\label{alf:tools:timing} +The main toolbar of the ALF display contains buttons that allow you to toggle +the timing displays. In order to view the throughput of a port, right click on +the desired port and select ``Get Info.'' Note that the port must support +timing. This feature can be added when creating the component. Timing +support is available only for the custom\_ports and py\_comp component +generation options. Currently no documentation exists for the custom\_ports +option beyond the comments in the generated source code, so it is recommended +for advanced developers only. + +\subsubsection{The Connect Tool} +\label{alf:tools:connecttool} +On the main toolbar of the ALF display, to the right of the timing buttons, there +is a button to start the connect tool. To connect two ports, specify the {\it uses} +port on the left half of the connect tool display and specify the {\it provides} port +on the right side of the connect tool display. To specify a port, select the +appropriate waveform from the first drop-down menu. Once the waveform is +selected, the second drop-down menu will allow you to select a component. Once +the component is selected, select the name of the port you wish to connect in the drop-down men below the component selected. Once both the {\it uses} and {\it provides} port have been selected, press the ``Connect'' button. + +\subsubsection{The Automation Tool} +\label{alf:tools:automationtool} +The Automation Tool is a feature which allows aggregate waveforms to be built. Through the use of XML files, additional components can be added or +removed while the waveform is running. To start the tool, select the ``Connect Tool'' button on the main toolbar within ALF. This will display the +Connect Tool window, which at the bottom has a path to an automation file and a ``Load Automation File'' button. Double click on a waveform in the +Launch Waveform Applications panel in the main ALF window to start the waveform. Browse to the XML file and select`` Load Automation File.'' For example, to run the {\tt pass\_data\_waveform}, browse to {\tt /usr/lib/python2.5/site-packages/alf/config/example1.xml}, then select +``Load Automation File.'' + +This will bring up the Arbitrary Waveform Generator window. The AWG allows components to be added to the waveform through the Packet Headers box, and determines which kind of data will be sent to the components. In this example, the waveform has two consumers, labeled 1 and 2. These are components which can be installed and uninstalled through setting the appropriate packet headers. To send a packet to a consumer enter its number into the Packet Headers box, separated by commas. For example, to send two packets to consumer 1, and one to consumer 2, enter the following: +\begin{lstlisting}[] +1, 1, 2 +\end{lstlisting} + +To uninstall a consumer, enter a negative sign before the consumer number. For example, to send three packets to consumer 1 and then uninstall it, enter: +\begin{lstlisting}[] +1, 1, 1, -1 +\end{lstlisting} + +By selecting Push Packet at the bottom, a single packet will be pushed to the corresponding consumer listed in the Packet Headers box. Each time the button is selected, it will advance to the next consumer listed and when it reaches the end of the list it will loop back to the beginning. Selecting the Start button sends the sequence continually until the Stop button is selected. + +\subsubsection{Automation XML File} +\label{alf:tools:automationxmlfile} +The Automation Tool determines which components are available to be installed. The XML file lists producers and consumers, which provide and consume packets, respectively. The XML file also defines the names of the producers and consumers, what their number designation is, when they are installed, which waveform they are assigned to, the name of the component and the input or output port. For example, in {\tt example1.xml}: +\begin{lstlisting}[] + + My first consumer +
1
+ True + pass_data_waveform + pass_data + cshort_in +\end{lstlisting} +The name of the consumer is ``My first consumer'' and it is designated 1, which means to send a packet to the consumer using the AWG the number 1 +must be entered in the Packet Headers text box. The consumer is set to be installed at start up, denoted by the install\_at\_startup tag. If this was +set as False, the consumer would only be installed when the first packet is pushed to it. The component is {\tt pass\_data}, and the input port is +defined as {\tt cshort\_in}. + + + + + Index: /documentation/ossie/user-guide-0.8.1/Introduction.tex =================================================================== --- /documentation/ossie/user-guide-0.8.1/Introduction.tex (revision 9972) +++ /documentation/ossie/user-guide-0.8.1/Introduction.tex (revision 9972) @@ -0,0 +1,86 @@ +% ------------------------------------------------------------------ +% +% TITLE: Introduction +% AUTHORS: +% CREATED: +% REVISED: +% URL: http://ossie.wireless.vt.edu/ +% +% ------------------------------------------------------------------ + +\section{Introduction} +\label{section:introduction} + +\subsection{About this Guide} +\label{section:introduction:about} +The aim of the \href{http://www.mprg.org}{MPRG}'s Open Source SCA +Implementation::Embedded (OSSIE) project is to provide an open source framework +for testing the behavior of SDR waveforms and platforms. This software can help +achieve a better understanding of software-defined radio and its trade-offs for +educational and commercial purposes. This user guide is meant to be a +comprehensive introductory and reference source for users of the OSSIE framework +and tools, as well as serve as a useful information source for developers. In +the guide, we attempt to assume only general computer knowledge and explain how +things work along the way. Additionally, this guide is an evolving document. If +you have any suggestions for improving it, please submit them to the mailing +list (see Section~\ref{section:mailinglists}, Trac (see +Section~\ref{section:trac}) or \href{mailto:cov@vt.edu}{email the maintainer} directly. + +\subsection{Further Help} +\label{section:introduction:help} +There are several ways to obtain help and further information. The +online wiki, the Trac bug tracking tickets, the mailing lists and the IRC +channel are available to you during moments of breakage, confusion, and +inspiration. + +\subsubsection{Wiki} +\label{section:wiki} +A wiki is a collaborative website tool. It allows many users to work together +to write and revise web pages. Our wiki contains news, documentation +and other information. You can visit it at \\ +\href{http://ossie.wireless.vt.edu/trac/wiki}{http://ossie.wireless.vt.edu/trac/wiki}. + +\subsubsection{Mailing Lists} +\label{section:mailinglists} +We maintain two public mailing lists for OSSIE. {\em ossie-discuss} is for +general help and discussion. {\em ossie-dev} is meant for more technical +discussion and development-related traffic. Both lists can be subscribed to by sending a +message to \href{mailto:listserv@listserv.vt.edu}{listserv@listserv.vt.edu} +with the following in the message body, replacing the information in angle +brackets with your appropriate information. + +\begin{lstlisting}[] + subscribe +\end{lstlisting} + +To send a message of all subscribers to the list, address it to +\href{mailto:ossie-discuss@listserv.vt.edu}{ossie-discuss@listserv.vt.edu} or +\href{mailto:ossie-dev@listserv.vt.edu}{ossie-dev@listserv.vt.edu}, as +appropriate. + +\subsubsection{Trac Bug Tracking System} +\label{section:trac} +The \href{http://trac.edgewall.org/}{Trac software} provides a web-based +interface to our bug tracking database. Reporting previously unreported bugs +is extremely helpful to the developers, allowing you to inform them of problems +not encountered during their testing. Bug trackers are also good places to +search for known problems and work-arounds. You will need to register for an +account on the website and log in before being allowed to submit new bugs. Visit +\href{http://ossie.wireless.vt.edu/trac/newticket}{http://ossie.wireless.vt.edu/trac/newticket} +to initiate the bug reporting process. Please be sure to tag the bug with version +\ossieversion. We will strive to squash all bugs as soon as possible and incorporate +usability and feature improvement suggestions into an appropriate future +release. If you're interested in crafting very helpful bug reports, +consider reading Simon Tatham's essay on the topic~\cite{writingbugreports:web}. + +\subsubsection{The \#ossie IRC Channel} +\label{section:irc} +Several OSSIE team members idle in an Internet Relay Chat to aid those interested in real-time communication. +Our channel, +\href{irc://irc.freenode.net/\#ossie}{\#ossie}, is on the +\href{http://freenode.net/}{Freenode network}. To visit it, try clicking on the +channel name in the previous sentence or fire up your favorite IRC client, log +onto the Freenode servers and join the \#ossie channel. If you have never used +IRC before, irchelp.org's +\href{http://www.irchelp.org/irchelp/irctutorial.html}{IRC Tutorial} is a good +starting point. Index: /documentation/ossie/user-guide-0.8.1/WaveformWorkshop.tex =================================================================== --- /documentation/ossie/user-guide-0.8.1/WaveformWorkshop.tex (revision 9972) +++ /documentation/ossie/user-guide-0.8.1/WaveformWorkshop.tex (revision 9972) @@ -0,0 +1,62 @@ +% ------------------------------------------------------------------ +% +% TITLE: Waveform Workshop +% AUTHORS: M. Carrick +% CREATED: +% REVISED: +% URL: +% +% ------------------------------------------------------------------ + +\section{Waveform Workshop} +\label{section:wavework} +The Waveform Workshop is the collection of development and debugging tools associated with +the OSSIE Core Framework. The Waveform Workshop is comprised of OSSIE Eclipse Feature +(Section \ref{section:oef}), OSSIE Waveform Developer (Section \ref{section:owd}), +ALF Graphical Debugging (Section \ref{section:alf}), and WaveDash (Section \ref{section:wavedash}). + +\subsection{OSSIE Eclipse Feature} +\label{section:WWoef} +OEF is a development tool and it provides the ability to create signal processing components +which the core framework can run, as well as the ability to connect multiple components +together to create a waveform. + +OEF is an Eclipse plug-in and requires the installation of Java and Eclipse to run. + +\begin{center} +\includegraphics[scale=0.3]{figures/oef/oef_component_editor.png} +\end{center} + +\subsection{OSSIE Waveform Developer} +\label{section:WWowd} +OWD is a development tool and it provides the same capabilities of OEF, however the application is standalone and only +requires the installation of python to run. + +\begin{center} +\includegraphics[scale=0.4]{figures/owd/owd_my_ossie_demo_complete.png} +\end{center} + + +\subsection{ALF Graphical Debugging} +\label{section:WWalf} +ALF is a debugging tool which allows waveforms to be debugged visually. It provides the +capability to run waveforms and view the spectrum and the I/Q plot at the input or output of +any component in a running waveform. + +\begin{center} +\includegraphics[scale=0.25]{figures/alf/alf_ossie_demo_tools_list.png} +\end{center} + +\subsection{WaveDash} +\label{section:WWwd} +WaveDash is a GUI application to interactively configure component properties +of SDR waveforms. The GUI can further be customized to show or hide component +and their properties on per waveform basis. + +\begin{center} +\includegraphics[scale=1.0]{figures/wavedash/10_property_context_menu.png} +\end{center} + + + + Index: /documentation/ossie/user-guide-0.8.1/HelpingWithDevelopment.tex =================================================================== --- /documentation/ossie/user-guide-0.8.1/HelpingWithDevelopment.tex (revision 9972) +++ /documentation/ossie/user-guide-0.8.1/HelpingWithDevelopment.tex (revision 9972) @@ -0,0 +1,34 @@ +% ------------------------------------------------------------------ +% +% TITLE: Helping with OSSIE Development +% AUTHORS: +% CREATED: +% REVISED: +% URL: http://ossie.wireless.vt.edu/ +% +% ------------------------------------------------------------------ +\section{Helping With Development} +\label{section:helpingwithdevelopment} +OSSIE is an open source project and we encourage everyone interested to +contribute to the project. + +\subsection{Giving Feedback and Submitting Bugs} +The {\it ossie-discuss} mailing list and the \#ossie IRC channel on Freenode are +probably the best methods of discussing and collaboratively solving end-user problems. +For development-oriented issues, Trac tickets and the {\it ossie-dev} mailing +list are probably best. See Section ~\ref{section:irc} for more information on +the IRC channel and Section ~\ref{section:mailinglists} for details on the +mailing lists. + +\subsection{Contributing Code} +Contributions are heartily welcomed. The best way to get to know the developers +and really get involved is submit patches that fix bugs or add features. Patches can generally be sent to us through Trac or the mailing +list. Write access to the subversion repository can be given to contributors +who have proved their reliability. + +In order to make sure OSSIE stays open, we have licensed the source code under +the GNU General Public License Version 2 and the Lesser General Public License. +Contributions to the project must be made under these licenses. Also, the +preferred coding style is that devised for the Linux +kernel~\cite{linuxkernelcodingstyle:web}. See~\cite{gnugpl:web, gnuglpl:web} for +more information about the licenses. Index: /documentation/ossie/user-guide-0.8.1/OEFGuide.tex =================================================================== --- /documentation/ossie/user-guide-0.8.1/OEFGuide.tex (revision 9972) +++ /documentation/ossie/user-guide-0.8.1/OEFGuide.tex (revision 9972) @@ -0,0 +1,417 @@ +% ------------------------------------------------------------------ +% +% TITLE: OSSIE Eclipse Feature Guide +% AUTHORS: M. Carrick, C. Dietrich +% CREATED: +% REVISED: +% URL: +% +% ------------------------------------------------------------------ + +\section{OSSIE Eclipse Feature} +\label{section:oef} +The OSSIE Eclipse Feature (OEF) is an interface for working with OSSIE tools +and the core framework. OEF is a drag and drop interface for creating +waveforms, as well as creating components and interfacing with the OSSIE +core framework. + +\subsection{Creating a New Waveform from Existing Components} +\label{section:oef:newwaveform} +To start Eclipse on the Fedora 9 VMware Image, open a terminal and enter the following command: +\begin{lstlisting}[] + $ /home/ossie/ossie/src/eclipse/eclipse +\end{lstlisting} + +The main window will appear: + +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_blank_oef.png} +\end{center} + +As an example, {\tt ossie\_demo} will be recreated using OEF. On the toolbar, +start by selecting File : New : OSSIE Waveform. This will bring up the New +OSSIE Waveform Project window. Enter ossie\_demo\_2 for the Project Name and +keep Use default box selected. Select Finish. +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_new_waveform.png} +\end{center} + +There are two problems to be aware of when naming a waveform. The +first is to remove all spaces from a waveform name or replace them with +an underscore. The second problem is waveforms cannot start with the text +AM\_. This prefix is interpreted as an automake macro and will prevent +the project from building. + +This window displays three panels: Available Resources, Waveform, and Platform. +Available resources lists all of the available components, devices, and +nodes that a waveform can use. The Waveform panel shows the waveform being +built, and the Platform panel shows how the resources are deployed. + +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_window_panels.png} +\end{center} + +\subsubsection{Adding Components to the Waveform} +\label{section:oef:addingcomponents} +From the Available Resources panel, under Components locate the TxDemo +component and drag it into the Waveform panel. Do the same for the +ChannelDemo and RxDemo components. The Waveform Panel now shows the three +components which will make up the logical and signal processing blocks of +the waveform. + +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_added_components.png} +\end{center} + +\subsubsection{Connecting Components} +\label{section:oef:connectingcomponents} +Connect the components by first selecting the arrow next to each +component name in the Waveform panel. This will display all of the +provides and uses ports for each component. Under TxDemo, click and +drag the symbols\_out port to the samples\_in port under ChannelDemo. +The puzzle pieces should connect next to the port names, denoting a +connection has been made. Connect samples\_out under ChannelDemo to +symbols\_in under RxDemo to complete all of the connections. + +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_connect_components.png} +\end{center} + +\subsubsection{Setting the Assembly Controller} +\label{section:oef:setassemblycontroller} +After all of the connections have been made, the assembly controller +must be defined. Right click on TxDemo and select Set Assembly +Controller. The icon for the component will then turn dark blue indicating +it is the Assembly Controller. + +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_set_assembly_controller.png} +\end{center} + +\subsubsection{Editing Component Properties} +\label{section:oef:editingproperties} +It is possible to change properties of components using OEF. Right +click on ChannelDemo in the Waveform panel and select Edit Component +Properties. Two properties are displayed, noise\_std\_dev and +phase\_offset. To change the value of either, click on the right box +under the label Value and enter a new value and select OK. Properties +of other components can be changed using this method, however the +properties that are available depend on the component. + +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_edit_properties.png} +\end{center} + +\subsubsection{Deploying Components to a Node} +\label{section:oef:deploytonode} +Now the platform must be defined. In the Available Resources panel, +under Nodes select default\_GPP\_node and drag it into the Platform +panel. Click on the arrow next to the name to display the GPP device. +The waveform will run on the GPP of the local machine, so all of the +components must be deployed to this device. In the Waveform panel, +select TxDemo and drag it onto the GPP device. Click the arrow next +to the GPP device to show that TxDemo has been deployed to it. Repeat +the procedure for ChannelDemo and RxDemo. + +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_deploy_to_node.png} +\end{center} + +The waveform should be completely defined and ready to be run. Save +the waveform by pressing CTRL+S or File : Save, which will also +compile and install it to the {\tt /sdr/waveforms/} directory. + +\subsection{Creating a New Component} +\label{section:oef:createcomponent} +This section will walk through the steps required to build a new +component from scratch. To generate a new component, on the +toolbar within OEF select File : New : OSSIE Component. Enter +amplifier\_test for the Project Name, keep the Use default check box +selected and select Finish. + +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_new_component.png} +\end{center} + +There are two problems to be aware of when naming a component. The +first is to remove all spaces from a waveform name or replace them with +an underscore. The second problem is waveforms cannot start with the text +AM\_. This prefix is interpreted as an automake macro and will prevent +the project from building. + + +This will bring up the Component Editor workspace which has four main +panels: Description, Generation Options, Ports, and Properties. The +Description panel is where the developer enters a basic description of +the component. The Generation Options panel defines the type of ports to +be used and if Timing Port Support and ACE Support are enabled. The Ports +panel allows for the addition and removal of ports for the component. The +Properties panel allows for the addition and removal of editable properties +for the component. + +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_component_editor.png} +\end{center} + +\subsubsection{Adding Ports to the Component} +\label{section:oef:addingports} +To add a port to the component, select Add in the Ports panel. Things +brings up the Add Port window, where the name, port type, and interface +is defined. Enter {\tt dataIn} as the Port Name, select Provides as the +Port Type, and select Standard Interfaces : complexShort as the interface. +\footnote{Within the SCA, input and output ports are renamed to provides +and uses. Depending on how the framework is implemented, the input can +be either named as a provides or a uses. The method that OSSIE uses +implements input ports as provides, and output ports as uses.} Select OK +to add the port. + +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_port_information.png} +\end{center} + +Select Add again, and enter dataOut as the Port Name, Uses as the Port +Type and Standard Interfaces : complexShort as the Interface. Select OK +to add the port. OEF should now look like the following: + +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_after_ports.png} +\end{center} + +\subsubsection{Adding Properties to the Component} +\label{section:oef:addprops} +A property, the gain, will be added to the component so it can be set by +a user when building a waveform. Add the property by selecting Add in the +Properties panel. This will bring up the Property Editor window where +various parameters can be set for the property. For this example, enter +gain for the Name, ``Amplifier gain'' for the Description and select Add +Property to add it to the component. + +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_define_property.png} +\end{center} + +Now the default value for the gain must be entered. Click on the clear blank +text box under Default value in the Properties panel, and enter 1. + +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_default_value.png} +\end{center} + +To finish the component, a description must be entered and the source code +must be generated. Enter a description, and in the Generation Options panel +ensure that basic\_ports is selected, and Timing Port Support and ACE Support +are both deselected. Before generating the component, OEF should look like +the following image: + +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_component_final.png} +\end{center} + +\subsubsection{Generating the Source Code} +\label{section:oef:generatesourcecode} +On the OEF toolbar, select OSSIE : Generate Component. This generates all of +the files for the component in the local eclipse workspace directory. + +Generating the component will produce multiple files along with the source code. +\begin{enumerate} +\item {\tt configure.ac}: This is the script that autoconf uses to generate +the configure file. It checks for dependencies such as which compiler to use, +as well as the presence of OSSIE libraries. +\item {\tt Makefile.am}: This is the script that automake uses to generate +the Makefile. It includes all the source files for the component. +\item {\tt reconf}: This is a script to run the automake tools. +\item {\tt component\_name.h}: Component class header file. +\item {\tt component\_name.cpp}: Component class implementation definition. +\item {\tt main.cpp}: Contains the mandatory {\tt int main()} definition. +\item {\tt component\_name.prf.xml}: Component property file. +\item {\tt component\_name.scd.xml}: Software component descriptor. +\item {\tt component\_name.spd.xml}: Software package descriptor. +\item {\tt documentation.txt}: File for documenting your component. +\item {\tt Doxyfile}: Doxygen file for generating documentation. +\end{enumerate} +Additional files are generated when using the {\tt pyi\_comp} option: +\begin{enumerate} +\item {\tt component\_name.py}: Python file with port implementations. +\item {\tt WorkModule.py}: Python file where processing is done. +\item {\tt setup.py}: Install script used to copy Python and XML files into the +appropriate subdirectories under {\tt /sdr} once the component is edited to +provide functionality. This is executed by typing {\tt python setup.py install}. +\end{enumerate} + +At this point the signal processing or logical function of the component must be +defined. The process for doing so is different depending on whether the component +is written in C++ or python. + +\subsubsection{Editing C++ Components} +\label{section:oef:editingccomponent} +In this example, by selecting {\tt basic\_ports} the component was generated as +a C++ component. To edit the component, open {\tt component\_name.cpp} and find +the {\tt ProcessData} function. +\begin{lstlisting}[] +$ cd /path/to/OEF/workspace/component_name/ +$ nano -w component_name.cpp +\end{lstlisting} + +Within the function, there will be a {\tt while} loop and inside of it will be +a line: +\begin{lstlisting}[] +/*insert code here to do work*/ +\end{lstlisting} +This is where the signal processing function should be implemented. The property +that was generated, {\tt gain} will be available in the source code initially as +{\tt simplei\_0\_value}. Reassign this to a new variable named {\tt gain} in the +{\tt configure} function in the same file. + +\subsubsection{Editing Python Components} +\label{section:oef:editpythoncomponents} +Generated component template code must be modified to +process data. The instructions here apply to a very basic Python component with +one {\it uses} and one {\it provides} port and no properties. Property values +can be used in the processing operations, but this will be the subject of a +future exercise. + +All data coming into a {\it provides} port will be loaded into the +WorkModule buffer. The data going into this buffer will be loaded +into variables called I and Q. See the generated WorkModule.py and +look for: +\begin{lstlisting}[] + I = new_data[0] + Q = new_data[1] +\end{lstlisting} +This implies that if you try to run a component that is getting real +data only, Q should be empty, and this may even cause an error. There are +comments in various parts of the python files describing how to adjust your code +appropriately. + +The next two lines initialize two arrays to store your new data: +\begin{lstlisting}[] + newI = [0 for x in range(len(I)))] + newQ = [0 for x in range(len(Q)))] +\end{lstlisting} +%TODO: Make listings highlighted +Following these lines are comments with an example of how to +process data. If you uncomment the 3-line example, your +component will pass the data received by the {\it provides} (input) port to the +{\it uses} (output) port, assuming you have one {\it uses} port of type {\tt +complexShort} and one {\it provides} port, also of type {\tt complexShort}. +Code can be added to process the data. + +The next set of lines following the comment ``{\tt \# Output the new data},'' +will send the {\tt newI} and {\tt newQ} vectors to all of your output ports. + +\subsubsection{Editing the SPD File} + +You will need to edit {\tt MyComponent.spd.xml} before your Python +component will work properly. Find the XML tag below the tag {\tt }. By default the next tag is: +\begin{lstlisting}[] + } +\end{lstlisting} +This needs to be changed to: +\begin{lstlisting}[] + +\end{lstlisting} + +\subsubsection{Making Sure Files are Executable} + +After you have installed the component (see below), you will need to make sure +that you have permission to execute the Python files. To do this, navigate to +{\tt /sdr/bin/MyComponent} and type: +\begin{lstlisting}[] + $ chmod +x *.py +\end{lstlisting} + +\subsubsection{Installing a Component} +\label{section:oef:installcomponent} +After the component has been edited, it must be compiled and installed to +{\tt /sdr}. To do this, move into the component's workspace directory and run +the automake tools. +\begin{lstlisting}[] +$ cd /path/to/eclipse/workspace/component_name/ +$ ./reconf +$ ./configure +$ make +$ make install +\end{lstlisting} + +If the commands execute successfully, the component will be installed to +{\tt /sdr} and it will be possible to use the component in a waveform. Start +a new waveform in OEF to verify that the component has been installed correctly. + +\subsection{Importing and Exporting Eclipse Projects} +\label{section:oef:importexportprojects} + +Projects developed within Eclipse can be saved to be used as a backup, or to +transport to another development platform. This is done by exporting and importing +projects. + +\subsubsection{Exporting a Project From Eclipse} +\label{section:oef:exportproject} + +To export a project, from the Eclipse toolbar select File : Export. Under the +General folder, select Archive File and click Next. + +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_export_type.png} +\end{center} + +In the next display, in the upper left panel select the boxes next to projects that +will be saved. Multiple projects can be saved at one time by selecting more than one +project. In the upper right panel, files being saved will have a check mark next to +their name. By default, when a project is selected all of the files within the project +will be saved. It is recommended to save all of the files however if some files are +not needed, they may be deselected by removing the check mark next to their name. + +Select Browse to choose a location for the archive to be saved, enter a +name for the archive, and select OK. The display should look like the following image: + +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_archive_interface.png} +\end{center} + +Select Finish to save the archive. + +\subsubsection{Importing Project in Eclipse} +\label{section:oef:importproject} + +To import a project, from the Eclipse toolbar select File : Import. Under the General +folder, select Existing Projects Into Workspace and click Next. + +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_import_type.png} +\end{center} + +Select the radio button next to Select archive file, and click Browse. Locate the archive +and select OK. + +\begin{center} +\includegraphics[scale=0.4]{figures/oef/oef_import_project.png} +\end{center} + +The projects saved within the archive file will now be displayed in the Projects pane. +To import a project, ensure that the box next to the project name has been selected. +Although multiple projects may have been archived, it is not necessary to import all +of them. Select Finish to import the project. The project files will now be displayed +in the left panel of the Eclipse GUI, and the project has been imported. + + +\subsection{Additional OEF Instruction} +\label{section:oef:additionaloef} +For more information on using OEF and other OSSIE tools, please visit the +OSSIE website at \href{http://ossie.wireless.vt.edu/}{http://ossie.wireless.vt.edu} +and select Getting Started : Labs. + + + + + + + + + + + + + + + Index: /documentation/ossie/user-guide-0.8.1/Troubleshooting.tex =================================================================== --- /documentation/ossie/user-guide-0.8.1/Troubleshooting.tex (revision 9972) +++ /documentation/ossie/user-guide-0.8.1/Troubleshooting.tex (revision 9972) @@ -0,0 +1,61 @@ +% ------------------------------------------------------------------ +% +% TITLE: OSSIE Troubleshooting Guide +% AUTHORS: Joseph Gaeddert +% CREATED: +% REVISED: +% URL: http://ossie.wireless.vt.edu/ +% +% ------------------------------------------------------------------ +\section{Troubleshooting} +\label{section:troubleshooting} +This section includes several common problems you may encounter when +installing and running OSSIE. It is by no means complete. +If you cannot find your problem here, please feel free to contact the team +(refer to Section~\ref{section:introduction:help}) + +\subsection{nodeBooter Throws an Exception} +\label{section:troubleshooting:nodebooter1} +When I try to start {\tt nodeBooter}, I get this output: +\begin{lstlisting}[] + $ nodeBooter -D -d dev/nodes/default_GPP_node/DeviceManager.dcd.xml + NB: Starting Domain Manager + Fatal: An exception occurred! Type:RuntimeException, Message:The primary + document entity could not be opened. + Id=/home/ossieuser/domain/DomainManager.dmd.xml + PublicId : + SystemId : + Line number : 0 + Column number : 0 + terminate called after throwing an instance of 'int' + Aborted +\end{lstlisting} +{\bf Solution: } You need to run {\tt nodeBooter} from the {\tt /sdr} directory. + +\subsection{nodeBooter Fails to Resolve `TRANSIENT' NameService} +\label{section:troubleshooting:nodebooter2} +When I try to start {\tt nodeBooter} I get this output: +\begin{lstlisting}[] + $ nodeBooter -D -d dev/nodes/default_GPP_node/DeviceManager.dcd.xml + Failed to resolve NameService: TRANSIENT + terminate called after throwing an instance of 'CORBA::TRANSIENT' + Aborted +\end{lstlisting} +{\bf Solution: } You need to start the naming service. If you installed omniORB +via your system's package manager, +{\tt omniNames} will start automatically when you restart your machine, if the service is configured properly. Refer to +Appendix~\ref{appendix:services} for instructions on managing services under Fedore Core 9. You can +manually start the {\tt omniNames} by creating and running the shell script +described in Appendix~\ref{appendix:omninamessh}. + +\subsection{OWD Component Editor Does Not Allow me to Select the Device} +\label{section:troubleshooting:owdselectdevice} +I am trying to edit a component to assign it to a device. I have selected the +{\tt default\_XXX\_node} under ``Waveform Deployment Settings'' but nothing +exists under the ``Device'' spinbox. + +{\bf Solution: } This is a bug in OWD. You have probably not +selected {\tt default\_XXX\_node} with the mouse, even though it is visible on the screen. +Click on the ``Node'' spinbox again and re-select {\tt default\_XXX\_node}, +making sure that you actually click on the text. Now when you click on the +``Device'' spinbox you should see the device you want. Index: /documentation/ossie/user-guide-0.8.1/Abbreviations.tex =================================================================== --- /documentation/ossie/user-guide-0.8.1/Abbreviations.tex (revision 9972) +++ /documentation/ossie/user-guide-0.8.1/Abbreviations.tex (revision 9972) @@ -0,0 +1,14 @@ +\section{List of Abbreviations} +\label{chapter:abbreviations} + +\begin{description} +\item[ALF] A waveform application visualization and debugging environment for OSSIE. The name was initially derived from the "Alien Life Form" television series and character. +\item[DAS] Device Assignment Sequence +\item[JTRS] Joint Tactical Radio System +\item[OSSIE] Open-source SCA Implementation::Embedded +\item[OWD] OSSIE Waveform Developer +\item[QPSK] Quadrature phase-shift keying +\item[SAD] Software Assembly Descriptor +\item[SCA] Software Communications Architecture +\end{description} + Index: /documentation/ossie/user-guide-0.8.1/UserGuide.bib =================================================================== --- /documentation/ossie/user-guide-0.8.1/UserGuide.bib (revision 9972) +++ /documentation/ossie/user-guide-0.8.1/UserGuide.bib (revision 9972) @@ -0,0 +1,87 @@ + + +@MISC{cxxtest:web, + title = {{CXXTest}}, + howpublished = "\url{http://cxxtest.sourceforge.net/}" +} + +@MISC{linuxkernelcodingstyle:web, + title = {{Linux kernel coding style}}, + howpublished = "\url{http://pantransit.reptiles.org/prog/CodingStyle.html}" +} + +@MISC{doxygen:web, + title = {{Doxygen}}, + howpublished = "\url{http://www.stack.nl/~dimitri/doxygen/}" +} + +@MISC{ieee1012:web, + howpublished = "\url{http://standards.ieee.org/reading/ieee/std_public/description/se/1012-1998_desc.html}" +} + +@MISC{autoconf:web, + title = {{Autoconf}}, + howpublished = "\url{http://www.gnu.org/software/autoconf/}" +} + +@MISC{automake:web, + title = {{Automake}}, + howpublished = "\url{http://www.gnu.org/software/automake/}" +} + +@MISC{vmware:web, + title = {{VMWare Player User Manual}}, + howpublished = "\url{http://www.vmware.com/pdf/vmware_player200.pdf}" +} + +@MISC{irctutorial:web, + title = {{IRC Tutorial}}, + howpublished = "\url{http://www.irchelp.org/irchelp/irctutorial.html}" +} + +@MISC{gnugpl:web, + title = {{GNU General Public License}}, + howpublished = "\url{http://www.gnu.org/licenses/old-licenses/gpl-2.0.html#TOC1}" +} + +@MISC{jtrssca:web, + title = {{The JTRS Software Communications Architecture}}, + howpublished = "\url{http://sca.jpeojtrs.mil/}" +} + +@MISC{gnuglpl:web, + title = {{GNU Lesser General Public License}}, + howpublished = "\url{http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html#TOC1}" +} + +@MISC{writingbugreports:web, + title = {{How to Report Bugs Effectively}}, + author = {Simon Tatham}, + howpublished = "\url{http://www.chiark.greenend.org.uk/~sgtatham/bugs.html}" +} + +@BOOK{Bard:2007, + author = {{John Bard and Vincent J Kovarik}}, + title = {{Software Defined Radio: The Software Communications Architecture}}, + publisher = {Wiley}, + year = {2007}, + address = {Hoboken, NJ} +} + +@ARTICLE{Buracchini:2000, + author = {{E. Buracchini}}, + title = {{The Software Radio Concept}}, + journal = {{IEEE Commun. Mag.}}, + volume = {38}, + number ={9}, + pages = {138--143}, + year = {2000}, +} + +@BOOK{Reed:2002, + author = {{J. H. Reed}}, + title = {{Software Radio: a Modern Approach to Radio Engineering}}, + address = {Upper Saddle River}, + publisher = {Prentice Hall}, + year = {2002}, +} Index: /documentation/ossie/user-guide-0.8.1/UserGuide.tex =================================================================== --- /documentation/ossie/user-guide-0.8.1/UserGuide.tex (revision 9972) +++ /documentation/ossie/user-guide-0.8.1/UserGuide.tex (revision 9972) @@ -0,0 +1,466 @@ +% ------------------------------------------------------------------ +% +% TITLE: OSSIE Installation and User Guide 0.8.1 +% 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: +% 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.1} + +%@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 \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 + +September, 2009 + + +\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} + +% ------------------- 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.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. +\end{enmerate} + +\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} Index: /documentation/ossie/user-guide-0.8.1/Bugs.tex =================================================================== --- /documentation/ossie/user-guide-0.8.1/Bugs.tex (revision 9972) +++ /documentation/ossie/user-guide-0.8.1/Bugs.tex (revision 9972) @@ -0,0 +1,68 @@ +% ------------------------------------------------------------------ +% +% TITLE: OSSIE Known Bugs +% AUTHORS: +% CREATED: +% REVISED: +% URL: +% +% ------------------------------------------------------------------ + +\section{Known Bugs} +\label{section:bugs} + +\subsection{OSSIE Core Framework} +\label{section:bugs:ossiecf} +\begin{enumerate} +\item After running a waveform, {\tt nodeBooter} must be killed using +{\tt Ctrl-C} and does not exit gracefully. +\item Running {\tt wavLoader.py} results in two copies of each SAD file, for +example: +\begin{verbatim} + 1: //waveforms/ossie_demo/ossie_demo.sad.xml + 2: /DeviceManager/waveforms/ossie_demo/ossie_demo.sad.xml +\end{verbatim} +This is an artifact of the filesystem. +You should always choose the first one and ignore the second. +\end{enumerate} + +\subsection{OWD} +\label{section:bugs:owd} +\begin{enumerate} +\item Generating components with certain interfaces result in code that cannot +be compiled directly. OWD generates the source, but will display a warning in +the terminal: +\begin{verbatim} +Interfaces other than complex and real Short, Float, Char, long and Double are +not supported yet in the process data function generation!! + See writeProcessDataDeclaration in genStructure. +\end{verbatim} +\item When trying to assign a component to a device in the ``Waveform +Deployment Settings'' section in the OSSIE Component Editor window, if +the ``Node'' is not properly selected, no devices will appear in the spinbox. +\item When generating a waveform, the {\tt configure.ac} file includes tests +for source code instead of just installation. +\item After opening ComponentFrame from OWD for a new component, Python will +not quit when you quit OWD. +\end{enumerate} + +\subsection{ALF} +\label{section:bugs:alf} +\begin{enumerate} +\item Waveforms with more than about fifteen components will not display properly and are cut off from view. +\item Aside from components, the {\bf\sf Launch Components as Waveforms} pane +includes devices. NodeBooter doesn't seem to crash when trying to launch a device as a waveform, although an error appears in the nodeBooter window. +\item Pointing ALF to an IP address does not fully recognize the available components or available applications. We still need to implement support for the CF::FileSystem. +\end{enumerate} + +\subsection{OEF} +\label{section:bugs:oef} +\begin{enumerate} +\item OEF does not support generation of new node definitions. Currently, we still rely on OWD for that functionality. +\end{enumerate} + +\subsection{WaveDash} +\label{section:bugs:wavedash} +\begin{enumerate} +\item Display of dialog does not expand to support large words. +\end{enumerate} Index: /documentation/ossie/user-guide-0.8.1/Installation.tex =================================================================== --- /documentation/ossie/user-guide-0.8.1/Installation.tex (revision 9972) +++ /documentation/ossie/user-guide-0.8.1/Installation.tex (revision 9972) @@ -0,0 +1,619 @@ +% ------------------------------------------------------------------ +% +% TITLE: OSSIE 0.8.1 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: +% 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}. + +% NOTE: We lack yum install at the moment + +% For most users on Fedora systems, installing OSSIE and its dependencies via yum is the best +% route. The only reason not to install via yum is if you plan on doing active +% development \emph{on} OSSIE, and need access to the source code. Note that this +% does not include application/waveform developers who are developing \emph{with} +% OSSIE, as they do not need access to the OSSIE source code. + +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 via Yum} +% \label{section:installation:yum} + +% Note: At the time this guide was compiled, the latest version of OSSIE available by Yum was 0.7.0. Version 0.7.1 is expected to be available by Yum in late 2008 or early 2009. + +% \subsubsection{Add OSSIE Repository to Yum} +% \label{section:installation:yum:ossierepo} +% In order to install OSSIE via the YUM repository, you must first edit your `/etc/yum.conf' to +% add the OSSIE repository to the YUM search list. In this example, we use {\tt nano}, but you may use +% whatever editor you wish ({\tt vim}, {\tt emacs}, etc). Unless your nanorc has already been configured to not +% wrap lines, the `-w' flag is necessary to prevent {\tt nano} from adding line breaks to the file. +% \begin{lstlisting}[] +% $ su - +% # nano -w /etc/yum.conf +% \end{lstlisting} +% Add the following lines at the bottom of the file: +% \begin{lstlisting}[] +% [ossie-vt] +% name = OSSIE-VT +% baseurl=http://ossie.wireless.vt.edu/yum/ossie-vt/ +% gpgcheck=0 +% \end{lstlisting} +% Now update your system. This will refresh your yum package cache. It is also always smart to have +% a fully updated system before installing new software anyways. +% \begin{lstlisting}[] +% # yum update +% \end{lstlisting} +% +% \subsubsection{Install OSSIE} +% \label{section:installation:yum:installviayum} +% Now install OSSIE and its dependencies via yum by typing: +% \begin{lstlisting}[] +% # yum install ossie +% # exit +% \end{lstlisting} + +% Congratulations! You should now have a fully-operable OSSIE installation. + +\subsection{Installing OSSIE from Source} +\label{section:installation:source} + +\subsubsection{Notes on OSSIE Installation from Source} +\label{section:installation:source:notesonsource} +This section assumes that the user is familiar with basic +Linux commands such as {\tt cd} and {\tt ls}. +Commands run with root permissions are prefixed with {\tt \#}, while others +are prefixed with {\tt \$}. + +OSSIE depends on the following software packages: +\begin{itemize} +\item Boost - a C++ library of common mechanisms +\item omniORB - a CORBA implementation +\item omniORBpy - a Python interface for omniORB, necessary for the OSSIE tools and components +\item wxPython - a Python interface for the wxWidgets graphical library, used by the OSSIE tools +\item numpy - a Python numerical library used by the OSSIE tools +\end{itemize} + +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} + +% OSSIE \ossieversion\ is packaged with a convenient Python script called {\tt build.py} to automatically +% configure and build the packages necessary for the framework, tools, and other +% libraries. Use of this script is not mandatory, and you can manually compile and install all/part of +% OSSIE as you wish. + +\subsubsection{Installing Dependencies on Fedora} +\label{section:installation:source:dependencies:fedora} + On Fedora systems, the dependencies can be installed via {\tt yum}. +% +% First, add the OSSIE yum repository to your yum.conf. This is described in +% Section~\ref{section:installation:yum:ossierepo} +% +This is the entire dependency list, so some of these packages may already be installed. +\begin{lstlisting}[] +# yum -y install wxPython wxPython-devel numpy \ +rpm-build cabextract glibc-devel \ +python-devel openssl-devel gcc gcc-c++ libtool +\end{lstlisting} + +We recommend installing omniORB and omniORBpy from source. +\begin{lstlisting}[] + $ wget http://omniorb.sourceforge.net/releases/omniORB-4.1.4.tar.gz + $ wget http://omniorb.sourceforge.net/releases/omniORBpy-3.4.tar.gz + $ tar -xvf omniORB-4.1.4.tar.gz + $ tar -xvf omniORBpy-3.4.tar.gz + $ cd omniORB-4.1.4/ + $ mkdir build + $ cd build + $ ../configure + $ make + $ sudo make install + $ cd ../../omniORBpy-3.4/ + $ mkdir build + $ cd build + $ ./configure + $ make + $ sudo make install +\end{lstlisting} + +If you plan on using GNURadio 3.2 or higher, or the USRP2, as part of your work, then you will need to install Boost v1.35 or higher. +Currently, Fedora and Ubuntu do not ship with this version, so you will need to install it. +Whether you are using Fedora or Ubuntu, we recommend that you install Boost from source. Download Boost from +\href{http://sourceforge.net/projects/boost/files/boost/1.37.0/boost\_1\_37\_0.tar.bz2/download}{http://sourceforge.net/projects/boost/} and unpack {\tt boost\_1\_37\_0.tar.bz2}. +\begin{lstlisting}[] + $ wget http://sourceforge.net/projects/boost/files/boost/1.37.0/ \ + boost_1_37_0.tar.bz2/download + $ tar -xvf boost_1_37_0.tar.bz2 + $ cd boost_1_37_0/ + $ ./configure --prefix=/usr/ + $ make + $ sudo make install +\end{lstlisting} + +If you are using Fedora Core 10 or higher, you will need to download the RPM for the SDL library in order to user the JPEGVideoViewer component. +\begin{lstlisting}[] + $ wget http://www.libsdl.org/release/SDL-devel-1.2.13-1.i386.rpm + $ rpm -Ui SDL-devel-1.2.13-1.i386.rpm +\end{lstlisting} +% +% Now move onto Section~\ref{section:installation:source:dependencies:gnuradio} +% +\subsubsection{Installing Dependencies on Ubuntu} +\label{section:installation:dependencies:ubuntu} + +This is the entire dependency list, so some of these packages may already be installed. +Install all of the following packages: +\begin{lstlisting}[] +$ sudo aptitude install gcc build-essential +$ sudo aptitude -y install omniorb4 libomniorb4-dev omniidl4-python \ +omniorb4-nameserver python-omniorb2 libgtk2.0-dev freeglut3-dev \ +python-wxgtk2.8 python-wxversion python-wxtools python-numpy \ +python-numpy-ext python-numpy-dev g++ automake libtool subversion \ +python-dev fftw3-dev libcppunit-dev libboost-dev sdcc libusb-dev +libasound2-dev libsdl1.2-dev guile-1.8 libqt3-mt-dev swig \ +python-profiler automake1.9 python2.5-dev sdcc-nf guile-1.8-dev \ +libqt4-dev ccache python-opengl libgsl0-dev python-lxml \ +doxygen qt4-dev-tools libqwt5-qt4-dev libqwtplot3d-qt4-dev +\end{lstlisting} + +\subsubsection{Configure omniORB} +\label{section:installation:source:dependencies:configomni} +omniORB must be configured through the modification of a file. This file may be either \\ +{\tt /etc/omniORB.cfg} or {\tt /etc/omniORB4.cfg}, depending on the +version of the omniORB dependency. If the file is not found, copy +{\tt sample.cfg} from the omniORB-4.1.4 directory and rename it. +\begin{lstlisting}[] + $ cd omniORB-4.1.4 + # cp sample.cfg /etc/ + # mv /etc/sample.cfg /etc/omniORB.cfg +\end{lstlisting} +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}} + +At this time it is a good idea to restart your machine. + +\subsubsection{Installing Portions of GNU Radio} +\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 installing portions of GNU Radio. OSSIE provides support +for both the USRP and USRP2. If you would like to use the USRP2, then you will need to +install GNURadio v3.2; otherwise, GNURadio v3.1 will work fine. + +First, we must install the GNU Radio firmware that can communicate with the USRP. + +If you are using Fedora 11, or Fedora 10 or lower and would like to use GNURadio v3.1, then: +\begin{lstlisting}[] + # yum install usrp-devel +\end{lstlisting} + +If you are using Ubuntu, and would like to use GNURadio v3.1 then: +\begin{lstlisting}[] + $ sudo apt-get install usrp-firmware +\end{lstlisting} + +If you would like to use GNURadio v3.2, and do not have Fedora 11 installed, +then you must install from source: +\begin{lstlisting}[] + $ wget ftp://ftp.gnu.org/gnu/gnuradio/gnuradio-3.2.2.tar.gz + $ tar -xvf gnuradio-3.2.2.tar.gz + $ cd gnuradio-3.2.2/ + $ ./configure + $ make + $ sudo make install +\end{lstlisting} + +% First, GNU Radio's dependencies must be installed. If you are using Ubuntu and followed +% the instructions for installing the dependencies, skip down to checking out the source +% code from the GNU Radio Subversion repository. If you are installing on Fedora 9, +% proceed with the following directions. + +% Install the Engineering and Scientific packages as well as the Software Development +% packages as root entering the command: + +% \begin{lstlisting}[] +% # yum groupinstall "Engineering and Scientific" "Development Tools" +% \end{lstlisting} + +% Additional utilities such as the FFT library and the CPP Test Framework must also be +% installed. As root, enter the following command + +% \begin{lstlisting}[] +% # yum install fftw-devel cppunit-devel wxPython-devel libusb-devel \ +% guile boost-devel alsa-lib-devel numpy +% \end{lstlisting} + +% The Small Device C Compiler, SDCC, must be installed: + +% \begin{lstlisting}[] +% # yum install sdcc +% \end{lstlisting} + +% The path for the SDCC must be set. Open the .bashrc file and add the path to the end +% of the file. To open the file, enter the command: + +% \begin{lstlisting}[] +% $ vim ~/.bashrc +% \end{lstlisting} + +% Add the following path to the end of the file: +% \begin{lstlisting}[] +% export PATH=/usr/libexec/sdcc:$PATH +% \end{lstlisting} + +% At this point, all of the GNU Radio dependencies have been installed. Now, the GNU Radio +% software must be installed. + +% Download the GNU Radio source code by entering the command: +% \begin{lstlisting}[] +% $ svn co http://gnuradio.org/svn/gnuradio/branches/releases/3.1 gnuradio +% \end{lstlisting} + +% Move into the {\tt gnuradio} directory and start building the source code by entering the +% following commands: + +% \begin{lstlisting}[] +% $ cd gnuradio/ +% $ ./bootstrap +% $ ./configure --disable-all-components --enable-gnuradio-core \ +% --enable-usrp --enable-gr-usrp --enable-omnithread +% \end{lstlisting} + +% This sets up the install to only build resources for the USRP which OSSIE requires. +% Compile the source code by entering the command: + +% \begin{lstlisting}[] +% $ make +% \end{lstlisting} + +% Verify that the compile worked by running a check: + +% \begin{lstlisting}[] +% $ make check +% \end{lstlisting} + +% Install the portions of GNU Radio by running the following command as root: + +% \begin{lstlisting}[] +% # make install +% \end{lstlisting} + +% The libraries installed by GNU Radio need to be linked: + +% \begin{lstlisting}[] +% # /sbin/ldconfig +% \end{lstlisting} + +At this point, GNU Radio and its dependencies have been installed. Now setup the +proper permissions for the USRP. As root, create a group which will have access +to the USRP: + +\begin{lstlisting}[] + # /usr/sbin/groupadd usrp +\end{lstlisting} + +Add users to the group which need access to the USRP: + +\begin{lstlisting}[] + # /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}[] + # vim /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}[] + # 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.bz2}. +\begin{lstlisting}[] + $ wget http://ossie.wireless.vt.edu/download/tarballs/0.8.1/ \ + ossie-0.8.1.tar.bz2 + $ tar -xvjf ossie-0.8.1.tar.bz2 +\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}[] + # mkdir /sdr + # 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.1 + $ ./configure --prefix=/sdr --libdir=/usr/local/lib/ \ + --includedir=/usr/local/include/ --with-boost --with-boost-filesystem + $ make + $ sudo make install +\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 futher 'configure' options, use {\tt configure --help}. + +%\subsubsection{Using Installation Scripts} +%\label{section:installation:source:ossiecf:buildpy} + +%The included {\tt build.py} and {\tt setup.py} scripts automate the building and installation of +%the OSSIE packages. Because OSSIE is built as a set of dependent libraries it is +%necessary to build and install each one separately so that +%they can link properly. These scripts take care of that for you. + +%In order for the script to run uninterrupted, the {\tt sudo} command must be +%able to execute {\tt make install}. +%As root, edit the {\tt sudoers} file\footnote{By default the sudoers file must +%be edited with the {\tt visudo} command} +%\begin{lstlisting}[] +% # /usr/sbin/visudo +%\end{lstlisting} + +%At the end of the file, add the following line: +%\begin{lstlisting}[] +% ALL ALL = NOPASSWD: /usr/bin/make install +%\end{lstlisting} + +%Save and quit ({\tt :wq}). If you made an error, visudo will tell you. We +%recommend that you comment this line out by putting a pound character (`\#') in +%front of it once you have finished installing OSSIE. +%%TODO: Have a more secure (wheel group only?) method + +%The {\tt setup.py} script installs the tools used for component and waveform development. To install the tools, move into the {\tt tools} directory and run the {\tt setup.py} script as follows \\(optionally, use {\tt su -c ""} instead of {\tt sudo }): + +%\begin{lstlisting}[] +% $ cd /home/username/path_to_ossie/tools +% $ python setup.py build && sudo python setup.py install +%\end{lstlisting} + +%The {\tt build.py} script installs the core framework, components, devices and a few demonstration waveforms. This script should not be run as root. +%To install, first exit out of root, then move into the directory where the OSSIE \ossieversion\ tarball has been unpacked and run the script: + +%\begin{lstlisting}[] +% # exit +% $ cd /home/username/path_to_ossie/ +% $ python build.py +%\end{lstlisting} + +%Depending on the speed of your system this might take several minutes. You may +%be asked for a password during the first {\tt make install} command. Because we +%are using {\tt sudo}, this prompt is asking for your user password, not the +%root password. If successful, the prompt should say: +%\begin{lstlisting}[] +%********************************************************* + +% Complete installation of OSSIE 0.8.1 finished! + +%********************************************************* +%\end{lstlisting} + +\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}[] + # /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:oefinstall} +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. + +Fedora Core 9 comes with the Sun JDK pre-installed but older versions require manual installation. On other distributions it is advisable to use the +package manager to manage the installation, if possible. + +\subsubsection{Installing Java on Older Versions of Fedora} +\label{section:installation:javafedora} +Go to \href{http://java.sun.com/javase/downloads/index.jsp}{http://java.sun.com/javase/downloads/index.jsp} +and click Download next to JDK 6 Update 6. Choose Linux in the platform drop down menu, click the check-box +agreeing to the license agreement, and click continue. Download the Linux rpm in self extracting file, +{\tt jdk-6u6-linux-i586-rpm.bin}. + +Open a terminal and navigate to the file. As root, execute the following command: +\begin{lstlisting}[] + # sh jdk-u6-linux-i586-rpm.bin +\end{lstlisting} + +Create {\tt java.sh} in {\tt /etc/profile.d/} with the following contents: +\begin{lstlisting}[] + export JAVA_HOME="/usr/java/latest" + export JAVA_PATH="$JAVA_HOME" + export PATH="$PATH:$JAVA_HOME/bin" +\end{lstlisting} + +Log out and back in to allow the changes to update. + +\subsubsection{Installing Java on Ubuntu} +\label{section:installation:javaubuntu} +In a terminal, enter the following lines: +\begin{lstlisting}[] + $ sudo apt-get update + $ sudo apt-get install sun-java5-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 Software Updates}. +In the new window, select the ``Available Software" tab and click the ``Add Site" +button the right hand side. Enter the URL: {\tt http://ossie.wireless.vt.edu/eclipse/} +and select OK. The window will then add the URL, OSSIE, OSSIE Waveform Developer +Feature to the list of software to update. Place a check in the box next to OSSIE +Waveform Developer Feature and click Install. 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 a complete Fedora Core 9-based Linux system with all necessary +dependencies and a complete install of OSSIE \ossieversion\ 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 no fee 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. + + Index: /documentation/ossie/user-guide-0.8.1/WaveDash.tex =================================================================== --- /documentation/ossie/user-guide-0.8.1/WaveDash.tex (revision 9972) +++ /documentation/ossie/user-guide-0.8.1/WaveDash.tex (revision 9972) @@ -0,0 +1,136 @@ +% ------------------------------------------------------------------ +% +% TITLE: WaveDash +% AUTHORS: D. Seeralan, M. Carrick +% CREATED: +% REVISED: +% URL: +% +% ------------------------------------------------------------------ + +\section{WaveDash} +\label{section:wavedash} +Wavedash is an interactive configurable GUI used to work with OSSIE SDR +waveforms. Through this tool, users can install/uninstall or start/stop +waveforms and configure the component properties at run time. This eliminates +the need to restart or rebuild the waveform every time when component +properties need to be changed. Users can also customize the GUI to view only +the component and properties of their interest. Further, it also allows the +users to change the widget type of a property that makes the configuration +process more interactive. + +\subsection{Running Wavedash} +\label{section:RunningWavedash} +Wavedash is a part of OSSIE Tools and hence the tools setup should install +this application as well. Make sure that the naming service and nodeBooter are +running before starting Wavedash . To run Wavedash, open a terminal and type +\begin{lstlisting}[] + $ WAVEDASH + \end{lstlisting} +This should open the Wavedash initial window without any errors. +\begin{center} +\includegraphics[scale=1.0]{figures/wavedash/1_initial_window.png} +\end{center} + +\subsection{ Installing and Un-installing waveforms} +\label{section:InstallandUninstall} +The Waveforms menu in the menu bar will lists the SDR waveforms available in the +/sdr/dom/waveforms directory. To install a waveform, pull down the Waveform menu +and highlight the waveform to be installed. This should open a submenu where you +can choose to just Install the waveform or install and start the waveform.You can +also preview the waveform to view the waveform’s components, properties and +their default values. + +\begin{center} +\includegraphics[scale=1.0]{figures/wavedash/2_waveform_lists.png} +\end{center} + +Once a waveform is installed, it can be started, stopped or uninstalled by +using the appropriate buttons in the tool bar. +\subsection{Selecting a Waveform} +\label{section:selectwaveform} +From Ossie 0.8.0, Wavedash uses tabbed view to display the installed waveform +applications. Click on the appropriate tab which displays the waveform you +wish to control.The Component menu is updated each time when the tab is +switched. The operations such as Start,Stop and Uninstall operates on the +waveform application denoted by the active tab. The active tab displays the +component panels where in the user can change the component property values. +Except for a Slider control, changes to property values are applied only when +the presses ENTER or switches the focus to another property. If Slider is used +for a property, then the changes are applied to the waveform as and when the +slider value changes. + +\begin{center} +\includegraphics[scale=1.0]{figures/wavedash/5_waveform_selection.png} +\end{center} + +\subsection{ Refresh } +\label{section:Refresh} +Since waveforms can be installed or uninstalled from ALF also, Wavedash can be +refreshed to sync with the current state of waveforms running in the +nodeBooter. Click on the Refresh button in the toolbar to refresh. + +\subsection{GUI Customization} +\label{section:guicustomization} +\subsubsection{Show or Hide Components} +\label{section:showorhidecomponents} +Waveforms may contain different components of which only few may be used +frequently. In such case, users can select only the components they wish to +see in the application. The Components menu is updated whenever a waveform is +selection. Pull down the components menu and select/deselect the components +that you wish to show/hide. + +\begin{center} +\includegraphics[scale=1.0]{figures/wavedash/7_component_hidden.png} +\end{center} + +\subsubsection{Re-arrange components} +\label{section:rearrangecomponents} +Components can also be stacked differently from the default order. To +rearrange, right click on the component area and move it up or down using Move +Up/Move Down choice in that context menu. +\begin{center} +\includegraphics[scale=1.0]{figures/wavedash/8_component_movedown.png} +\end{center} + +\subsubsection{Show or Hide Properties} +\label{section:showorhideproperties} +Similar to components, properties of a component can also be customized. The +component box context menu has a submenu Properties which lists the properties +of a component. Select/Deselect the properties from the context menu to +show/hide the properties on the screen. +\begin{center} +\includegraphics[scale=1.0]{figures/wavedash/9_properties_hidden.png} +\end{center} + +\subsubsection{Change Property Widget} +\label{section:changepropertywidget} +Each property of a component has its own data type associated. The application +provides a default mapping of the property data type to a GUI widget. For e.g. +integer values are shown in a text box, short values are shown in a spin box, +etc
 However, user may change the widget for a property by right clicking on +the current widget and choose the alternate widget compatible to the property +datatype. The compatibility here refers to the right mapping between datatype +and the GUI widget. For e.g. a property of type “string” cannot be represented +by a spin box or slider. Hence, no alternative widget can be seen when you +open the context menu of a property. +\begin{center} +\includegraphics[scale=1.0]{figures/wavedash/10_property_context_menu.png} +\end{center} + +\begin{center} +\includegraphics[scale=1.0]{figures/wavedash/11_property_widget_changed.png} +\end{center} + +The widgets Spinbox and Slider have a minimum and maximum values associated +with them. When spin box or slider is chosen as a widget, the application sets +the default minimum and maximum as 0 and 10000 respectively. Should the user +wish to change these values for better access, right click on the widget and +choose Configure. This would open a new dialog box where you can configure +minimum and maximum values. + +\begin{center} +\includegraphics[scale=1.0]{figures/wavedash/12_widget_configuration.png} +\end{center} + + Index: /documentation/ossie/user-guide-0.8.1/OWDGuide.tex =================================================================== --- /documentation/ossie/user-guide-0.8.1/OWDGuide.tex (revision 9972) +++ /documentation/ossie/user-guide-0.8.1/OWDGuide.tex (revision 9972) @@ -0,0 +1,575 @@ +% ------------------------------------------------------------------ +% +% TITLE: OSSIE Waveform Developer Guide +% AUTHORS: A. Cormier, C. Dietrich, J. Gaeddert +% CREATED: +% REVISED: +% URL: +% +% ------------------------------------------------------------------ + +\section{OSSIE Waveform Developer} +\label{section:owd} +The OSSIE Waveform Developer (OWD) is available for constructing code for +waveforms and components based on JTRS's Software Communications Architecture. A +user does not need to have detailed knowledge of the SCA or CORBA to use the +tool. OWD allows you to draw from a library of available components to construct an +SCA-based waveform or create the skeleton code for custom-made C++ or Python +components. + +\subsection{Creating a New Waveform from Existing Components} +\label{section:owd:newwaveform} +To start OWD, open a terminal and type: +\begin{lstlisting}[] + $ OWD +\end{lstlisting} +The main window should appear without warnings or errors: +\begin{center} +\includegraphics[scale=0.4]{figures/owd/owd_main_screen_blank.png} +\end{center} +% +At this time we will re-create the {\tt ossie\_demo} waveform packaged with +the \ossieversion\ release to demonstrate how waveforms can be easily created in OWD. + +\subsubsection{Adding an Existing Node to a Waveform} +\label{section:owd:addexistingnodes} +%A waveform is a group of components running on a set of nodes +A node is a set of devices upon which components and other resources may be +deployed. You can click the arrows next to the components, devices and nodes +listed in the pane on the left to reveal the resources installed in your {\tt +/sdr} directory. + +Under ``Nodes,'' right-click {\tt default\_GPP\_node} and select ``Add to +Platform.'' Click the arrow next to {\tt default\_GPP\_node} to display all +devices associated with the node. In this case, you will see only one device, +{\tt GPP1}, which corresponds to the general purpose processor on your +computer. +% +\begin{center} +\includegraphics[scale=0.4]{figures/owd/owd_add_node_to_platform.png} +\end{center} + +\subsubsection{Adding an Existing Component to a Waveform} +\label{section:owd:addexistingcomponents} +Add an instance of the {\tt TxDemo} component to the waveform by right-clicking +and selecting ``Add to Waveform.'' +\begin{center} +\includegraphics[scale=0.4]{figures/owd/owd_add_TxDemo_to_waveform.png} +\end{center} +This will bring up a box requesting an instance name for the +component. +The default value, ``TxDemo1,'' is usually fine. Select ``OK'' and +you should see an instance called ``TxDemo1'' on the Waveform pane: +% +\begin{center} +\includegraphics[scale=0.4]{figures/owd/owd_TxDemo.png} +\end{center} +% +Now add instances of the {\tt ChannelDemo} and the {\tt +RxDemo} components to the waveform using the same process as you did for {\tt +TxDemo}. +\begin{center} +\includegraphics[scale=0.4]{figures/owd/owd_my_ossie_demo_01.png} +\end{center} + +\subsubsection{Connecting Components} +\label{section:owd:connectingcomponents} +We are now ready to connect the components. +Right-click the ``TxDemo1'' instance and select ``Connect'' to open the +``Connections'' window. +The left pane lists all the ports owned by ``TxDemo1'' which should just +include {\tt symbols\_out}. +The {\tt TxDemo} component itself generates a sequence of QPSK symbols that +are pushed by this port. + +The right pane lists all the ports associated with the components and devices +currently included in the waveform. +Click the drop arrow next to ``Components.'' +You should see a list of all the component instances and their available +ports. +As indicated by the legend, a black box indicates a {\it uses} port while +a white box indicates a {\it provides} port. +Generally speaking, a {\it uses} port is an output interface while a +{\it provides} port is an input interface. +There are a few rules to remember when connecting ports: +\begin{enumerate} +\item A {\it provides} port must be connected to a {\it uses} port, and vice +versa +\item Both ports must be of the same interface or data type (e.g. {\tt complexShort}) +\end{enumerate} + +From the left pane select the ``TxDemo1'' {\it uses} port {\tt symbols\_out}. +From the right pane, under ``Components'', select the ``ChannelDemo1'' {\it +provides} port {\tt samples\_in}. Click the ``Connect'' button in the center of +the window to establish the connection. +The ``Connections'' pane should now indicate this connection: +\begin{center} +\includegraphics[scale=0.4]{figures/owd/owd_TxDemo_connect.png} +\end{center} +% +Select ``OK'' to confirm the connection you specified. This returns you to the +main OWD window. You should now see a drop arrow next to the ``TxDemo1'' +component instance. Clicking the arrow reveals all connections made by the component. +% +Repeat these steps to connect the ``ChannelDemo1'' {\it uses} port +{\tt samples\_out} to the ``RxDemo1'' {\it provides} port {\tt symbols\_in}. +Start by right-clicking on the ``ChannelDemo1'' component and selecting +``Connect.'' + +\subsubsection{Deploying Components and Editing Component Properties} +\label{section:owd:editingcomponentproperties} + +Each component needs to be deployed to the node and device where it will run. +Also, components have properties which are configured during waveform run time. +Optionally, for each component instance in a waveform, default property values +can be overridden by an XML-format SAD file that describes how the waveform is +assembled. This can be done by changing a component's properties within OWD. + +To bring up the Component Editor, right-click the ``TxDemo1'' component +instance and select ``Edit.'' +\begin{center} +\includegraphics[scale=0.4]{figures/owd/owd_TxDemo_edit.png} +\end{center} +% +This window contains nearly all the information about the component itself +including its ports, properties, and node and device assignments. +At the moment the component instance is not assigned to any device. +It is necessary to make this assignment for each component in the waveform. +For this example, select {\tt default\_GPP\_node} under the ``Nodes'' +spinbox.\footnote{It is imperative that you actually select the +{\tt default\_GPP\_node} text with the mouse, otherwise you will not see a +list of available devices in the ``Device'' spinbox} +Click on the ``Device'' spinbox and select ``GPP1.'' + +Now it is time to set the component properties. +For the {\tt TxDemo} example, you should see a {\it packet\_delay\_ms} +property with a default value of {\tt 1000} ms. +This particular property is specific to the component and determines how long +``TxDemo1'' should wait between sending each QPSK packet. + +Right-click on the {\it packet\_delay\_ms} property and select ``Edit.'' +Change the default value from {\tt 1000} to {\tt 250}: +\begin{center} +\includegraphics[scale=0.4]{figures/owd/owd_TxDemo_edit_packet_delay_property.png} +\end{center} +% +Click ``OK'' to return the the Component Editor window. +Click ``Close'' to return to OWD's main window. + +Repeat the component deployment steps for the ``RxDemo1'' component. You can +see that ``ChannelDemo1'' has properties, but they can be left unchanged. + +%Make the following property changes to the ``ChannelDemo1'' component +%instance: +%\begin{enumerate} +%\item {\it phase\_offset}: {\tt 30} +%\item {\it noise\_std\_dev}: {\tt 100} +%\end{enumerate} + +\subsubsection{Setting the Assembly Controller} +\label{section:owd:settingtheassemblycontroller} +Each waveform must have just one assembly controller. +Calling ``start'' on the waveform actually invokes the {\tt start()} function on +the assembly controller component. +In this case, the assembly controller is ``TxDemo1.'' +Right click the ``TxDemo1'' component instance and select ``Set Assembly +Controller.'' +Notice that ``TxDemo1'' now appears in bold face to indicate its new status: +\begin{center} +\includegraphics[scale=0.4]{figures/owd/owd_TxDemo_assembly_controller.png} +\end{center} +% +\subsubsection{Generating the Waveform} +\label{section:owd:generatingthewaveform} +Before OWD can generate the waveform XML, you need to give the waveform a name. +In the upper left textbox type {\tt my\_ossie\_demo}. +If you click on all the drop arrows to display details, your completed +waveform should look like this: +\begin{center} +\includegraphics[scale=0.4]{figures/owd/owd_my_ossie_demo_complete.png} +\end{center} +% +Select Waveform$\to$Generate. If everything has worked, you should not get any +warnings or error messages. +Select the destination for the source (usually something like +{\tt \~/src/waveforms/}). This can be done by typing the destination path into +the text box labeled ``Name.'' Now click ``OK'' or ``Open.'' + +\subsubsection{Installing the Waveform} +\label{section:owd:installingthewaveform} +In a terminal, change to the directory in which the source files were +generated, and run the included {\tt setup.py} script: +\begin{lstlisting}[] + $ cd /home/mysername/src/waveforms/my_ossie_demo + $ python setup.py install +\end{lstlisting} +This should copy the DAS and SAD files to the new directory +{\tt /sdr/waveforms/my\_ossie\_demo}. You can now load and run the waveform +using wavLoader (see Section~\ref{section:runningwaveforms}) or ALF +(Section~\ref{section:alf}). + +%\subsection{Creating a New Node} + +%It is possible to define a new node with one or more devices. To add a node to the waveform, right click on the bottom half of the waveform layout and select ``Add Node.'' + +%In order to add a device, a node must first be present in the waveform layout. +%Right click on the desired device in the available resources and select ``Add to +%node.'' You will be given an option as to which node to add the device to. + + +\subsection{Creating a New Component} +\label{section:owd:newcomponent} +A component is a communications system function that is implemented in +software. When modularity is desired, components implement only simple +functions. Multiple components are then connected to implement more complex +functions. The Component Builder allows the user to develop template code for +SCA-based components given a set of properties and ports. In the generated +template, a section is created where the user can enter the algorithm. + +To start the stand-alone component builder, run the following command from +any directory: +\begin{lstlisting}[] + $ OWDC +\end{lstlisting} +This should bring up the OSSIE Component Editor window: +\begin{center} +\includegraphics[scale=0.4]{figures/owd/owd_component_editor.png} +\end{center} + +There are five major steps to creating an SCA-based component using the +OWD Component Editor: +\begin{enumerate} +\item Adding ports +\item Adding properties +\item Selecting component generation options +\item Generating the source code +\item Building and installing the binaries +\end{enumerate} +These steps are described in detail in the following sections. + +\subsubsection{Adding Ports} +\label{section:owd:addingports} +A port is an interface that allows components to communicate with one +another. +Generally, ports are used to either pass data or call functions. +Release \ossieversion\ of OSSIE is packaged with several pre-defined standard +interfaces that make development of components simple. + +To add one or more ports to your component, click on the ``Add Port'' +button from the OSSIE Component Editor window. +% +\begin{center} +\includegraphics[scale=0.4]{figures/owd/owd_add_port.png} +\end{center} +% +The Add Port dialog box will be opened. You may then select the data +type for the component ({\tt complexShort} or {\tt complexFloat} from +standardInterfaces is recommended) and its type. +Whether or not the port is a {\it uses} or {\it provides} port is often a point +of confusion for users who are unfamiliar with the SCA. In most simple cases, a +{\it uses} port corresponds to an output interface, while a {\it provides} port +corresponds to an input interface. + +Give the port a unique name (e.g. {\tt complex\_baseband}) and click ``Ok.'' +The new port should now appear in the ``Ports'' pane of the OSSIE +Component Editor window. + +\subsubsection{Adding Properties} +\label{section:owd:addingproperties} +To add one or more properties to your component, click on the +bottom ``Add Property'' button. A properties dialog box will be opened. +\begin{center} +\includegraphics[scale=0.4]{figures/owd/owd_add_property.png} +\end{center} +A new, unique ID for +the property will automatically be generated. The element types ``Simple'' and +``SimpleSequence'' are completely supported. Default property values can be added +to the property. Once added, the default value cannot be changed, but the +value stored in the ``Value'' column can be changed by clicking on it. Once all +of the configurations are set, click on ``Add Property'' to add the property to +the component. After the property has been generated, the instance values of +the property can be changed in the Component Editor. + +\subsubsection{Selecting Component Generation Options} +\label{section:owd:selectingcomponentgenerationoptions} +Component generation options include templates (basic\_ports, custom\_ports, +and py\_comp) and optional timing and ACE support. When the basic\_ports option +is selected, the C++ source code files generated will include port +implementations. The custom\_ports option generates C++ code with ports +implemented in separate files from the functional component code. The +custom\_ports option allows support for timing but documentation for +custom\_ports is limited to comments in the source code. The py\_comp option +generates Python code, suitable for components that do not need to process data +at high rates. The py\_comp option allows for timing support, which is +selected by checking a box below the template selection. The user must edit +the generated source code to add functionality to the component. +Computer science laboratory format exercises are under development that will +include step by step instructions for building simple components using the +basic\_ports and py\_comp options, and for using the timing support feature. +The exercises and updates to this guide will be posted at +\href{http://ossie.wireless.vt.edu}{http://ossie.wireless.vt.edu}. + +\subsubsection{Generating the Source} +\label{section:owd:generatingsource} +Before generating the source code for the component, you must first give it a +name. Type whatever name you would like into the ``Component Name'' box in the +Component Editor. Select Component$\rightarrow$Generate Component to select a +directory to save the source code that will be generated. The location +of the stored source code is arbitrary and many users will +create a components directory to store all of their source code. Once +you select a directory and click ``Open'' or ``Ok,'' your code will +automatically be generated. + +\textbf{Files Generated Using the basic\_ports C++ Option} + \begin{description} + \item[configure.ac] This is the script that {\tt autoconf} \cite{autoconf:web} + uses to generate the {\tt configure} file. It checks for dependencies such as + which compiler to use, as well as the presence of OSSIE libraries. + \item[Makefile.am] This is the script that {\tt automake} \cite{automake:web} uses + to generate the {\tt Makefile}. It includes all the source files for the + component. + \item[reconf] This is a script to run the automake tools. + \item[MyComponent.h] Component class header file + \item[MyComponent.cpp] Component class implementation definition + \item[main.cpp] Contains the mandatory {\tt int main()} definition + \item[MyComponent.prf.xml] Component property file + \item[MyComponent.scd.xml] Software component descriptor + \item[MyComponent.spd.xml] Software package descriptor + \item[documentation.txt] File for documenting your component + \item[Doxyfile] Doxygen \cite{doxygen:web} file for generating documentation + \end{description} + +\textbf{Files Generated Using py\_comp Option} + \begin{description} + \item[MyComponent.py] Python file with port implementations + \item[WorkModule.py] Python file where processing is done + \item[setup.py] Install script used to copy Python and XML files into the + appropriate subdirectories under {\tt /sdr} once the component is edited to + provide functionality. This is executed by typing {\tt python setup.py install} + \item[MyComponent.prf.xml, MyComponent.scd.xml, MyComponent.spd.xml] Same as for C++ components + \end{description} + + +\subsubsection{Building a Working Python Component} + +Generated component template code must be modified to +process data. The instructions here apply to a very basic Python component with +one {\it uses} and one {\it provides} port and no properties. Property values +can be used in the processing operations, but this will be the subject of a +future exercise. + +All data coming into a {\it provides} port will be loaded into the +WorkModule buffer. The data going into this buffer will be loaded +into variables called I and Q. See the generated WorkModule.py and +look for: +\begin{lstlisting}[] + I = new_data[0] + Q = new_data[1] +\end{lstlisting} +This implies that if you try to run a component that is getting real +data only, Q should be empty, and this may even cause an error. There are +comments in various parts of the python files describing how to adjust your code +appropriately. + +The next two lines initialize two arrays to store your new data: +\begin{lstlisting}[] + newI = [0 for x in range(len(I)))] + newQ = [0 for x in range(len(Q)))] +\end{lstlisting} +%TODO: Make listings highlighted +Following these lines are comments with an example of how to +process data. If you uncomment the 3-line example, your +component will pass the data received by the {\it provides} (input) port to the +{\it uses} (output) port, assuming you have one {\it uses} port of type {\tt +complexShort} and one {\it provides} port, also of type {\tt complexShort}. +Code can be added to process the data. + +The next set of lines following the comment ``{\tt \# Output the new data},'' +will send the {\tt newI} and {\tt newQ} vectors to all of your output ports. + +\subsubsection{Editing the SPD File} + +You will need to edit {\tt MyComponent.spd.xml} before your Python +component will work properly. Find the XML tag below the tag {\tt }. By default the next tag is: +\begin{lstlisting}[] + } +\end{lstlisting} +This needs to be changed to: +\begin{lstlisting}[] + +\end{lstlisting} + +\subsubsection{Making Sure Files are Executable} + +After you have installed the component (see below), you will need to make sure +that you have permission to execute the Python files. To do this, navigate to +{\tt /sdr/bin/MyComponent} and type: +\begin{lstlisting}[] + $ chmod +x *.py +\end{lstlisting} + +\textbf{\emph{C++ components}} + +For C++ components, within the generated {\tt your\_component\_name.cpp} file you +may enter the code for processing data. Look for {\tt /*insert code here to do +work*/} within the process\_data function. Editing the SPD file should not be +necessary. The installed executable file, \\ +{\tt /sdr/bin/your\_component\_name}, needs to be executable, but this should +be done by default. + +\subsubsection{Building and Installing the Binaries} +\label{section:owd:buildandinstall} + +Once the component has been generated, use a terminal to navigate to the +directory of the created source code (e.g. +~{\tt \/src/components}). Four commands must be executed (in order) +in order to install a C++ component to the {\tt /sdr} directory: +\begin{lstlisting}[] + $ ./reconf + $ ./configure + $ make + $ make install +\end{lstlisting} +If you do not have ownership of your target install directory, (by default {\tt +/sdr}), you will need to run {\tt make install} as root. + +To install a Python component, from the directory that contains the generated +and edited source code, simply execute the following command: +\begin{lstlisting}[] + $ python setup.py install +\end{lstlisting} + +Just as with the C++ installation, if you do not have ownership of your target +install directory you will need to run {\tt python setup.py install} with root +privileges. + +%In OWD, pushing the ''Refresh'' button will cause the installed component to appear in +%the available resources list. + +\subsection{Custom License Generation} + + +OWD allows for customization of the license headers that proceed component or +waveform source files. By changing some simple parameters, these licenses can be +tailored to a specific need. + +The configuration file that must be modified to customize the header is +{\tt tools/WaveDev/wavedev.cfg}. There are multiple XML tags within this file, but the +three that need to be considered are {\tt sourcepreamble}, {\tt licensefile}, and +{\tt developer}. + +The user will need to configure this header, as a meaningful default header will not +be used. By default, the license header will display as: +\begin{lstlisting}[] +Copyright $YEAR by __DEVELOPER__, all rights reserved. +\end{lstlisting} + +The {\tt developer} option is simply the name of the person(s), company, or +organization to whom the file should be copywritten. The {\tt sourcepreamble} option +should contain an absolute path to a file (readable by the user) that contains the +preamble to be placed at the top of all source files. The {\tt sourcepreamble} file +is parsed as follows: + +\_\_COMP\_NAME\_\_ is replaced with the name of the component or waveform, +\_\_YEAR\_\_ is replaced with the current year, and \_\_DEVELOPER\_\_ is replaced +with the {\tt developer} value from {\tt wavedev.cfg} file. Finally, {\tt licensefile} +is an absolute path to a full license file (e.g. the GPL) that will accompany the +generated component or waveform. + + +\subsection{Removing Components, Devices, Nodes and Waveforms} +\label{section:owd:removingcompdevnodesandwav} + +\subsubsection{Removal Notes} +\label{section:owd:removalnotes} +The files that need to be removed all exist within the {\tt /sdr} directory. +To remove a component or device, the executable must be removed from +{\tt /sdr/bin/} as well as the xml files in {\tt /sdr/xml/}. To remove a node the +xml files must be removed from {\tt /sdr/nodes/}, and to remove a waveform the xml +files must be removed from {\tt /sdr/waveforms/}. The following steps will walk through +the procedure required to uninstall a component or device, a node and a waveform. + +\subsubsection{Component and Device Removal} +\label{section:owd:componentdeviceremoval} +Files in both {\tt /sdr/bin/} and {\tt /sdr/xml/} must be deleted to uninstall a +component or a device. Move into the {\tt /sdr/bin} directory. +\begin{lstlisting}[] + $ cd /sdr/bin +\end{lstlisting} +Now delete the executable. The file is write protected, so the {\tt -f} option will +not ask you to verify that you want to delete the file. +\begin{lstlisting}[] + $ rm -f COMPONENT_OR_DEVICE_NAME +\end{lstlisting} +Now move into the {\tt xml/} directory. +\begin{lstlisting} + $ cd ../xml/ +\end{lstlisting} +Remove the directory containing all of the xml files. This command must be +executed as root, however exit out of root after the folder has been removed. +\begin{lstlisting}[] + # rm -rf COMPONENT_OR_DEVICE_NAME + # exit +\end{lstlisting} +The component has now been removed. Open OWD to verify the component is no longer +available. +\begin{lstlisting} + $ OWD +\end{lstlisting} +Within OWD, click the arrow next to {\tt Components} if you are removing a component, +or {\tt Devices} if you are removing a device, in the left pane. Verify that the +component is no longer listed. If OWD was running while the component or device was +removed, click the {\tt Refresh} button above the component list to refresh the list of +available components and devices. + +\subsubsection{Node Removal} +\label{noderemoval} +To remove a node only a single directory within {\tt /sdr/nodes/} needs to be removed. +Move into the {\tt nodes/} directory. +\begin{lstlisting}[] + $ cd /sdr/nodes/ +\end{lstlisting} +Remove the directory containing the xml files. This must be done as root, however +exit out of root after entering the command. +\begin{lstlisting}[] + # rm -rf NODE_NAME + # exit +\end{lstlisting} +The node has now been removed. Open OWD to verify the node is no longer available. +\begin{lstlisting}[] + $ OWD +\end{lstlisting} +Within OWD, click the arrow next to {\tt Nodes} in the left pane. Verify that the node +is no longer listed. If OWD was running while the node was removed, click the +{\tt Refresh} button above the component list to refresh the list of available nodes. + +\subsubsection{Waveform Removal} +\label{waveformremoval} +To remove a waveform, only a single directory within {\tt /sdr/waveforms/} needs to +be removed. + +To remove a waveform, first move into the {\tt waveforms/} directory. +\begin{lstlisting}[] + $ cd /sdr/waveforms/ +\end{lstlisting} +Remove the directory containing the xml files. This should not be done as root. +\begin{lstlisting}[] + $ rm -rf WAVEFORM_NAME +\end{lstlisting} +The waveform has now been removed. + + + + +% \subsection{Obtaining and Installing Components from the Web} +% Where to find components on the Internet and how to install them. Available +% library (under development) includes +% \begin{itemize} +% \item PHY synchronizers +% \item Basic digital modulators/demodulators +% \item MAC synchronizers +% \item Interpolators/Decimators +% \item Sound capture/playback +% \end{itemize} + Index: /documentation/ossie/user-guide-0.8.1/QuickStartGuide.tex =================================================================== --- /documentation/ossie/user-guide-0.8.1/QuickStartGuide.tex (revision 9972) +++ /documentation/ossie/user-guide-0.8.1/QuickStartGuide.tex (revision 9972) @@ -0,0 +1,122 @@ +% ------------------------------------------------------------------ +% +% 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 dev/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} + +The terminal will list all of the available waveforms to run. Although multiple +waveforms may be listed, the waveform that the wavLoader command was started +with will only work. + +Since the wavLoader command run on {\tt ossie\_demo\_DAS.xml}, +select the first listing of the OSSIE demonstration waveform, +{\tt //waveforms/ossie\_demo/ossie\_demo.sad.xml} +\begin{lstlisting}[] + Selection: 1 +\end{lstlisting} + +The terminal should look similar to the following: +\begin{center} +\includegraphics[scale=0.4]{figures/quickstart/startWaveform.png} +\end{center} + +Now that the waveform is loaded, it must be started. Enter {\tt s} to start +the waveform. 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 \ossieversion. 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}. + + Index: /documentation/ossie/user-guide-0.8.1/RunningWaveforms.tex =================================================================== --- /documentation/ossie/user-guide-0.8.1/RunningWaveforms.tex (revision 9972) +++ /documentation/ossie/user-guide-0.8.1/RunningWaveforms.tex (revision 9972) @@ -0,0 +1,118 @@ +% ------------------------------------------------------------------ +% +% TITLE: Running OSSIE Waveforms +% AUTHORS: +% CREATED: +% REVISED: +% URL: http://ossie.wireless.vt.edu/ +% +% ------------------------------------------------------------------ + +\section{Running Waveforms} +\label{section:runningwaveforms} + +\subsection{Starting the CORBA Naming Service} +If you installed omniORB using {\tt rpm} or your system package manager and +have since restarted your machine chances are the naming service is running. +Refer to Appendix~\ref{appendix:services} for how to manage services under +Fedora Core 9. If you chose to install omniNames from source, you will need to +run {\tt omniNames.sh} (see Appendix~\ref{appendix:omninamessh}). + +\subsection{Running {\tt nodeBooter}} +To run {\tt nodeBooter}, open a terminal and execute the following: +\begin{lstlisting}[] + $ cd /sdr + $ nodeBooter -D -d dev/nodes/default_GPP_node/DeviceManager.dcd.xml +\end{lstlisting} +It is important that {\tt nodeBooter} be run from the {\tt /sdr} directory +because nodeBooter uses paths that are defined relatively to the directory in +which it is run. + +\subsection{Nodebooter Clean-Up} +If a waveform crashes or is uninstalled incorrectly, Nodebooter will not be +able to shut down all of the processes that it starts. This is currently +being addressed by the development team, however in the interim the processes +must be stopped by hand. To find which processes were not stopped, enter the +following command: +\begin{lstlisting}[] + $ ps -e +\end{lstlisting} + +This will list all of the currently running processes. Processes with the names +of components or devices that are in the waveform need to be shutdown. To stop +a process, enter the following command: +\begin{lstlisting}[] + $ killall USRP GPP TxDemo Decimator +\end{lstlisting} + +If the USRP node (default\_GPP\_USRP\_sound\_node) cannot be started, this is +typically resolved by killing the USRP, soundCardPlayback and soundCardCapture +devices. + +To make this process faster, create a script to kill all of the processes created +by a certain waveform. For example, create a text file called {\tt killOSSIEDemo}. +\begin{lstlisting}[] + $ cd ~ + $ vim killOSSIEDemo +\end{lstlisting} + +In this text file, press {\tt i} to insert text and enter the following on a single +line: +\begin{lstlisting}[] + killall GPP TxDemo ChannelDemo RxDemo +\end{lstlisting} + +Press {\tt }, {\tt :wq}, and then {\tt } to save the file and exit. Now +change the permissions so the script can be executed. + +\begin{lstlisting}[] + $ chmod +x killOSSIEDemo +\end{lstlisting} + +Now the script has been created and can be run by entering the command: +\begin{lstlisting}[] + $ ./killOSSIEDemo +\end{lstlisting} + +If not all processes within the script are running a warning will be printed stating +that the process has not been killed, which is fine. + + +\subsection{Loading a Waveform} +The \ossieversion\ release supports two options for loading a waveform: +\begin{enumerate} +\item The command-line {\tt c\_wavLoader} utility discussed +below +\item The graphical tool ALF described in Section~\ref{section:alf} +\end{enumerate} + +Directions here are for running the OSSIE demonstration waveform, {\tt +ossie\_demo}. \describeossiedemo\ To run another waveform, substitute {\tt +ossie\_demo} with the name of your waveform. + +Load the waveform using c\_wavLoader. In a terminal window, execute: +\begin{lstlisting}[] + $ c_wavLoader +\end{lstlisting} + +One or more SAD files (ending in {\tt .sad.xml}) will be listed. To load the +waveform, enter the number that corresponds to {\tt ossie\_demo.sad.xml}. +Finally, enter {\tt s} to start the waveform. + +The terminal window in which nodeBooter was started will 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} +X denotes the number of QPSK bit errors out of 1024 that have been detected +by the RxDemo component. +The terminal should look like this: +\begin{center} +\includegraphics[scale=0.4]{figures/quickstart/RxDemo.png} +\end{center} + +Congratulations! You have just run the QPSK demonstration waveform for version +\ossieversion. From here you may be interested in learning how to create your own +waveforms and components using the OSSIE Eclipse Feature described +in the following section or the OSSIE Waveform Developer described in Section~\ref{section:owd}. Index: /documentation/ossie/user-guide-0.8.1/generatehtmltex.sh =================================================================== --- /documentation/ossie/user-guide-0.8.1/generatehtmltex.sh (revision 9972) +++ /documentation/ossie/user-guide-0.8.1/generatehtmltex.sh (revision 9972) @@ -0,0 +1,85 @@ +#!/bin/bash + +# Name of the subdirectory we'll be using. +MY_DIR="html" + +# Name of the main tex source (no extension). +MY_MAIN_FILE="UserGuide" + +# Title we should give the generated web page. +MY_TITLE="OSSIE 0.7.1 User Guide" + +# Width we want images to become. +MY_WIDTH=600 + +# Error message function +die () { + echo -e " error." + exit +} + +# Wipe our directory, partly because it might show up while we're trying +# to find real directories and also because we'll be overwriting its +# contents anyway. +if [ -d ${MY_DIR} ] ; then + rm -rf ${MY_DIR} +fi + +# Find directories that might contain files we'll need to copy or play +# with. +DIRS=`find . -type d | grep -v '.svn'` + +echo -n "Creating directory structure... " +for DIR in ${DIRS} ; do + mkdir -p ${MY_DIR}/${DIR} || die +done +echo " done." + +echo -n "Copying bibliography source files... " +BIBS=`find ${DIRS} -type f -name "*.bib"` +for FILE in ${BIBS} ; do + cp ${FILE} ${MY_DIR}/${FILE} || die +done +echo " done." + +echo -n "Editing and copying LaTeX source files... " +TEXS=`find ${DIRS} -type f -name "*.tex"` +for FILE in ${TEXS} ; do + sed -e 's/\(\\href\)\({.*}\)\({.*}\)/\\htmladdnormallink\3\2/' \ + -e 's/\\begin{lstlisting}\(\[.*\]\)*/\\begin{verbatim}/' \ + -e 's/\\end{lstlisting}/\\end{verbatim}/' \ + -e 's/%@/\\/' ${FILE} \ + > ${MY_DIR}/${FILE} || die +done +echo " done." + +echo -n "Resizing and copying images... " +IMAGES=`find ${DIRS} -type f -name "*.png"` +for FILE in ${IMAGES} ; do + convert -resize ${MY_WIDTH} ${FILE} ${MY_DIR}/${FILE} || die + #cp ${FILE} ${MY_DIR}/${FILE} #(useful for faster testing) +done +echo " done." + +echo -n "Running LaTex and bibTeX... " +cd ${MY_DIR} +pdflatex ${MY_MAIN_FILE}.tex +bibtex ${MY_MAIN_FILE} +pdflatex ${MY_MAIN_FILE}.tex +pdflatex ${MY_MAIN_FILE}.tex +echo " done." + +echo -n "Creating sectioned HTML version... " +# the -mkdir argument to latex2html is borked +mkdir sectioned +latex2html -title "${MY_TITLE}" -noinfo -image_type png \ + -dir sectioned -show_section_numbers ${MY_MAIN_FILE}.tex || die +echo " done." + +echo -n "Creating massive 1-page HTML version... " +mkdir massive +latex2html -title "${MY_TITLE}" -split 0 -noinfo -image_type png \ + -dir massive -show_section_numbers ${MY_MAIN_FILE}.tex || die +echo " done." + +echo 'All finished; enjoy your HTML :).' Index: /documentation/ossie/user-guide-0.8.1/Makefile =================================================================== --- /documentation/ossie/user-guide-0.8.1/Makefile (revision 9972) +++ /documentation/ossie/user-guide-0.8.1/Makefile (revision 9972) @@ -0,0 +1,14 @@ +projName = UserGuide + +all: clean $(projName).pdf + +$(projName).pdf: $(projName).tex + pdflatex $(projName) + bibtex $(projName) + pdflatex $(projName) + pdflatex $(projName) + +clean: + rm -f *.ps *.dvi *.aux *.toc *.idx *.ind *.ilg *.log *.out *.bbl *.blg \ + $(projName).pdf +