gnss-sdr/README

HOW TO BUILD GNSS-SDR
----------------------

This document describes how to set up the compilation environment and build GNSS-SDR. See also http://gnss-sdr.org/documentation/building-guide

Ubuntu 11.04, 11.10, 12.04, 12.10 (32 and 64 bits)
--------------------------------------------------

* Install GNU Radio:

- Downloading, building and installing GNU Radio and all its dependencies is not a simple task. We recommend to use Marcus Leech's build-gnuradio script, which automatically does all the work for you. In a terminal, do:

$ wget http://www.sbrac.org/files/build-gnuradio
$ chmod a+x build-gnuradio
$ ./build-gnuradio

This can take a while (up to two hours to complete, depending on your system), and installs the latest versions of UHD and GNU Radio in your system, including all their dependencies. In case you do not want to use the script and prefer to build and install GNU Radio manually from source, follow instructions in http://gnuradio.org/redmine/projects/gnuradio/wiki/BuildGuide

- Set up some system variables needed by the GNSS-SDR build system:

export PYTHONPATH=/usr/local/lib/python2.7/dist-packages
export LD_LIBRARY_PATH=/usr/local/lib

In order to avoid defining these variables each time you enter a session, you may want to add these three lines to your $HOME/.bashrc file.

* Install other libraries used by GNSS-SDR:

- Download, compile, and install the Armadillo linear algebra library
$ sudo apt-get install libatlas-dev
$ wget http://sourceforge.net/projects/arma/files/armadillo-3.6.1.tar.gz
$ tar xvfz armadillo-3.6.1.tar.gz
$ cd armadillo-3.6.1
$ cmake .
$ make
$ sudo make install

The full stop separated from "cmake" by a space is important. CMake will figure out what other libraries are currently installed and will modify Armadillo's configuration correspondingly. CMake will also generate a run-time armadillo library, which is a combined alias for all the relevant libraries present on your system (eg. BLAS, LAPACK and ATLAS).


- Download, unzip, configure, build and install gperftools, a set of performance analysis tools:

$ wget http://gperftools.googlecode.com/files/gperftools-2.0.tar.gz 
$ tar xvfz gperftools-2.0.tar.gz 
$ cd gperftools-2.0
$ ./configure --enable-frame-pointers
$ make
$ sudo make install


- Download, unzip, configure, and build Google C++ Testing Framework (also known as Google Test):

$ wget http://googletest.googlecode.com/files/gtest-1.6.0.zip
$ unzip gtest-1.6.0.zip
$ cd gtest-1.6.0
$ ./configure
$ make

Please DO NOT install gtest (do not do "sudo make install"). Every user needs to compile his tests using the same compiler flags used to compile the installed Google Test libraries; otherwise he may run into undefined behaviors (i.e. the tests can behave strangely and may even crash for no obvious reasons). The reason is that C++ has this thing called the One-Definition Rule: if two C++ source files contain different definitions of the same class/function/variable, and you link them together, you violate the rule. The linker may or may not catch the error (in many cases it is not required by the C++ standard to catch the violation). If it does not, you get strange run-time behaviors that are unexpected and hard to debug. If you compile Google Test and your test code using different compiler flags, they may see different definitions of the same class/function/variable (e.g. due to the use of #if in Google Test). Therefore, for your sanity, we recommend to avoid installing pre-compiled Google Test libraries. Instead, each project should compile Google Test itself such that it can be sure that the same flags are used for both Google Test and the tests. The building system of GNSS-SDR does the compilation and linking of gtest its own tests; it is only required that you tell the system where the gtest folder that you downloaded resides. Just add to your $HOME/.bashrc file the following line:

export GTEST_DIR=/home/username/gtest-1.6.0

changing /home/username/gtest-1.6.0 by the actual directory where you downloaded gtest. Again, it is recommended to add this line to your $HOME/.bashrc file.


- Download, unzip, configure, build and install Google's gflags package, a commandline flags processing module for C++:

$ wget http://google-gflags.googlecode.com/files/gflags-2.0.zip
$ unzip gflags-2.0.zip
$ cd gflags-2.0
$ ./configure
$ make
$ sudo make install
$ sudo ldconfig

- Download, unzip, configure, build and install glog, a Google's library that implements application-level logging:

$ wget http://google-glog.googlecode.com/files/glog-0.3.2.tar.gz 
$ tar xvfz glog-0.3.2.tar.gz 
$ cd glog-0.3.2
$ ./configure
$ make
$ sudo make install
$ sudo ldconfig

- Install Subversion

$ sudo apt-get install subversion

* Check out the latest version of GNSS-SDR

$ svn co http://svn.code.sf.net/p/gnss-sdr/code/trunk gnss-sdr

Checking out GNSS-SDR as in the line above will create a folder named gnss-sdr with the following structure:

 |-gnss-sdr
 |---build      <- where gnss-sdr is built
 |---cmake      <- CMake-related files
 |---conf       <- Configuration files. Each file represents one receiver.
 |---data       <- Populate this folder with your captured data.
 |---docs       <- Contains documentation-related files
 |---drivers    <- Drivers for some RF front-ends
 |---firmware   <- Firmware for some front-ends
 |---install    <- Executables 
 |---src        <- Source code folder
 |-----algorithms
 |-----core
 |-----main
 |-----tests
 |-----utils     <- some utilities (e.g. Matlab scripts)



* Build GN3S V2 Custom firmware and driver (OPTIONAL)

- Go to GR-GN3S root directory, compile and install the driver:
  (read the drivers/gr-gn3s/README for more information)
  
$ cd gnss-sdr/drivers/gr-gn3s
$ cd build
$ cmake ../
$ make
$ sudo make install
$ sudo ldconfig

- Set the environment variable GN3S_DRIVER=1 in order to enable the GN3S_Signal_Source in GNSS-SDR (OPTIONAL)

$ export GN3S_DRIVER=1

In order to gain access to USB ports, gnss-sdr should be used as root.
In addition, the driver requires access to the GN3S firmware binary file. 
It should be available in the same path where the application is called.
GNSS-SDR comes with a pre-compiled custom GN3S firmware available at gnss-sdr/firmware/GN3S_v2/bin/gn3s_firmware.ihx. 
Please copy this file to the application path. The GNSS-SDR default path is gnss-sdr/install

(in order to disable the GN3S_Signal_Source compilation, you should remove the GN3S_DRIVER variable and build again GNSS-SDR)

* Build RTL-SDR support (OPTIONAL)

- Install the OsmoSDR library and GNU Radio source (http://sdr.osmocom.org/trac/) 

$ git clone git://git.osmocom.org/osmo-sdr.git
$ cd osmo-sdr/software/libosmosdr
$ mkdir build
$ cd build/
$ cmake ../
$ make
$ sudo make install
$ sudo ldconfig
$ cd ../../
$ git clone git://git.osmocom.org/gr-osmosdr
$ cd gr-osmosdr
$ mkdir build
$ cd build
$ cmake ../ -Wno-dev
$ make
$ sudo make install
$ sudo ldconfig

- Set the environment variable RTLSDR_DRIVER=1 in order to enable the Rtlsdr_Signal_Source in GNSS-SDR (OPTIONAL)

$ export RTLSDR_DRIVER=1

- In order to compile the RTLSDR adapter you should also provide the path to the gr-osmosdr source code using:

$ export OSMOSDR_ROOT=/path/to/gr-osmosdr

The default will be OSMOSDR_ROOT=/usr/local

(in order to disable the Rtlsdr_Signal_Source compilation, you should remove the RTLSDR_DRIVER variable and build again GNSS-SDR)


* Build GNSS-SDR

You can choose either Bjam or CMake as a building tool. We are progressively moving to CMake, but Bjam is still available. 

Using CMake
------------
- Go to GNSS-SDR's build directory:

$ cd gnss-sdr/build

- Configure and build the program:

$ cmake ../
$ make

- Move the executables to the install folder

$ make install

If everything goes well, two new executables will be created at gnss-sdr/install, namely gnss-sdr and run_tests. 

You can create the documentation by doing:

$ make doc

from the gnss-sdr/build folder. This will generate HTML documentation that can be retrieved pointing your browser of preference to gnss-sdr/docs/html/index.html.
If a LaTeX installation is detected in your system,

$ make pdfmanual

will create a PDF manual at gnss-sdr/docs/GNSS-SDR_manual.pdf. Please note that the PDF generation requires some fonts to be installed on the host system. In Ubuntu 12.10, those fonts do not come by default. You can install them by doing:

$ sudo apt-get install texlive-fonts-recommended

and then run cmake ../ and make pdfmanual again. Finally,

$ make doc-clean

will remove the content of previously-generated documentation.

By default, CMake will build the Release version, meaning that the compiler will generate a faster, optimized executable. This is the recommended build type when using a RF front-end and you need to attain real time. Ifyou are working with a file (and thus without real-time constraints), you may want to obtain more information about the internals of the receiver, as well as more fine-grained logging. This can be done by building the Debug version, by doing:

$ cd gnss-sdr/build
$ cmake -DCMAKE_BUILD_TYPE=Debug ../
$ make
$ make install



Using Bjam
----------

- Go to GNSS-SDR's root directory and compile the program:

$ cd gnss-sdr
$ bjam

If everything went fine, two new executables will be created at gnss-sdr/install, namely gnss-sdr and run_tests.

- You can also build the release version (an optimized, faster executable) by typing:

$ bjam release

You can create the documentation by doing:

$ doxygen

from the gnss-sdr/build folder. This will generate HTML documentation that can be retrieved pointing your browser of preference to gnss-sdr/docs/html/index.html.



Updating GNSS-SDR
-----------------

If you checked out GNSS-SDR some days ago, it is possible that some developer has updated files at the Subversion repository. You can update your working copy by doing:

$ cd gnss-sdr
$ svn up

Before rebuiling the source code, it is safe (and recommended) to remove the remainders of old builds:

$ rm -rf gnss-sdr/build/*



Mac OS X 
------------------------------
NOTE: Currently, Apple's GCC toolchain is broken. We are working towards the use of LLVM/Clang. 

WARNING: GNU Radio's VOLK component (which handles vector optimized instructions and routines) compiles best when using GCC. 
The default compiler for macports is CLANG, which will result in a fully functioning GNU Radio install but the VOLK component will not utilize the CPU's capabilities.
In order to take advantage of VOLK, compile it with the (rather old) GCC 4.2:

$ sudo port install gnuradio-devel +grc +python27 +uhd +orc +swig +qtgui +wxgui configure.compiler=llvm-gcc-4.2

However, GNSS-SDR cannot be compiled by GCC 4.2. It has been succesfully built with GCC 4.6, and (could) work in 4.5. If you compile GNU Radio with clang, apart from neglecting the benefits of VOLK, then the problem for building GNSS-SDR is Armadillo.
Check out http://llvm.org/bugs/show_bug.cgi?id=14768 in order to see the status of this bottleneck.


GETTING STARTED
---------------


1. After building the code, you will find the gnss-sdr executable file at gnss-sdr/install 

2. In post-processing mode, you have to provide a captured GNSS signal file.
    
    2.1. The signal file can be easily recorded using the GNU Radio file sink in gr_complex<float> mode.

    2.2. You will need a GPS active antenna and a suitable USRP daughter board to receive GPS L1 C/A signals. GNSS-SDR require to have at least 2 MHz of bandwidth in 1.57542 GHz. (remember to enable the DC bias with the daughter board jumper).
We use the DBSRX to do the task, but you can try the newer ETTUS daughter boards as well. 

    2.3. The easiest way to capture a signal file is to use the GNU Radio Companion GUI. Only two blocks are needed: an USRP signal source connected to complex float file sink. You need to tune the USRP central frequency and decimation factor using USRP signal source properties box. We suggest using a decimation factor of 20 if you use the USRP2. This will give you 100/20= 5 MSPS which will be enough to receive GPS L1 C/A signals. The front-end gain should also be configured. In our test with the DBSRX we obtained good results with G=50

    2.4. Capture at least 80 seconds of signal in an open sky conditions (at this moment, the acquisition is not very sensitive..). During the process, be aware of USRP driver buffer underuns messages. If your hard disk is not fast enough to write data at this speed you can capture to a virtual RAM drive. 80 seconds of signal at 5 MSPS occupies less than 3 Gbytes using gr_complex<float>.

3. You are ready to configure the receiver to use your captured file among other parameters:

    3.1. The configuration file reside in ./conf/gnss-sdr.conf
    3.2. You need to modify at least the following settings:
        3.2.1. SignalSource.filename= (absolute or relative route to your GNSS signal captured file)
        3.2.2. GNSS-SDR.internal_fs_hz=(captured file sampling rate in Hz)
        3.2.3. SignalSource.sampling_frequency=(captured file sampling rate in Hz)
        3.2.4. SignalConditioner.sample_freq_in=(captured file sampling rate in Hz)
        3.2.5. SignalConditioner.sample_freq_out=(captured file sampling rate in Hz)
        3.2.6. TelemetryDecoder.fs_in=(captured file sampling rate in Hz)

    3.3. The configuration file has in-line documentation, you can try to tune the number of channels and several receiver parameters.

4. Run the receiver from the install directory. The program reports the current status in text mode, directly to the terminal window. If all goes well, and GNSS-SDR is able to successfully track an decode at least 4 satellites, you will get a PVT fix. The program will write a Google Earth KML file and RINEX (yet experimental) files in the install directory. Among the console output, GNSS-SDR also writes log files in /tmp/.