mirrors/gnss-sdr
1
0
Fork 0
mirror of https://github.com/gnss-sdr/gnss-sdr synced 2025-06-26 15:12:51 +00:00
Code Issues Releases Wiki Activity

Add Table of Contents to README.med file

Browse Source 
Improve wording
This commit is contained in:
Carles Fernandez 2021-05-26 22:10:58 +02:00
parent b2fccc826e
commit 54f9a01082
No known key found for this signature in database
GPG Key ID: 4C583C52B0C3877D
1 changed files with 190 additions and 137 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

327
README.md
View File

@ -18,7 +18,7 @@ SPDX-FileCopyrightText: 2011-2021 Carles Fernandez-Prades <carles.fernandez@cttc
This program is a software-defined receiver which is able to process (that is, This program is a software-defined receiver which is able to process (that is,
to perform detection, synchronization, demodulation and decoding of the to perform detection, synchronization, demodulation and decoding of the
navigation message, computation of observables and, finally, computation of navigation message, computation of observables, and, finally, computation of
position fixes) the following Global Navigation Satellite System's signals: position fixes) the following Global Navigation Satellite System's signals:
In the L1 band: In the L1 band:
@ -44,7 +44,68 @@ raw sample file formats, generates processing outputs in standard formats,
allows for the full inspection of the whole signal processing chain, and offers allows for the full inspection of the whole signal processing chain, and offers
a framework for the development of new features. Please visit a framework for the development of new features. Please visit
[https://gnss-sdr.org](https://gnss-sdr.org "GNSS-SDR website") for more [https://gnss-sdr.org](https://gnss-sdr.org "GNSS-SDR website") for more
information about this open source software-defined GNSS receiver. information about this open-source, software-defined GNSS receiver.
# Table of Contents
<details>
<summary><b>(click to expand)</b></summary>
<!-- MarkdownTOC -->
1. [How to build GNSS-SDR](#how-to-build-gnss-sdr)
1. [GNU/Linux](#gnulinux)
1. [Alternative 1: Install dependencies using software packages](#alternative-1-install-dependencies-using-software-packages)
1. [Debian / Ubuntu](#debian--ubuntu)
1. [Arch Linux](#arch-linux)
1. [CentOS](#centos)
1. [Fedora](#fedora)
1. [OpenSUSE](#opensuse)
1. [Alternative 2: Install dependencies using PyBOMBS](#alternative-2-install-dependencies-using-pybombs)
1. [Manual installation of other required dependencies](#manual-installation-of-other-required-dependencies)
1. [Armadillo](#install-armadillo-a-c-linear-algebra-library)
1. [gflags](#install-gflags-a-commandline-flags-processing-module-for-c)
1. [google-glog](#install-glog-a-library-that-implements-application-level-logging)
1. [googletest](#download-the-google-c-testing-framework-also-known-as-google-test)
1. [GnuTLS or OpenSSL](#install-the-gnutls-or-openssl-libraries)
1. [matio](#install-matio-matlab-mat-file-io-library)
1. [Protocol Buffers](#install-protocol-buffers-a-portable-mechanism-for-serialization-of-structured-data)
1. [pugixml](#install-pugixml-a-light-weight-c-xml-processing-library)
1. [Clone GNSS-SDR's Git repository](#clone-gnss-sdrs-git-repository)
1. [Build and install GNSS-SDR](#build-and-install-gnss-sdr)
1. [Build OsmoSDR support (optional)](#build-osmosdr-support-optional)
1. [Build IIO support (optional)](#build-fmcomms2-based-sdr-hardware-support-optional)
1. [Build OpenCL support (optional)](#build-opencl-support-optional)
1. [Build CUDA support (optional)](#build-cuda-support-optional)
1. [Build a portable binary](#build-a-portable-binary)
1. [macOS](#macos)
1. [Macports](#macports)
1. [Homebrew](#homebrew)
1. [Build GNSS-SDR](#build-gnss-sdr)
1. [Other builds](#other-builds)
1. [Updating GNSS-SDR](#updating-gnss-sdr)
1. [Getting started](#getting-started)
1. [Using GNSS-SDR](#using-gnss-sdr)
1. [Control Plane](#control-plane)
1. [Configuration](#configuration)
1. [GNSS block factory](#gnss-block-factory)
1. [Signal Processing Plane](#signal-processing-plane)
1. [Signal Source](#signal-source)
1. [Signal Conditioner](#signal-conditioner)
1. [Data type adapter](#data-type-adapter)
1. [Input filter](#input-filter)
1. [Resampler](#resampler)
1. [Channel](#channel)
1. [Acquisition](#acquisition)
1. [Tracking](#tracking)
1. [Decoding of the navigation message](#decoding-of-the-navigation-message)
1. [Observables](#observables)
1. [Computation of Position, Velocity and Time](#computation-of-position-velocity-and-time)
1. [About the software license](#about-the-software-license)
1. [Publications and Credits](#publications-and-credits)
1. [Ok, now what?](#ok-now-what)
<!-- /MarkdownTOC -->
</details>
# How to build GNSS-SDR # How to build GNSS-SDR
@ -59,7 +120,7 @@ This section describes how to set up the compilation environment in GNU/Linux or
- Supported microprocessor architectures: - Supported microprocessor architectures:
- i386: Intel x86 instruction set (32-bit microprocessors). - i386: Intel x86 instruction set (32-bit microprocessors).
- amd64: also known as x86-64, the 64-bit version of the x86 instruction set, - amd64: also known as x86-64, the 64-bit version of the x86 instruction set,
originally created by AMD and implemented by AMD, Intel, VIA and others. originally created by AMD and implemented by AMD, Intel, VIA, and others.
- armel: ARM embedded ABI, supported on ARM v4t and higher. - armel: ARM embedded ABI, supported on ARM v4t and higher.
- armhf: ARM hard float, ARMv7 + VFP3-D16 floating-point hardware extension + - armhf: ARM hard float, ARMv7 + VFP3-D16 floating-point hardware extension +
Thumb-2 instruction set and above. Thumb-2 instruction set and above.
@ -68,7 +129,7 @@ This section describes how to set up the compilation environment in GNU/Linux or
- mipsel: MIPS architecture (little-endian, such as Loongson 3). - mipsel: MIPS architecture (little-endian, such as Loongson 3).
- mips64el: 64-bit version of MIPS architecture. - mips64el: 64-bit version of MIPS architecture.
- powerpc: the RISC 32-bit microprocessor architecture developed by IBM, - powerpc: the RISC 32-bit microprocessor architecture developed by IBM,
Motorola (now Freescale) and Apple. Motorola (now Freescale), and Apple.
- ppc64: 64-bit big-endian PowerPC architecture. - ppc64: 64-bit big-endian PowerPC architecture.
- ppc64el: 64-bit little-endian PowerPC architecture. - ppc64el: 64-bit little-endian PowerPC architecture.
- s390x: IBM System z architecture for mainframe computers. - s390x: IBM System z architecture for mainframe computers.
@ -82,7 +143,7 @@ the source code. It is in general not a good idea to mix both approaches.
### Alternative 1: Install dependencies using software packages ### Alternative 1: Install dependencies using software packages
If you want to start building and running GNSS-SDR as quick and easy as If you want to start building and running GNSS-SDR as quickly and easily as
possible, the best option is to install all the required dependencies as binary possible, the best option is to install all the required dependencies as binary
packages. packages.
@ -108,7 +169,7 @@ above).
**Note for Ubuntu 14.04 LTS "trusty" users:** you will need to build from source **Note for Ubuntu 14.04 LTS "trusty" users:** you will need to build from source
and install GNU Radio manually, as explained below, since GNSS-SDR requires and install GNU Radio manually, as explained below, since GNSS-SDR requires
`gnuradio-dev` >= 3.7.3, and Ubuntu 14.04 came with 3.7.2. Install all the `gnuradio-dev` >= 3.7.3, and Ubuntu 14.04 came with 3.7.2. Install all the
packages above BUT EXCEPT `libuhd-dev`, `gnuradio-dev` and `gr-osmosdr` (and packages above BUT EXCEPT `libuhd-dev`, `gnuradio-dev`, and `gr-osmosdr` (and
remove them if they are already installed in your machine), and install those remove them if they are already installed in your machine), and install those
dependencies using PyBOMBS. The same applies to `libmatio-dev`: Ubuntu 14.04 dependencies using PyBOMBS. The same applies to `libmatio-dev`: Ubuntu 14.04
came with 1.5.2 and the minimum required version is 1.5.3. Please do not install came with 1.5.2 and the minimum required version is 1.5.3. Please do not install
@ -205,9 +266,9 @@ Once you have installed these packages, you can jump directly to
### Alternative 2: Install dependencies using PyBOMBS ### Alternative 2: Install dependencies using PyBOMBS
This option is adequate if you are interested in development, in working with This option is adequate if you are interested in development, in working with
the most recent versions of software dependencies, want more fine tuning on the the most recent versions of software dependencies, want more fine-tuning on the
installed versions, or simply in building everything from the scratch just for installed versions, or simply in building everything from the scratch just for
the fun of it. In such cases, we recommend to use the fun of it. In such cases, we recommend using
[PyBOMBS](https://github.com/gnuradio/pybombs "Python Build Overlay Managed Bundle System") [PyBOMBS](https://github.com/gnuradio/pybombs "Python Build Overlay Managed Bundle System")
(Python Build Overlay Managed Bundle System), GNU Radio's meta-package manager (Python Build Overlay Managed Bundle System), GNU Radio's meta-package manager
tool that installs software from source, or whatever the local package manager tool that installs software from source, or whatever the local package manager
@ -240,7 +301,7 @@ Add list of default recipes:
$ pybombs recipes add-defaults $ pybombs recipes add-defaults
``` ```
Download, build and install GNU Radio, related drivers and some other extra Download, build and install GNU Radio, related drivers, and some other extra
modules into the directory `/path/to/prefix` (replace this path by your modules into the directory `/path/to/prefix` (replace this path by your
preferred one, for instance `$HOME/sdr`): preferred one, for instance `$HOME/sdr`):
@ -267,17 +328,17 @@ $ pybombs install gnss-sdr
``` ```
By default, PyBOMBS installs the ‘next’ branch of GNSS-SDR development, which is By default, PyBOMBS installs the ‘next’ branch of GNSS-SDR development, which is
the most recent version of the source code. This behaviour can be modified by the most recent version of the source code. This behavior can be modified by
altering the corresponding recipe at altering the corresponding recipe at
`$HOME/.pybombs/recipes/gr-recipes/gnss-sdr.lwr` `$HOME/.pybombs/recipes/gr-recipes/gnss-sdr.lwr`
In case you do not want to use PyBOMBS and prefer to build and install GNSS-SDR In case you do not want to use PyBOMBS and prefer to build and install GNSS-SDR
step by step (i.e., cloning the repository and doing the usual step by step (i.e., cloning the repository and doing the usual
`cmake .. && make && make install` dance), Armadillo, GFlags, Glog and GnuTLS `cmake .. && make && make install` dance), Armadillo, GFlags, Glog, GnuTLS, and
can be installed either by using PyBOMBS: Matio can be installed either by using PyBOMBS:
``` ```
$ pybombs install armadillo gflags glog gnutls $ pybombs install armadillo gflags glog gnutls matio
``` ```
or manually as explained below, and then please follow instructions on how to or manually as explained below, and then please follow instructions on how to
@ -304,8 +365,8 @@ The full stop separated from `cmake` by a space is important.
[CMake](https://cmake.org/ "CMake's Homepage") will figure out what other [CMake](https://cmake.org/ "CMake's Homepage") will figure out what other
libraries are currently installed and will modify Armadillo's configuration libraries are currently installed and will modify Armadillo's configuration
correspondingly. CMake will also generate a run-time armadillo library, which is 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. a combined alias for all the relevant libraries present on your system (e.g.,
BLAS, LAPACK and ATLAS). BLAS, LAPACK, and ATLAS).
#### Install [Gflags](https://github.com/gflags/gflags "Gflags' Homepage"), a commandline flags processing module for C++: #### Install [Gflags](https://github.com/gflags/gflags "Gflags' Homepage"), a commandline flags processing module for C++:
@ -341,7 +402,7 @@ $ unzip v1.10.x.zip
Please **DO NOT build or install** Google Test. Every user needs to compile Please **DO NOT build or install** Google Test. Every user needs to compile
tests using the same compiler flags used to compile the Google Test libraries; tests using the same compiler flags used to compile the Google Test libraries;
otherwise he or she may run into undefined behaviors (_i.e._, the tests can otherwise, he or she may run into undefined behaviors (_i.e._, the tests can
behave strangely and may even crash for no obvious reasons). The explanation is behave strangely and may even crash for no obvious reasons). The explanation is
that C++ has the One-Definition Rule: if two C++ source files contain different that C++ has the One-Definition Rule: if two C++ source files contain different
definitions of the same class/function/variable, and you link them together, you definitions of the same class/function/variable, and you link them together, you
@ -381,6 +442,18 @@ $ sudo pacman -S openssl # For Arch Linux
In case the GnuTLS library with openssl extensions package is not available in In case the GnuTLS library with openssl extensions package is not available in
your GNU/Linux distribution, GNSS-SDR can also work well with OpenSSL. your GNU/Linux distribution, GNSS-SDR can also work well with OpenSSL.
#### Install [Matio](https://github.com/tbeu/matio "Matio's Homepage"), MATLAB MAT file I/O library:
```
$ wget https://github.com/tbeu/matio/releases/download/v1.5.21/matio-1.5.21.tar.gz
$ tar xvfz matio-1.5.21.tar.gz
$ cd matio-1.5.21
$ ./configure
$ make
$ sudo make install
$ sudo ldconfig
```
#### Install [Protocol Buffers](https://developers.google.com/protocol-buffers/ "Protocol Buffers' Homepage"), a portable mechanism for serialization of structured data: #### Install [Protocol Buffers](https://developers.google.com/protocol-buffers/ "Protocol Buffers' Homepage"), a portable mechanism for serialization of structured data:
GNSS-SDR requires Protocol Buffers v3.0.0 or later. If the packages that come GNSS-SDR requires Protocol Buffers v3.0.0 or later. If the packages that come
@ -405,6 +478,19 @@ $ sudo make install
$ sudo ldconfig $ sudo ldconfig
``` ```
#### Install [Pugixml](https://pugixml.org/ "Pugixml's Homepage"), a light-weight C++ XML processing library:
```
$ wget https://github.com/zeux/pugixml/releases/download/v1.11.4/pugixml-1.11.4.tar.gz
$ tar xvfz pugixml-1.11.4.tar.gz
$ cd pugixml-1.11.4
$ mkdir build && cd build
$ cmake ..
$ make
$ sudo make install
$ sudo ldconfig
```
### <a name="download-and-build-linux">Clone GNSS-SDR's Git repository</a>: ### <a name="download-and-build-linux">Clone GNSS-SDR's Git repository</a>:
``` ```
@ -460,7 +546,7 @@ $ make
By default, CMake will build the Release version, meaning that the compiler will By default, CMake will build the Release version, meaning that the compiler will
generate a fast, optimized executable. This is the recommended build type when generate a fast, optimized executable. This is the recommended build type when
using an RF front-end and you need to attain real time. If working with a file using an RF front-end and you need to attain real-time. If working with a file
(and thus without real-time constraints), you may want to obtain more (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 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: logging. This can be done by building the Debug version, by doing:
@ -480,9 +566,9 @@ $ sudo make install
``` ```
This will also make a copy of the conf/ folder into This will also make a copy of the conf/ folder into
/usr/local/share/gnss-sdr/conf for your reference. We suggest to create a /usr/local/share/gnss-sdr/conf for your reference. We suggest creating a working
working directory at your preferred location and store your own configuration directory at your preferred location and store your own configuration and data
and data files there. files there.
You could be interested in creating the documentation (requires: You could be interested in creating the documentation (requires:
`sudo apt-get install doxygen-latex` in Ubuntu/Debian) by doing: `sudo apt-get install doxygen-latex` in Ubuntu/Debian) by doing:
@ -505,10 +591,10 @@ will create a PDF manual at build/docs/GNSS-SDR_manual.pdf. Finally,
$ make doc-clean $ make doc-clean
``` ```
will remove the content of previously-generated documentation. will remove the content of previously generated documentation.
GNSS-SDR comes with a library which is a module of the Vector-Optimized Library GNSS-SDR comes with a library which is a module of the Vector-Optimized Library
of Kernels (so called of Kernels (so-called
[VOLK_GNSSSDR](./src/algorithms/libs/volk_gnsssdr_module/volk_gnsssdr/README.md)) [VOLK_GNSSSDR](./src/algorithms/libs/volk_gnsssdr_module/volk_gnsssdr/README.md))
and a profiler that will build a config file for the best SIMD architecture for and a profiler that will build a config file for the best SIMD architecture for
your processor. Run `volk_gnsssdr_profile` that is installed into `$PREFIX/bin`. your processor. Run `volk_gnsssdr_profile` that is installed into `$PREFIX/bin`.
@ -544,40 +630,6 @@ and then import the created project into Eclipse:
After building the project, you will find the generated binaries at After building the project, you will find the generated binaries at
`eclipse/install`. `eclipse/install`.
###### Build GN3S V2 Custom firmware and driver (OPTIONAL):
Install the GNU Radio module:
```
$ git clone https://github.com/gnss-sdr/gr-gn3s
$ cd gr-gn3s/build
$ cmake ..
$ make
$ sudo make install
$ sudo ldconfig
```
Then configure GNSS-SDR to build the `GN3S_Signal_Source` by:
```
$ cd gnss-sdr/build
$ cmake -DENABLE_GN3S=ON ..
$ make
$ sudo make install
```
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
gr-gn3s/firmware/GN3S_v2/bin/gn3s_firmware.ihx. Please copy this file to the
application path.
(in order to disable the `GN3S_Signal_Source` compilation, you can pass
`-DENABLE_GN3S=OFF` to cmake and build GNSS-SDR again).
More info at https://github.com/gnss-sdr/gr-gn3s
###### Build OSMOSDR support (OPTIONAL): ###### Build OSMOSDR support (OPTIONAL):
Install the [OsmoSDR](https://osmocom.org/projects/sdr "OsmoSDR's Homepage") Install the [OsmoSDR](https://osmocom.org/projects/sdr "OsmoSDR's Homepage")
@ -834,7 +886,7 @@ $ open ./docs/html/index.html
``` ```
GNSS-SDR comes with a library which is a module of the Vector-Optimized Library GNSS-SDR comes with a library which is a module of the Vector-Optimized Library
of Kernels (so called of Kernels (so-called
[VOLK_GNSSSDR](./src/algorithms/libs/volk_gnsssdr_module/volk_gnsssdr/README.md)) [VOLK_GNSSSDR](./src/algorithms/libs/volk_gnsssdr_module/volk_gnsssdr/README.md))
and a profiler that will build a config file for the best SIMD architecture for and a profiler that will build a config file for the best SIMD architecture for
your processor. Run `volk_gnsssdr_profile` that is installed into `$PREFIX/bin`. your processor. Run `volk_gnsssdr_profile` that is installed into `$PREFIX/bin`.
@ -951,24 +1003,24 @@ Git commands `fetch` and `merge`, as described in our
The signal file can be easily recorded using the GNU Radio file sink in The signal file can be easily recorded using the GNU Radio file sink in
`gr_complex<float>` mode. 2. You will need a GPS active antenna, a `gr_complex<float>` mode. 2. You will need a GPS active antenna, a
[USRP](https://www.ettus.com/products/) and a suitable USRP daughter board to [USRP](https://www.ettus.com/products/) and a suitable USRP daughter board to
receive GPS L1 C/A signals. GNSS-SDR require to have at least 2 MHz of receive GPS L1 C/A signals. GNSS-SDR requires to have at least 2 MHz of
bandwidth in 1.57542 GHz. (remember to enable the DC bias with the daughter bandwidth in 1.57542 GHz. (remember to enable the DC bias with the
board jumper). We use a [DBSRX2](https://www.ettus.com/all-products/DBSRX2/) daughterboard jumper). We use a
to do the task, but you can try the newer Ettus' daughter boards as well. 3. [DBSRX2](https://www.ettus.com/all-products/DBSRX2/) to do the task, but you
The easiest way to capture a signal file is to use the GNU Radio Companion can try the newer Ettus' daughter boards as well. 3. The easiest way to
GUI. Only two blocks are needed: a USRP signal source connected to complex capture a signal file is to use the GNU Radio Companion GUI. Only two blocks
float file sink. You need to tune the USRP central frequency and decimation are needed: a USRP signal source connected to a complex float file sink. You
factor using USRP signal source properties box. We suggest using a decimation need to tune the USRP central frequency and decimation factor using the USRP
factor of 20 if you use the USRP2. This will give you 100/20 = 5 MSPS which signal source properties box. We suggest using a decimation factor of 20 if
will be enough to receive GPS L1 C/A signals. The front-end gain should also you use the USRP2. This will give you 100/20 = 5 MSPS which will be enough to
be configured. In our test with the DBSRX2 we obtained good results with receive GPS L1 C/A signals. The front-end gain should also be configured. In
`G=50`. 4. Capture at least 80 seconds of signal in open sky conditions. our test with the DBSRX2 we obtained good results with `G=50`. 4. Capture at
During the process, be aware of USRP driver buffer underruns messages. If least 80 seconds of signal in open sky conditions. During the process, be
your hard disk is not fast enough to write data at this speed you can capture aware of USRP driver buffer underruns messages. If your hard disk is not fast
to a virtual RAM drive. 80 seconds of signal at 5 MSPS occupies less than 3 enough to write data at this speed you can capture it to a virtual RAM drive.
Gbytes using `gr_complex<float>`. 5. If you have no access to an RF 80 seconds of signal at 5 MSPS occupies less than 3 Gbytes using
front-end, you can download a sample raw data file (that contains GPS and `gr_complex<float>`. If you have no access to an RF front-end, you can
Galileo signals) from download a sample raw data file (that contains GPS and Galileo signals) from
[here](https://sourceforge.net/projects/gnss-sdr/files/data/). [here](https://sourceforge.net/projects/gnss-sdr/files/data/).
3. You are ready to configure the receiver to use your captured file among other 3. You are ready to configure the receiver to use your captured file among other
parameters: parameters:
@ -1035,29 +1087,29 @@ file.
GNSS-SDR's main method initializes the logging library, processes the command GNSS-SDR's main method initializes the logging library, processes the command
line flags, if any, provided by the user and instantiates a line flags, if any, provided by the user and instantiates a
[ControlThread](./src/core/receiver/control_thread.h) object. Its constructor [ControlThread](./src/core/receiver/control_thread.h) object. Its constructor
reads the configuration file, creates a control queue and creates a flowgraph reads the configuration file, creates a control queue, and creates a flowgraph
according to the configuration. Then, the program's main method calls the run() according to the configuration. Then, the program's main method calls the run()
method of the instantiated object, an action that connects the flowgraph and method of the instantiated object, an action that connects the flowgraph and
starts running it. After that, and until a stop message is received, it reads starts running it. After that, and until a stop message is received, it reads
control messages sent by the receiver's modules through a safe-thread queue and control messages sent by the receiver's modules through a safe-thread queue and
processes them. Finally, when a stop message is received, the main method processes them. Finally, when a stop message is received, the main method
executes the destructor of the ControlThread object, which deallocates memory, executes the destructor of the ControlThread object, which deallocates memory,
does other cleanup and exits the program. does other cleanup, and exits the program.
The [GNSSFlowgraph](./src/core/receiver/gnss_flowgraph.h) class is responsible The [GNSSFlowgraph](./src/core/receiver/gnss_flowgraph.h) class is responsible
for preparing the graph of blocks according to the configuration, running it, for preparing the graph of blocks according to the configuration, running it,
modifying it during run-time and stopping it. Blocks are identified by its role. modifying it during run-time, and stopping it. Blocks are identified by their
This class knows which roles it has to instantiate and how to connect them. It role. This class knows which roles it has to instantiate and how to connect
relies on the configuration to get the correct instances of the roles it needs them. It relies on the configuration to get the correct instances of the roles
and then it applies the connections between GNU Radio blocks to make the graph it needs and then it applies the connections between GNU Radio blocks to make
ready to be started. The complexity related to managing the blocks and the data the graph ready to be started. The complexity related to managing the blocks and
stream is handled by GNU Radio's `gr::top_block` class. GNSSFlowgraph wraps the the data stream is handled by GNU Radio's `gr::top_block` class. GNSSFlowgraph
`gr::top_block` instance so we can take advantage of the `gnss_block_factory` wraps the `gr::top_block` instance so we can take advantage of the
(see below), the configuration system and the processing blocks. This class is `gnss_block_factory` (see below), the configuration system, and the processing
also responsible for applying changes to the configuration of the flowgraph blocks. This class is also responsible for applying changes to the configuration
during run-time, dynamically reconfiguring channels: it selects the strategy for of the flowgraph during run-time, dynamically reconfiguring channels: it selects
selecting satellites. This can range from a sequential search over all the the strategy for selecting satellites. This can range from a sequential search
satellites' ID to other more efficient approaches. over all the satellites' ID to other more efficient approaches.
The Control Plane is in charge of creating a flowgraph according to the The Control Plane is in charge of creating a flowgraph according to the
configuration and then managing the modules. Configuration allows users to configuration and then managing the modules. Configuration allows users to
@ -1066,7 +1118,7 @@ define in an easy way their own custom receiver by specifying the flowgraph
channel and each module, strategies for satellite selection, type of output channel and each module, strategies for satellite selection, type of output
format, etc.). Since it is difficult to foresee what future module format, etc.). Since it is difficult to foresee what future module
implementations will be needed in terms of configuration, we used a very simple implementations will be needed in terms of configuration, we used a very simple
approach that can be extended without a major impact in the code. This can be approach that can be extended without a major impact on the code. This can be
achieved by simply mapping the names of the variables in the modules with the achieved by simply mapping the names of the variables in the modules with the
names of the parameters in the configuration. names of the parameters in the configuration.
@ -1122,7 +1174,7 @@ encapsulates the complexity of blocks' instantiation. With that approach, adding
a new block that requires new parameters will be as simple as adding the block a new block that requires new parameters will be as simple as adding the block
class and modifying the factory to be able to instantiate it. This loose class and modifying the factory to be able to instantiate it. This loose
coupling between the blocks' implementations and the syntax of the configuration coupling between the blocks' implementations and the syntax of the configuration
enables extending the application capacities in a high degree. It also allows enables extending the application capacities to a high degree. It also allows
producing fully customized receivers, for instance a testbed for acquisition producing fully customized receivers, for instance a testbed for acquisition
algorithms, and to place observers at any point of the receiver chain. algorithms, and to place observers at any point of the receiver chain.
@ -1154,16 +1206,16 @@ are required to be implemented by a derived class.
Subclassing GNSSBlockInterface, we defined interfaces for the GNSS receiver Subclassing GNSSBlockInterface, we defined interfaces for the GNSS receiver
blocks depicted in the figure above. This hierarchy provides the definition of blocks depicted in the figure above. This hierarchy provides the definition of
different algorithms and different implementations, which will be instantiated different algorithms and different implementations, which will be instantiated
according to the configuration. This strategy allows multiple implementations according to the configuration. This strategy allows multiple implementations to
sharing a common interface, achieving the objective of decoupling interfaces share a common interface, achieving the objective of decoupling interfaces from
from implementations: it defines a family of algorithms, encapsulates each one, implementations: it defines a family of algorithms, encapsulates each one, and
and makes them interchangeable. Hence, we let the algorithm vary independently makes them interchangeable. Hence, we let the algorithm vary independently of
of the program that uses it. the program that uses it.
Internally, GNSS-SDR makes use of the complex data types defined by Internally, GNSS-SDR makes use of the complex data types defined by
[VOLK](https://www.libvolk.org/ "Vector-Optimized Library of Kernels home"). [VOLK](https://www.libvolk.org/ "Vector-Optimized Library of Kernels home").
They are fundamental for handling sample streams in which samples are complex They are fundamental for handling sample streams in which samples are complex
numbers with real and imaginary components of 8, 16 or 32 bits, common formats numbers with real and imaginary components of 8, 16, or 32 bits, common formats
delivered by GNSS (and generic SDR) radio frequency front-ends. The following delivered by GNSS (and generic SDR) radio frequency front-ends. The following
list shows the data type names that GNSS-SDR exposes through the configuration list shows the data type names that GNSS-SDR exposes through the configuration
file: file:
@ -1192,7 +1244,7 @@ parameters can be found at the
### Signal Source ### Signal Source
The input of a software receiver are the raw bits that come out from the The inputs of a software receiver are the raw bits that come out from the
front-end's analog-to-digital converter (ADC). Those bits can be read from a front-end's analog-to-digital converter (ADC). Those bits can be read from a
file stored in the hard disk or directly in real-time from a hardware device file stored in the hard disk or directly in real-time from a hardware device
through USB or Ethernet buses. through USB or Ethernet buses.
@ -1204,8 +1256,8 @@ USB or Ethernet buses. Since real-time processing requires a highly optimized
implementation of the whole receiver, this module also allows reading samples implementation of the whole receiver, this module also allows reading samples
from a file stored in a hard disk, and thus processing without time constraints. from a file stored in a hard disk, and thus processing without time constraints.
Relevant parameters of those samples are the intermediate frequency (or baseband Relevant parameters of those samples are the intermediate frequency (or baseband
I&Q components), the sampling rate and number of bits per sample, that must be I&Q components), the sampling rate, and the number of bits per sample, which
specified by the user in the configuration file. must be specified by the user in the configuration file.
This module also performs bit-depth adaptation, since most of the existing RF This module also performs bit-depth adaptation, since most of the existing RF
front-ends provide samples quantized with 2 or 3 bits, while operations inside front-ends provide samples quantized with 2 or 3 bits, while operations inside
@ -1213,7 +1265,7 @@ the processor are performed on 32- or 64-bit words, depending on its
architecture. Although there are implementations of the most intensive architecture. Although there are implementations of the most intensive
computational processes (mainly correlation) that take advantage of specific computational processes (mainly correlation) that take advantage of specific
data types and architectures for the sake of efficiency, the approach is data types and architectures for the sake of efficiency, the approach is
processor-specific and hardly portable. We suggest to keep signal samples in processor-specific and hardly portable. We suggest keeping signal samples in
standard data types and letting the compiler select the best library version standard data types and letting the compiler select the best library version
(implemented using SIMD or any other processor-specific technology) of the (implemented using SIMD or any other processor-specific technology) of the
required routines for a given processor. required routines for a given processor.
@ -1246,14 +1298,14 @@ complex stream via Data Type Adapter block (see below).
**_Example: Two-bit packed file source_** **_Example: Two-bit packed file source_**
Sometimes, samples are stored in files with a format which is not in the list of Sometimes, samples are stored in files with a format that is not in the list of
_native_ types supported by the `File_Signal_Source` implementation (i.e, it is _native_ types supported by the `File_Signal_Source` implementation (i.e, it is
not among `byte`, `ibyte`, `short`, `ishort`, `float` or `gr_complex`). This is not among `byte`, `ibyte`, `short`, `ishort`, `float`, or `gr_complex`). This is
the case of 2-bit samples, which is a common format delivered by GNSS RF the case of 2-bit samples, which is a common format delivered by GNSS RF
front-ends. The `Two_Bit_Packed_File_Signal_Source` implementation allows front-ends. The `Two_Bit_Packed_File_Signal_Source` implementation allows
reading two-bit length samples from a file. The data is assumed to be packed as reading two-bit length samples from a file. The data is assumed to be packed as
bytes `item_type=byte` or shorts `item_type=short` so that there are 4 two bit bytes `item_type=byte` or shorts `item_type=short` so that there are 4 two-bit
samples in each byte. The two bit values are assumed to have the following samples in each byte. The two-bit values are assumed to have the following
interpretation: interpretation:
| **b_1** | **b_0** | **Value** | | **b_1** | **b_0** | **Value** |
@ -1263,14 +1315,14 @@ interpretation:
| 1 | 0 | -3 | | 1 | 0 | -3 |
| 1 | 1 | -1 | | 1 | 1 | -1 |
Within a byte the samples may be packed in big endian `big_endian_bytes=true` Within a byte the samples may be packed in big-endian `big_endian_bytes=true`
(if the most significant byte value is stored at the memory location with the (if the most significant byte value is stored at the memory location with the
lowest address, the next byte value in significance is stored at the following lowest address, the next byte value in significance is stored at the following
memory location, and so on) or little endian `big_endian_bytes=false` (if the memory location, and so on) or little-endian `big_endian_bytes=false` (if the
least significant byte value is at the lowest address, and the other bytes least significant byte value is at the lowest address, and the other bytes
follow in increasing order of significance). If the order is big endian then the follow in increasing order of significance). If the order is big-endian then the
most significant two bits will form the first sample output, otherwise the least most significant two bits will form the first sample output. Otherwise, the
significant two bits will be used. least significant two bits will be used.
Additionally, the samples may be either real `sample_type=real`, or complex. If Additionally, the samples may be either real `sample_type=real`, or complex. If
the sample type is complex, then the samples are either stored in the order: the sample type is complex, then the samples are either stored in the order:
@ -1278,8 +1330,8 @@ real, imag, real, imag, ... `sample_type=iq` or in the order: imag, real, imag,
real, ... `sample_type=qi`. real, ... `sample_type=qi`.
Finally, if the data is stored as shorts `item_type=short`, then it may be Finally, if the data is stored as shorts `item_type=short`, then it may be
stored in either big endian `big_endian_items=true` or little endian stored in either big-endian `big_endian_items=true` or little-endian
`big_endian_items=false`. If the shorts are big endian then the 2nd byte in each `big_endian_items=false`. If the shorts are big-endian then the 2nd byte in each
short is output first. short is output first.
The output data type is either `float` or `gr_complex` depending on whether or The output data type is either `float` or `gr_complex` depending on whether or
@ -1443,8 +1495,9 @@ More documentation and examples are available at the
The signal conditioner is in charge of resampling the signal and delivering a The signal conditioner is in charge of resampling the signal and delivering a
reference sample rate to the downstream processing blocks, acting as a facade reference sample rate to the downstream processing blocks, acting as a facade
between the signal source and the synchronization channels, providing a between the signal source and the synchronization channels, providing a
simplified interface to the input signal. In case of multiband front-ends, this simplified interface to the input signal. In the case of multiband front-ends,
module would be in charge of providing a separated data stream for each band. this module would be in charge of providing a separated data stream for each
band.
If your signal source is providing baseband signal samples of type `gr_complex` If your signal source is providing baseband signal samples of type `gr_complex`
at 4 Msps, you can bypass the Signal Conditioner block by: at 4 Msps, you can bypass the Signal Conditioner block by:
@ -1455,7 +1508,7 @@ SignalConditioner.implementation=Pass_Through
If you need to adapt some aspect of your signal, you can enable the Signal If you need to adapt some aspect of your signal, you can enable the Signal
Conditioner and configure three internal blocks: a data type adapter, an input Conditioner and configure three internal blocks: a data type adapter, an input
signal and a resampler. signal, and a resampler.
``` ```
;#[Signal_Conditioner] enables this block. Then you have to configure [DataTypeAdapter], [InputFilter] and [Resampler] blocks ;#[Signal_Conditioner] enables this block. Then you have to configure [DataTypeAdapter], [InputFilter] and [Resampler] blocks
@ -1485,7 +1538,7 @@ More documentation at the
This block filters the input data. It can be combined with frequency translation This block filters the input data. It can be combined with frequency translation
for IF signals. The computation of the filter taps is based on parameters of GNU for IF signals. The computation of the filter taps is based on parameters of GNU
Radio's function Radio's function
[pm_remez](https://www.gnuradio.org/doc/doxygen/pm__remez_8h.html), that [pm_remez](https://www.gnuradio.org/doc/doxygen/pm__remez_8h.html), which
calculates the optimal (in the Chebyshev/minimax sense) FIR filter impulse calculates the optimal (in the Chebyshev/minimax sense) FIR filter impulse
response given a set of band edges, the desired response on those bands, and the response given a set of band edges, the desired response on those bands, and the
weight given to the error in those bands. weight given to the error in those bands.
@ -1566,7 +1619,7 @@ More documentation at the
A channel encapsulates all signal processing devoted to a single satellite. A channel encapsulates all signal processing devoted to a single satellite.
Thus, it is a large composite object which encapsulates the acquisition, Thus, it is a large composite object which encapsulates the acquisition,
tracking and navigation data decoding modules. As a composite object, it can be tracking, and navigation data decoding modules. As a composite object, it can be
treated as a single entity, meaning that it can be easily replicated. Since the treated as a single entity, meaning that it can be easily replicated. Since the
number of channels is selectable by the user in the configuration file, this number of channels is selectable by the user in the configuration file, this
approach helps to improve the scalability and maintainability of the receiver. approach helps to improve the scalability and maintainability of the receiver.
@ -1624,10 +1677,10 @@ ephemeris and almanac data is still valid, or this information is provided by
other means), and an acquisition process can finish deciding that the satellite other means), and an acquisition process can finish deciding that the satellite
is not present, that longer integration is needed in order to confirm the is not present, that longer integration is needed in order to confirm the
presence of the satellite, or declaring the satellite present. In the latter presence of the satellite, or declaring the satellite present. In the latter
case, acquisition process should stop and trigger the tracking module with case, the acquisition process should stop and trigger the tracking module with
coarse estimations of the synchronization parameters. The mathematical coarse estimations of the synchronization parameters. The mathematical
abstraction used to design this logic is known as finite state machine (FSM), abstraction used to design this logic is known as a finite state machine (FSM),
that is a behavior model composed of a finite number of states, transitions which is a behavior model composed of a finite number of states, transitions
between those states, and actions. between those states, and actions.
The abstract class [ChannelInterface](./src/core/interfaces/channel_interface.h) The abstract class [ChannelInterface](./src/core/interfaces/channel_interface.h)
@ -1643,11 +1696,11 @@ More documentation at the
The first task of a GNSS receiver is to detect the presence or absence of The first task of a GNSS receiver is to detect the presence or absence of
in-view satellites. This is done by the acquisition system process, which also in-view satellites. This is done by the acquisition system process, which also
provides a coarse estimation of two signal parameters: the frequency shift with provides a coarse estimation of two signal parameters: the frequency shift with
respect to the nominal frequency, and a delay term which allows the receiver to respect to the nominal frequency, and a delay term that allows the receiver to
create a local code aligned with the incoming code. create a local code aligned with the incoming code.
[AcquisitionInterface](./src/core/interfaces/acquisition_interface.h) is the [AcquisitionInterface](./src/core/interfaces/acquisition_interface.h) is the
common interface for all the acquisition algorithms and their corresponding common interface for all the acquisition algorithms and their corresponding
implementations. Algorithms' interface, that may vary depending on the use of implementations. Algorithms' interface, which may vary depending on the use of
information external to the receiver, such as in Assisted GNSS, is defined in information external to the receiver, such as in Assisted GNSS, is defined in
classes referred to as _adapters_. These adapters wrap the GNU Radio blocks classes referred to as _adapters_. These adapters wrap the GNU Radio blocks
interface into a compatible interface expected by AcquisitionInterface. This interface into a compatible interface expected by AcquisitionInterface. This
@ -1789,13 +1842,13 @@ More documentation at the
Most of GNSS signal links are modulated by a navigation message containing the Most of GNSS signal links are modulated by a navigation message containing the
time the message was transmitted, orbital parameters of satellites (also known time the message was transmitted, orbital parameters of satellites (also known
as ephemeris) and an almanac (information about the general system health, rough as ephemeris), and an almanac (information about the general system health,
orbits of all satellites in the network as well as data related to error rough orbits of all satellites in the network as well as data related to error
correction). Navigation data bits are structured in words, pages, subframes, correction). Navigation data bits are structured in words, pages, subframes,
frames and superframes. Sometimes, bits corresponding to a single parameter are frames, and superframes. Sometimes, bits corresponding to a single parameter are
spread over different words, and values extracted from different frames are spread over different words, and values extracted from different frames are
required for proper decoding. Some words are for synchronization purposes, required for proper decoding. Some words are for synchronization purposes,
others for error control and others contain actual information. There are also others for error control, and others contain actual information. There are also
error control mechanisms, from parity checks to forward error correction (FEC) error control mechanisms, from parity checks to forward error correction (FEC)
encoding and interleaving, depending on the system. All this decoding complexity encoding and interleaving, depending on the system. All this decoding complexity
is managed by a finite state machine. is managed by a finite state machine.
@ -1837,7 +1890,7 @@ More documentation at the
GNSS systems provide different kinds of observations. The most commonly used are GNSS systems provide different kinds of observations. The most commonly used are
the code observations, also called pseudoranges. The _pseudo_ comes from the the code observations, also called pseudoranges. The _pseudo_ comes from the
fact that on the receiver side the clock error is unknown and thus the fact that on the receiver side the clock error is unknown and thus the
measurement is not a pure range observation. High accuracy applications also use measurement is not a pure range observation. High-accuracy applications also use
the carrier phase observations, which are based on measuring the difference the carrier phase observations, which are based on measuring the difference
between the carrier phase transmitted by the GNSS satellites and the phase of between the carrier phase transmitted by the GNSS satellites and the phase of
the carrier generated in the receiver. Both observables are computed from the the carrier generated in the receiver. Both observables are computed from the
@ -1865,14 +1918,14 @@ More documentation at the
Although data processing for obtaining high-accuracy PVT solutions is out of the Although data processing for obtaining high-accuracy PVT solutions is out of the
scope of GNSS-SDR, we provide a module that can compute position fixes (stored scope of GNSS-SDR, we provide a module that can compute position fixes (stored
in GIS-friendly formats such as [GeoJSON](https://tools.ietf.org/html/rfc7946), in GIS-friendly formats such as [GeoJSON](https://tools.ietf.org/html/rfc7946),
[GPX](https://www.topografix.com/gpx.asp) and [GPX](https://www.topografix.com/gpx.asp), and
[KML](https://www.opengeospatial.org/standards/kml), or transmitted via serial [KML](https://www.opengeospatial.org/standards/kml), or transmitted via serial
port as [NMEA 0183](https://en.wikipedia.org/wiki/NMEA_0183) messages), and port as [NMEA 0183](https://en.wikipedia.org/wiki/NMEA_0183) messages), and
leaves room for more sophisticated positioning methods by storing observables leaves room for more sophisticated positioning methods by storing observables
and navigation data in [RINEX](https://en.wikipedia.org/wiki/RINEX) files (v2.11 and navigation data in [RINEX](https://en.wikipedia.org/wiki/RINEX) files (v2.11
or v3.02), and generating or v3.02), and generating
[RTCM](https://www.rtcm.org/ "Radio Technical Commission for Maritime Services") [RTCM](https://www.rtcm.org/ "Radio Technical Commission for Maritime Services")
3.2 messages that can be disseminated through the Internet in real time. 3.2 messages that can be disseminated through the Internet in real-time.
The common interface is [PvtInterface](./src/core/interfaces/pvt_interface.h). The common interface is [PvtInterface](./src/core/interfaces/pvt_interface.h).
@ -1926,7 +1979,7 @@ PVT.rtcm_MT1077_rate_ms=1000
[Marble](https://marble.kde.org), [osgEarth](http://osgearth.org), or used [Marble](https://marble.kde.org), [osgEarth](http://osgearth.org), or used
with the [NASA World Wind SDK for Java](https://worldwind.arc.nasa.gov/java/). with the [NASA World Wind SDK for Java](https://worldwind.arc.nasa.gov/java/).
- **GPX** (the GPS Exchange Format) is a light-weight XML data format for the - **GPX** (the GPS Exchange Format) is a lightweight XML data format for the
interchange of GPS data (waypoints, routes, and tracks) between applications interchange of GPS data (waypoints, routes, and tracks) between applications
and Web services on the Internet. The format is open and can be used without and Web services on the Internet. The format is open and can be used without
the need to pay license fees, and it is supported by a the need to pay license fees, and it is supported by a
@ -1934,7 +1987,7 @@ PVT.rtcm_MT1077_rate_ms=1000
- **NMEA 0183** is a combined electrical and data specification for - **NMEA 0183** is a combined electrical and data specification for
communication between marine electronics such as echo sounder, sonars, communication between marine electronics such as echo sounder, sonars,
anemometer, gyrocompass, autopilot, GPS receivers and many other types of anemometer, gyrocompass, autopilot, GPS receivers, and many other types of
instruments. It has been defined by, and is controlled by, the U.S. instruments. It has been defined by, and is controlled by, the U.S.
[National Marine Electronics Association](https://www.nmea.org/). The NMEA [National Marine Electronics Association](https://www.nmea.org/). The NMEA
0183 standard uses a simple ASCII, serial communications protocol that defines 0183 standard uses a simple ASCII, serial communications protocol that defines
@ -1959,7 +2012,7 @@ PVT.rtcm_MT1077_rate_ms=1000
(usually with other data unknown to the original receiver, such as better (usually with other data unknown to the original receiver, such as better
models of the atmospheric conditions at time of measurement). RINEX files can models of the atmospheric conditions at time of measurement). RINEX files can
be used by software packages such as [GPSTk](https://github.com/SGL-UT/GPSTk), be used by software packages such as [GPSTk](https://github.com/SGL-UT/GPSTk),
[RTKLIB](http://www.rtklib.com/) and [gLAB](https://gage.upc.edu/gLAB/). [RTKLIB](http://www.rtklib.com/), and [gLAB](https://gage.upc.edu/gLAB/).
GNSS-SDR by default generates RINEX version GNSS-SDR by default generates RINEX version
[3.02](ftp://igs.org/pub/data/format/rinex302.pdf). If [3.02](ftp://igs.org/pub/data/format/rinex302.pdf). If
[2.11](ftp://igs.org/pub/data/format/rinex211.txt) is needed, it can be [2.11](ftp://igs.org/pub/data/format/rinex211.txt) is needed, it can be
@ -1974,7 +2027,7 @@ PVT.rinex_version=2
correction applications. Developed by the Radio Technical Commission for correction applications. Developed by the Radio Technical Commission for
Maritime Services Maritime Services
([RTCM](https://www.rtcm.org/ "Radio Technical Commission for Maritime Services")), ([RTCM](https://www.rtcm.org/ "Radio Technical Commission for Maritime Services")),
they have become an industry standard for communication of correction they have become an industry standard for the communication of correction
information. GNSS-SDR implements RTCM version 3.2, defined in the document information. GNSS-SDR implements RTCM version 3.2, defined in the document
_RTCM 10403.2, Differential GNSS (Global Navigation Satellite Systems) _RTCM 10403.2, Differential GNSS (Global Navigation Satellite Systems)
Services - Version 3_ (February 1, 2013), which can be Services - Version 3_ (February 1, 2013), which can be
@ -1993,7 +2046,7 @@ PVT.rinex_version=2
operate on port 2101 (which is the recommended port for RTCM services operate on port 2101 (which is the recommended port for RTCM services
according to the Internet Assigned Numbers Authority, according to the Internet Assigned Numbers Authority,
[IANA](https://www.iana.org/assignments/service-names-port-numbers/ "Service Name and Transport Protocol Port Number Registry")), [IANA](https://www.iana.org/assignments/service-names-port-numbers/ "Service Name and Transport Protocol Port Number Registry")),
and will identify the Reference Station with ID=1234. This behaviour can be and will identify the Reference Station with ID=1234. This behavior can be
changed in the configuration file: changed in the configuration file:
``` ```
@ -2004,9 +2057,9 @@ PVT.rtcm_station_id=1111
**Important note:** **Important note:**
In order to get well-formatted GeoJSON, KML and RINEX files, always terminate In order to get well-formatted GeoJSON, KML, and RINEX files, always terminate
`gnss-sdr` execution by pressing key `q` and then key `ENTER`. Those files will `gnss-sdr` execution by pressing key `q` and then key `ENTER`. Those files will
be automatically deleted if no position fix have been obtained during the be automatically deleted if no position fix has been obtained during the
execution of the software receiver. execution of the software receiver.
More documentation at the More documentation at the
@ -2084,7 +2137,7 @@ processed.
Another interesting option is working in real-time with an RF front-end. We Another interesting option is working in real-time with an RF front-end. We
provide drivers for UHD-compatible hardware such as the provide drivers for UHD-compatible hardware such as the
[USRP family](https://www.ettus.com/product), for OsmoSDR and other front-ends [USRP family](https://www.ettus.com/product), for OsmoSDR and other front-ends
(HackRF, bladeRF, LimeSDR), for the GN3S v2 USB dongle and for some DVB-T USB (HackRF, bladeRF, LimeSDR), for the GN3S v2 USB dongle, and for some DVB-T USB
dongles. Start with a low number of channels and then increase it in order to dongles. Start with a low number of channels and then increase it in order to
test how many channels your processor can handle in real-time. test how many channels your processor can handle in real-time.