-
Notifications
You must be signed in to change notification settings - Fork 7
/
README.original
2102 lines (1717 loc) · 87.4 KB
/
README.original
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!-- prettier-ignore-start -->
[comment]: # (
SPDX-License-Identifier: GPL-3.0-or-later
)
[comment]: # (
SPDX-FileCopyrightText: 2011-2020 Carles Fernandez-Prades <[email protected]>
)
<!-- prettier-ignore-end -->
[](https://gnss-sdr.org "GNSS-SDR website")
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://api.reuse.software/info/github.com/gnss-sdr/gnss-sdr)
[](CODE_OF_CONDUCT.md)
**Welcome to GNSS-SDR!**
This program is a software-defined receiver which is able to process (that is,
to perform detection, synchronization, demodulation and decoding of the
navigation message, computation of observables and, finally, computation of
position fixes) the following Global Navigation Satellite System's signals:
In the L1 band:
- 🛰 GLONASS L1 C/A (centered at 1602.00 MHz) :white_check_mark:
- 🛰 GPS L1 C/A (centered at 1575.42 MHz) :white_check_mark:
- 🛰 Galileo E1b/c (centered at 1575.42 MHz) :white_check_mark:
- 🛰 BeiDou B1I (centered at 1561.098 MHz) :white_check_mark:
In the L2 band:
- 🛰 BeiDou B3I (centered at 1268.520 MHz) :white_check_mark:
- 🛰 GLONASS L2 C/A (centered at 1246.00 MHz) :white_check_mark:
- 🛰 GPS L2C (centered at 1227.60 MHz) :white_check_mark:
In the L5 band:
- 🛰 GPS L5 (centered at 1176.45 MHz) :white_check_mark:
- 🛰 Galileo E5a (centered at 1176.45 MHz) :white_check_mark:
GNSS-SDR provides interfaces for a wide range of radio frequency front-ends and
raw sample file formats, generates processing outputs in standard formats,
allows for the full inspection of the whole signal processing chain, and offers
a framework for the development of new features. Please visit
[https://gnss-sdr.org](https://gnss-sdr.org "GNSS-SDR website") for more
information about this open source software-defined GNSS receiver.
# How to build GNSS-SDR
This section describes how to set up the compilation environment in GNU/Linux or
[macOS / Mac OS X](#macosx), and to build GNSS-SDR. See also our
[build and install page](https://gnss-sdr.org/build-and-install/ "GNSS-SDR's Build and Install").
## GNU/Linux
- Tested distributions: Ubuntu 14.04 LTS and above; Debian 8.0 "jessie" and
above; Arch Linux; CentOS 7; Fedora 26 and above; OpenSUSE 42.3 and above.
- Supported microprocessor architectures:
- i386: Intel x86 instruction set (32-bit microprocessors).
- 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.
- armel: ARM embedded ABI, supported on ARM v4t and higher.
- armhf: ARM hard float, ARMv7 + VFP3-D16 floating-point hardware extension +
Thumb-2 instruction set and above.
- arm64: ARM 64 bits or ARMv8.
- mips: MIPS architecture (big-endian, such as those manufactured by SGI).
- mipsel: MIPS architecture (little-endian, such as Loongson 3).
- mips64el: 64-bit version of MIPS architecture.
- powerpc: the RISC 32-bit microprocessor architecture developed by IBM,
Motorola (now Freescale) and Apple.
- ppc64: 64-bit big-endian PowerPC architecture.
- ppc64el: 64-bit little-endian PowerPC architecture.
- s390x: IBM System z architecture for mainframe computers.
Older distribution releases might work as well, but you will need GCC 4.7 or
newer.
Before building GNSS-SDR, you need to install all the required dependencies.
There are two alternatives here: through software packages or building them from
the source code. It is in general not a good idea to mix both approaches.
### Alternative 1: Install dependencies using software packages
If you want to start building and running GNSS-SDR as quick and easy as
possible, the best option is to install all the required dependencies as binary
packages.
#### Debian / Ubuntu
If you are using Debian 8, Ubuntu 14.10 or above, this can be done by copying
and pasting the following line in a terminal:
```
$ sudo apt-get install build-essential cmake git pkg-config libboost-dev libboost-date-time-dev \
libboost-system-dev libboost-filesystem-dev libboost-thread-dev libboost-chrono-dev \
libboost-serialization-dev liblog4cpp5-dev libuhd-dev gnuradio-dev gr-osmosdr \
libblas-dev liblapack-dev libarmadillo-dev libgflags-dev libgoogle-glog-dev \
libgnutls-openssl-dev libpcap-dev libmatio-dev libpugixml-dev libgtest-dev \
libprotobuf-dev protobuf-compiler python3-mako
```
Please note that the required files from `libgtest-dev` were moved to
`googletest` in Debian 9 "stretch" and Ubuntu 18.04 "bionic", and moved back
again to `libgtest-dev` in Debian 10 "buster" and Ubuntu 18.10 "cosmic" (and
above).
**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
`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
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
came with 1.5.2 and the minimum required version is 1.5.3. Please do not install
the `libmatio-dev` package and install `libtool`, `automake` and `libhdf5-dev`
instead. A recent version of the library will be downloaded and built
automatically if CMake does not find it installed.
In distributions older than Ubuntu 16.04 or Debian 9, `python3-mako` must be
replaced by `python-mako`. For Ubuntu 14.04, you will need to add the package
`python-six` to the list of dependencies.
**Note for Debian 8 "jessie" users:** please see the note about `libmatio-dev`
above. Install `libtool`, `automake` and `libhdf5-dev` instead. You will also
need `python-six`.
Once you have installed these packages, you can jump directly to
[download the source code and build GNSS-SDR](#download-and-build-linux).
#### Arch Linux
If you are using Arch Linux:
```
$ pacman -S gcc make cmake pkgconf git boost boost-libs log4cpp libvolk gnuradio \
blas lapack gflags google-glog openssl pugixml libmatio protobuf \
python-mako libpcap gtest
```
Once you have installed these packages, you can jump directly to
[download the source code and build GNSS-SDR](#download-and-build-linux).
#### CentOS
If you are using CentOS 7, you can install the dependencies via Extra Packages
for Enterprise Linux ([EPEL](https://fedoraproject.org/wiki/EPEL)):
```
$ sudo yum install wget
$ wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
$ sudo rpm -Uvh epel-release-latest-7.noarch.rpm
$ sudo yum install make automake gcc gcc-c++ kernel-devel libtool \
hdf5-devel cmake git boost-devel boost-date-time boost-system \
boost-filesystem boost-thread boost-chrono boost-serialization \
log4cpp-devel gnuradio-devel gr-osmosdr-devel blas-devel lapack-devel \
armadillo-devel openssl-devel libpcap-devel python-mako python-six pugixml-devel
```
Once you have installed these packages, you can jump directly to
[download the source code and build GNSS-SDR](#download-and-build-linux).
#### Fedora
If you are using Fedora 26 or above, the required software dependencies can be
installed by doing:
```
$ sudo yum install make automake gcc gcc-c++ kernel-devel cmake git boost-devel \
boost-date-time boost-system boost-filesystem boost-thread boost-chrono \
boost-serialization log4cpp-devel gnuradio-devel gr-osmosdr-devel \
blas-devel lapack-devel matio-devel armadillo-devel gflags-devel \
glog-devel openssl-devel libpcap-devel pugixml-devel python3-mako \
protobuf-devel protobuf-compiler
```
Once you have installed these packages, you can jump directly to
[download the source code and build GNSS-SDR](#download-and-build-linux).
#### openSUSE
If you are using openSUSE Leap:
```
zypper install cmake git gcc-c++ boost-devel libboost_atomic-devel \
libboost_system-devel libboost_filesystem-devel libboost_chrono-devel \
libboost_thread-devel libboost_serialization-devel log4cpp-devel \
gnuradio-devel pugixml-devel libpcap-devel armadillo-devel libtool \
automake hdf5-devel openssl-devel python3-Mako protobuf-devel
```
If you are using openSUSE Tumbleweed:
```
zypper install cmake git gcc-c++ boost-devel libboost_atomic-devel \
libboost_system-devel libboost_filesystem-devel libboost_date_time-devel \
libboost_thread-devel libboost_chrono-devel libboost_serialization-devel \
log4cpp-devel gtest gnuradio-devel pugixml-devel libpcap-devel \
armadillo-devel libtool automake hdf5-devel libopenssl-devel \
python3-Mako protobuf-devel
```
Once you have installed these packages, you can jump directly to
[download the source code and build GNSS-SDR](#download-and-build-linux).
### Alternative 2: Install dependencies using PyBOMBS
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
installed versions, or simply in building everything from the scratch just for
the fun of it. In such cases, we recommend to use
[PyBOMBS](https://github.com/gnuradio/pybombs "Python Build Overlay Managed Bundle System")
(Python Build Overlay Managed Bundle System), GNU Radio's meta-package manager
tool that installs software from source, or whatever the local package manager
is, that automatically does all the work for you. Please take a look at the
configuration options and general PyBOMBS usage at
https://github.com/gnuradio/pybombs. Here we provide a quick step-by-step
tutorial.
First of all, install some basic packages:
```
$ sudo apt-get install git python3-pip
```
Download, build and install PyBOMBS:
```
$ sudo pip3 install --upgrade git+https://github.com/gnuradio/pybombs.git
```
Apply a configuration:
```
$ pybombs auto-config
```
Add list of default recipes:
```
$ pybombs recipes add-defaults
```
Download, build and install GNU Radio, related drivers and some other extra
modules into the directory `/path/to/prefix` (replace this path by your
preferred one, for instance `$HOME/sdr`):
```
$ pybombs prefix init /path/to/prefix -a myprefix -R gnuradio-default
```
This will perform a local installation of the dependencies under
`/path/to/prefix`, so they will not be visible when opening a new terminal. In
order to make them available, you will need to set up the adequate environment
variables:
```
$ cd /path/to/prefix
$ . ./setup_env.sh
```
Now you are ready to use GNU Radio and to jump into building GNSS-SDR after
installing a few other dependencies. Actually, those are steps that PyBOMBS can
do for you as well:
```
$ pybombs install gnss-sdr
```
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
altering the corresponding recipe at
`$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
step by step (i.e., cloning the repository and doing the usual
`cmake .. && make && make install` dance), Armadillo, GFlags, Glog and GnuTLS
can be installed either by using PyBOMBS:
```
$ pybombs install armadillo gflags glog gnutls
```
or manually as explained below, and then please follow instructions on how to
[download the source code and build GNSS-SDR](#download-and-build-linux).
### Manual installation of other required dependencies
#### Install [Armadillo](http://arma.sourceforge.net/ "Armadillo's Homepage"), a C++ linear algebra library:
```
$ sudo apt-get install libblas-dev liblapack-dev # For Debian/Ubuntu/LinuxMint
$ sudo yum install lapack-devel blas-devel # For Fedora/CentOS/RHEL
$ sudo zypper install lapack-devel blas-devel # For OpenSUSE
$ sudo pacman -S blas lapack # For Arch Linux
$ wget https://sourceforge.net/projects/arma/files/armadillo-9.880.1.tar.xz
$ tar xvfz armadillo-9.880.1.tar.xz
$ cd armadillo-9.880.1
$ cmake .
$ make
$ sudo make install
```
The full stop separated from `cmake` by a space is important.
[CMake](https://cmake.org/ "CMake's Homepage") 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).
#### Install [Gflags](https://github.com/gflags/gflags "Gflags' Homepage"), a commandline flags processing module for C++:
```
$ wget https://github.com/gflags/gflags/archive/v2.2.2.tar.gz
$ tar xvfz v2.2.2.tar.gz
$ cd gflags-2.2.2
$ cmake -DBUILD_SHARED_LIBS=ON -DBUILD_STATIC_LIBS=OFF -DBUILD_gflags_nothreads_LIB=OFF .
$ make
$ sudo make install
$ sudo ldconfig
```
#### Install [Glog](https://github.com/google/glog "Glog's Homepage"), a library that implements application-level logging:
```
$ wget https://github.com/google/glog/archive/v0.4.0.tar.gz
$ tar xvfz v0.4.0.tar.gz
$ cd glog-0.4.0
$ ./autogen.sh
$ ./configure
$ make
$ sudo make install
$ sudo ldconfig
```
#### Download the [Google C++ Testing Framework](https://github.com/google/googletest "Googletest Homepage"), also known as Google Test:
```
$ wget https://github.com/google/googletest/archive/v1.10.x.zip
$ unzip v1.10.x.zip
```
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;
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
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
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, GNSS-SDR does not
make use of pre-compiled Google Test libraries. Instead, it compiles Google
Test's source code 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 manages the
compilation and linking of Google Test's source code to its own tests; it is
only required that you tell the system where the Google Test folder that you
downloaded resides. Just type in your terminal (or add it to your
`$HOME/.bashrc` file for a permanent solution) the following line:
```
export GTEST_DIR=/home/username/googletest-1.10.x
```
changing `/home/username/googletest-1.10.x` by the actual path where you
unpacked Google Test. If the CMake script does not find that folder, or the
environment variable is not defined, or the source code is not installed by a
package, then it will download a fresh copy of the Google Test source code and
will compile and link it for you.
#### Install the [GnuTLS](https://www.gnutls.org/ "GnuTLS's Homepage") or [OpenSSL](https://www.openssl.org/ "OpenSSL's Homepage") libraries:
```
$ sudo apt-get install libgnutls-openssl-dev # For Debian/Ubuntu/LinuxMint
$ sudo yum install openssl-devel # For Fedora/CentOS/RHEL
$ sudo zypper install openssl-devel # For OpenSUSE
$ sudo pacman -S openssl # For Arch Linux
```
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.
#### 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
with your distribution are older than that (_e.g._, Ubuntu 16.04 Xenial and
Debian 8 Jessie came with older versions), then you will need to install it
manually. First, install the dependencies:
```
$ sudo apt-get install autoconf automake libtool curl make g++ unzip
```
and then:
```
$ wget https://github.com/protocolbuffers/protobuf/releases/download/v3.12.3/protobuf-cpp-3.12.3.tar.gz
$ tar xvfz protobuf-cpp-3.12.3.tar.gz
$ cd protobuf-3.12.3
$ ./autogen.sh
$ ./configure
$ make
$ sudo make install
$ sudo ldconfig
```
### <a name="download-and-build-linux">Clone GNSS-SDR's Git repository</a>:
```
$ git clone https://github.com/gnss-sdr/gnss-sdr
```
Cloning the GNSS-SDR repository 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 defines one particular receiver.
|---data <- Populate this folder with your captured data.
|---docs <- Contains documentation-related files.
|---install <- Executables will be placed here.
|---src <- Source code folder.
|-----algorithms <- Signal processing blocks.
|-----core <- Control plane, interfaces, systems' parameters.
|-----main <- Main function of the C++ program.
|-----tests <- QA code.
|-----utils <- some utilities (e.g. Matlab scripts).
```
By default, you will be in the 'master' branch of the Git repository, which
corresponds to the latest stable release. If you want to try the latest
developments, you can use the 'next' branch by going to the newly created
gnss-sdr folder doing:
```
$ git checkout next
```
More information about GNSS-SDR-specific Git usage and pointers to further
readings can be found at our
[Git tutorial](https://gnss-sdr.org/docs/tutorials/using-git/ "Using Git").
### Build and install GNSS-SDR
Go to GNSS-SDR's build directory:
```
$ cd gnss-sdr/build
```
Configure and build the application:
```
$ cmake ..
$ make
```
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
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
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:
```
$ cmake -DCMAKE_BUILD_TYPE=Debug ..
$ make
```
This will create four executables at gnss-sdr/install, namely `gnss-sdr`,
`run_tests`, `front-end-cal` and `volk_gnsssdr_profile`. You can run them from
that folder, but if you prefer to install `gnss-sdr` on your system and have it
available anywhere else, do:
```
$ sudo make install
```
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
working directory at your preferred location and store your own configuration
and data files there.
You could be interested in creating the documentation (requires:
`sudo apt-get install doxygen-latex` in Ubuntu/Debian) 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 build/docs/html/index.html.
If a LaTeX installation is detected in your system,
```
$ make pdfmanual
```
will create a PDF manual at build/docs/GNSS-SDR_manual.pdf. Finally,
```
$ make doc-clean
```
will remove the content of previously-generated documentation.
GNSS-SDR comes with a library which is a module of the Vector-Optimized Library
of Kernels (so called
[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
your processor. Run `volk_gnsssdr_profile` that is installed into `$PREFIX/bin`.
This program tests all known VOLK kernels for each architecture supported by the
processor. When finished, it will write to
`$HOME/.volk_gnsssdr/volk_gnsssdr_config` the best architecture for the VOLK
function. This file is read when using a function to know the best version of
the function to execute. It mimics GNU Radio's [VOLK](https://www.libvolk.org/)
library, so if you still have not run `volk_profile`, this is a good moment to
do so.
If you are using [Eclipse](https://www.eclipse.org/ide/) as your development
environment, CMake can create the project for you. However, if the build
directory is a subdirectory of the source directory (as is the case of the
`gnss-sdr/build` folder), this is not supported well by Eclipse. It is strongly
recommended to use a build directory which is a sibling of the source directory.
Hence, type from the `gnss-sdr` root folder:
```
$ cd ..
$ mkdir eclipse && cd eclipse
$ cmake -G "Eclipse CDT4 - Unix Makefiles" -DCMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT=TRUE -DCMAKE_ECLIPSE_VERSION=4.5 ../gnss-sdr
```
and then import the created project into Eclipse:
1. Import project using Menu File -> Import.
2. Select General -> Existing projects into workspace.
3. Select your root directory: Browse and select your newly created `eclipse/`
directory. Keep "Copy projects into workspace" unchecked.
4. Click on "Finish" and you will get a fully functional Eclipse project.
After building the project, you will find the generated binaries at
`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):
Install the [OsmoSDR](https://osmocom.org/projects/sdr "OsmoSDR's Homepage")
library and GNU Radio's source block:
```
$ 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
```
Then, configure GNSS-SDR to build the `Osmosdr_Signal_Source` by:
```
$ cmake -DENABLE_OSMOSDR=ON ..
$ make
$ sudo make install
```
(in order to disable the `Osmosdr_Signal_Source` compilation, you can pass
`-DENABLE_OSMOSDR=OFF` to cmake and build GNSS-SDR again).
###### Build FMCOMMS2 based SDR Hardware support (OPTIONAL):
Install the [libiio](https://github.com/analogdevicesinc/libiio.git) (>=v0.11),
[libad9361](https://github.com/analogdevicesinc/libad9361-iio.git) (>=v0.1-1)
libraries and [gr-iio](https://github.com/analogdevicesinc/gr-iio.git) (>v0.3)
gnuradio block:
```
$ sudo apt-get install libxml2-dev bison flex
$ git clone https://github.com/analogdevicesinc/libiio.git
$ cd libiio
$ mkdir build
$ cd build
$ cmake ..
$ make && sudo make install && sudo ldconfig
$ cd ../..
$ git clone https://github.com/analogdevicesinc/libad9361-iio.git
$ cd libad9361-iio
$ mkdir build
$ cd build
$ cmake ..
$ make && sudo make install && sudo ldconfig
$ cd ../..
$ git clone https://github.com/analogdevicesinc/gr-iio.git
$ cd gr-iio
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/usr ..
$ make && sudo make install && sudo ldconfig
$ cd ../..
```
Then configure GNSS-SDR to build the `Fmcomms2_Signal_Source` implementation:
```
$ cd gnss-sdr/build
$ cmake -DENABLE_FMCOMMS2=ON ..
$ make
$ sudo make install
```
or configure it to build `Plutosdr_Signal_Source`:
```
$ cmake -DENABLE_PLUTOSDR=ON ..
$ make
$ sudo make install
```
With `Fmcomms2_Signal_Source` you can use any SDR hardware based on
[FMCOMMS2](https://wiki.analog.com/resources/eval/user-guides/ad-fmcomms2-ebz),
including the ADALM-PLUTO (PlutoSdr) by configuring correctly the .conf file.
The `Plutosdr_Signal_Source` offers a simpler manner to use the ADALM-PLUTO
because implements only a subset of FMCOMMS2's parameters valid for those
devices.
###### Build OpenCL support (OPTIONAL):
In order to enable the building of blocks that use OpenCL, type:
```
$ cmake -DENABLE_OPENCL=ON ..
$ make
$ sudo make install
```
###### Build CUDA support (OPTIONAL):
In order to enable the building of blocks that use CUDA, NVIDIA's parallel
programming model that enables graphics processing unit (GPU) acceleration for
data-parallel computations, first you need to install the CUDA Toolkit from
[NVIDIA Developers Download page](https://developer.nvidia.com/cuda-downloads "CUDA Downloads").
Make sure that the SDK samples build well. Then, build GNSS-SDR by doing:
```
$ cmake -DENABLE_CUDA=ON ..
$ make
$ sudo make install
```
Of course, you will also need a GPU that
[supports CUDA](https://developer.nvidia.com/cuda-gpus "CUDA GPUs").
###### Build a portable binary
In order to build an executable that not depends on the specific SIMD
instruction set that is present in the processor of the compiling machine, so
other users can execute it in other machines without those particular sets, use:
```
$ cmake -DENABLE_GENERIC_ARCH=ON ..
$ make
$ sudo make install
```
Using this option, all SIMD instructions are exclusively accessed via VOLK,
which automatically includes versions of each function for different SIMD
instruction sets, then detects at runtime which to use, or if there are none,
substitutes a generic, non-SIMD implementation.
More details can be found in our tutorial about
[GNSS-SDR configuration options at building time](https://gnss-sdr.org/docs/tutorials/using-git/ "Configuration options at building time").
## <a name="macosx">macOS</a>
GNSS-SDR can be built on macOS (or the former Mac OS X), starting from 10.9
(Mavericks) and including 10.15 (Catalina). If you still have not installed
[Xcode](https://developer.apple.com/xcode/ "Xcode"), do it now from the App
Store (it's free). You will also need the Xcode Command Line Tools. Launch the
Terminal, found in /Applications/Utilities/, and type:
```
$ xcode-select --install
```
Agree to Xcode license:
```
$ sudo xcodebuild -license
```
Software pre-requisites can be installed using either [Macports](#macports) or
[Homebrew](#homebrew).
#### <a name="macports">Macports</a>
First, [install Macports](https://www.macports.org/install.php). If you are
upgrading from a previous installation, please follow the
[migration rules](https://trac.macports.org/wiki/Migration).
In a terminal, type:
```
$ sudo port selfupdate
$ sudo port upgrade outdated
$ sudo port install armadillo cmake gnuradio gnutls lapack libad9361-iio libiio \
matio pkgconfig protobuf3-cpp pugixml google-glog +gflags
$ sudo port install py37-mako
$ sudo port install doxygen +docs
```
You also might need to activate a Python installation. The list of installed
versions can be retrieved with:
```
$ port select --list python
```
and you can activate a certain version by typing:
```
$ sudo port select --set python python37
```
#### <a name="homebrew">Homebrew</a>
First, install [Homebrew](https://brew.sh/). Paste this in a terminal prompt:
```
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
```
The script explains what it will do, and then it pauses before doing it. There
are more installation options [here](https://docs.brew.sh/Installation.html).
Install pip3:
```
$ curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
$ sudo python3 get-pip.py
```
Install the required dependencies:
```
$ brew update && brew upgrade
$ brew install armadillo cmake hdf5 gflags glog gnuradio lapack libmatio log4cpp \
openssl pkg-config protobuf pugixml
$ pip3 install mako
$ brew cask install mactex # when completed, restart Terminal
$ brew install graphviz doxygen
```
#### Build GNSS-SDR
Finally, you are ready to clone the GNSS-SDR repository, configure and build the
software:
```
$ git clone https://github.com/gnss-sdr/gnss-sdr
$ cd gnss-sdr/build
$ cmake ..
$ make
```
This will create three executables at gnss-sdr/install, namely `gnss-sdr`,
`run_tests` and `volk_gnsssdr_profile`. You can install the software receiver on
your system by doing:
```
$ sudo make install
```
Note, it is advisable not to run the install step in a homebrew environment.
The documentation can be built by:
```
$ make doc
```
and can be viewed doing:
```
$ open ./docs/html/index.html
```
GNSS-SDR comes with a library which is a module of the Vector-Optimized Library
of Kernels (so called
[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
your processor. Run `volk_gnsssdr_profile` that is installed into `$PREFIX/bin`.
This program tests all known VOLK kernels for each architecture supported by the
processor. When finished, it will write to
`$HOME/.volk_gnsssdr/volk_gnsssdr_config` the best architecture for the VOLK
function. This file is read when using a function to know the best version of
the function to execute. It mimics GNU Radio's [VOLK](https://www.libvolk.org/)
library, so if you still have not run `volk_profile`, this is a good moment to
do so.
###### Other package managers
GNU Radio and other dependencies can also be installed using other package
managers than Macports, such as [Fink](http://www.finkproject.org/ "Fink") or
[Homebrew](https://brew.sh/ "Homebrew"). Since the version of Python that ships
with OS X is great for learning but it is not good for development, you could
have another Python executable in a non-standard location. If that is the case,
you need to inform GNSS-SDR's configuration system by defining the
`PYTHON_EXECUTABLE` variable as:
```
cmake -DPYTHON_EXECUTABLE=/path/to/bin/python3 ..
```
In case you have installed Macports in a non-standard location, you can use:
```
$ cmake -DCMAKE_PREFIX_PATH=/opt/local -DUSE_MACPORTS_PYTHON=/opt/local/bin/python ..
```
changing `/opt/local` by the base directory in which your software is installed.
The CMake script will create Makefiles that download, build and link Armadillo,
Gflags, Glog, Matio, Protocol Buffers, PugiXML and Google Test on the fly at
compile time if they are not detected in your machine.
## Other builds
- **Docker image**: A technology providing operating-system-level virtualization
to build, ship, and run distributed applications, whether on laptops, data
center VMs, or the cloud. Visit
[https://github.com/carlesfernandez/docker-gnsssdr](https://github.com/carlesfernandez/docker-gnsssdr)
or
[https://github.com/carlesfernandez/docker-pybombs-gnsssdr](https://github.com/carlesfernandez/docker-pybombs-gnsssdr)
for instructions.
- **Snap package**: [Snaps](https://snapcraft.io) are universal Linux packages
aimed to work on any distribution or device, from IoT devices to servers,
desktops to mobile devices. Visit
[https://github.com/carlesfernandez/snapcraft-sandbox](https://github.com/carlesfernandez/snapcraft-sandbox)
for instructions, or directly
[get the software from the Snap Store](https://snapcraft.io/gnss-sdr-next):
<p align="center">
<a href="https://snapcraft.io/gnss-sdr-next"><img src="https://snapcraft.io/static/images/badges/en/snap-store-white.svg" alt="Get GNSS-SDR from the Snap Store"></a>
</p>
- **GNSS-SDR in embedded platforms**: we provide a Software Development Kit
(SDK) based on [OpenEmbedded](http://www.openembedded.org/wiki/Main_Page) for
cross-compiling GNSS-SDR in your desktop computer and for producing
executables that can run in embedded platforms, such as a Zedboard or a
Raspberry Pi 3. Visit
[Cross-compiling GNSS-SDR](https://gnss-sdr.org/docs/tutorials/cross-compiling/)
for instructions.
# Updating GNSS-SDR
If you cloned or forked GNSS-SDR some time ago, it is possible that some
developer has updated files at the Git repository. If you still have not done
so, add the `upstream` repository to the list of remotes:
```
$ git remote add upstream https://github.com/gnss-sdr/gnss-sdr.git
```
and then you can update your working copy by doing:
```
$ git checkout master # Switch to branch you want to update
$ git pull upstream master # Download the newest code from our repository
```
or, if you want to test the latest developments:
```
$ git checkout next
$ git pull upstream next
```
Before rebuilding the source code, it is safe (and recommended) to remove the
remainders of old compilations:
```
$ rm -rf gnss-sdr/build/*
```
If you are interested in contributing to the development of GNSS-SDR, please
check out
[how to do it](https://gnss-sdr.org/contribute/ "How to contribute to GNSS-SDR source code").
There is a more controlled way to upgrade your repository, which is to use the
Git commands `fetch` and `merge`, as described in our
[Git Tutorial](https://gnss-sdr.org/docs/tutorials/using-git/ "Using Git").
# Getting started
1. After building the code, you will find the `gnss-sdr` executable file at
gnss-sdr/install. You can make it available everywhere else by
`sudo make install`. Run the profilers `volk_profile` and
`volk_gnsssdr_profile` for testing all available VOLK kernels for each
architecture supported by your processor. This only has to be done once.
2. In post-processing mode, you have to provide a captured GNSS signal file. 1.
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
[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
bandwidth in 1.57542 GHz. (remember to enable the DC bias with the daughter
board jumper). We use a [DBSRX2](https://www.ettus.com/all-products/DBSRX2/)
to do the task, but you can try the newer Ettus' daughter boards as well. 3.
The easiest way to capture a signal file is to use the GNU Radio Companion
GUI. Only two blocks are needed: a 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 DBSRX2 we obtained good results with
`G=50`. 4. Capture at least 80 seconds of signal in open sky conditions.
During the process, be aware of USRP driver buffer underruns 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>`. 5. If you have no access to an RF
front-end, you can download a sample raw data file (that contains GPS and
Galileo signals) from
[here](https://sourceforge.net/projects/gnss-sdr/files/data/).
3. You are ready to configure the receiver to use your captured file among other
parameters:
1. The default configuration file resides at
[/usr/local/share/gnss-sdr/conf/default.conf](./conf/gnss-sdr.conf).
2. You need to review/modify at least the following settings:
- `SignalSource.filename=` (absolute or relative route to your GNSS signal
captured file)
- `GNSS-SDR.internal_fs_sps=` (captured file sampling rate in samples per
second)
- `SignalSource.sampling_frequency=` (captured file sampling rate in
samples per second)
- `SignalConditioner.sample_freq_in=` (captured file sampling rate in
samples per second)
- `SignalConditioner.sample_freq_out=` (captured file sampling rate in
samples per second)
3. The configuration file has in-line documentation, you can try to tune the
number of channels and several receiver parameters. Store your .conf file
in some working directory of your choice.
4. Run the receiver invoking the configuration by
`$ gnss-sdr --config_file=/path/to/my_receiver.conf` 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 and decode at least 4
satellites, you will get PVT fixes. The program will write .kml, .geojson and
RINEX files in the folder from which `gnss-sdr` was run. In addition to the
console output, GNSS-SDR also writes log files at /tmp/ (configurable with
the commandline flag `./gnss-sdr --log_dir=/path/to/log`).
For more information, check out our
[quick start guide](https://gnss-sdr.org/quick-start-guide/).