Global receiver parameters

This page describes GNSS-SDR global parameters.

The notation is as follows: for a global parameter XXX with value YY, its entry in the configuration file is:

GNSS-SDR.XXX=YY

If a parameter is not specified in the configuration file, it takes its default value.

Sampling rate of the GNSS baseband engine

In the current design, all the processing Channels need to accept streams of samples at the same rate. This is not necessarily the same as the sampling frequency of the Signal Source, since the Signal Conditioner block can apply some resampling. Please note that this is a mandatory parameter, it needs to be present in the configuration file.

Global GNSS-SDR parameter: channel’s input sampling rate.

Example in the configuration file:

GNSS-SDR.internal_fs_sps=4000000

Multiple signal sources

Example:

GNSS-SDR.num_sources=2

For more details, please check how to configure multiple signal sources.

Internal observables processing rate

This global parameter allows to control the internal rate at which observable sets are processed.

Example in the configuration file:

GNSS-SDR.observable_interval_ms=10

Open Service Navigation Message Authentication (OSNMA)

The Galileo OSNMA service is enabled by default if the configuration file defines 1B (that is, Galileo E1 OS) channels.

Users must register and log in on the European GNSS Service Centre website, and download the OSNMA public key (“GSC Products > OSNMA_PublicKey”, the file with .crt format) and the OSNMA Merkle Tree root file (“GSC Products > OSNMA_MerkleTree”, in .xml format), and set the corresponding options in the GNSS-SDR configuration file:

Example in the configuration file:

GNSS-SDR.osnma_public_key=./OSNMA_PublicKey_20251210100000_newPKID_2.crt
GNSS-SDR.osnma_merkletree=./OSNMA_MerkleTree_20251210100000_newPKID_2.xml

The same, but with the strict mode:

GNSS-SDR.osnma_public_key=./OSNMA_PublicKey_20251210100000_newPKID_2.crt
GNSS-SDR.osnma_merkletree=./OSNMA_MerkleTree_20251210100000_newPKID_2.xml
GNSS-SDR.osnma_mode=strict

Example to turn off the OSNMA reception:

GNSS-SDR.osnma_enable=false

Telecommand via TCP/IP

The user can access the receiver interactive interface by connecting a TCP/IP client (e.g., with a telnet client) to the TCP port specified in the configuration file for telecommand.

In order to use it, the executable gnss-sdr must be called with the gnss-sdr-harness.sh script provided at utils/scripts:

$ gnss-sdr-harness.sh gnss-sdr -c config_file.conf

The configuration of the Telecommand system is as follows:

Global GNSS-SDR parameters for telecommand.

Example in the GNSS-SDR configuration file:

GNSS-SDR.telecommand_enabled=true
GNSS-SDR.telecommand_tcp_port=3333

The user commands must be sent as a lower-case string, command parameters separated by 1 space, and ended by \r \n (carriage-return and line feed). The commands will provide feedback to the user.

The following commands are implemented in GNSS-SDR’s telecommand interface:

Telecommand execution examples using telnet:

user@ubuntu:~\$ telnet receiver_ip tc_port
Trying receiver_ip...
Connected to receiver_ip.
Escape character is '^]'.
status
---------------------------------------------------------
ch | sys | sig  | mode | Tlm | Eph | Doppler  |   CN0   |
   |     |      |      |     |     |  [Hz]    | [dB-Hz] |
---------------------------------------------------------
0  | GPS | L1CA | TRK  | YES | YES | 23412.4  |  44.3   |
1  | GPS | L1CA | TRK  | YES | YES | -14725.4 |  45.4   |
2  | GPS | L1CA | TRK  | YES | YES | 4562.1   |  41.0   |
3  | GPS | L1CA | TRK  | YES | YES | 15223.4  |  38.2   |
4  | GPS | L1CA | TRK  | YES | NO  |-8456.0   |  40.5   |
5  | GPS | L1CA | ACQ  | NO  | NO  | -------- |  ----   |
6  | GPS | L1CA | STBY | NO  | NO  | -------- |  ----   |
---------------------------------------------------------

- Receiver UTC Time: 02/04/2017 21:02:33
- Receiver Position WGS84 [Lat, Long, H]: 41.2750209, 1.98558393, 58.1
- Receiver Speed over Ground [km/h]: 2
- Receiver Course over ground [deg]: 175.3

Example of the status command.

user@ubuntu:~\$ telnet receiver_ip tc_port
Trying receiver_ip...
Connected to receiver_ip.
Escape character is '^]'.
standby
OK
coldstart
OK

Example of the coldstart command.

user@ubuntu:~\$ telnet receiver_ip tc_port
Trying receiver_ip...
Connected to receiver_ip.
Escape character is '^]'.
standby
OK
warmstart 1/12/2018 09:15:42 41.234 1.76 560.0
OK

Example of the warmstart command.

Assisted GNSS

GNSS-SDR can read satellite’s ephemeris and almanacs from other sources than GNSS signals themselves.

Assisted GNSS via XML files

GNSS-SDR can read assistance data from Extensible Markup Language (XML) files for faster Time-To-First-Fix, and can store navigation data decoded from GNSS signals in the same format. Check this folder for XML Schemas describing those XML files structure.

When reading AGNSS data from XML files, you must provide a rough initial reference position and time (parameters AGNSS_ref_location and AGNSS_ref_utc_time), which will be used to compute the list of visible satellites (those with positive elevation angle) from your receiver standpoint before getting any GNSS signal. Hence, the receiver can start searching for those satellites and thus accelerate its Time-To-First-Fix.

Global GNSS-SDR parameters: Assisted GNSS via XML files.

Example in the configuration file:

GNSS-SDR.AGNSS_XML_enabled=true
GNSS-SDR.AGNSS_ref_location=41.39,2.31

The location in the example refers to a latitude of 41.39º N and a longitude of 2.31º E.

Please note that the parameter AGNSS_gal_almanac_xml accepts, in addition to the own-defined XML format for the Galileo almanac, the XML format published by the European GNSS Service Centre and available here. Just download the latest almanac XML file from there, and set the following parameters in your configuration file:

GNSS-SDR.AGNSS_XML_enabled=true
GNSS-SDR.AGNSS_ref_location=41.39,2.31
GNSS-SDR.AGNSS_ref_utc_time=22/11/2018 17:45:53
GNSS-SDR.AGNSS_gal_almanac_xml=2018-11-06.xml

(changing 2018-11-06.xml by the name of the file you actually downloaded, as well as your reference position) and the format will be detected and read automatically. If AGNSS_ref_utc_time is not set, the receiver will read the system time from the computer executing the software receiver and will take that as a reference. So, if you are using the receiver with live signals from an RF front-end, you do not need to set this parameter.

You could find useful the utility program rinex2assist for the generation of compatible XML files from recent, publicly available RINEX navigation data files.

Assisted GNSS via SUPL v1.0

One way of accelerating a GNSS receiver’s Time-To-First-Fix is to use assistance data from a Secure User Plane Location (SUPL) server. SUPL is a standard produced by the Open Mobile Alliance (OMA) that allows a device such as a mobile phone to connect to a location server using the TCP/IP protocol, and to request assistance data for location.

In order to retrieve that information from a SUPL server, the device to be located needs to send some information, namely its Location Area Identity (which uniquely identifies a location area within a mobile network, and consists of the Mobile Country Code, the Mobile Network Code and the Location Area Code) and the Cell ID to which the device is connected.

These parameters are defined as follows:

• The Mobile Country Code (MCC) is used in wireless telephone networks (GSM, CDMA, UMTS, LTE, etc.) in order to identify the country to which a mobile subscriber belongs. Defined by the ITU-T Recommendation E.212, this code is an integer number (three digits) represented with 16 bits.

• The Mobile Network Code (MNC) is used for the international identification of networks. Jointly with the MCC, these parameters are used to uniquely identify a mobile network operator. This code is an integer of two or three digits, depending on the country.

• The Location Area Code (LAC) is a unique number of the current local area. The served area of a cellular radio network is usually divided into location areas. Location areas are comprised of one or several radio cells, and each location area is given a unique number within the network - the LAC. Please note that in some networks, the LAC is called Tracking Area Code (TAC). Both the LAC and TAC share the same concept of providing the location code of a base station set. The only difference between LAC and TAC is that the LAC is the terminology used in GSM/UMTS while the TAC is the terminology used in LTE networks.

• The Cell ID (CID) is a generally unique number used to identify each Base Transceiver Station (BTS) or sector of a BTS within a location area code. While BTS is the terminology for GSM networks, this is called Node B in UMTS and eNode B in LTE networks. Valid values for the CID range from \(0\) to \(65535\), that is, (\(2^{16} − 1\)), on GSM and CDMA networks and from \(0\) to \(268435455\), that is, (\(2^{28} − 1\)), on UMTS and LTE networks.

Those values can be easily retrieved using any net monitor on a smartphone. There are a lot of apps that can do that (an example here). These applications are able to provide the required MMC, MNC, LAC, and CI parameters for your location. A list of MCC and MNC around the World can be found at mcc-mnc.com and at the Wikipedia.

GNSS-SDR is a SUPL Enabled Terminal (SET) receiver that can use a TCP/IP network connection to retrieve Assisted GPS data from a remote server via the Secure User Plane Location (SUPL) v1.0 and hence accelerate its Time-To-First-Fix. SUPL v1.0 only applies to GPS L1 C/A assistance.

GNSS-SDR configuration parameters for Assisted GNSS with SUPL v1.0 are shown below:

Global GNSS-SDR parameters: Assisted GPS via SUPL V1.0.

LAC and CI may be presented in a decimal or hexadecimal form, and the GNSS-SDR configuration accepts both. Setting GNSS-SDR.SUPL_LAC=0x59e2 is equivalent to GNSS-SDR.SUPL_LAC=23010.

An example of GNSS-SDR configuration file follows:

GNSS-SDR.SUPL_gps_enabled=true
GNSS-SDR.SUPL_read_gps_assistance_xml=false
GNSS-SDR.SUPL_gps_ephemeris_server=supl.google.com
GNSS-SDR.SUPL_gps_ephemeris_port=7275
GNSS-SDR.SUPL_gps_acquisition_server=supl.google.com
GNSS-SDR.SUPL_gps_acquisition_port=7275
GNSS-SDR.SUPL_MCC=244
GNSS-SDR.SUPL_MNC=5
GNSS-SDR.SUPL_LAC=0x59e2
GNSS-SDR.SUPL_CI=0x31b0

Self-assistance in multi-frequency receivers

In case the receiver is configured to work with signals from different frequency bands from the same satellite (for instance, GPS L1 and GPS L5, Galileo E1 and E5a, etc.), GNSS-SDR makes use of the acquisition parameters obtained in the primary band to accelerate acquisition in the secondary band(s). This allows reducing the computational load (since the search grid in the secondary band(s) can be smaller) and the acquisition-to-tracking latency. This behavior can be deactivated by setting this parameter to false, which makes the receiver search satellites in each band independently.

Moreover, the Doppler search in the secondary band is always narrowed to a single bin centered at the projected value, instead of sweeping the full grid (see Reduced Doppler search in the Acquisition documentation). Setting assist_dual_frequency_acq=false restores the independent, full-range search in each band, and Acquisition_XX.dual_freq_assisted_doppler_narrowing=false keeps the assistance but forces a full-range search for a given signal only.

Example for satellites searched independently in each band:

GNSS-SDR.assist_dual_frequency_acq=false

Visibility-aware acquisition search

By default, each idle channel takes the next satellite to search for from a single first-in, first-out queue per signal. Satellite visibility only affects the initial order of that queue when assisted GNSS is enabled; after that, a satellite that fails acquisition simply goes to the back of the queue, so channels keep spending time on satellites that are below the horizon.

GNSS-SDR v0.0.22 added an optional visibility-aware search. Once a receiver position is available, either from a position fix or from AGNSS_ref_location and AGNSS_ref_utc_time, satellites are continuously classified as visible (elevation above search_elevation_mask), excluded (elevation at or below the mask, or flagged as unhealthy) or maybe visible (no ephemeris or almanac decoded yet), using the freshest ephemeris or almanac available for GPS, Galileo, BeiDou, GLONASS, and QZSS. Idle channels then favor visible satellites over the maybe visible ones and skip the excluded ones. The classification is refreshed when the position fix becomes valid, when new ephemeris or almanac data arrive, when the receiver moves, periodically, and when the data used for a satellite becomes stale. A satellite that is already being tracked is never released because of this classification, and PVT.elevation_mask still decides which observations enter the navigation solution.

Satellites listed in the <System>_banned_prns parameters described below are never classified as visible.

Example:

GNSS-SDR.enable_visibility_aware_search=true
GNSS-SDR.search_elevation_mask=15
GNSS-SDR.visible_vs_mayvisible_search_ratio=10
GNSS-SDR.visibility_recompute_interval_s=120.0
GNSS-SDR.visibility_recompute_position_threshold_m=1000.0
GNSS-SDR.visibility_almanac_max_age_s=259200.0

Doppler prediction from ephemeris and almanac

With the visibility-aware search enabled, the receiver can also use the ephemeris or almanac of a satellite classified as visible to predict its Doppler shift, and narrow the acquisition search around that value (see Reduced Doppler search in the Acquisition documentation). The prediction adds the geometric Doppler, computed from the satellite orbit and the receiver position and velocity, and the receiver clock drift, both scaled to the carrier frequency of the searched signal. With a position fix no older than one second of receiver time, the position, velocity, and clock drift come from that fix, and a single Doppler bin is searched. Primary bands (GPS L1 C/A, Galileo E1, GLONASS L1, BeiDou B1I and B1C, QZSS L1) use this prediction whenever it is available. Secondary bands only use it if Acquisition_XX.alm_ephe_assisted_doppler_narrowing=true and they are searched without dual-frequency assistance (see Self-assistance in multi-frequency receivers). No prediction is made while a reference position and time received by telecommand is active.

Before the first position fix, the prediction can optionally be computed at AGNSS_ref_location (at zero height), assuming a static receiver with a clock drift equal to clock_frequency_offset_ppm, at the time given by AGNSS_ref_utc_time (or by the system time when the receiver starts) plus the elapsed sample time. Since the receiver velocity and clock drift are not solved yet, the search is widened to cover

Hz on each side of the predicted value, where \(c\) is the speed of light. This is only done if doppler_prediction_before_fix=true, AGNSS_ref_location is set, and both clock_frequency_max_error_ppm and receiver_max_velocity_m_s are explicitly set to finite, nonnegative values; otherwise, the full Doppler grid is searched until the first fix. Setting a bound to zero asserts that there is no uncertainty in that component. \(U\) does not account for errors in the reference position or time, so the reference location should be close to the receiver, and in file replays AGNSS_ref_utc_time must match the time of the recorded samples.

Example:

GNSS-SDR.enable_visibility_aware_search=true
GNSS-SDR.AGNSS_ref_location=41.39,2.31
GNSS-SDR.assist_dual_frequency_acq=false
GNSS-SDR.doppler_prediction_before_fix=true
GNSS-SDR.clock_frequency_offset_ppm=0.0
GNSS-SDR.clock_frequency_max_error_ppm=1.0
GNSS-SDR.receiver_max_velocity_m_s=30.0
Acquisition_L5.alm_ephe_assisted_doppler_narrowing=true

With these values, \(U \approx 1733\) Hz for GPS L1 C/A and \(U \approx 1294\) Hz for GPS L5 before the first fix.

Banned satellites

By default, GNSS-SDR searches for all the available satellites by PRN identification, from 1 up to the nominal maximum identifier (32 for GPS, 36 for Galileo, and so on). The order in which they are searched for can be altered if assisted GNSS is enabled, but all of them will be eventually processed as long as there are channels available.

The following parameters allow to remove specific satellites from the list of potentially available ones:

With these parameters, users can specify lists of satellites that will not be processed. Satellites on those lists will never be assigned to a processing channel.

Example: since Galileo E14 and E18 satellites are not usable for PVT, they can be removed from the list of Galileo searched satellites by setting:

GNSS-SDR.Galileo_banned_prns=14,18

Processing old data files

GPS L1 C/A navigation messages broadcast the week number modulo 1024, so the week counter rolls over every 1024 weeks (about 19.7 years; rollovers occurred on August 21, 1999, and April 6, 2019, and the next one will occur on November 20, 2038). By default, the receiver resolves this ambiguity using the computer’s current date, which is the right choice when operating in real time, but yields a wrong date and time (and a wrong leap-second offset) when post-processing a raw data file recorded more than about ten years ago. If you are processing an old recording, set the approximate date of the signal capture with this parameter in order to get the right date and time:

Example: for a file recorded on December 20, 2014:

GNSS-SDR.observation_date=2014-12-20

This parameter replaces GNSS-SDR.pre_2009_file, available in older versions of GNSS-SDR, which could only select the August 1999 - April 2019 era (so, for instance, GNSS-SDR.pre_2009_file=true is the right setting for a file recorded in 2014). The old flag still works, but it is deprecated and ignored if GNSS-SDR.observation_date is also set.

Getting the TOW and the Week Number in the Tracking blocks

In some applications, it can be useful to get the Time of Week and Week Number at the Tracking blocks, when available.

Activating this configuration parameter makes this information available both in the dump files generated by the Tracking blocks and in the Gnss_Synchro objects they emit.

Example:

GNSS-SDR.tow_to_trk=true