# Locus Lock Documentation > LEO100 and PpRx documentation for LLM consumption. Release notes are published via Frill (see /announcements). This file contains the FULL CONTENT of every page concatenated into one document. Use this when you want to ingest the entire documentation set at once (e.g. pasting into a context window). If you only need a link index to fetch specific pages on demand, use llms.txt instead. When answering questions using this documentation: answer only based on the content below; if something is not covered here, say so rather than guessing; and do not describe unreleased or internal features as available. ## Analyze and Convert GBX Files import PhaseProgress from '@site/src/components/PhaseProgress'; # Analyze and Convert GBX Files Learn how to export GBX files from the GUI using the `Export GBX as...` dialog window. Then, learn to inspect or convert GBX files from the CLI with Binflate. Binflate is included with all PpRx licenses. To verify the installation, run: ```bash which binflate binflate --version ``` ## Overview GBX files are compressed binaries containing a range of processed GNSS data, including observables, ephemeris, and final position and timing solutions. GBX files are the primary output format of PpRx. See the [GBX Protocol Description](/pprx/gbx-protocol) for the binary wire format. A `.gbx` file produced by a PpRx run can be exported to other file types containing this information. This can be done either in the GUI or via the CLI. ## Exporting GBX Files in the GUI Open the `Export GBX` dialog in the GUI by selecting `File` → `Export GBX as…` in the menu bar. After selecting a `.gbx` file to export and an output folder for the file or files, entering an output filename will populate filenames for each selected output product, as shown below: ![Export GBX](/img/leo100/analyze-gbx-2.png) Selecting the `Export` button will create the desired output products in the output folder. ## Exporting GBX Files in the Command Line with Binflate The same operations can be completed in the CLI using the `binflate` utility included in the software installation. To inspect the available arguments: ```bash binflate --help ``` Suppose there is a `pprx.gbx` file in the current directory. Common conversions include: ```bash binflate -i pprx.gbx -s rin # Export RINEX 2.11 output binflate -i pprx.gbx -s kml # Export KML for map visualization (for import to Google Earth Pro) binflate -i pprx.gbx -s log # Export log (.csv) files binflate -i pprx.gbx -s mat # Export MATLAB `.mat` files ``` Depending on the selected conversion, files such as `grid.obs`, `standard.kml`, `channel.log`, and `navsol.mat` will be created in the current directory. ## Analyzing GBX Files in the Command Line with Binflate Interactive Mode Binflate also provides an _interactive_ mode, which allows rapid inspection and debugging on embedded systems. Interactive mode is activated by passing the `-x` argument. For example: ```bash binflate -i pprx.gbx -x # Open `pprx.gbx` in interactive mode ``` ```text ――――――――――――――― GRID: General Radionavigation Interfusion Device ―――――――――――― RRT: 0 weeks 0.1 seconds Build ID: 5272 ORT: 9999 weeks -1.0 seconds ――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――― CH TXID Doppler BCP PR C/N₀ Az El CS (Hz) (cycles) (meters) (dB-Hz) (deg) (deg) ―――――――――――――――――――――――――――― GPS_L1_CA_PRIMARY ―――――――――――――――――――――――――――― 1 1? 1524.3 ------------- ----------- 44.2 ----- ---- 3* 2 2? -425.3 ------------- ----------- 45.1 ----- ---- 3* 3 13? -676.1 ------------- ----------- 40.9 ----- ---- 3* 4 10? -2092.4 ------------- ----------- 48.3 ----- ---- 3* 5 12? -18.7 ------------- ----------- 45.6 ----- ---- 3* 6 25? 1418.1 ------------- ----------- 45.1 ----- ---- 3* 7 31? 3064.0 ------------- ----------- 46.3 ----- ---- 3* 8 28? 988.5 ------------- ----------- 46.1 ----- ---- 3* ―――――――――――――――――――――――――――― GPS_L2_CLM_PRIMARY ――――――――――――――――――――――――――― 1 -- --------- ------------- ----------- ---- ----- ---- - 2 -- --------- ------------- ----------- ---- ----- ---- - 3 -- --------- ------------- ----------- ---- ----- ---- - 4 -- --------- ------------- ----------- ---- ----- ---- - 5 -- --------- ------------- ----------- ---- ----- ---- - 6 -- --------- ------------- ----------- ---- ----- ---- - ―――――――――――――――――――――――――――― GPS_L5_IQ_PRIMARY ―――――――――――――――――――――――――――― 1 -- --------- ------------- ----------- ---- ----- ---- - 2 -- --------- ------------- ----------- ---- ----- ---- - 3 -- --------- ------------- ----------- ---- ----- ---- - 4 -- --------- ------------- ----------- ---- ----- ---- - 5 -- --------- ------------- ----------- ---- ----- ---- - 6 -- --------- ------------- ----------- ---- ----- ---- - ―――――――――――――――――――――――――――― Standard Solution ―――――――――――――――――――――――――――― PX: 0.00 PY: 0.00 PZ: 0.00 δtR: 0.00 VX: 0.00 VY: 0.00 VZ: 0.00 δtRdot: 0.00 Hσ: 0.00 Vσ: 0.00 εν: 0.00 ――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――― ``` To exit Binflate, press `Ctrl+C`. Commands can be listed while in interactive mode using `help`. ```text > help Commands: next ........... continue to next epoch prev ........... rewind to previous epoch goto ARG ....... go to ARG seconds (RRT) jump ARG ....... jump by ARG seconds (can be negative) setpause ARG ... set pause to ARG milliseconds quit ........... quit ``` ## Processing Binflate `.log` and `.mat` Files Processing `.log` and `.mat` files may be useful for receiver performance analysis. The `.log` files are CSV outputs that can be loaded into applications such as Microsoft Excel or Google Sheets. The `.mat` files can be imported into MATLAB using, for example: ```matlab load channel.mat; channel = channel'; % Transpose to put in columnar format ``` The column formats are the same for all `.log` and `.mat` file products produced by Binflate. Formats are defined in the following text files: - `attitude2d.txt` - `channel.txt` - `display.txt` - `iono.txt` - `iq.txt` - `iqtaps.txt` - `navsol.txt` - `poseandtwist.txt` - `sbrtk.txt` - `scint.txt` - `txinfo.txt` When processing data, the mapping between signals and GenericTypes may also be required and is [available here](/pprx/generictype-mapping). ## Notes - The RINEX format is useful for porting PpRx outputs to external PPP processing tools such as CSRS-PPP. --- ## Configure PpRx Outputs in the GUI import PhaseProgress from '@site/src/components/PhaseProgress'; # Configure PpRx Outputs in the GUI Learn how to configure PpRx output products in the GUI. ## Overview By default, the GUI does not produce any outputs other than what is displayed in the visualization. To set outputs for a given run, either select the gear icon in the top-right corner of the I/O overlay or select `Run` → `Configure PpRx Outputs` from the menu bar. After selecting an output folder, the output types can be configured. Information on each output type can be accessed by the corresponding `?` button. ## Output Summary | Output | When it is written | Typical use | | --- | --- | --- | | GBX | During the run | Primary processed output format | | NMEA | During the run | Serial, UDP, or file output for navigation consumers | | `.bin` | During the run | Save raw RF data for later post-processing | | Named Pipe | During the run | Real-time integration with external software | | KML | After the run completes | Quick visualization in map tools such as Google Earth | | RINEX | After the run completes | Export observations to external GNSS workflows | | `.log` | After the run completes | Human-readable CSV outputs for analysis | | `.mat` | After the run completes | MATLAB-friendly outputs for analysis | ## Live Outputs The following outputs are produced live as PpRx runs, whether PpRx is running in live processing or post-processing mode. ### GBX The GBX output will automatically be checked when an output folder is selected, because any PpRx run producing output data must write to at least a GBX file. GBX files are Locus Lock proprietary compressed binaries containing a range of processed GNSS data, including observables, ephemeris, and final position/timing solutions. All other outputs, except raw RF data, can be derived from a GBX file or stream. ### NMEA Checking the NMEA output will write GPGGA and GPRMC NMEA messages to a `.nmea` file (with each message on a new line), a serial port, a UDP destination, or any combination. After selecting a valid serial port and baud rate, NMEA messages will be broadcast when PpRx is started. These NMEA message broadcasts allow plug-and-play integration with a variety of devices, such as a CubePilot. ### `.bin` Files With the `.bin` file checkbox selected, the raw RF data being processed by PpRx will be logged to a `.bin` file so that PpRx can operate on it later in post-processing mode. This allows PpRx to be run live while also saving the data for later optimization of `.opt` and `.config` files. Note that this option is identical to a `Raw Data Capture` and consumes roughly 1.2 GB/min of storage space. ### Named Pipe Checking the Named Pipe option will, in addition to writing the GBX binary stream to a `.gbx` file, also write it to a POSIX named pipe (FIFO). Named-pipe reading is useful for direct real-time integration with external software or scripts. :::danger The named pipe **must** have a reader or it will block PpRx/GUI execution until one is available. ::: ## Post-Processed Outputs The remaining output types are not produced live, but are generated from the `.gbx` output file when a PpRx run is completed or stopped. These outputs are generated using [Binflate](/advanced-tutorials/analyze-gbx). ### KML Selecting the KML checkbox produces a `.kml` file at the end of the run, containing positioning and time outputs viewable in applications such as Google Earth. ### RINEX The RINEX checkbox produces a file in standard RINEX 2.11 format when the run is complete. The RINEX format is useful for porting PpRx outputs to external PPP processing tools such as CSRS-PPP. ### `.log` Files The `.log` files option produces a series of human-readable CSV files containing a number of PpRx outputs, including raw GNSS observables data, transmitter information, navigation solution outputs, and diagnostics. For column definitions of each `.log` file type, see [Analyze and Convert GBX Files](/advanced-tutorials/analyze-gbx#processing-binflate-log-and-mat-files). ### `.mat` Files The `.mat` files contain the same information as the `.log` files, but are packaged in MATLAB-readable format. For column definitions of each `.mat` file type, see [Analyze and Convert GBX Files](/advanced-tutorials/analyze-gbx#processing-binflate-log-and-mat-files). :::note All output filenames are selected automatically with an index number that avoids overwriting existing outputs in the selected folder. The outputs of a given PpRx run always share the same output index number, so if a folder has up to `output_037.gbx` and `output_012.nmea`, the next output names generated for a run producing GBX and NMEA will be `output_038.gbx` and `output_038.nmea`. ::: --- ## Set Up PpRx in a Docker Container import PhaseProgress from '@site/src/components/PhaseProgress'; import ProductName from '@site/src/components/ProductName'; # Set Up PpRx in a Docker Container Learn how to run PpRx inside a Docker container while keeping the RadioLion kernel module and license setup on the host. ## Overview PpRx can run inside a Docker container, with the install directory mounted from the host. This keeps the installed files, RadioLion kernel module, and license checkout on the host filesystem, so they persist across container rebuilds, while PpRx itself executes inside the container. Installation and RadioLion kernel setup happen on the **host**, outside the container. License checkout happens **inside** the container, since that reflects the actual runtime environment PpRx will execute in. :::note Ensure the Docker image's Ubuntu version is at or above the host computer's Ubuntu version. ::: :::warning A dockerized PpRx install is CLI-only. The Locus Lock GUI is not available inside the container. Only the CLI specific sections of the tutorials will be applicable. ::: ## Steps 1. On the host, run the install script with the `--docker` flag. Note the install location, since it's needed for the container mount in a later step. ```bash bash -c "$(curl -fsSL https://install.locuslock.com/installer.sh)" --docker ``` The `--docker` flag skips the license-checkout prompt during install; license checkout happens later, from inside the container. 2. Set up the RadioLion kernel module on the host: ```bash cd cd src/front-end/radiolion-r2/scripts ./reload_femodule.bash ``` Verify that two RadioLion device nodes are present: ```bash ls /dev/rad* ``` 3. Save the following as `docker-compose.yml`, updating the bind mount `source` to point to your actual `locus-lock` install directory from step 1: ```yaml services: locuslock: container_name: locuslock image: ubuntu:24.04 post_start: - command: > sh -c ' apt-get update && apt-get install -y curl ca-certificates ' environment: - PATH=/home/locus-lock/src/bin:$PATH network_mode: host volumes: - type: bind source: /home/ubuntu/locus-lock # <-- change this to whatever the install path on the host is target: /home/locus-lock - type: bind source: /etc/machine-id target: /etc/machine-id read_only: true devices: - /dev/radiolion0:/dev/radiolion0 - /dev/radiolion1:/dev/radiolion1 entrypoint: ["sleep", "infinity"] ``` :::tip Persisting the install directory across container rebuilds, whether through this bind mount or a dedicated Docker volume, matters: it's what keeps a checked-out license valid instead of requiring a new checkout after every rebuild. ::: :::note The `/etc/machine-id` bind mount is optional, but including it gives PpRx's license checkout more information to identify the machine. ::: 4. Start the Docker container: ```bash sudo docker compose up -d ``` 5. Check out a license from inside the container: ```bash docker exec -it -w /home/locus-lock/src/license-management locuslock ./checkout_license ``` `checkout_license` prompts for a Customer ID or License ID. See [License Management](/license-management) for the difference between the two. :::note Docker containers have a weak hardware ID. A license checked out here must check in again (by re-running `checkout_license`) at least once every 30 days, and is intended for development use only. See [License Check-Ins](/license-management#license-check-ins). ::: 6. PpRx is now ready to run within the container. ## Why License Checkout Happens Inside the Container Running `checkout_license` from inside the container, rather than during the host-side install in step 1, ensures the license reflects the actual runtime environment PpRx executes in. Performing the rest of the install (steps 1–2) on the host keeps a persistent local file structure across container rebuilds, and ensures the RadioLion kernel module is set up correctly on the host it's physically connected to. --- ## Advanced Tutorials import PhaseProgress from '@site/src/components/PhaseProgress'; import Link from '@docusaurus/Link'; # Advanced Tutorials **This page is a menu, not a sequence.** Unlike the Beginner Tutorials, you do not work through every page here. Pick the tutorials that match your deployment, skip the rest, and use what you picked to build a bench-level evaluation against your target application. If you haven't completed the [Beginner Tutorials](/beginner-tutorials) yet, do those first. ## Pick what fits | If you need to... | Follow | |---|---| | Plan which of NMEA, GBX, RINEX, KML, `.log`, or `.mat` your application consumes | [Configure PpRx Outputs in the GUI](/advanced-tutorials/configure-outputs) | | Inspect or convert receiver output files | [Analyze and Convert GBX Files](/advanced-tutorials/analyze-gbx) | | Wire PpRx outputs into an external application in real time | [Porting GBX to Other Applications](/advanced-tutorials/porting-gbx) | | Have PpRx start automatically with the host | [Set Up a PpRx Service](/advanced-tutorials/setup-service) | | Run PpRx headless or embedded | [Run PpRx from the CLI](/advanced-tutorials/run-cli) | | Configure for precision heading | [Configure for Precision Heading in the GUI](/advanced-tutorials/precision-heading) | | Cut time-to-first-fix with ephemeris/almanac preloading | [Warm Start PpRx](/advanced-tutorials/warmstart-pprx) | | Tune GUI input/output reload behavior and map display | [User Preferences in the GUI](/advanced-tutorials/user-preferences) | | Run PpRx inside a Docker container | [Set Up PpRx in a Docker Container](/advanced-tutorials/docker-setup) | Detailed reference material for these tutorials lives in the [PpRx docs](/pprx/intro), and is linked from individual tutorials as needed. **You're done with Phase 4 when:** a recorded or simulated RF input flows through PpRx and is consumed by a stub of your target application. From there, continue to Phase 5 (Prototype) via the [Setup Journey](/setup-journey). --- ## Porting GBX to other Applications import PhaseProgress from '@site/src/components/PhaseProgress'; # Porting GBX to other Applications Learn the basics of parsing GBX output streams for use in other applications. ## Overview A common use case of PpRx output is to provide GNSS measurements and full PNT solutions to external applications. This is typically accomplished by streaming the GBX output to a parsing application through a POSIX pipe. This tutorial provides a guide for running the example `gbx_parser.py` on a GBX stream produced by PpRx in either the GUI or CLI. The `gbx_parser.py` example comes pre-packaged within the `locus-lock` folder. ## GUI Instructions Set up PpRx to output a GBX stream to a named pipe: 1. Configure PpRx `.opt` and `.config` files within the GUI. 2. Configure PpRx for `Post-Processing` mode and enable `Simulate Realtime`. 3. Select a pre-recorded `.bin` file as the data input. 4. Configure PpRx to output to a Named Pipe (for example `gbx_pipe`) in the configured output folder. 5. In a terminal window, navigate to the output folder and create the named pipe with `mkfifo gbx_pipe`. Set up `gbx_parser.py` in a terminal window: 1. `cd /utilities/gbx-toolbox` 2. Build the python virtual environment with `setup_venv.sh` 3. Source the virtual environment with `source venv/bin/activate` 4. Run the parser with `python3 gbx_parser.py --verbose --pipe_path '/gbx_pipe' --output_path '/parser_output.gbx'` :::note The `--output_path` argument sets the file path to which parsed data is logged. ::: :::note The parser will wait until data is published to the pipe. ::: To run PpRx and verify outputs: 1. In the GUI, press the `Run PpRx` button. 2. In the terminal window running `gbx_parser.py`, observe the parsed message contents printed to the terminal. ## CLI Instructions Set up PpRx for CLI use: 1. Create PpRx `.opt` and `.config` files (for example `example.opt` and `example.config`) for post-processing a pre-recorded `.bin` dataset. 2. Create a POSIX pipe with `mkfifo gbx_pipe`. 3. Ensure PpRx is configured to write GBX data to the POSIX pipe with the `.opt` file argument `-o gbx_pipe`. Set up `gbx_parser.py` in a terminal window: 1. `cd /utilities/gbx-toolbox` 2. Build the python virtual environment with `setup_venv.sh` 3. Source the virtual environment with `source venv/bin/activate` 4. Run the parser with `python3 gbx_parser.py --verbose --pipe_path '' --output_path ''` To run PpRx from the CLI and verify outputs: 1. In a terminal window, run PpRx with `pprx -f example.opt` 2. In the terminal window running `gbx_parser.py`, observe the parsed message contents printed to the terminal. ## Streaming Over UDP PpRx does not have a native UDP output option. To reach a parsing application over the network, keep PpRx writing to a local named pipe as above, then use `netcat` to forward that pipe's contents to a UDP port. Create the named pipe and point PpRx at it as described in the CLI or GUI instructions above (for example `-o gbx_pipe`), then in a separate terminal window, forward the pipe to the destination host and port: ```bash nc -u < gbx_pipe ``` This works for keeping PpRx and the parsing application on the same host too: point `netcat` at `127.0.0.1` and a listening application bound to the same port. On the receiving end, any application that can bind a UDP listener on the configured port can consume the stream. This includes `gbx_parser.py`, though it expects a file or named pipe path by default. Using `gbx_parser.py` with a UDP source as-is requires a small wrapper that binds a UDP socket and writes received data to a named pipe, or feeds it directly into a parser. ## Expected Result If run with `gbx_parser.py --verbose`, the parser will print parsed GBX message data while PpRx is running. ## Additional Reading `gbx_parser.py` is an example. For reduced overhead in high-performance applications, optimized parsing applications are recommended. See [GBX Protocol Description](/pprx/gbx-protocol) for useful information when creating a GBX parsing application. --- ## Configure for Precision Heading in the GUI import PhaseProgress from '@site/src/components/PhaseProgress'; import ProductName from '@site/src/components/ProductName'; # Configure for Precision Heading in the GUI Learn how to configure PpRx for dual-antenna precision heading or IMU-aided pose in the GUI. ## Overview This tutorial walks through configuring PpRx to output precision heading or a full IMU-aided pose from a dual-antenna setup. Precision heading and IMU-aided pose are enabled by setting `ESTIMATOR_PROFILE` in the PpRx `[ESTIMATOR]` block. `ESTIMATOR_PROFILE` can also be set from the GUI: the Configuration Generator asks which estimator profile you want to use. A profile is a product-level preset, not a customer-configurable combination of positioning methods, IMU coupling strategies, or filter types. Selecting a dual-antenna or IMU-aided profile adds estimators to the standard navigation solution; it does not replace it. | `ESTIMATOR_PROFILE` | Standard navigation | Dual-antenna heading | IMU-propagated pose | Requirements | | --- | :---: | :---: | :---: | --- | | `STANDARD` | Yes | No | No | No additional requirements | | `STANDARD_DUAL_ANTENNA_HEADING` | Yes | Yes | No | PRIMARY and ALT1 antennas; `BASELINE_VECTOR_B` | | `STANDARD_IMU_DUAL_ANTENNA_HEADING` | Yes | Yes | Yes | PRIMARY and ALT1 antennas; `BASELINE_VECTOR_B`; [`[IMU]`](/pprx/reference-definitions/pprx-configs/imu) configuration | The `[CDGNSS]` and `[IMU]` blocks only matter for the profile that requires them. See [CDGNSS](/pprx/reference-definitions/pprx-configs/cdgnss) and [IMU](/pprx/reference-definitions/pprx-configs/imu) for details. Prerequisites: - Two antennas plugged into the (PRIMARY and ALT1). Antennas should be statically mounted on the vehicle. - A measurement of the full body-frame vector between antenna phase centers. Recommended precision is on the order of millimeters. Measure the baseline consistently between the same antenna phase centers used in the config. Baseline orientation and distance should match the physical installation. :::note Body-frame convention: PpRx uses a right-handed forward-left-up body frame centered at the phase center of the PRIMARY antenna (positive X forward, positive Y left/port, positive Z up). See [PpRx Estimator Profiles](/pprx/reference-definitions/pprx-configs/estimator) for the full convention. ::: ## Configure via the GUI Open the Configuration Generator and scroll to the **Estimator Configuration** section. Select the desired **Estimator Profile** from the dropdown. For dual-antenna heading (no IMU), select `STANDARD_DUAL_ANTENNA_HEADING` and enter the baseline vector between the PRIMARY and ALT1 antennas, in the forward-left-up body frame: ![Estimator Configuration: dual-antenna heading](/img/leo100/precision-heading-gui-1.png) For a full IMU-aided pose, select `STANDARD_IMU_DUAL_ANTENNA_HEADING`. This adds fields for the IMU's position and orientation in the body frame, and the IMU hardware in use: ![Estimator Configuration: IMU-aided dual-antenna pose](/img/leo100/precision-heading-gui-2.png) For the body-frame convention and how to express `POS_IMU_B` and `ORIENTATION_IMU_B` (including quaternion component order), see Body Frame and IMU Orientation Reference. Generate and set the `.opt`/`.config` files as usual. The GUI writes the corresponding `ESTIMATOR_PROFILE`, baseline, and `[IMU]` parameters described below. To configure for CLI use, inspect the generated `.opt`/`.config` files to see how the GUI expresses these settings, and cross-reference against the example blocks under [Estimator Profiles](/pprx/reference-definitions/pprx-configs/estimator#estimator-profiles). ## Expected Result Once a solution is obtained, check the information window at the bottom of the GUI. For dual-antenna heading (no IMU), the information window only reports `Heading`: ![Precision Heading](/img/leo100/precision-heading-1.png) For a full IMU-aided pose, the information window reports `Heading`, `Roll`, `Pitch`, and `Yaw`: ![IMU-Aided Pose](/img/leo100/precision-heading-2.png) For the full parameter reference (tuning, `[CDGNSS]` settings, vehicle-velocity and zero-velocity constraints), see [PpRx Estimator Profiles](/pprx/reference-definitions/pprx-configs/estimator). --- ## Run PpRx from the CLI import PhaseProgress from '@site/src/components/PhaseProgress'; # Run PpRx from the CLI Learn how to process live and recorded RF data with PpRx from the CLI. ## Overview Executing PpRx from the command line interface (CLI) is useful, especially in embedded or production environments. The CLI provides complete, precise control over PpRx, much of which is otherwise abstracted away by the GUI. The CLI also avoids the CPU and RAM overhead of the GUI. ## Modifying PpRx `.opt` and `.config` Files PpRx behavior is determined by the input Option (`.opt`) and Configuration (`.config`) files. These files are human-readable and can be modified with any text editor. A list of PpRx options can be viewed with: ```bash pprx --help ``` Options are typically higher-level behavior settings such as input/output, threading, and update intervals. Any option can be added to the `.opt` file. If the same option appears more than once, the last value is used. Options can also be passed directly on the CLI when calling PpRx. When an option is present in both places, the CLI value overrides the value in the `.opt` file for that run. Configurations are lower-level behavior settings and are generally more complex, such as tracking loops, estimators, and code generation. Definitions for each configuration parameter are available in the [PpRx Advanced Documentation](/pprx/intro). :::warning Manual `.opt` and `.config` tuning is complex. As a starting point, use the GUI [Configuration Generator](/beginner-tutorials/configure-pprx) to generate a first-pass `.opt` and `.config`, then edit those files for CLI use. ::: ## Switching Between Live and Post-Processing To toggle PpRx between live and post-processing modes, the following parameters are most relevant: 1. The `-i [ --input-file]` argument in the `.opt` file must point either to a `radiolion` device node (live) or a `.bin` file (post-processing). 2. The `[BL_LION]` section of the `.config` file must set the `TYPE` field to either `USB` (live) or `FILE` (post-processing). 3. In post-processing mode, the `--imu-file` argument is usually removed. Here is an example `.opt` file for live and post-processing: ``` # Live Processing -i /dev/radiolion0 --imu-file /dev/radiolion1 -c ./autogen_01.config -t -1 --bitpack lion --log-interval 10 --ref-interval 1 --acq-interval 33 --verbose -o pprx.gbx ``` ``` # Post-Processing -i /home/user/capture.bin -c ./autogen_01.config -t -1 --bitpack lion --log-interval 10 --ref-interval 1 --acq-interval 33 --verbose -o pprx.gbx ``` Here is an example `[BL_LION]` section for live and post-processing: ``` # Live Processing [BL_LION] DEVICE = LION TYPE = USB FRONT_ENDS = LION LION_L5 ``` ``` # Post-Processing [BL_LION] DEVICE = LION TYPE = FILE FRONT_ENDS = LION LION_L5 ``` ## Running PpRx from the CLI Run PpRx by providing the `.opt` file. PpRx must be run from the same directory as the `.opt` file (or use absolute paths inside the `.opt`), because the config path inside `.opt` is typically relative: ```bash cd /path/to/your/pprx/files pprx -f autogen_01.opt ``` You can override specific options on the CLI without editing the `.opt` file. CLI arguments take precedence over values in the `.opt` file: ```bash # Override output path and run time, keep everything else from the .opt file pprx -f ./autogen_01.opt -o ./output/pprx_out.gbx -t 60 ``` ```bash # Temporarily enable verbose display without editing the .opt file pprx -f ./autogen_01.opt --verbose ``` :::tip Adding the `--verbose` argument enables the [PpRx Display](/pprx/pprx-display) on `stdout`. This provides useful real-time diagnostic information while the receiver is running. ::: ## Output Files Each PpRx run creates several files in the **working directory** (the directory from which `pprx` is called): | File | When created | Description | |---|---|---| | `pprx.gbx` (or as set by `-o`) | Always | Primary binary output containing all GBX reports | | `display.log` | When `--verbose` is **not** passed | Plain-text copy of the display, updated each refresh interval. Useful for post-run review. | | `diagnostics.log` | Always | Channel-level event log. Without `--debug`: contains INFO-level events (acquisitions, promotions/demotions). With `--debug`: full trace (~300+ messages/sec). | | `.mat` / `.log` files | When `-s mat` or `-s log` is set | Series of MATLAB- or log-format output files, one per output category (observables, navigation solution, diagnostics, and so on). See [Configure PpRx Outputs in the GUI](/advanced-tutorials/configure-outputs) for the full breakdown. | :::note `diagnostics.log` is always created in the working directory and is appended to across runs (not overwritten). The count shown at the end of a run (`See N messages in diagnostics file.`) reflects the total in the file, not just the current run. ::: For the log-interval startup warning, see [PpRx Tuning Tips](/pprx/pprx-tuning#log-interval-warning). For real-time performance issues, see [Troubleshooting Tips](/troubleshooting). --- ## Set Up PpRx systemd Service import PhaseProgress from '@site/src/components/PhaseProgress'; import ProductName from '@site/src/components/ProductName'; # Set Up PpRx systemd Service in the GUI Learn how to set up a `systemd` service to enable automatic PpRx execution on boot. ## Overview The host computer can be configured to automatically execute PpRx on boot. On Ubuntu devices, this can be accomplished with a `systemd` service. This tutorial shows how `systemd` services can be created and managed within the GUI application. :::note The `systemd` service created by the GUI application is an example configuration. Production systems may require a custom service definition. ::: The GUI-created `systemd` service is intended to run on live data streams. The service waits for a valid `radiolion` device to be present in the filesystem before executing PpRx. ## Steps PpRx `systemd` services can be managed from the **PpRx Service Manager** dialog within the GUI. To open this dialog, select `Run` → `PpRx Service Manager` from the menu bar. The PpRx service manager dialog will look like this: ![systemd Service Configuration](/img/leo100/setup-service-1.png) Select the PpRx `.opt` and `.config` files and the service output folder. The service will create subfolders within the service output folder with names based on the system time at which the folder was created. A new subfolder will be created for each PpRx run the service attempts. The service is capable of outputting three types of data products: 1. GBX data to file [required] 2. NMEA GPGGA and GPRMC sentences to file or UDP port [configurable] 3. Raw RF data samples to file [configurable] For this tutorial, all output products are configured: ![systemd Service Configuration](/img/leo100/setup-service-2.png) To install the `systemd` service, press `Install Service`. If a valid `radiolion` device is available, the service will automatically run PpRx. The right-hand pane should then indicate that the service is installed and active. The PpRx display of the current running service can be viewed by selecting `Tools` → `PpRx Display`. ![systemd Service Configuration](/img/leo100/setup-service-3.png) Remove an existing service by pressing the `Remove Service` button. The current service must be removed before it can be modified. An installed service can be controlled using the buttons in the `Service Control` pane. Hover over each button for a description of its functionality. If the PpRx service is running and has been configured to output NMEA sentences on port `127.0.0.1:5280`, then outputs can be viewed by opening a terminal and running: ```bash nc -4 -u -l -k 5280 ``` ## Expected Result For each PpRx run attempted by the `systemd` service, a subfolder will be created within the configured Service Output Folder. Each subfolder will contain: 1. PpRx `.opt` and `.config` files used in that run 2. `diagnostics.log` and `display.log` files 3. The output `.gbx` file 4. If configured, NMEA and raw RF data files --- ## User Preferences in the GUI import PhaseProgress from '@site/src/components/PhaseProgress'; # User Preferences in the GUI The User Preferences dialog allows you to configure input/output reload behavior and map display settings for the Locus Lock GUI. Navigate to **File** → **User Preferences** in the menu bar to open the dialog. ![LEO100 GUI User Preferences Dialog](/img/leo100/user-preferences-1.png) Click **Save Preferences** to apply any changes. Click **Restore Defaults** to reset all fields to their default values. --- ## PpRx Input/Output Preferences Controls which PpRx settings are restored from the previous session when the GUI is reopened. | Field | Default | Description | |---|---|---| | **Reload PpRx Configuration (.opt + .config)** | Enabled | Restores the previously used PpRx `.opt` and `.config` file paths on GUI startup. | | **Reload RF and IMU Data Files** | Enabled | Restores the previously used raw RF `.bin` and IMU data file inputs on GUI startup. | | **Reload Processing Mode Arguments** | Enabled | Restores the previously used processing mode arguments on GUI startup. | | **Reload Output Folder** | Enabled | Restores the previously used output folder path on GUI startup. | | **Reload Output Products** | Disabled | When enabled, restores the previously selected output products on GUI startup. | | **Reload Warm-Start Imports (.eph + .alm + auto-use exported)** | Enabled | Restores the previously selected ephemeris and almanac import files, and the **Automatically use exported .eph and .alm files** setting, on GUI startup. | --- ## Map Tile Preferences Controls how map tiles are fetched, cached, and displayed in the GUI. By default, the GUI uses **OpenStreetMap (OSM)**. Switch to Google Maps to access **Satellite** or **Hybrid** view. ![LEO100 Map Tile Preferences Dialog](/img/leo100/user-preferences.png) ### Switching to Google Maps :::warning Google Maps requires a valid API key. Review [Google Maps Platform pricing and terms](https://mapsplatform.google.com/) before proceeding, as tile usage may incur costs against your Google Cloud account. ::: **Step 1: Generate a Google Maps API Key** If you already have a Google Maps API key, skip to Step 2. 1. Go to [Google Maps Platform](https://mapsplatform.google.com/) and log in or create an account. 2. Navigate to **Keys & Credentials** in the sidebar. 3. Select **API key** from the **Create Credentials** dropdown. 4. Copy and store the key somewhere safe. **Step 2: Set the Map Provider and Map Type** 1. Set **Map Provider** to **Google**. 2. Set **Map Type** to **Street**, **Satellite**, or **Hybrid**. 3. Paste your API key into the **Google API Key** field. **Step 3: Validate the API Key** Click **Run Google Tile Diagnostic**. A successful result displays: 'Session OK (hybrid). HTTP 200' If the diagnostic fails, verify the key is correct and that the Maps JavaScript API and Map Tiles API are enabled in your Google Cloud project. **Step 4: Save Preferences** Click **Save Preferences**. The map will reload with the new settings. ### Map Tile Preference Fields | Field | Default | Description | |---|---|---| | **Map Provider** | OpenStreetMap | Tile source: **OpenStreetMap** (no key required) or **Google** (requires API key). | | **Map Type** | Street | Visual style: **Street** (OSM or Google), **Satellite** or **Hybrid** (Google only). | | **Google API Key** | — | Authenticates Google tile requests. Cached in RAM for the session only. Use **Clear** to remove. | | **Test Google API Key** | — | Runs a live tile fetch to validate the entered API key. A successful result displays `Session OK. HTTP 200`. | | **Google Tile Usage** | — | Number of Google tiles downloaded this session. Resets on GUI restart. | | **RAM Cache (MB)** | 128 | RAM allocated for caching map tiles during a session. Reduces redundant network fetches. | | **Disk Cache (MB)** | 1,024 | Disk space reserved for persisting tile cache across sessions. | | **OSM Backup** | Enabled | When enabled, falls back to OSM Street tiles if the primary provider is unavailable. | | **RAM Cache Used** | — | Read-only display of current RAM cache consumption. | | **Disk Cache Used** | — | Read-only display of current disk cache consumption. Use **Clear Map Tile Cache** to flush. | --- ## Offline Maps (OSM only) Enables downloading OSM tiles for offline use. Only available when **OpenStreetMap** is selected as the map provider. :::note Tile downloads will be interrupted if the GUI goes offline during the download. ::: | Field | Default | Description | |---|---|---| | **Offline Min Zoom** | 12 | Minimum zoom level to include in the offline tile download. Lower values cover larger areas at less detail. | | **Offline Max Zoom** | 18 | Maximum zoom level to include in the offline tile download. Higher values capture more detail but require significantly more storage. | | **Offline Cache (MB)** | 1,024 | Maximum disk space allocated for the offline tile cache. | | **Estimated Download** | — | Estimated size of the offline tile download for the current map view and zoom range. Displays `Unavailable` when Google is selected as the map provider. | | **Offline Cache Used** | — | Read-only display of current offline cache consumption. | | **Clear Offline Map** | — | Deletes the offline tile cache. | | **Download Offline Map** | — | Starts downloading tiles for the current map view at the configured zoom range. | --- ## Warm Start PpRx import PhaseProgress from '@site/src/components/PhaseProgress'; # Warm Start PpRx Learn how to import and export ephemeris and almanac files using PpRx. ## Overview A warm start allows PpRx to begin with previously collected navigation data instead of waiting for bits over the RF stream. In practice, this means exporting ephemeris (`.eph`) and almanac (`.alm`) files during one run, then importing those files into the next run. Ephemeris files can also be downloaded from the internet using the GUI. Importing ephemeris has the largest effect on time-to-first-fix (TTFF): it lets PpRx compute a position as soon as it has pseudorange measurements, instead of waiting to demodulate ephemeris data from the signal's navigation message bitstream (which can take tens of seconds). Importing almanac data shortens acquisition instead, by narrowing which satellites and signals PpRx searches for first. This tutorial covers warm start procedures using both the GUI and CLI. These workflows are most useful when the same system is restarted repeatedly in the field or when PpRx settings are being iterated during post-processing or development. :::note This tutorial covers warm starting with imported ephemeris and almanac data. The same `.opt` pattern can be used whether PpRx is launched directly from the CLI or through a service that points to the same `.opt` file. ::: :::warning Ephemeris data is typically only useful within a few hours of capture time. In practice, use the newest available `.eph` file for the next run. Expired ephemeris data is ignored by PpRx. ::: ## Export Warm Start Data from the GUI Ephemeris and almanac information can be exported from the GUI by configuring the relevant output products in the Output Configuration dialog. See [Configure PpRx Outputs in the GUI](/advanced-tutorials/configure-outputs). The ephemeris (`.eph`) and almanac (`.alm`) files will be written to the configured output folder. ## Download Ephemeris Data in the GUI The GUI can download ephemeris data (GPS and Galileo only) from relevant NASA websites. This feature requires an internet connection and can be accessed by selecting `Run` → `Configure PpRx Warmstart` from the menu bar. To download ephemeris data: 1. Select an output folder for the `.eph` file. 2. Choose a `.eph` output file name (for example `output_ephemeris`). 3. Select the desired ephemeris time using the GPS Week, TOW, UTC Date, and UTC TOD fields. 4. Press `Download .eph` to download data only, or `Download + Set .eph` to download and set the ephemeris data. ![Download Ephemeris Files](/img/leo100/warmstart-download-1.png) Ephemeris data will be written to the output folder. ## Import Ephemeris and Almanac Data from the GUI Open the Configure PpRx Warmstart dialog by selecting `Run` → `Configure PpRx Warmstart`. Both ephemeris and almanac data can be imported from the GUI. ![Configure PpRx Warmstart: Ephemeris and Almanac Import](/img/leo100/warmstart-import-1.png) To import ephemeris and/or almanac data during the next PpRx run in the GUI: 1. Under **Ephemeris Import**, press `Select Ephemeris (.eph) file` and choose the desired `.eph` file. Under **Almanac Import**, press `Select Almanac (.alm) file` and choose the desired `.alm` file. 2. The GUI parses and displays a summary of each selected file (constellations, satellite counts, and approximate validity time). Verify it looks correct. 3. Close the Configure PpRx Warmstart dialog window. In the Input/Output overlay, a small text message should confirm that PpRx is configured for warm start with the selected ephemeris and/or almanac information. 4. Run PpRx. :::note The **Automatically use exported .eph and .alm files** toggle, when enabled, sets the most recently exported ephemeris and almanac files as the warm start inputs for the next run automatically, once the current run finishes. Manual file selection and clearing are disabled while this is on. ::: ## Export Warm Start Files from the CLI Start from a working `.opt` file and add export options for ephemeris and almanac data: ```bash -i /dev/radiolion0 --imu-file /dev/radiolion1 -c ./autogen_01.config -t -1 --bitpack lion -o ./output/pprx.gbx --export-ephem ./output/warmstart.eph --export-alm ./output/warmstart.alm --exp-interval 60 ``` Relevant options: - `--export-ephem` writes ephemeris data for reuse on a later run. - `--export-alm` writes almanac data for reuse on a later run. - `--exp-interval` periodically updates exportable navigation data while PpRx is running. Let the run finish normally, or stop it with `Ctrl+C`. By default, PpRx also writes these files when a run completes cleanly. If the process is terminated without normal shutdown, the final export may not be written. ## Import the Files from the CLI Once recent warm start files are available, add the import options to the next PpRx startup: ```bash pprx -f ./autogen_01.opt \ --import-ephem ./output/warmstart.eph \ --import-alm ./output/warmstart.alm \ -o ./output/pprx_out.gbx ``` Alternatively, add the same import options directly to the `.opt` file: ```bash --import-ephem ./output/warmstart.eph --import-alm ./output/warmstart.alm ``` Warm starts are most effective when the imported files are recent and were captured close in time to the next run. :::note After importing ephemeris on a warm start, transmitter identifiers (TXID) in the PpRx Display may still show a `?` decoration (health status unknown) on some satellites, even though ephemeris was imported successfully. This is normal. The `?` flag is cleared only once the satellite health status has been received over the RF signal, not from the `.eph` file. It does not indicate that the import failed, and those channels will still contribute to the navigation solution once locked. ::: ## Configure PpRx for Auto Warm Start using the `.opt` file PpRx can be configured to warm start automatically upon start up. With this configuration PpRx will overwrite the almanac and ephemeris files at the end of every run, and import those files in the following run. Auto Warm Start is most effective when consecutive PpRx runs are close in time, ensuring relevant almanac and ephemeris data. To enable Auto Warm Start, add the import and export options directly to the PpRx `.opt` file: ```bash --import-ephem ./output/warmstart.eph --import-alm ./output/warmstart.alm --export-ephem ./output/warmstart.eph --export-alm ./output/warmstart.alm ``` These options will ensure that ephemeris and almanac data will be imported at the start of every run and written at the end of every run. :::warning There must be pre-existing files at the paths specified by `--import-ephem` and `--import-alm` before the first run. On the very first run, either export the files from a prior PpRx session, or remove the import lines from the `.opt` file until at least one export run has completed. ::: ## Warm Start File Validity | File | Typical useful lifetime | Notes | |------|------------------------|-------| | `.eph` (ephemeris) | 2–4 hours | PpRx silently ignores records past their fit interval; very stale files add no benefit but do not cause errors | | `.alm` (almanac) | Days to weeks | Almanac data changes slowly; older files still reduce acquisition search space | ## Expected Result PpRx can be restarted using previously exported `.eph` and `.alm` files, reducing time-to-first-fix by avoiding the wait to demodulate ephemeris data over the RF signal, and reducing acquisition time by narrowing the initial satellite search with almanac data. --- ## Check Installation import PhaseProgress from '@site/src/components/PhaseProgress'; import ProductName from '@site/src/components/ProductName'; # Check Installation Verify that PpRx is installed correctly and that the enumerates on your host. You're done when the GUI shows as *Connected* and two `/dev/radiolion*` nodes appear in the CLI. ## Check Installation in the GUI Open the GUI and verify the following: 1. PpRx Version is not "Unknown" 2. shows as "Connected" when plugged in. Below is an example of the GUI with plugged in. ![LEO100 GUI installation verification](/img/leo100/verify-install-gui.png) ## Check Installation in the CLI To verify proper software installation via CLI, open a terminal and run: ```bash pprx --version ``` To verify that the is connected over USB, check for the Linux devices: ```bash ls /dev/rad* ``` Two device nodes should appear, for example `radiolion0` and `radiolion1`. The device nodes may enumerate higher on some systems (e.g. `radiolion1` and `radiolion2`). This is normal. The lower-numbered node is always the RF stream and the higher-numbered node is the IMU stream. :::note For live CLI operation, ensure that the `.opt` file points to the correct `radiolion` device-node numbers for the host system. ::: If the expected device nodes do not appear, see [Troubleshooting Tips](/troubleshooting). --- ## Configure PpRx in the GUI import PhaseProgress from '@site/src/components/PhaseProgress'; import ProductName from '@site/src/components/ProductName'; # Configure PpRx in the GUI Generate a working `.opt` and `.config` pair so PpRx is ready to run on either your captured `.bin` or a live stream. ## Background PpRx needs three inputs to run, and each input plays a distinct role: 1. **Options (`.opt`) file**: controls I/O. Which devices and files PpRx reads, which outputs it writes, and where. 2. **Configuration (`.config`) file**: controls receiver internals. Acquisition, tracking-loop, and estimator tuning. 3. **RF data source**: either a live stream from , or a `.bin` file recorded in the previous tutorial for post-processing (replay mode). PpRx is _highly_ configurable through the `.opt` and `.config` files. To make initial file generation more approachable, Locus Lock includes a Configuration Generator in the GUI. ## Configuration Generator The Locus Lock GUI includes a Configuration Generator utility. Open it with `Run` → `Open Configuration Generator`. ![GUI Configuration Generator](/img/leo100/config-generator-1.png) Select the desired settings. Press the `?` buttons to open information dialogs relevant to each field. Choose an output folder where the `.opt` and `.config` files will be written. The Configuration Generator also includes an **Estimator Configuration** section, where the desired estimator profile is selected. Leave this at its default for standard single-antenna operation. For dual-antenna heading or IMU-aided pose, see [Configure for Precision Heading in the GUI](/advanced-tutorials/precision-heading). :::tip For low-power host computers (e.g. Raspberry Pi), use the `Low` Processing Power setting. ::: Press the `Generate and set .opt + .config` button to generate and set these files as PpRx inputs within the GUI. For example, the generator may create files such as `autogen_01.opt` and `autogen_01.config` in the selected folder, then immediately load them into the Input/Output Overlay. Close the Configuration Generator dialog and verify the `.opt` and `.config` files are selected in the Input/Output Overlay. ![GUI Configuration Generator](/img/leo100/config-generator-2.png) PpRx is now configured to run with the generated `.opt` and `.config` files. You can open and edit these files in a text editor using `File` → `Edit Options File` or `File` → `Edit Configuration File` from the menu bar. --- ## Beginner Tutorials import PhaseProgress from '@site/src/components/PhaseProgress'; import Link from '@docusaurus/Link'; import ProductName from '@site/src/components/ProductName'; # Beginner Tutorials Four short tutorials that take LEO100 from components on the bench to a working receiver producing a position fix. This is a **fixed, linear sequence.** Follow all four in order. These pages assume the Locus Lock GUI is installed. CLI workflows will be included in the [Advanced Tutorials](/advanced-tutorials). 1 Check Installation Verify PpRx is installed and the enumerates on your host. 2 Record RadioLion Data Capture a reproducible .bin file from the you can replay for the rest of the journey. 3 Configure PpRx in the GUI Generate a working .opt and .config pair with the Configuration Generator. 4 Process Data Run PpRx on your .bin and on a live stream. See a position fix on the map. :::tip [PpRx Display](/pprx/pprx-display) explains what the diagnostic readouts in the last tutorial actually mean. Keep it open in a tab the first few times you run PpRx. ::: **You're done with Phase 3 when:** PpRx reports a position fix on both your post-processed `.bin` and a live stream. From there, continue to Phase 4 ([Advanced Tutorials](/advanced-tutorials)). --- ## Process Data import PhaseProgress from '@site/src/components/PhaseProgress'; import ProductName from '@site/src/components/ProductName'; # Process Data This is the moment LEO100 stops being a set of components and becomes a receiver. You'll watch satellites get acquired and tracked, then see the resulting position fix appear on the map. You're done when PpRx reports a position fix on **both** your post-processed `.bin` (recorded in the previous tutorial) and a live stream. That proves the full path, from RF samples to a PVT solution, works end-to-end on your host. ## Overview Once PpRx has been configured in the GUI, it can process both captured and live RF data. Configuring the PpRx RF data input is done within the Input/Output (I/O) Overlay. After PpRx has been properly configured, the `Run PpRx` button will be enabled. :::note PpRx can be run without output products specified. For this tutorial, leave output products disabled. ::: ## Running PpRx on Captured Data (Post-Process) To configure PpRx for post-processing within the GUI: 1. Within the `Data Input` section of the I/O Overlay, select `Mode: Post-Processing`. 2. Select a `.bin` file containing captured raw RF data from a device. 3. Choose to enable or disable the `Simulate Realtime` PpRx option. Press the `?` button to open an info dialog on this setting. Press the `Run PpRx` button. PpRx will begin processing the captured data file. Live diagnostic information will be displayed in the GUI. ## Running PpRx on Live Data To configure PpRx for live processing within the GUI: 1. Within the `Data Input` section of the I/O Overlay, select `Mode: Live Processing`. 2. Verify a device is connected to the host computer and `RadioLion: Connected` is displayed in the GUI. Press the `Run PpRx` button. PpRx will begin streaming and processing live RF data from the . :::tip After a few seconds, if the status does not show `Connected`, see [Troubleshooting Tips](/troubleshooting). ::: ## Navigating the GUI Window The GUI displays receiver diagnostic information while it is running. Raw Receiver Time (RRT) will appear first in the bottom information bar. RRT refers to the time since the start of the run. As satellites are acquired and tracked, the number of unique satellites is updated. Timing, position, and other information is displayed as it becomes available. Position is displayed on the map with a 95% confidence ellipse, and a ground track is drawn for the preceding 30 seconds. An altitude plot over time is also displayed. ![Main GUI Window](/img/leo100/process-data-2.png) I/O overlay visibility, altitude plot visibility, and map locking can be toggled using the buttons in the bottom right of the GUI window. Various informative displays can be found under the `Tools` menu. Shown below are sky and C/N0 plots. ![GUI Tool Windows](/img/leo100/process-data-3.png) ## Where you're at in the Setup Journey You've completed the linear "first fix" arc: a configured PpRx, running against both recorded and live RF, producing a position solution on your host. That's the foundation everything from here on out will build on. Next up in the [Setup Journey](/setup-journey) is Phase 4 (Advanced Tutorials), where you'll pick from a menu of tutorials to scope and run your evaluation. --- ## Record RadioLion Data import PhaseProgress from '@site/src/components/PhaseProgress'; import ProductName from '@site/src/components/ProductName'; # Record RadioLion Data Capture a reproducible RF dataset you'll lean on for future debugging and tuning sessions. ## Overview Recording raw RF/IMU data from the gives you a **known-good `.bin` file** you can replay through PpRx as many times as you want. Every later step is dramatically easier when you can re-run against an unchanging dataset instead of chasing a live sky: comparing PpRx versions, tuning `.opt` and `.config`, debugging a regression, and so on. You're done with this tutorial when you have a `.bin` file on disk. Even 30 seconds is enough to move on. Data can be captured via either the GUI or CLI. The `.bin` file extension is recommended, but not required. ## Prerequisites - A suitable GNSS antenna plugged into the . - A benign RF environment for your first capture: record outdoors with a clear view of the sky, away from likely sources of interference. :::warning Recording data from is storage intensive: **~1.199 GB/min** of RF data and ~162.45 kB/min of IMU data. Pick your output folder accordingly. ::: ## Recording Raw Data via GUI To record data via the GUI, select the `Run` → `Record Raw Data` option in the menu bar. This brings up the following dialog: ![LEO100 GUI Record Data Dialog](/img/leo100/record-raw-data-1.png) Select an output folder and name for the raw data recording (`.bin` extension is added automatically). Checking `Log IMU Data` will also record raw IMU data from the . If the Status is `Connected`, a capture can be started by pressing the `Start Capture` button. During raw recording, the dialog will indicate storage used and elapsed time. The user cannot close the dialog window until data recording is stopped. ## Recording Raw Data via CLI To record data via the CLI, open a terminal window and verify the devices are present. Then start a capture with `dd`: ```bash ls /dev/rad* # Check for RadioLion device nodes sudo dd if=/dev/radiolion0 of=test_01.bin # Start a capture from the lower-enumeration RF data stream ``` The `dd` command produces no output while it is running, but prints a summary after the capture is stopped with `Ctrl+C`. For short captures, plain `dd` is usually sufficient. For long captures, or when live throughput and size information are required, pipe the stream through `pv` (pipeviewer). ```bash dd if=/dev/radiolion0 | pv | dd of=test_01.bin # Start a capture with live progress output ``` :::note `pv` may not be installed by default. Install it with: ```bash sudo apt install pv ``` If `pv` is unavailable, use `dd` with the `status=progress` flag as a fallback: ```bash sudo dd if=/dev/radiolion0 of=test_01.bin status=progress ``` ::: To also record IMU data via CLI, start the RF capture first, then open a second terminal and run: ```bash sudo dd if=/dev/radiolion1 of=test_01_imu.gbx # Record IMU stream. Must be started after the RF stream is running ``` You now have a raw RF capture from your sitting on disk as a `.bin` file. From here on, every PpRx run, configuration change, and version comparison can be re-tested against that exact same input. Any difference you see is the change you made, not a change in the sky. --- ## FAQs import ProductName from '@site/src/components/ProductName'; # FAQs See below for answers to frequently asked questions about LEO100. ## Getting Started ### Do I need to install software before I can use the LEO100? That depends on the purchased configuration. - Development kits purchased with a host computer include all required software pre-installed - Systems purchased without a host computer require software installation before starting the tutorials. See the [Software Installation](./installation.mdx) page for the full setup process. ### Can I use the Locus Lock GUI, or do I need to use the CLI? The Locus Lock GUI is the recommended starting point. It provides the most direct workflow for configuring the system, verifying hardware connectivity, and collecting or processing data. CLI workflows are also supported and are intended for production, automation, embedded deployments, and advanced workflows. ### Are GNSS antennas included with the LEO100? No. GNSS antennas are required for operation, but they are not included with the LEO100 hardware package. ### What antennas does Locus Lock recommend? Almost any triple-frequency GNSS antenna is compatible with , but antenna choice significantly affects performance. Antennas Locus Lock has qualified for use with : | **Device** | **Price** | **Link** | | --- | --- | --- | | Trimble AV28 | ~$450 | [Trimble AV28](https://www.terrisgps.com/product/trimble-av28-gnss-antenna/) | | Harxon GPS1000 | ~$210 | https://en.harxon.com/product/detail/98 | | Tallysman TW3972 | ~$370 | https://www.calian.com/advanced-technologies/gnss_product/tw3972-triple-band-gnss-antenna-l-band/ | | Trimble AG25 | ~$1000 | https://oemgnss.trimble.com/en/products/antennas/ag25 | | U-blox ANN MB 02 | ~$60 | [Digikey \| UBLOX ANN MB 02](https://www.digikey.com/en/products/detail/u-blox/ANN-MB-02/9817927) | This list is not exhaustive. ### How do I know whether to use the Beginner Tutorials or the Advanced Tutorials? The [Beginner Tutorials](/beginner-tutorials) are intended for initial familiarization with the standard GUI workflow. The [Advanced Tutorials](/advanced-tutorials) assume prior familiarity with configuring inputs, outputs, and basic PpRx operation. ## Updates and Maintenance ### How do software updates work? PpRx can be updated from the GUI or by rerunning the device installer from the CLI. The Locus Lock GUI is updated by rerunning the latest GUI installer. See [Update Software](./update-software.mdx) for the supported workflows. ### Where can I find the latest feature and fix information? The most recent feature and fix information for the PpRx GUI and CLI can be found in the [Release Notes](/announcements). ## Troubleshooting ### What should I do if the system is not producing the output I expect? Start with the basics: - Confirm the hardware is connected and powered correctly. - Verify that the correct software components are installed for the LEO100 variant in use. - Verify in the GUI or CLI configuration that the intended outputs are enabled. If problems continue, reach out using the **Support** button. --- ## Glossary import ProductName from '@site/src/components/ProductName'; # Glossary Plain-language definitions for terms used throughout the LEO100 documentation. Use this page as a reference whenever a term in the [Setup Journey](/setup-journey) or a tutorial is unfamiliar. ## A **Almanac:** A coarse, long-validity set of orbital parameters for all satellites in a GNSS constellation. Used alongside the [Ephemeris](#e) for [warm starts](/advanced-tutorials/warmstart-pprx) to reduce time-to-first-fix. ## B **`.bin` file:** The default file extension for raw RF recordings produced by the . Replayable through PpRx for post-processing. IMU data, if recorded, is written to a separate `.gbx` file rather than combined with the RF recording. See the [Record RadioLion Data](/beginner-tutorials/record-data) tutorial. ## C **C/N0:** Carrier-to-noise-density ratio, in dB-Hz. A standard measure of received GNSS signal quality. Visible in the GUI's C/N0 plot during a PpRx run. **CLI:** Command-line interface. PpRx, the device nodes, and supporting tooling can all be driven from a terminal. See the [Advanced Tutorials](/advanced-tutorials) for CLI-only workflows. **Cold start:** A PpRx run started with no prior knowledge of satellite positions or time. Time-to-first-fix is typically around 30 seconds in good RF environments. Compare to [warm start](/advanced-tutorials/warmstart-pprx). **`.config` file:** The PpRx configuration file. Controls receiver internals: acquisition, tracking-loop, and estimator tuning. Generated by the Configuration Generator during the Beginner Tutorials (Phase 3). ## D **DSP:** Digital signal processing. PpRx performs all of its GNSS receiver work, including acquisition and tracking, as software DSP on the host CPU. ## E **Ephemeris:** A precise, short-validity set of orbital parameters for a specific satellite. Required to compute that satellite's position when generating a PNT solution. Preloading ephemerides enables [warm start](/advanced-tutorials/warmstart-pprx). ## G **GBX:** Locus Lock's binary serialization format for PpRx outputs (reports, observables, ephemerides, etc.). The wire format you'll most often parse from middleware. See the [GBX Protocol Description](/pprx/gbx-protocol). **GenericType:** A signal-identifier field used inside GBX, `.log`, and `.mat` files. Mapped to specific GNSS signals via the [GenericType Mapping](/pprx/generictype-mapping) table. **GNSS:** Global Navigation Satellite System. The umbrella term for all satellite positioning constellations (GPS, Galileo, GLONASS, BeiDou, etc.). **GUI:** Graphical User Interface: the graphical application for configuring, running, and observing PpRx. Recommended starting point before moving to CLI-only workflows. ## H **Host computer:** The machine on which PpRx and the Locus Lock GUI run. LEO100 can be purchased with or without a Locus Lock-supplied host. Minimum specs are listed on the [Software Installation](/installation) page. ## I **IMU:** Inertial measurement unit. The exposes an IMU data stream on a second `/dev/radiolion*` device node. Recording IMU data is optional and unnecessary for most users. **I/O Overlay:** The Input/Output panel in the GUI where PpRx's data sources and outputs are configured. Introduced in the [Configure PpRx in the GUI](/beginner-tutorials/configure-pprx) tutorial. ## L **L1, L2, L5:** GNSS frequency bands. The is a triple-frequency front end and conditions all three. **LEO100:** The full Locus Lock turnkey PNT solution. Includes PpRx, the RF front end, and the Locus Lock GUI. See [Introduction](/) for variant details. ## M **Middleware:** Any code that sits between PpRx's outputs and your target application. Typically a parser or wrapper for GBX, NMEA, or other configured output streams. ## N **NMEA:** National Marine Electronics Association. A standard ASCII protocol for GNSS position and timing messages. One of several output formats PpRx can produce. The PpRx output follows NMEA 0183. See [Configure PpRx Outputs in the GUI](/advanced-tutorials/configure-outputs). **NTP:** Network Time Protocol. PpRx allows your host system to act as a Stratum 1 [GNSS-Disciplined NTP server](/pprx/ntp-server) to discipline the host clock. ## O **`.opt` file:** The PpRx options file. Controls I/O: which devices and files PpRx reads, which outputs it writes, and where. Generated by the Configuration Generator during the Beginner Tutorials (Phase 3). ## P **PNT:** Position, Navigation, and Timing. The class of solution LEO100 produces. **Post-processing:** Running PpRx against a previously recorded `.bin` file rather than a live stream. The default workflow for repeatable testing. **PpRx:** Locus Lock's software-defined GNSS receiver. Processes raw RF samples from the and produces a PNT solution plus configurable outputs. ## R **:** Locus Lock's RF front end. Triple-frequency (L1/L2/L5), available in single- or dual-antenna configurations. Exposes two Linux device nodes when connected: a lower-enumeration RF stream and a higher-enumeration IMU stream. **RF:** Radio frequency. The raw signal class the conditions and digitizes before handing samples to PpRx. **RINEX:** Receiver Independent Exchange Format. A standard text format for GNSS observables and navigation data. One of PpRx's optional output formats. **RRT:** Raw Receiver Time. The time since the start of a PpRx run, shown in the GUI's bottom information bar. **RTK:** Real-Time Kinematic positioning. A technique that uses carrier-phase observables and a reference station to achieve centimeter-level accuracy. ## S **Simulate Realtime:** A PpRx post-processing option that throttles `.bin` playback to wall-clock speed, mimicking a live run. ## T **TTFF:** Time to first fix. The interval between PpRx starting and producing its first valid PNT solution. Reduced by [warm start](/advanced-tutorials/warmstart-pprx). ## W **Warm start:** A PpRx run that begins with preloaded ephemeris and almanac data, reducing TTFF compared to a cold start. See [Warm Start PpRx](/advanced-tutorials/warmstart-pprx). --- ## Information Flow Overview import PhaseProgress from '@site/src/components/PhaseProgress'; import InfoFlowDiagram from '@site/src/components/InfoFlowDiagram'; # Information Flow Overview > **Phase 1 of the [Setup Journey](/setup-journey).** Build your mental model of the data path *before* installing software or plugging in hardware. LEO100 is built for **real-time embedded applications**. It produces PNT solutions, raw observables, and ancillary data entirely in software on your host computer, with no separate hardware receiver in the loop. That lets it drop cleanly into flight controllers, autopilots, autonomy stacks, and other on-vehicle compute. Knowing how a GNSS signal becomes a position fix on that host is what makes every later choice obvious instead of arbitrary: which output to enable, where to put middleware, and what to record for debugging. Trace the full path below. **You're done with Phase 1 when:** you can sketch this data path and name which LEO100 component owns each stage. Next up is Phase 2, [Software Installation](/installation). --- ## Software Installation import PhaseProgress from '@site/src/components/PhaseProgress'; # Software Installation Get PpRx and the Locus Lock GUI running on your host machine. :::tip **Purchased LEO100 with a host computer?** PpRx and the GUI come pre-installed. Skim the requirements below if you like, then jump to [Phase 3: Beginner Tutorials](/beginner-tutorials). ::: If you purchased LEO100 without a host computer, follow the steps below to install the required software on your own machine. ## Prerequisites Before running the installation scripts, have your Customer ID and/or License ID ready: the scripts will prompt for them. See [License Management](/license-management) for details on Customer ID vs. License ID. :::note Installing inside a Docker container instead? See [Set Up PpRx in a Docker Container](/advanced-tutorials/docker-setup). ::: ## Host Computer Requirements Locus Lock generally recommends the following specifications for the host computer: | Spec | Minimum | | :-: | :-: | | CPU | 64-bit, 4+ cores, 1+ GHz | | RAM | 2 GB | | Storage | 5 GB | | OS | Ubuntu LTS 22.04, 24.04, or 26.04 | Locus Lock supports all current Ubuntu LTS versions for standard installation. Software builds for other OS or architectures are available, contact support for details. ## Installing PpRx PpRx can be installed with the following command. The installer detects your computer's architecture and operating system, then installs the PpRx build for your environment. ```bash bash -c "$(curl -fsSL https://install.locuslock.com/installer.sh)" ``` PpRx requires a valid license to run. During installation, the script will prompt for your Customer ID and/or License ID, and ask whether you want to check out a license now. See [License Management](/license-management) for details. ## Install the Locus Lock GUI The Locus Lock GUI provides the primary workflow for configuring, verifying, and operating PpRx. GUI-based setup is recommended before moving to CLI-only workflows. ![Locus Lock GUI](/img/leo100/gui.png) To install the Locus Lock GUI application, run the following command: ```bash bash -c "$(curl -fsSL https://install.locuslock.com/gui_installer.sh)" ``` :::note For installations on **NVIDIA Jetson** computers, disabling VSYNC for Qt applications improves GUI performance. Run the following command in a terminal: ```bash echo "QSG_NO_VSYNC=1" | sudo tee -a /etc/environment ``` Reboot the Jetson for this setting to take effect. ::: --- ## Introduction import Link from '@docusaurus/Link'; import ProductName from '@site/src/components/ProductName'; Real-Time PNT ready to integrate. LEO100 is a turnkey Position, Navigation, and Timing solution: a software-defined GNSS receiver, a triple-frequency RF front end, and the tooling to drive both. Designed to drop into flight controllers, autopilots, autonomy stacks, and more. Begin the Setup Journey → The LEO100 docs take you from an unopened LEO100 to a working evaluation against your own application. Follow the **[Setup Journey](/setup-journey)** to achieve a fully functional software-defined GNSS receiver running in your environment. ## What's in the box Hardware The RF front end. Triple-frequency (L1/L2/L5), available in single- and dual-antenna configurations. Delivers digitized RF samples to software. Software PpRx The software-defined GNSS receiver. Processes digitized RF samples and returns a PNT solution alongside configurable outputs. Tooling Locus Lock GUI The graphical application for configuring, evaluating and operating Locus Lock LEO100. :::note GNSS antennas are **not** included with any LEO100 variant, but are required for live operation. Check the [FAQs page](/faqs#what-antennas-does-locus-lock-recommend) for Locus Lock's list of recommended antennas. ::: All LEO100 variants can be purchased with or without a host computer. If a host computer is purchased, PpRx and the GUI come pre-installed. --- ## License Management PpRx requires a valid license to run. This page covers checking out a license, checking license status, and inspecting the currently installed license. ## Customer ID vs. License ID PpRx licensing uses two different identifiers, and either one can be supplied when checking out a license or checking license status: - **Customer ID**: identifies your organization's account as a whole. Every license is associated with a single Customer ID, and there may be multiple licenses associated with a single Customer ID. - **License ID**: the unique identifier for each license. ## License Management Utilities `checkout_license` and `license_status` are standalone executables included with the PpRx installation. Both utilities require internet access. ### Checking Out a License To check out a license from the CLI, run `checkout_license`: ```bash cd /src/license-management ./checkout_license ``` `checkout_license` prompts for a Customer ID or License ID, then activates the license for the current machine. :::note If you'd like to check out a particular license associated with your account, input the License ID. Otherwise, use your Customer ID. ::: In the GUI, select `Help` → `License Management` → `Checkout License`. Follow the prompts. :::note Always run `checkout_license` in the same environment PpRx will execute in. If PpRx runs in a Docker container, run `checkout_license` in that container rather than on the host. See [Set Up PpRx in a Docker Container](/advanced-tutorials/docker-setup). ::: ### Checking License Status To inspect the status of a particular license, or the licenses associated with a Customer ID, run `license_status`: ```bash cd /src/license-management ./license_status ``` When prompted, enter the desired Customer ID or License ID. In the GUI, `license_status` can be run by selecting `Help` → `License Management` → `License Status`. ## Viewing the Installed License Once a license is checked out, `pprx --license` displays the license currently installed on the machine. This command does **not** require internet access: ```bash pprx --license ``` This prints the License ID, Customer ID, and expiration date associated with the installed license. If applicable, the next check-in date is also displayed. ## License Check-Ins License check-ins may be required depending on the environment in which PpRx runs. This is most common in VMs and Docker containers. When check-ins are required, run `checkout_license` at least once every 30 days. Use `pprx --license` to view your next check-in date, if applicable. Keep in mind that this licensing scheme is intended for LEO100 evaluation kits; production PpRx licensing is tailored to customer needs. Please contact Locus Lock at support@locuslock.com with questions about production licensing. --- ## Setup Journey import Link from '@docusaurus/Link'; import ProductName from '@site/src/components/ProductName'; # Setup Journey: From Unboxing to Evaluation This page is the starting point for LEO100 setup. Follow it from top to bottom to go from an unopened box to a working evaluation of LEO100 outputs against your target application. The process is organized into six phases. Phases 1 through 3 follow a fixed sequence. Phase 4 is organized as a decision-driven menu. Phase 5 depends on your deployment. Phase 6 focuses on selecting a production path. Relevant pages from the PpRx reference manual are linked throughout. --- ## Phase 1. Understand the data path **Goal:** before plugging anything in, build a mental model of how a GNSS signal becomes a position fix on your host computer. Knowing the four-stage flow (antenna, RF front end, PpRx, your application) is what makes every later choice obvious instead of arbitrary. Which output to enable, where to put middleware, what to record for debugging: all become easier when the flow is clear. **You're done with Phase 1 when:** you can sketch the four stages and name which LEO100 component owns each one. Go to Information Flow Overview → --- ## Phase 2. Install the software **Goal:** get PpRx and the Locus Lock GUI running on your host machine. PpRx also requires a valid license to run. See [License Management](/license-management) for checking out a license and understanding Customer ID vs. License ID. **You're done with Phase 2 when:** `pprx --version` returns a real version string and the Locus Lock GUI launches. Go to Software Installation → --- ## Phase 3. Beginner Tutorials **Goal:** verify the hardware, capture your first RF dataset, configure PpRx, and produce a position fix on both recorded and live data. This is a fixed, linear sequence of four short tutorials meant to be completed in order. By the end, LEO100 stops being a box of components and becomes a working receiver on your bench. **You're done with Phase 3 when:** PpRx reports a position fix on both your post-processed `.bin` and a live stream. Go to Beginner Tutorials → --- ## Phase 4. Advanced Tutorials **Goal:** evaluate LEO100 against the specific requirements of *your* deployment. This phase is a menu, not a sequence: pick the tutorials that match your platform and skip the rest, building toward a recorded or simulated RF input flowing through PpRx into a stub of your target application. **You're done with Phase 4 when:** a recorded or simulated RF input flows through PpRx and is consumed by a stub of your target application. Go to Advanced Tutorials → --- ## Phase 5. Prototype on the real platform **Goal:** move from the bench to a non-production version of your actual platform, in conditions that closely represent real operation. This phase typically includes: - Moving from bench evaluation to platform-level integration - Designing interfaces and building middleware between LEO100 outputs and the target application - Evaluating receiver performance on production hardware (RF and/or host computer) - High-fidelity field tests in representative or challenging conditions During this phase the PpRx reference tab becomes your primary working document. The pages you'll lean on most: - [PpRx Intro](/pprx/intro). Top of the reference section if you want to browse the full set. - [PpRx Tuning Tips](/pprx/pprx-tuning). The actual knobs that move receiver performance on a real platform. This is where most of your iteration time will go. - [PpRx Display](/pprx/pprx-display). Diagnostic readout reference, for interpreting what's happening in long field runs. - [GBX Protocol Description](/pprx/gbx-protocol) and [GenericType Mapping](/pprx/generictype-mapping). Required when middleware needs to parse PpRx output streams. - [PpRx as NTP Server](/pprx/ntp-server). For platforms that need the host clock disciplined to GNSS time. **You're done with Phase 5 when:** LEO100 runs end-to-end on your real platform hardware, in representative conditions, meeting your performance bar. --- ## Phase 6. Choose a production path **Goal:** decide how LEO100 will ship in production. Most deployments fall into one of two paths: 1. **Standard deployment.** Use LEO100 largely off the shelf, with minor modifications or support as needed. 2. **Custom deployment.** Engage Locus Lock to adapt and integrate PpRx for your specific platform requirements. This may include deploying PpRx on custom RF hardware, host processors, operating systems, middleware stacks, or application architectures, as well as implementing custom receiver features or interfaces. This phase usually involves closer coordination with Locus Lock engineering to optimize the solution for your final target platform and use case. Depending on your requirements, the resulting deployment may use the complete LEO100 platform or PpRx integrated directly into your existing hardware and software ecosystem. **You're done with Phase 6 when:** a production deployment path is selected and the corresponding engineering work is scoped. --- ## After the journey At this point, you’ve completed the evaluation and deployment planning process. The references you'll keep coming back to are all reachable from the PpRx tab in the top bar: - [PpRx Intro](/pprx/intro), [Tuning Tips](/pprx/pprx-tuning), [Display](/pprx/pprx-display), [GBX Protocol](/pprx/gbx-protocol), [GenericType Mapping](/pprx/generictype-mapping), [NTP Server](/pprx/ntp-server). The long-lived reference manual. - [Release Notes](/announcements). Check before updating or testing new features. - [Update Software](/update-software). Keeping PpRx and the GUI current. - [License Management](/license-management). Checking out and verifying a PpRx license. - [FAQs](/faqs) and [Troubleshooting](/troubleshooting). Common questions and fixes. - [Glossary](/glossary). Plain-language definitions for every acronym and term used in these docs. --- ## Troubleshooting Tips import ProductName from '@site/src/components/ProductName'; # Troubleshooting Tips ## Connection Problems If does not connect to the host computer, reload the `radiolion` kernel module in the GUI. This operation is available under `Help` → `Hardware Management` → `Reload RadioLion Kernel Module`. If the GUI is unavailable, the same check can be performed from the CLI: 1. Stop any running GUI session, service, or CLI process that may still be using the device. 2. Check whether the device nodes are present: ```bash ls /dev/rad* ``` 3. Reload the kernel module: ```bash cd cd src/front-end/radiolion-r2/scripts ./reload_femodule.bash ``` 4. After `reload_femodule.bash` runs successfully, verify that the device nodes reappear: ```bash ls /dev/rad* ``` If the device still does not appear, reconnect the hardware and inspect recent kernel messages with `dmesg`. ## Clock Drift If left unpowered for significant periods of time (>6 months), the clock may drift slightly from its intended frequency, degrading performance. The clock does not drift while the unit is powered, whether or not PpRx is actively running. The clock frequency offset can be gauged by running PpRx and looking at the `δtRdot` field in the PpRx Display. The typical desired range should be between approximately -100 and 100. In extreme cases, a clock offset may prevent a stable position solution and finding a `δtRdot` value may not be possible. In many cases, the drift can be reduced by powering the for several hours, even when PpRx is not running, allowing the clock to converge back toward its intended frequency. ## PpRx Real-Time Performance During live operation, `diagnostics.log` may contain: ``` BL.ERROR.REALTIME: Operating slower than real-time. BL.ERROR.REALTIME: Resumed real-time operation. ``` This indicates the host computer briefly fell behind the incoming RF data rate, causing potential data loss. If this occurs repeatedly, the host is under too much CPU load for the current configuration. The GUI Configuration Generator's Processing Power setting (see [Configure PpRx in the GUI](/beginner-tutorials/configure-pprx)) is the fastest way to regenerate a lower-load `.opt`/`.config` pair; for manual tuning, see the [PpRx Options](/pprx/reference-definitions/pprx-opts) and [PpRx Configuration](/pprx/reference-definitions/pprx-configs) reference. --- ## Update Software Software updates are periodically available from Locus Lock. Use the workflow below that matches the software being updated: - Update **PpRx** from the GUI if the GUI is already installed and working. - Update **PpRx** from the CLI by rerunning the device installer on headless systems or when the GUI is unavailable. - Update the **Locus Lock GUI** by rerunning the GUI installer. ## Update PpRx from the GUI PpRx software can be updated directly in the GUI: 1. Select `Help` → `Software Management` → `Update PpRx Software` from the GUI menu bar. 2. Enter the customer ID number. 3. Press `Check/Update`. 4. If updates are available, follow the prompts to install them. 5. After the update completes, restart the Locus Lock GUI. ## Update PpRx from the CLI Use the CLI workflow on headless systems or when the GUI is not available. First, locate the current PpRx installation: ```bash which pprx ``` Then download the latest device installer package and rerun `installer.sh` from that package, following the same process described in [Software Installation](/installation). Reinstalling over the existing `locus-lock` directory is the preferred update path; deleting the installation first is not necessary. Alternatively, run `update_pprx` from the `license-management` directory of the install to check for and install an update directly, without rerunning the full installer: ```bash cd /src/license-management ./update_pprx ``` This checks the installed PpRx version against the latest available version and updates it if a newer version exists. ## Update the Locus Lock GUI To update the GUI application, download the latest GUI installer package and rerun the installer, as outlined in [Software Installation](/installation). --- ## GBX Protocol Description _gbx_ is a binary serialization format for data handling within GSS (GRID Software Suite) and related software (PpRx). The _gbx_ format defines the binary representation of several reports (sometimes referred to as _messages_). ## Table of Contents 1. [Conventions](#conventions) 2. [Numeric Data Types](#numeric-data-types) 3. [GBX File/Stream Structure](#gbx-filestream-structure) 4. [GBX Report Structure](#gbx-report-structure) - [Header](#header) - [Payload](#payload) - [Footer](#footer) - [Sample Report](#sample-report) 5. [GBX Stream Structure](#gbx-stream-structure) - [The Epoch](#the-epoch) - [IMU and IMU Configuration Reports](#imu-and-imu-configuration-reports) 6. [Deserialization techniques and recommendations](#deserialization-techniques-and-recommendations) 7. [Example Program for Processing GBX Data](#example-program-for-processing-gbx-data) 8. [The Report Types](#the-report-types) 9. [Protobuf Message Definitions](#protobuf-message-definitions) ## Conventions The following conventions shall apply throughout this document: - All numerals with prefix '0x' are in base-16 (hexadecimal) notation. - All numerals without a prefix are in base-10 (decimal) notation. - value < m > represents bit _m_ in value, where bit 0 is the least significant bit. - value < m : n > represents the (_m_ - _n_ + 1)-bit bitfield from bit _m_ down to bit _n_. ## Numeric Data Types All multi-byte fields are stored in **little-endian byte order**. All signed integers are stored in **twos-complement** representation. Type | Description ---- | ----------- u8 | unsigned 8-bit integer s8 | signed 8-bit integer u16 | unsigned 16-bit integer s16 | signed 16-bit integer u32 | unsigned 32-bit integer s32 | signed 32-bit integer u64 | unsigned 64-bit integer s64 | signed 64-bit integer f32 | single-precision IEEE-754 floating point value f64 | double-precision IEEE-754 floating point value bN | **N**-bit bitfield ## GBX File/Stream Structure A properly structured _gbx_ file is simply a file which contains one or several _gbx reports_ (and nothing else). For example, a _gbx_ file which contains 2 reports, each being 10 bytes in length, is exactly 20 bytes in length. This means that there are not any separate headers at the beginning of a _gbx_ file which might be used, for example, to specify the origins of the file. As such, it is recommended that you track the origins of your _gbx_ files separately (perhaps with a similarly named .txt file) to stay organized. The recommended file extension for a _gbx_ file is ``.gbx``. ## GBX Report Structure _gbx_ reports are composed of a header, payload, and footer (in that order). As will be seen, the header has a fixed size of 8 bytes, the payload varies with report type, and the footer has a fixed size of 2 bytes. A payload size of 0 is valid and, as an example, such a payload would be serialized into a _gbx_ report totaling 10 bytes in length. ### Header Offset | Type | Name/Value | Description ------ | ---- | ---------- | ----------- 0 | u8 | 0x55 | First synchronization byte 1 | u8 | 0x54 | Second synchronization byte 2 | u8 | reportType | Report type 3 | u8 | streamId | Stream identifier 4 | u32 | reportSize | Report payload size The **fixed size of the header is 8 bytes**. #### Synchronization Bytes Protocol-specific values which should always be verified during deserialization. Earlier versions of the _gbx_ format are similar in report structure but had different values for synchronization bytes. This change was deliberate to prevent confusion. #### Report Type (``reportType``) Specifies the type of report; that is, the nature and structure of data to be found in the payload. A discussion of common report types is found [here](#the-report-types). #### Stream Identifier (``streamId``) Allows for multiple logical streams to be multiplexed into a single _gbx_ report stream. Each specific logical stream (e.g., a particular GPS receiver) shall be assigned a unique ``streamId`` value. For a _gbx_ report stream containing only one logical stream, this value will normally be 0. In the case where a second logical stream is included (e.g., a reference GNSS receiver for RTK), this second stream should be assigned a value of 1. Using any other values with the standard set of GSS tools may result in ignoring the stream. At worst, it will result in undefined behavior. #### Report Size (``reportSize``) Specifies the size of the payload (in bytes). This value __does not__ include the additional length of the header and footer. ### Payload Structure varies dependent on the specified ``reportType``. The size of the payload is specified (in bytes) by the ``reportSize`` field of the header. The payload of every report type is actually a Google Protobuf 3 binary buffer. The developer's guide for ``proto3`` is available [here](https://developers.google.com/protocol-buffers/docs/proto3). Message definition files can be found in the ``gss`` repository under the ``gss/gbxframework/messages`` directory. ### Footer Offset | Type | Name/Value | Description ------ | ---- | ---------- | ----------- 0 | u16 | checksum | Fletcher-16 checksum The **fixed size of the footer is 2 bytes**. During report deserialization, the _Fletcher-16 checksum_ should be calculated locally for the received header and payload. This calculated checksum should then be compared against the received checksum. If the calculated and received checksums do not match then the report shall be considered corrupt and discarded. The _Fletcher-16_ checksum value is for the **header and payload** and can be calculated with the following algorithm (C implementation): ~~~c u16 fletcher16(const u8* data, u32 bytes) { u16 sum1 = 0xff, sum2 = 0xff; u32 tlen; while (bytes) { tlen = ((bytes >= 20) ? 20 : bytes); bytes -= tlen; do { sum2 += sum1 += *data++; tlen--; } while (tlen); sum1 = (sum1 & 0xff) + (sum1 >> 8); sum2 = (sum2 & 0xff) + (sum2 >> 8); } /* Second reduction step to reduce sums to 8 bits */ sum1 = (sum1 & 0xff) + (sum1 >> 8); sum2 = (sum2 & 0xff) + (sum2 >> 8); return (sum2 << 8) | sum1; } ~~~ **NOTE**: Variations of the _Fletcher-16_ checksum implementation may provide different checksum values for a particular input. If using different implementations (by algorithm or language), it is recommended that you compare their output against the provided algorithm. ### Sample Report A valid and complete _gbx_ report: ``55 54 14 00 03 00 00 00 08 82 01 4C DD`` (hexadecimal byte values, left byte first) The first 8 bytes represent the [header](#header) and communicate the following: - This is a _gbx_ report (``0x55 0x54``), - of report type ``CODA`` (see [The Report Types](#the-report-types)), - multiplexed on streamId 0, - with a payload that is 3 bytes in length (note Little-Endian byte ordering of a u32) The 3 byte payload contains: ``0x08 0x82 0x01`` And the Fletcher-16 checksum (the 2 byte [footer](#footer)) of the first 11 bytes is ``0x4C 0xDD``, the Little-Endian representation of the value ``0xDD4C``. ## GBX Stream Structure With few exceptions, each individual report is entirely self-contained; that is, it contains all relevant information required to use all other information contained in the report. Where reports are found in the stream relative to other reports is generally irrelevant (other than to infer relative timing). Reports can generally be encountered in any order. This is the rule. The exceptions are to follow. ### The Epoch The _epoch_ represents a set of reports whose mutual information is applicable to the same instant in time (the _epoch_). The _epoch_ is the periodic output (say, 5Hz) of the GNSS receiver, PpRx. Every _epoch_ begins with a report of type ``OBSERVABLES_MEASUREMENT_TIME `` and ends with a report of type ``CODA``. Any ``OBSERVABLES_MEASUREMENT_TIME `` (or ``CODA``) report encountered without an associated ``CODA`` (or ``OBSERVABLES_MEASUREMENT_TIME ``) shall be considered to represent a corrupt stream or incomplete _epoch_. The following report types represent the _epoch_ produced by PpRx: 1. ``GNSS_OBSERVABLES`` 1. ``STANDARD_NAVIGATION_SOLUTION`` 1. ``TRANSMITTER_INFO`` 1. ``IQ_METADATA`` 1. ``IONOSPHERE`` 1. ``SCINTILLATION_PARAMETERS`` Note that other applications (e.g., another PpRx instance or an RTK application) operating on a PpRx-produced _gbx_ stream may add other reports to the epoch, or may remove PpRx-emplaced reports. The _epoch_ has two primary purposes: 1. The first purpose is to allow proper interpretation of individually _incomplete_ reports (e.g., due to not storing an applicable timestamp). Any timestamp associated with one _epoch_-associated report is applicable to all _epoch_-associated reports. 1. The second purpose is to facilitate robust, low-latency stream processing. The end of the _epoch_ (the ``CODA`` report) serves as an explicit signal that no other reports associated with this epoch will be received in the future. Without the benefit of this explicit signal, a processing node could only infer the completion of one epoch by the beginning of the next epoch (with resultant substantial latency). Not all _epoch_-associated report types may be present in any given epoch; in fact, a valid epoch may contain no _epoch_-associated report types. Some _epoch_-associated report types may be repeated multiple times. If any other report types have an associated timestamp which is exactly coincident to that of the _epoch_ (by design and not mere coincidence) then they shall also be members of that _epoch_. For example, the result of any measurement update using GNSS observables of the _epoch_ is, by design, coincident with the _epoch_ and is a member of that _epoch_. A stream is considered ill-formed if any _epoch_-associated report is encountered outside of an associated pairing of ``OBSERVABLES_MEASUREMENT_TIME`` and ``CODA`` reports; undefined behavior may result. It is not required that the recipient ignore these _misplaced reports_. Rather, the producer shall assume that they will be ignored. Any and all other report types may be encountered between a pairing of ``OBSERVABLES_MEASUREMENT_TIME`` and ``CODA`` reports. This is allowable but circumstantial. These other report types are not associated with the epoch. ### IMU and IMU Configuration Reports ``IMU`` and ``IMU_CONFIG`` are not entirely self-contained and independent. The ``IMU`` report contains a partial timestamp (the lower 32-bits of a 64-bit value). The ``IMU_CONFIG`` report is periodically published and contains (among other things) a full 64-bit timestamp. The upper 32-bits of the full 64-bit timestamp from the ``IMU_CONFIG`` report should be used to disambiguate and recover the full 64-bit timestamp associated with each ``IMU`` report. If the need arises to use this fact and further clarification is required, contact the developers. ## Deserialization techniques and recommendations A valid _gbx_ report can be identified in a byte-stream through the following process: 1. Locate the first occurrence of the two synchronization bytes (``0x55 0x54``). 1. Assuming this sequence marks the beginning of a valid _gbx_ report header, extract the payload size. Use the payload size to extract the footer checksum. 1. Calculate the checksum of the received header and payload and compare against the received checksum found in the footer. - If the checksums compare equal then it can be assumed that a valid _gbx_ report has been found. - If the checksums do not compare equal then either misalignment or corruption has occurred. In either case, the payload size is suspect and should not be used to attempt to skip forward to the next report. Instead, the next occurrence of ``0x55 0x54`` should be located and the process repeated. Undesired reports can be ignored based on report type and/or stream identifier. In these cases, it is not necessary to deserialize their payloads. However, it is recommended to still calculate and compare checksums on ignored reports. Keep in mind that filtering reports from a stream may impact proper operation of GSS tools. Importantly, if either ``OBSERVABLES_MEASUREMENT_TIME`` and/or ``CODA`` reports are filtered then _the epoch_ structure of the _gbx_ stream will be damaged and all _epoch_-associated reports will be negatively impacted (and potentially rendered useless). In short, it is best to only filter report types from a stream if you know exactly what you are doing. ## Example Program for Processing GBX Data For worked examples of reading and using GBX data, see the following guides: - [Analyze GBX](/advanced-tutorials/analyze-gbx) - [Porting GBX](/advanced-tutorials/porting-gbx) ## The Report Types The presence of report types in this list does not necessarily imply software capabilities that are available for licensing (or that even exist) at this time. Certain report types might be implemented for future-use or not even fully implemented. All report type values not included in this list shall be considered reserved. Cross-check this list with `reporttype.inc` to ensure completeness and accuracy. Name | Report Type ---- | ----------- DUMMY_REPORT | 0x00 IQ | 0x01 GNSS_OBSERVABLES | 0x02 OBSERVABLES_MEASUREMENT_TIME | 0x03 ESTIMATOR_INNOVATIONS | 0x04 ESTIMATOR_STATE | 0x05 IMU | 0x06 IMU_CONFIG | 0x07 TRANSMITTER_INFO | 0x08 IQ_METADATA | 0x09 SCINTILLATION_PARAMETERS | 0x0A IONOSPHERE | 0x0B DIAGNOSTIC_MESSAGE | 0x0C ANTENNA_PCV | 0x0D POSE_AND_TWIST | 0x0E STANDARD_NAVIGATION_SOLUTION | 0x0F TRIGGER_TIME | 0x10 EPHEMERIS | 0x11 ALMANAC | 0x12 BITCONTAINER | 0x13 CODA | 0x14 SPECTRUM | 0x15 INFO | 0x16 STATUS | 0x17 ATTITUDE_2D | 0x18 ATTITUDE_3D | 0x19 SINGLE_BASELINE_RTK | 0x1A MULTI_BASELINE_RTK_ATTITUDE_2D | 0x1B MULTI_BASELINE_RTK_ATTITUDE_3D | 0x1C RADAR | 0x1D RADAR_CONFIG | 0x1E TIME_CONVERSION | 0x1F EPHEMERIS_PARAMETERS | 0x20 ATMOSPHERIC_PARAMETERS | 0x21 DIFFERENTIAL_CODE_BIAS | 0x22 IMAGE | 0x23 MEASUREMENTS | 0x24 MEASUREMENTS_BATCH | 0x25 DIFFERENTIAL_CORRECTIONS | 0x26 COMMAND | 0x27 COMMAND_RESPONSE | 0x28 ## Protobuf Message Definitions Protobuf message definitions for each report payload are included within the `locus-lock` folder, under `doc/gbx/protos`. For GBX stream parser development support, contact support@locuslock.com. --- ## GenericType Mapping When writing middleware to parse PpRx output, particularly signal-typed GBX reports such as `GNSS_OBSERVABLES`, you will encounter a GenericType integer field that identifies which GNSS signal the data belongs to. The mapping between GenericType integers and signals is given below. Not all entries are supported in the current version of PpRx. Unsupported entries are reserved for future development. ``` enum GenericType { GPS_L1_CA = 0; // GPS L1 civil C/A code (C1C) GPS_L2_CM = 1; // GPS L2 civil M code (C2S) GPS_L2_CL = 2; // GPS L2 civil L code (C2L) GPS_L2_CLM = 3; // GPS L2 M+L combined code (C2X) GPS_L1_P = 4; // GPS L1 P code (C1P) GPS_L1_CP = 5; // GPS L1 civil C code (pilot) (C1L) GPS_L1_CD = 6; // GPS L1 civil C code (data) (C1S) GPS_L1_CPD = 7; // GPS L1 civil C code P+D combined tracking (C1X) SBAS_L1_I = 13; // SBAS L1 on I channel (C1C) GPS_L2_P = 14; // GPS L2 P code (C2P) GALILEO_E1_BC = 15; // Galileo E1 code (sum of E1B and E1C) (C1X) GALILEO_E1_B = 16; // E1B code for Galileo E1 (C1B) GALILEO_E1_C = 17; // E1C code for Galileo E1 (C1C) GPS_L1_L2_P_IFC = 18; // Ionosphere-free linear combination // of L1 P(Y) code and L2 P(Y) (e.g., // reference type for ephemeris clock models) GALILEO_E1_E5A_IFC = 19; // Ionosphere-free linear combination // of Galileo E1 and Galileo E5b (e.g., // reference type for precise clock models) GALILEO_E1_E5B_IFC = 20; // Ionosphere-free linear combination // of Galileo E1 and Galileo E5b (e.g., // reference type for I/NAV clock models) GPS_L5_I = 21; // GPS L5 civil in-phase (C5I) GPS_L5_Q = 22; // GPS L5 civil quadrature (C5Q) GPS_L5_IQ = 23; // GPS L5 civil combined IQ tracking (C5X) UNKNOWN_L1_CW = 24; // Continuous Wave (CW) signal at L1 (unknown system) UNKNOWN_L2_CW = 25; // Continuous Wave (CW) signal at L2 (unknown system) UNKNOWN_L5_CW = 26; // Continuous Wave (CW) signal at L5 (unknown system) GALILEO_E5A_I = 27; // Galileo E5a in-phase (C5I) GALILEO_E5A_Q = 28; // Galileo E5a quadrature (C5Q) GALILEO_E5A_IQ = 29; // Galileo E5a combined IQ tracking (C5X) GALILEO_E5B_I = 30; // Galileo E5b in-phase (C7I) GALILEO_E5B_Q = 31; // Galileo E5b quadrature (C7Q) GALILEO_E5B_IQ = 32; // Galileo E5b combined IQ tracking (C7X) GALILEO_E5_I = 33; // Galileo E5a+E5b in-phase (C8I) GALILEO_E5_Q = 34; // Galileo E5a+E5b quadrature (C8Q) GALILEO_E5_IQ = 35; // Galileo E5a+E5b combined IQ tracking (C8X) GALILEO_E6_BC = 36; // Galileo E6 code (sum of E6B and E6C) (C6X) GALILEO_E6_B = 37; // E6B code for Galileo E6 (C6B) GALILEO_E6_C = 38; // E6C code for Galileo E6 (C6C) SBAS_L5_I = 39; // SBAS L5 in-phase (C5I) SBAS_L5_Q = 40; // SBAS L5 quadrature (C5Q) SBAS_L5_IQ = 41; // SBAS L5 combined IQ tracking (C5X) BDS_B1_I = 42; // BeiDou B1 in-phase (C2I) BDS_B1_Q = 43; // BeiDou B1 quadrature (C2Q) BDS_B1_IQ = 44; // BeiDou B1 combined IQ tracking (C2X) BDS_B2_I = 45; // BeiDou B2 in-phase (C7I) BDS_B2_Q = 46; // BeiDou B2 quadrature (C7Q) BDS_B2_IQ = 47; // BeiDou B2 combined IQ tracking (C7X) BDS_B3_I = 48; // BeiDou B3 in-phase (C6I) BDS_B3_Q = 49; // BeiDou B3 quadrature (C6Q) BDS_B3_IQ = 50; // BeiDou B3 combined IQ tracking (C6X) QZSS_L1_CA = 51; // QZSS L1 C/A (C1C) QZSS_L1_CP = 52; // QZSS L1CP (pilot) (C1L) QZSS_L1_CD = 53; // QZSS L1CD (data) (C1S) QZSS_L1_CPD = 54; // QZSS L1C P+D combined tracking (C1X) QZSS_L2_CM = 55; // QZSS L2CM (C2S) QZSS_L2_CL = 56; // QZSS L2CL (C2L) QZSS_L2_CLM = 57; // QZSS L2C M+L combined tracking (C2X) QZSS_L5_I = 58; // QZSS L5 in-phase (C5I) QZSS_L5_Q = 59; // QZSS L5 quadrature (C5Q) QZSS_L5_IQ = 60; // QZSS L5 combined IQ tracking (C5X) QZSS_L1_L2_C_IFC = 70; // Ionosphere-free linear combination // of L1 C/A code and L2 C (e.g., // reference type for Block I/II ephemeris clock // models) GLONASS_G1_CA = 61; // GLONASS G1 C/A code (C1C) GLONASS_G1_P = 62; // GLONASS G1 P code (C1P) GLONASS_G2_CA = 63; // GLONASS G2 C/A code (C2C) GLONASS_G2_P = 64; // GLONASS G2 P code (C2P) BDS_B1_CP = 65; // BeiDou B1 civil C code (pilot) (C1P) BDS_B1_CD = 73; // BeiDou B1 civil C code (data) (C1D) BDS_B1_CPD = 74; // BeiDou B1 civil C code P+D combined tracking (C1X) BDS_B2A_P = 66; // BeiDou B2a (pilot) (C5P) BDS_B2A_D = 67; // BeiDou B2a (data) (C5D) BDS_B2A_PD = 68; // BeiDou B2a P+D combined tracking (C5X) BDS_B2B_P = 69; // BeiDou B2b (pilot) (C7P) BDS_B2B_D = 71; // BeiDou B2b (data) (C7D) BDS_B2B_PD = 72; // BeiDou B2b P+D combined tracking (C7Z) GLONASS_G1A_CP = 75; // GLONASS L1OCp (pilot) (C4B) GLONASS_G1A_CD = 76; // GLONASS L1OCd (data) (C4A) GLONASS_G1A_CPD = 77; // GLONASS L1OC P+D combined tracking (C4X) GLONASS_G2A_CP = 78; // GLONASS L2OCp (pilot) (C6B) GLONASS_G2A_CD = 79; // GLONASS L2CSI (data) (C6A) GLONASS_G2A_CPD = 80; // GLONASS L2OC P+D combined tracking (C6X) GLONASS_G3_I = 81; // GLONASS L3OC in-phase (C3I) GLONASS_G3_Q = 82; // GLONASS L3OC quadrature (C3Q) GLONASS_G3_IQ = 83; // GLONASS L3OC combined IQ tracking (C3X) UNDEFINED_GENERIC_TYPE = -1; } ``` --- ## Introduction(Pprx) This is the PpRx reference manual: protocol details, tuning knobs, and parameter definitions. It is not meant to be read cover to cover. You will dip into specific pages as you progress with the [LEO100 Setup Journey](/setup-journey). For basic setup and operation, start at the [LEO100 documentation](/) and follow the Setup Journey from the top. ## When each page becomes relevant in the Setup Journey | Page | Most useful during | |---|---| | [PpRx Display](./pprx-display.md) | **Phase 3 (Beginner Tutorials).** Interpreting the diagnostic readouts the first time you run PpRx. | | [PpRx Options (.opt) Parameters](./reference-definitions/pprx-opts.md) | **Phase 3 (Beginner Tutorials) onward.** Full reference for the `.opt` file generated in the Beginner Tutorials. | | [GBX Protocol Description](./gbx-protocol.md) | **Phase 4 (Advanced Tutorials).** Parsing the binary output stream during evaluation. | | [GenericType Mapping](./generictype-mapping.md) | **Phase 4 (Advanced Tutorials).** Decoding GenericType fields in GBX, `.log`, or `.mat` outputs. | | [PpRx as NTP Server](./ntp-server.md) | **Phases 4 (Advanced Tutorials) and 5 (Prototype on the Real Platform).** For applications that need the host clock disciplined to GNSS time. | | [PpRx Tuning Tips](./pprx-tuning.md) | **Phase 5 (Prototype on the Real Platform).** Highest-impact knobs for receiver performance on real hardware. | | [PpRx Configuration (.config) Parameters](./reference-definitions/pprx-configs) | **Phase 5 (Prototype on the Real Platform).** Detailed receiver configuration blocks during tuning. | --- ## PpRx as NTP Server PpRx can be configured to provide a highly accurate GNSS-backed time source for NTP. When configured and while PpRx is running with a valid navigation solution, the system clock on the host computer will automatically be synchronized with GNSS time. PpRx writes GNSS time into shared memory (SHM) segments. The NTP daemon on the host reads those segments and uses them as a reference clock. The exact NTP configuration syntax depends on which NTP implementation is installed. ## Configuration for ntpsec (Ubuntu 22.04+) Modern Ubuntu systems ship with `ntpsec` instead of classic `ntpd`. Edit `/etc/ntpsec/ntp.conf` and add: ```bash refclock SHM unit 0 refid SHM0 refclock SHM unit 1 refid SHM1 refclock SHM unit 2 prefer refid SHM2 refclock SHM unit 3 refid SHM3 ``` :::note PpRx creates SHM units 0 and 1 with `600` permissions (root-readable only) and units 2 and 3 with `666` permissions (world-readable). Since ntpsec runs as the `ntpsec` user rather than root, only units 2 and 3 are accessible to it. The `prefer` keyword belongs on `unit 2`. ::: Then restart the NTP service: ```bash sudo systemctl restart ntpsec ``` :::note If the config file includes a `tos minclock` line (e.g., `tos minclock 4 minsane 3`), NTP will require at least 4 reachable clocks before disciplining the system clock. In a deployment without an internet connection, lower this value or remove the line so that the GNSS SHM source alone can be accepted: ```bash tos minclock 1 minsane 1 ``` ::: ## Configuration for classic ntpd On systems using classic `ntpd`, edit `/etc/ntp.conf` and add: ```bash server 127.127.28.0 fudge 127.127.28.0 refid SHM0 server 127.127.28.1 fudge 127.127.28.1 refid SHM1 server 127.127.28.2 prefer fudge 127.127.28.2 refid SHM2 server 127.127.28.3 fudge 127.127.28.3 refid SHM3 ``` Then restart the NTP service: ```bash sudo systemctl restart ntp ``` ## Configuration for chrony On systems using `chrony`, add the following to `/etc/chrony/chrony.conf`: ```bash refclock SHM 0 refid SHM0 refclock SHM 1 refid SHM1 refclock SHM 2 prefer refid SHM2 refclock SHM 3 refid SHM3 ``` Then restart: ```bash sudo systemctl restart chrony ``` :::note SHM units 0 and 1 will show `reach = 0`, since PpRx does not write valid time data to those units. Unit 2 is the active GNSS time source. ::: ## Running PpRx with NTP Add the `--ntp` option to the `.opt` file: ```bash --ntp ``` :::note `--ntp` requires PpRx to run as `sudo`, since writing to the shared memory segments used by NTP requires elevated privileges. ::: Then run PpRx as `sudo`: ```bash sudo pprx -f ./autogen_01.opt ``` NTP will automatically reconfigure to select the time solution found by PpRx once a valid navigation solution is achieved. ## Verifying GNSS Time is Active After PpRx acquires a navigation solution, check which NTP implementation is running and use the appropriate command. **ntpsec / ntpd:** run `ntpq -p` and look for: - `*SHM(2)` in the leftmost column. The `*` means it is selected as the primary source. - `reach = 377` on the `SHM(2)` row. All 8 recent polls succeeded. - `offset` settling under ±1 ms. A healthy steady-state `ntpq -p` output looks like: ``` remote refid st t when poll reach delay offset jitter ============================================================================== SHM(0) .SHM0. 0 l - 64 0 0.000 0.000 0.000 SHM(1) .SHM1. 0 l - 64 0 0.000 0.000 0.000 *SHM(2) .SHM2. 0 l 49 64 377 0.000 -0.011 3.175 SHM(3) .SHM3. 0 l - 64 0 0.000 0.000 0.000 ``` **chrony:** run `chronyc sources -v` and look for: - `#* SHM2` The `*` means it is selected as the primary source. - `Reach = 377` on the `SHM2` row. - `Last sample` offset under ±1 ms. A healthy steady-state `chronyc sources -v` output looks like: ``` MS Name/IP address Stratum Poll Reach LastRx Last sample =============================================================================== #? SHM0 0 4 0 - +0ns[ +0ns] +/- 0ns #? SHM1 0 4 0 - +0ns[ +0ns] +/- 0ns #* SHM2 0 4 377 13 -22us[ -13us] +/- 42us #? SHM3 0 4 0 - +0ns[ +0ns] +/- 0ns ``` ## Checking Shared Memory Status To confirm the shared memory segments were created: ```bash ipcs -m ``` Expected output includes four segments with keys starting at `0x4e545030`: ``` ------ Shared Memory Segments -------- key shmid owner perms bytes nattch status 0x4e545030 ... root 600 96 1 0x4e545031 ... root 600 96 1 0x4e545032 ... root 666 96 2 0x4e545033 ... root 666 96 1 ``` Units 0 and 1 have `600` permissions (root-readable only). ntpsec cannot attach to them (`nattch = 1`); chrony runs with sufficient privileges to attach (`nattch = 2`) but PpRx does not write valid data to those units so they show `reach = 0` regardless. Unit 2 (`666`) is the active source and shows `nattch = 2` (ntpsec) or `nattch = 3` (chrony) when actively read. If these segments are absent, PpRx is not running or was not started with `--ntp`. ## Troubleshooting #### `SHM(2)` never gets a `*` in `ntpq -p` PpRx may not have a valid navigation solution yet. The shared memory clock source is only populated once PpRx begins producing navigation solutions. Check the PpRx display (pass `--verbose` to PpRx) and confirm a Standard Solution is shown with reasonable position values before diagnosing NTP further. :::note `SHM(0)` and `SHM(1)` will always show `reach = 0`. This is expected due to their root-only permissions and is not an error. ::: #### `reach` field stays at 0 NTP is not reading from the shared memory segments. Confirm PpRx was started with the `--ntp` option, and that the NTP config additions were saved and the NTP service was restarted afterward. #### `offset` is large or oscillating If PpRx has a valid solution but offset is large (>10 ms), check: - The host system clock was not recently set to a wrong time (a large initial offset can cause NTP to step-adjust rather than slew). - No other high-stratum NTP sources are competing with `SHM(2)` and winning. The `prefer` keyword on the SHM2 line (shown in the config above) should prevent this. #### NTP is not installed - ntpsec (Ubuntu 22.04+): `sudo apt install ntpsec` - ntpd (older systems): `sudo apt install ntp`. On systems running `systemd-timesyncd` (which conflicts with `ntpd`), disable it first: `sudo systemctl disable --now systemd-timesyncd`. --- ## PpRx Display The PpRx Display provides useful diagnostic information while the software is running. It can be viewed in two ways, depending on how the user configures and runs PpRx: - When running PpRx from the GUI, the PpRx Display can be viewed by selecting `Tools` → `PpRx Display`. - When running PpRx from the CLI, the PpRx Display will be printed to `stdout` if the user passes the `--verbose` option. When `--verbose` is **not** passed, PpRx automatically writes a `display.log` file in the working directory. This file contains the same display content in plain text (no ANSI color codes), updated at each display refresh interval. It is useful for reviewing receiver behavior after the fact without re-running PpRx. A typical display looks as follows (with IMU connected): ``` ――――――――――――― GRID: General Radionavigation Interfusion Device ―――――――――――― RRT: 0 weeks 222.2 seconds Build ID: 4917 ORT: 1490 weeks 146234.0 seconds ――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――― CH TXID Doppler BCP PR C/N₀ Az El CS (Hz) (cycles) (meters) (dB-Hz) (deg) (deg) ―――――――――――――――――――――――――――― GPS_L1_CA_PRIMARY ―――――――――――――――――――――――――――― 1 5 -3700.2 12948972.2 24923426.7 40.0 41.4 7.3 7 2 14 -2283.5 12629722.8 21977305.3 49.3 110.9 41.4 7 3 16 3269.5 11395962.4 22297488.0 48.9 191.7 34.2 7 4 20 1337.7 11818247.0 22173947.0 49.4 298.4 36.6 7 5 22 -3804.2 12976976.9 25178762.7 38.7 164.5 3.9 7 6 29 1506.3 11785134.9 24108553.8 44.2 85.7 16.4 7 7 30 -2874.0 12758476.0 22460802.6 48.2 49.2 30.5 7 8 31 -330.1 12195832.6 20504836.0 54.5 347.7 76.0 7 9 32 263.7 12057205.4 21387833.5 52.9 274.0 54.2 7 10 -- --------- ------------- ----------- ---- ----- ---- - ―――――――――――――――――――――――――――― GPS_L2_CL_PRIMARY ―――――――――――――――――――――――――――― 1 29 1173.8 -219300.8 24108560.8 40.3 85.7 16.4 6 2 31 -257.3 42503.2 20504848.1 54.4 347.7 76.0 6 3 -- --------- ------------- ----------- ---- ----- ---- - ―――――――――――――――――――――――――――― Standard Solution ―――――――――――――――――――――――――――― PX: 1101966.84 PY: -4583482.27 PZ: 4282236.05 δtR: 12584.29 VX: 0.00 VY: 0.00 VZ: 0.00 δtRdot: 8.16 Hσ: 0.81 Vσ: 1.22 εν: 0.36 ――――――――――――――――――――――――――――――― IMU Data ――――――――――――――――――――――――――――――――― AX: 0.43 AY: 5.40 AZ: 8.18 ωBX: -0.28 ωBY: -0.13 ωBZ: 0.08 RRT: 79.992 Temp: 37.0 ――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――― ``` The IMU Data section appears when PpRx is receiving data from `--imu-file /dev/radiolion1`. It is absent when no IMU source is configured. With the following abbreviations: ``` RRT ------- Raw Receiver Time ORT ------- Offset Receiver Time CH -------- Channel TXID ------ Transmitter Identifier BCP ------- Beat Carrier Phase PR -------- Pseudorange C/N₀ ------ Carrier-to-Noise Ratio Az -------- Azimuth angle toward transmitter El -------- Elevation angle toward transmitter CS -------- Channel status PX -------- Position X coordinate in ECEF (meters) PY -------- Position Y coordinate in ECEF (meters) PZ -------- Position Z coordinate in ECEF (meters) δtR ------- Offset of ORT with respect to true GPS time, in meters equivalent VX -------- Velocity X coordinate in ECEF (meters/sec) VY -------- Velocity Y coordinate in ECEF (meters/sec) VZ -------- Velocity Z coordinate in ECEF (meters/sec) δtRdot ---- Offset rate of ORT with respect to true GPS time, in meters/sec equivalent Hσ -------- Horizontal error standard deviation (meters) Vσ -------- Vertical error standard deviation (meters) εν -------- Normalized innovation squared. For a properly-tuned receiver, this quantity's mean should be near unity. AX -------- IMU accelerometer X-axis (m/s²) AY -------- IMU accelerometer Y-axis (m/s²) AZ -------- IMU accelerometer Z-axis (m/s²) ωBX ------- IMU gyroscope X-axis (rad/s) ωBY ------- IMU gyroscope Y-axis (rad/s) ωBZ ------- IMU gyroscope Z-axis (rad/s) Temp ------ IMU temperature (°C) Channel Status (CS) indicator decorations: s --- spoofing detected * --- half cycle phase offset possible c --- data bit container complete (wipeoff will be highly accurate) - --- phase error detected e --- no ephemeris valid for navigation is yet available Transmitter Identifier (TXID) decorations: ? --- Health status unknown u --- Unhealthy Channel coloring: yellow --- steady-state conditions gray ----- channel's DLL has not yet settled into its steady-state tracking regime ``` :::note Color cues are only visible in environments that preserve the formatted display output. Plain logs or terminals without color support may not show these distinctions. ::: ## Interpreting C/N₀ C/N₀ (carrier-to-noise density ratio) is the primary signal quality indicator. Higher values mean cleaner signal and better ranging accuracy. | C/N₀ (dB-Hz) | Interpretation | |---|---| | ≥ 45 | Excellent — strong, clean signal. Typical for satellites at moderate to high elevation in open sky. | | 40–44 | Good — healthy tracking. Expected for most satellites in a clear environment. | | 35–39 | Marginal — tracking but reduced accuracy. May be affected by low elevation, obstructions, or mild interference. | | < 35 | Poor — signals may drop out, contribute noise to the solution, or fail strict selection. | Low elevation satellites (El < ~10°) routinely fall into the 35–40 dB-Hz range due to the longer atmospheric path and are normal. A satellite at high elevation with C/N₀ below 35 dB-Hz suggests RF issues (obstruction, interference, or antenna problem). ## Interpreting Channel Status (CS) The CS field shows a numeric tracking state followed by optional letter decorations. The number represents how many tracking-loop conditions have been met: | CS value | Meaning | |---|---| | `7` | Fully locked — DLL settled, data decoded, eligible for navigation solution. This is the steady-state value for a healthy channel. | | `6` | Tracking but data bit container not yet complete (`c` not yet set). Common on secondary frequency signals shortly after lock. | | `4` | DLL transitioning to steady state. Channel is gray; not yet contributing to navigation solution. Typical shortly after initial acquisition. | | `3` | Very early tracking — fewer conditions met than `4`. Seen immediately after acquisition before the DLL begins settling. | | `-` | Channel slot empty (no satellite assigned). | Letter decorations appear appended to the number (e.g., `4*`, `7e`): - `e` — No valid ephemeris for this satellite yet. The channel tracks but cannot participate in the navigation solution until ephemeris is received or imported. Using `--import-ephem` at startup prevents this delay. - `*` — Half-cycle phase offset is possible. The receiver has not yet resolved the half-cycle ambiguity for this signal. - `c` — Data bit container complete. The receiver has collected sufficient navigation message data for accurate carrier phase wipeoff. - `-` — Phase error detected. - `s` — Spoofing detected. At startup, channels typically begin at CS `4*` (transient, health unknown), progress to `4e` once health is confirmed but before ephemeris arrives, and reach `7` once fully locked with valid ephemeris. ## Interpreting the Standard Solution The solution section appears once PpRx has enough satellites and ephemeris to compute a navigation fix. - **PX/PY/PZ** — ECEF position in meters. To convert to latitude/longitude/altitude, use a standard ECEF-to-LLA formula or a tool like `binflate`. - **Hσ / Vσ** — Estimated horizontal and vertical positioning error standard deviations in meters. Values below ~1 m horizontal are typical in open-sky conditions. - **εν** — Normalized innovation squared. A well-tuned receiver produces a mean value near 1.0. Consistently high values (>3–5) indicate measurement-model inconsistency (multipath, interference, or misconfigured noise parameters). - **δtR** — Clock offset in meters equivalent (~1 meter ≈ 3.3 ns). Large values are normal and reflect oscillator offset from GPS time; what matters is stability over time. - **ORT** showing `9999 weeks` — The receiver has not yet solved for time. This disappears once a navigation solution is achieved. --- ## PpRx Tuning Tips import ProductName from '@site/src/components/ProductName'; # PpRx Tuning Tips The parameters below are usually the most impactful knobs for tuning PpRx performance for a given application. ## Signal Acquisition - [`BACKGROUND_ACQ_SEARCH_DEPTH`](./reference-definitions/pprx-configs/bank#background_acq_search_depth): Adjusts the number of non-coherent integration intervals used in signal acquisition. For clean RF environments, set this value lower to reduce CPU overhead (2 to 5). For difficult RF environments, set this value higher to increase SNR and the probability of acquiring a signal (6 to 10). - [`NOM_MIN_DOPPLER_FREQ_HZ`](./reference-definitions/pprx-configs/bank#nom_min_doppler_freq_hz) / [`NOM_MAX_DOPPLER_FREQ_HZ`](./reference-definitions/pprx-configs/bank#nom_max_doppler_freq_hz): Adjusts the range of Doppler frequency offsets searched during acquisition. For low-speed vehicles, moderate ranges (-4000 to +4000) work well. For higher-speed vehicles, increase this range (-7000 to +7000). - [`DIRECTED_ACQ_ONLY`](./reference-definitions/pprx-configs/bank#directed_acq_only): Forces signals in the specified bank to be acquired with aiding information from other banks. This can save CPU overhead, but should be used carefully if the aiding bank is expected to experience interference. ## Tracking Loops - [`EML_CHIP_SPACING`](./reference-definitions/pprx-configs/bank#eml_chip_spacing): Adjusts the spacing between the early-minus-late correlators within the tracking loops. For high precision in clean RF environments, set low (0.1 to 0.2). For robust performance in contested environments, set high (0.3 to 0.5). - [`NUM_SUBACCUM_PER_ACCUM`](./reference-definitions/pprx-configs/bank#num_subaccum_per_accum): Sets the coherent integration interval for signals in the specified bank. For highly dynamic vehicles, set this value low (1 to 5 on GPS L1 C/A). For degraded environments, set it higher (10 to 20 on GPS L1 C/A). - [`PLL_DEFAULT_BANDWIDTH_HZ`](./reference-definitions/pprx-configs/bank#pll_default_bandwidth_hz): Sets the carrier phase tracking gain. Lower values improve stability but reduce responsiveness to fast changes. Higher values (25 to 35) are better for highly dynamic use cases. - [`DLL_DEFAULT_BANDWIDTH_HZ`](./reference-definitions/pprx-configs/bank#dll_default_bandwidth_hz): Sets the code phase tracking gain. Lower values improve stability but reduce responsiveness. Higher values are generally better for highly dynamic use cases. ## Estimator Behavior - [`ZENITH_PSEUDORANGE_STD`](./reference-definitions/pprx-configs/estimator#zenith_pseudorange_std) / [`ZENITH_DOPPLER_STD`](./reference-definitions/pprx-configs/estimator#zenith_doppler_std): Tunes the estimator's trust in the observables. Higher values make the estimator slower to respond but can reduce noise. Lower values increase trust in incoming measurements. - [`SQRT_Q_TILDE`](./reference-definitions/pprx-configs/estimator#sqrt_q_tilde): Tunes the estimator's trust in the continuity of the vehicle dynamics. Lower values assume more predictable dynamics, while higher values are appropriate for aggressive changes in motion. - [`CLOCK_TYPE`](./reference-definitions/pprx-configs/estimator#clock_type): Adjusts the assumed sampling clock quality. For 's SiTime 5155 TCXO, it should be set to `TCXO`. - [`DYNAMICS_MODEL`](./reference-definitions/pprx-configs/estimator#dynamics_model): Sets the overall motion model for the receiver. For nearly all applications, choose `STATIC` for a stationary receiver or `NEARLY_CONSTANT_VELOCITY` for a dynamic receiver. ## Log Interval Warning At startup, PpRx may print a warning about the log interval: ``` WARNING: For computational efficiency in real-time operation, it is recommended that logInterval be chosen as the greatest common factor of logInterval, acqInterval, channel prune intervals, and other activity intervals when all are expressed in milliseconds. ``` This warning appears when the values of `--log-interval`, `--acq-interval`, and channel prune intervals do not share a common GCF factor. It does not prevent PpRx from running and can usually be ignored during development. For production real-time deployments, adjusting `--log-interval` to match the GCF reduces scheduling overhead. `.opt`/`.config` files generated by the GUI Configuration Generator do not trigger this warning. --- ## Parameter Definitions import Link from '@docusaurus/Link'; # Parameter Definitions Reference pages for every PpRx `.opt` (runtime options) and `.config` (configuration block) parameter. Use these as a lookup, not a reading list. Jump in when you need to know what a specific knob does, what its valid range is, or what its default is. These pages are reference material, not a step in the [Setup Journey](/setup-journey). You'll be sent here from inside the journey when a tutorial asks for parameter detail. Most users hit these pages during Phase 4 (Advanced Tutorials) and Phase 5 (Prototype) as they tune `.opt` and `.config` against their target platform. PpRx Options Command-line and `.opt`-file flags. Inputs, outputs, run mode, file paths. PpRx Configuration Receiver internals, block by block. Acquisition, tracking, estimator, output gating. :::tip You can list every available `.opt` flag from the CLI with `pprx --help`. The pages above add context and grouping that `--help` does not. ::: --- ## BANK import ProductName from '@site/src/components/ProductName'; The BANK configuration controls which GNSS signal types PpRx attempts to acquire and track, and how each signal type is configured. A BANK configuration has two levels: - The top-level `[BANK]` block lists the signal banks to create. - Each signal-specific block, such as `[GPS_L1_CA_PRIMARY]`, configures acquisition, tracking, pruning, and system settings for that signal type. Below is an example BANK configuration: ```bash [BANK] NUM_BANKS = 2 BK01 = GPS_L1_CA_PRIMARY BK02 = GPS_L2_CLM_PRIMARY [GPS_L1_CA_PRIMARY] FRONT_END = LION MAXCHANNELS = 10 NOM_MIN_DOPPLER_FREQ_HZ = -5000 NOM_MAX_DOPPLER_FREQ_HZ = 5000 NUM_SUBACCUM_PER_ACCUM = 10 BACKGROUND_ACQ_SEARCH_DEPTH = 2 CODEGEN_TYPE = LOOKUP CH_PRUNE_THRESHOLD = 10 TRACKING_STRATEGY = TRADITIONAL PLL_DEFAULT_BANDWIDTH_HZ = 25 PLL_ENABLE_LOOP_BANDWIDTH_ADAPTATION = TRUE PLL_DEFAULT_LOOP_ORDER = ORDER2 EML_CHIP_SPACING = 0.2 DLL_DEFAULT_BANDWIDTH_HZ = 0.003 DIRECTED_ACQ_ONLY = TRUE ELEVATION_MASK_ANGLE_ACQ_DEG = 10.0 NOISE_FLOOR_CORRECTION_FACTOR = 1.0 CIRCBUFF_STREAM_IDX = 0 ``` :::warning For every signal type listed in `[BANK]`, a matching signal-specific block must also be included. For example, if `[BANK]` lists `GPS_L1_CA_PRIMARY` and `GPS_L2_CLM_PRIMARY`, the config must also include `[GPS_L1_CA_PRIMARY]` and `[GPS_L2_CLM_PRIMARY]` blocks. `NUM_BANKS` must match the number of listed signal banks. ::: ### `[BANK]` block (top-level) The top-level `[BANK]` block defines which signal-specific bank blocks PpRx will create. Each listed bank must have a matching configuration block later in the file.
[BANK] block parameters ### NUM_BANKS **Default:** None \ **Parameter Class:** Operational Configuration \ **Technical Info:** Number of signal banks defined in the `[BANK]` block. This must match the number of `BKxx` entries provided. \ **Practical Tuning Info:** Set this to the number of signal types and antenna paths being configured. For example, tracking GPS L1, GPS L2, GPS L5, SBAS, and Galileo E1 requires `NUM_BANKS = 5` for one antenna, or `NUM_BANKS = 10` for two antennas. ### BK01, BK02, … **Default:** N/A \ **Parameter Class:** Operational Configuration \ **Technical Info:** Specifies the signal type assigned to each bank. Each value must correspond to a matching signal-specific block, such as `[GPS_L1_CA_PRIMARY]`. `BK01` is the root bank. \ **Practical Tuning Info:** Configure one `BKxx` entry for each signal bank. The root bank, `BK01`, is acquired first by default and its accumulation interval defines the unit used for PpRx logging intervals.
### `[SIGNAL_TYPE]` block (per signal) Each signal-specific block (for example `[GPS_L1_CA_PRIMARY]`) configures acquisition, tracking, pruning, and signal definition for that signal type. Parameters are grouped by where they sit in the DSP chain.
General These parameters set basic per-signal behavior and resource usage. Most defaults here work well; the main tuning knobs are `MAXCHANNELS`, `TXID_LIST`, and `CODEGEN_TYPE` for controlling CPU/RAM load and which satellites are searched. ### MAXCHANNELS **Default:** 8 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Maximum number of channels that PpRx will track of the given signal type. \ **Practical Tuning Info:** Values between 8–12 are recommended, with lower values reducing CPU usage. If MAXCHANNELS of a given signal are being tracked, acquisition of additional TXIDs of that signal type will not be attempted. ### TXID_LIST **Default:** [] \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** List of TxIds for the bank that PpRx will attempt to acquire and track. If this list is empty, then all TxIds are assumed valid for acquisition and tracking. \ **Practical Tuning Info:** If a constellation only has certain operational TXIDs (e.g. 131, 133, and 135 for SBAS, or L5's still-incomplete constellation), this field can be used to conserve resources by narrowing to only valid TXIDs. :::note As of June 2026, the following TXID lists can be used to narrow to only real satellites: For **GPS L2**: `TXID_LIST = 1 3 4 5 6 7 8 9 10 11 12 14 15 17 18 20 21 23 24 25 26 27 28 29 30 31 32` For **GPS L5**: `TXID_LIST = 1 3 4 6 8 9 10 11 14 18 20 21 23 24 25 26 27 28 30 32` For **Galileo E5**: `TXID_LIST = 2 3 4 5 6 7 8 9 10 11 12 13 15 16 19 21 23 25 26 27 28 29 30 31 33 34 36` For **SBAS**: `TXID_LIST = 131 133 135` ::: ### NOISE_FLOOR_CORRECTION_FACTOR **Default:** 1.0 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** This value allows for correction of thermal noise floor estimates, which can occur when incoming data samples are time correlated. Adjusting this value affects the signal strength threshold used for signal acquisition and C/N0 estimates. \ **Practical Tuning Info:** This should normally not be tuned, except for custom RF front-ends or simulated streams. ### DOPPLER_FREQ_STEP_HZ **Default:** 1000 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Defines the Doppler frequency spacing, in Hz, used to build pre-computed carrier generator lookup tables. \ **Practical Tuning Info:** Larger values will use less memory for pre-computed tables, and smaller values will more closely match the desired carrier frequency, but this value should not require tuning: gains from decreasing step size provide maximum gains of less than a thousandth of a dB-Hz, and lookup table memory using the default is on the order of tens of kilobytes. ### CODEGEN_TYPE **Default:** PSIAKI \ **Parameter Class:** Tunable \ **Impact of Change:** Medium **Options:** - `LOOKUP` - `PSIAKI` - `FULL_PRECISION` **Technical Info:** Sets code replica generation strategy. \ **Practical Tuning Info:** `LOOKUP` is recommended for reduced CPU usage, while `PSIAKI` is recommended for reduced RAM usage or for signals with long PRN codes, like GPS L2. `FULL_PRECISION` should normally not be used. ### MSAMPFRAC **Default:** 14 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Governs the adjustment resolution of code replicas used to correlate with raw RF data. The replica's location can be specified to a resolution of the sampling interval divided by `MSAMPFRAC` (e.g. for `MSAMPFRAC = 14` and a 10 Msps sampling rate, this produces a ~7.1 ns code replica adjustment resolution. Note that code replica adjustment resolution is unrelated to final measurement resolution.) \ **Practical Tuning Info:** This should normally not be tuned. The default `MSAMPFRAC` value of 14 has a worst-case C/N0 loss of only ~0.1 dB-Hz. Higher values can reduce this worst-case loss, but increase initialization time and cache pressure.
Acquisition These parameters control how signals are found before tracking. Tuning mainly trades acquisition speed and CPU load against the ability to find weaker or harder-to-acquire signals. ### NOM_MAX_DOPPLER_FREQ_HZ **Default:** 7000 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Maximum Doppler frequency used to define the search space for signal acquisition. This keeps the search space within practical bounds and prevents the possibility of acquiring signals with physically implausible Doppler shifts. \ **Practical Tuning Info:** Lower values decrease compute used for acquisition at the expense of potentially not acquiring signals closer to the horizon, or signals that have been Doppler shifted due to poor receiver clock stability or high vehicle speeds. The minimum value this should be set to is roughly 3500 Hz for L1-band signals and roughly 2500 Hz for L5-band signals. ### NOM_MIN_DOPPLER_FREQ_HZ **Default:** -7000 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** See [`NOM_MAX_DOPPLER_FREQ_HZ`](#nom_max_doppler_freq_hz). \ **Practical Tuning Info:** See [`NOM_MAX_DOPPLER_FREQ_HZ`](#nom_max_doppler_freq_hz). ### ACQ_STRATEGY **Default:** TRADITIONAL \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Options:** - `TRADITIONAL` - `MODEL_BASED` **Technical Info:** Defines the method used for signal acquisition. `TRADITIONAL` will search a sequence of Doppler shifts for signals, with a range defined by [`NOM_MAX_DOPPLER_FREQ_HZ`](#nom_max_doppler_freq_hz) / [`NOM_MIN_DOPPLER_FREQ_HZ`](#nom_min_doppler_freq_hz) and a step size defined by [`FFT_DOPPLER_FREQ_M`](#fft_doppler_freq_m). `MODEL_BASED` also searches the same range, but with a much sparser set of Doppler shifts, and then uses a model to infer and polish the signal frequency. \ **Practical Tuning Info:** For the same acquisition search depth (see [`BACKGROUND_ACQ_SEARCH_DEPTH`](#background_acq_search_depth)), model-based acquisition will find more signals in less time. At high search depths, it may find signals that are quite weak and difficult to track reliably. If a given search depth is working well for an application in `TRADITIONAL` acquisition, reducing search depth by 3 or 4 will often get similar results significantly faster. ### FFT_DOPPLER_FREQ_M **Default:** 4 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Defines the Doppler frequency step size used to define the search space for signal acquisition. This value maps to a frequency step size as a function of the sub-accumulation interval period as follows: `Step size (Hz) = 1 / [Subaccumulation period (sec) * FFT_DOPPLER_FREQ_M]` **Practical Tuning Info:** Tuning should mostly not be necessary: higher values will search proportionally more frequency bins during acquisition, though with steeply diminishing returns (doubling this value will roughly double acquisition compute, but provide roughly ~0.1 dB-Hz C/N0 benefit during acquisition). Lower values will save proportionally on compute, but at the risk of lowering the probability that a signal can be pulled into tracking successfully. :::note `FFT_DOPPLER_FREQ_M` is only applicable to `ACQ_STRATEGY = TRADITIONAL`. ::: ### INITIAL_ACQ_SEARCH_DEPTH **Default:** 8 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Defines the acquisition search depth used for this bank during the initial acquisition pass, where higher search depths perform more coherent accumulations to find signals. This parameter is the sole control for initial acquisition search depth. \ **Practical Tuning Info:** Use this when one signal bank should use a different startup acquisition depth than others, such as keeping expensive or low-priority signals shallow while allowing others to search deeper. :::note Galileo E1 BC uses a default `INITIAL_ACQ_SEARCH_DEPTH` of 0, due to its long primary code. The long E1 primary code also means that lower search depths acquire weaker signals but also use more compute; an `INITIAL_ACQ_SEARCH_DEPTH` of 3 is roughly equivalent to a depth of 12 for other signals and is at the high end of the recommended range for E1's `INITIAL_ACQ_SEARCH_DEPTH`. ::: ### BACKGROUND_ACQ_SEARCH_DEPTH **Default:** 5 \ **Parameter Class:** Tunable \ **Impact of Change:** High \ **Technical Info:** Background acquisition search depth defines the number of non-coherent integrations used during signal acquisition during background acquisition. \ **Practical Tuning Info:** For clean RF environments, set this value lower to reduce CPU overhead (2–5). For degraded RF environments, set this value higher to increase SNR and the probability of acquiring a signal (6–10). :::note Galileo E1 BC uses a default `BACKGROUND_ACQ_SEARCH_DEPTH` of 0, due to its long primary code. The long E1 primary code also means that lower search depths acquire weaker signals but also use more compute; a `BACKGROUND_ACQ_SEARCH_DEPTH` of 3 is roughly equivalent to a depth of 12 for other signals and is at the high end of the recommended range for E1's `BACKGROUND_ACQ_SEARCH_DEPTH`. ::: :::note `BACKGROUND_ACQ_SEARCH_DEPTH` was previously named `MAX_ACQ_SEARCH_DEPTH`. The old name is retained as an accepted alias for backward compatibility, and the underlying protobuf field name is unchanged. ::: ### MAX_DIRECTED_STANDARD_ACQ_ATTEMPTS_PER_CYCLE **Default:** 2 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Maximum number of directed standard acquisition attempts allowed per acquisition cycle. \ **Practical Tuning Info:** Leave at the default unless acquisition load is causing CPU spikes (adjust lower if so) or if reacquisition latency is especially important (adjust higher if so). ### MAX_DIRECTED_ACQ_CODE_GENS_PER_CYCLE **Default:** -1 (no maximum) \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Maximum number of new code generations performed during directed acquisition per acquisition interval. \ **Practical Tuning Info:** The default is normally best, but setting this parameter to 1 or 2 can be useful on low-power processors when using L2 in particular. This prevents many new codes from being generated at once when channels are initialized, which otherwise can cause PpRx to stall briefly. :::note Only relevant when `CODEGEN_TYPE = LOOKUP`. ::: ### DIRECTED_ACQ_ONLY **Default:** False \ **Parameter Class:** Tunable \ **Impact of Change:** High \ **Technical Info:** Allow only directed acquisition (either direct-to-track acquisition or directed standard acquisition) after initial acquisition. This narrows the acquisition search space to the signal's expected location using information from other tracked signals in the same constellation. \ **Practical Tuning Info:** Enable to reduce acquisition CPU load once the receiver has a valid solution and useful ephemeris aiding. Leave disabled to attempt acquisition of all possible signals, including ones which may not have enough information to be acquired through a directed acquisition. :::note Directed acquisition can only be conducted for signals within the same constellation. For example, GPS L1 C/A cannot provide directed acquisition information to Galileo E5a, but can for GPS L5. ::: :::note This gets overridden to `False` when too few root-bank signals have been acquired. The override ensures that processing power gets devoted to standard acquisition upon startup or after a complete loss of signals when directed acquisition isn't yet operable. ::: ### DIRECT_TO_TRACK_ACQ_ONLY **Default:** False \ **Parameter Class:** Tunable \ **Impact of Change:** High \ **Technical Info:** Allow only direct-to-track acquisition after initial acquisition. Direct-to-track acquisition skips FFT-based signal acquisition entirely, directly entering the tracking loops upon channel initialization. \ **Practical Tuning Info:** Enabling will reduce acquisition CPU load even more than enabling [`DIRECTED_ACQ_ONLY`](#directed_acq_only), but requires a higher-quality estimate of the signal's location to successfully acquire. :::note This is more restrictive than [`DIRECTED_ACQ_ONLY`](#directed_acq_only), which allows direct-to-track acquisition or directed standard acquisition. A runtime error will be thrown if this option is asserted simultaneously with [`DIRECTED_STANDARD_ACQ_ONLY`](#directed_standard_acq_only); they are mutually exclusive. ::: ### DIRECTED_STANDARD_ACQ_ONLY **Default:** False \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Allow only directed standard acquisition after initial acquisition (and do not allow direct-to-track acquisition). Directed standard acquisition utilizes aiding information from other signals from the same constellation to narrow the search space for FFT-based signal acquisition, reducing CPU usage. \ **Practical Tuning Info:** This should normally be `False`. It uses more CPU than [`DIRECTED_ACQ_ONLY`](#directed_acq_only) and [`DIRECT_TO_TRACK_ACQ_ONLY`](#direct_to_track_acq_only) but reduces the risk of initializing tracking from an incorrect code timing estimate. :::note This is more restrictive than [`DIRECTED_ACQ_ONLY`](#directed_acq_only), which allows direct-to-track acquisition or directed standard acquisition. A runtime error will be thrown if this option is asserted simultaneously with [`DIRECT_TO_TRACK_ACQ_ONLY`](#direct_to_track_acq_only); they are mutually exclusive. ::: ### BACKGROUND_ACQ_ONLY **Default:** False \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Setting to `True` prevents a given signal type from participating in the optional one-time initial acquisition pass (enabled using `-e` in the PpRx `.opt` file). \ **Practical Tuning Info:** Set to `True` for signal banks for which an exhaustive initial acquisition is unnecessary or computationally heavy, typically GPS L2/L5, Galileo E5a, and Beidou B1C. ### DISABLE_STANDARD_ACQ **Default:** False \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Disables the computationally heavy standard blind acquisition while PpRx is running, allowing standard acquisition only during the one-time initial acquisition and only directed acquisition after that. \ **Practical Tuning Info:** Enable to prevent a bank from spending CPU on broad searches after startup. This should usually be set to `True` for signal banks for which standard acquisition is computationally heavy, typically GPS L2/L5, Galileo E5a, and Beidou B1C. ### DIRECT_TO_TRACK_ACQ_INITIAL_CN0_DB_HZ **Default:** 40 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** C/N0 estimate used as an initial guess when initializing a channel via direct-to-track acquisition. \ **Practical Tuning Info:** This should normally not need tuning. Set lower if channels are being initialized too optimistically in very weak signal conditions and not tracking stably after direct-to-track acquisitions. ### ELEVATION_MASK_ANGLE_ACQ_DEG **Default:** 0 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Minimum satellite elevation angle, in degrees, required for a TXID to be considered for an acquisition attempt, when elevation information is available. Signals below this elevation angle are excluded from acquisition candidate lists and prevented from reacquisition after pruning. \ **Practical Tuning Info:** Typically set to 5–15 degrees, with higher values reducing acquisition attempts on low-elevation signals that are more likely to be weak, obstructed, or multipath-affected. Lower values may acquire more satellites near the horizon, but can increase CPU usage and the chance of spending acquisition compute on marginal signals. ### EXTENDED_ACQ_ACCUM_FOR_DATABIT_TRANSITION **Default:** False \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Enables a doubled acquisition window for Galileo E1 BC signals specifically. This changes acquisition from a 4 ms data window to an 8 ms data window, reducing sensitivity to 4 ms symbol transitions. \ **Practical Tuning Info:** Enable this for more robust unaided Galileo E1 BC acquisition, especially for weak signals. Leave disabled when it is important to keep acquisition compute low.
Tracking These parameters control how signals are tracked after acquisition. Tuning parameters from this section mainly balances measurement smoothness against responsiveness to dynamics. ### TRACKING_STRATEGY **Default:** TRADITIONAL \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Options:** - `TRADITIONAL` - `HYBRID` **Technical Info:** Selects the channel tracking architecture. `TRADITIONAL` uses local DLL/FLL/PLL tracking loops, while `HYBRID` uses the same local tracking loops but applies estimator/model-predicted Doppler aiding. \ **Practical Tuning Info:** Use `TRADITIONAL` when model/estimator aiding may be unavailable or unreliable. Use `HYBRID` when a reliable receiver solution/model is available. ### NUM_SUBACCUM_PER_ACCUM **Default:** 10 \ **Parameter Class:** Tunable \ **Impact of Change:** High \ **Technical Info:** Defines how many subaccumulation intervals (a 1 ms interval for most signals) are combined into one accumulation. An accumulation is the interval over which PpRx coherently integrates signals during tracking, and the interval at which tracking loops are updated. \ **Practical Tuning Info:** Higher values improve measurement quality, but reduce loop update rate and increase sensitivity to dynamics. 10 is a good default for most scenarios, while 20 works well for static/low-dynamics cases and 1, 2, or 4 may be required for extreme dynamics. :::note A subaccumulation interval is typically defined as one code period within PpRx. The subaccumulation interval for GPS L1/L2/L5, Galileo E5a, and Beidou B2a is 1 ms by default. For Galileo E1b/c it is 4 ms, and for Beidou B1c it is 10 ms. ::: :::note If the signal to be tracked is data modulated, then `NUM_SUBACCUM_PER_ACCUM` must be an integer divisor of the number of subaccumulations per data symbol (`NUM_SUBACCUM_PER_SYMBOL`). This means that for GPS L1 C/A, which has a symbol period of 20 ms, valid `NUM_SUBACCUM_PER_ACCUM` values are 1, 2, 4, 5, 10, and 20. ::: :::note PpRx logging rates (specified in the `.opt` file by `--log-interval`) are in units of accumulation intervals of the root bank. The root bank is the bank of signals specified as `BK01` in the `[BANK]` block. For example, if GPS L1 C/A is specified as `BK01` and GPS L1 C/A is set to `NUM_SUBACCUM_PER_ACCUM = 10`, then a root-bank accumulation interval is 10 ms. This means that if `--log-interval` is set to 10, then PpRx will output data at 10 × 10 ms = 100 ms = 10 Hz. If `NUM_SUBACCUM_PER_ACCUM` is then halved to 5, then PpRx will output data at 20 Hz. :::
Delay-Locked Loop (DLL) These parameters control code tracking and pseudorange behavior. Most tuning trades code measurement precision against robustness to weak signals, distortion, and dynamics. ### EML_CHIP_SPACING **Default:** 0.3 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Defines the early-minus-late correlator spacing, in chips, used for signal tracking. This value is the total spacing between the early and late correlators: the early correlator is placed at `-EML_CHIP_SPACING / 2`, the prompt at `0`, and the late correlator at `+EML_CHIP_SPACING / 2`. \ **Practical Tuning Info:** Lower values generally improve code tracking precision and reduce sensitivity to multipath, but can make the pseudorange measurements noisier and less robust if the signal is weak or distorted. For high-precision applications in clean RF environments, set lower (0.1–0.2). For highly dynamic applications or weak signals, set higher (0.4–0.5). ### DLL_DEFAULT_BANDWIDTH_HZ **Default:** 0.03 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Sets the steady-state delay-locked-loop (DLL) bandwidth, in Hz. \ **Practical Tuning Info:** Higher values (e.g. 0.1) improve responsiveness to vehicle dynamics, but increase noise. Lower values (e.g. 0.003) smooth tracking and can improve precision in low-dynamics or interference/multipath-heavy environments, but with reduced responsiveness. ### DLL_CARRIER_AIDING **Default:** True \ **Parameter Class:** Tunable \ **Impact of Change:** High \ **Technical Info:** Specifies whether the DLL is aided by the carrier tracking loop. \ **Practical Tuning Info:** This should normally be set to `True`. Carrier aiding significantly improves DLL tracking performance.
Frequency-Locked Loop (FLL) These parameters affect initial frequency locking and data-symbol synchronization. They usually have low impact after lock, and defaults are appropriate for most cases. ### FLL_DEFAULT_LOOP_ORDER **Default:** ORDER1 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Options:** - `ORDER1` - `ORDER2` **Technical Info:** Sets how aggressively the FLL uses measured frequency error while pulling a newly acquired signal toward frequency lock. `ORDER1` applies a direct correction from the measured frequency error, while `ORDER2` also keeps an internal trend estimate that can help follow rapidly changing Doppler. \ **Practical Tuning Info:** Leave at `ORDER1` for general robustness. `ORDER2` may help in highly dynamic cases where Doppler changes rapidly during signal pull-in / frequency locking. ### FLL_NOM_BANDWIDTH_HZ **Default:** 5.0 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Sets the bandwidth (or effective gain) of the FLL during initial frequency pull-in for cases where the signal is above a nominal C/N0 threshold (approximately 36 dB-Hz). \ **Practical Tuning Info:** Leave at the default for most cases. Higher values make the FLL correct frequency error faster, which can help in high-dynamic pull-in but makes the estimate more sensitive to noise; lower values smooth the frequency estimate more heavily, which can improve stability but may slow acquisition-to-tracking transition. ### FLL_TRANSIENT_EFPLL_THRESH_CYC **Default:** -1 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Defines an optional FLL lock quality threshold required for PpRx to declare a frequency lock. A value of -1 disables this quality gate, with the FLL pulling in frequency over a predefined sequence. \ **Practical Tuning Info:** Set to about 0.125 if used. Lower values are more conservative but can stall otherwise healthy signals. Values above 0.25 are generally not useful as a lock-quality check. ### FLL_EFPLL_FILTER_TAU_SEC **Default:** 0.01 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Defines the time constant, in seconds, for the low-pass filter applied to the FLL's frequency error metric. This metric is only relevant and only used as a quality gate on FLL lock progression when [`FLL_TRANSIENT_EFPLL_THRESH_CYC`](#fll_transient_efpll_thresh_cyc) is enabled (not -1). \ **Practical Tuning Info:** No tuning needed if `FLL_TRANSIENT_EFPLL_THRESH_CYC` is not set / at default. If set, use a value in the range of 0.2–0.5 sec to smooth short-term discriminator noise. Shorter values more easily incorrectly pass/fail signals, while longer values make the gate slow to react to FLL lock progression. ### FLL_WEAK_BANDWIDTH_HZ **Default:** 1.0 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Sets the bandwidth (or effective gain) of the FLL during initial frequency pull-in for cases where the signal is classified as weak (below approximately 36 dB-Hz). \ **Practical Tuning Info:** Leave at the default for most cases. Higher values make the FLL correct frequency error faster, which can help in high-dynamic pull-in but makes the estimate more sensitive to noise; lower values smooth the frequency estimate more heavily, which can improve stability but may slow acquisition-to-tracking transition. ### FLL_NBS1_NOM **Default:** 12 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Upper navigation bit synchronization threshold used by the FLL for nominal-strength signals (~36+ dB-Hz). During initial pull-in, the receiver builds a histogram of the likely data-symbol boundary locations; when one candidate boundary location reaches this threshold (and no other candidate locations have reached the [`FLL_NBS2_NOM`](#fll_nbs2_nom) threshold), the receiver declares a symbol lock. \ **Practical Tuning Info:** Leave at the default for most cases. For strong signals with 20 ms symbol intervals, the default value of 12 will typically achieve the threshold required to lock in ~0.5 sec. Higher values will increase this time proportionally, though may give more protection against false locks. ### FLL_NBS1_WEAK **Default:** 80 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Upper navigation bit synchronization threshold used by the FLL for weak signals (<36 dB-Hz). During initial pull-in, the receiver builds a histogram of the likely data-symbol boundary locations; when one candidate boundary location reaches this threshold (and no other candidate locations have reached the [`FLL_NBS2_WEAK`](#fll_nbs2_weak) threshold), the receiver declares a symbol lock. \ **Practical Tuning Info:** Leave at the default for most cases. For weak signals with 20 ms symbol intervals, the default value of 80 will typically achieve the threshold required to lock in ~5 sec. Higher values will increase this time proportionally, though may give more protection against false locks. ### FLL_NBS2_NOM **Default:** 7 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Lower navigation bit synchronization threshold used by the FLL as an ambiguity check for nominal-strength signals (~36+ dB-Hz). When one candidate boundary location reaches [`FLL_NBS1_NOM`](#fll_nbs1_nom), symbol lock is accepted only if no other candidate boundary locations have reached this threshold. \ **Practical Tuning Info:** Leave at the default for most cases. Lower values make the ambiguity check stricter and may cause more symbol-lock retries, though improve confidence in the data symbol synchronization. ### FLL_NBS2_WEAK **Default:** 70 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Lower navigation bit synchronization threshold used by the FLL as an ambiguity check for weak signals (<36 dB-Hz). When one candidate boundary location reaches [`FLL_NBS1_WEAK`](#fll_nbs1_weak), symbol lock is accepted only if no other candidate boundary locations have reached this threshold. \ **Practical Tuning Info:** Leave at the default for most cases. Lower values make the ambiguity check stricter and may cause more symbol-lock retries, though improve confidence in the data symbol synchronization.
Phase-Locked Loop (PLL) These parameters control carrier phase and steady-state Doppler tracking. Tuning mainly trades carrier-phase smoothness against dynamic responsiveness, especially when using hybrid Doppler aiding. ### PLL_DEFAULT_LOOP_ORDER **Default:** ORDER2 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Options:** - `ORDER1` - `ORDER2` - `ORDER3` **Technical Info:** Sets the loop filter order, or how much internal state the PLL uses, when converting carrier phase error into carrier tracking updates during normal tracking. `ORDER1` applies a direct phase-error correction, `ORDER2` also maintains a carrier frequency estimate in applying corrections, and `ORDER3` integrates an estimated frequency change over time. \ **Practical Tuning Info:** Leave at `ORDER2` for most use cases. `ORDER1` may be useful only in very low-dynamic, high-signal-strength scenarios, while `ORDER3` can be helpful or necessary for extreme dynamics, but may be more sensitive to noise and loop tuning. ### PLL_DEFAULT_BANDWIDTH_HZ **Default:** 25.0 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Sets the responsiveness, or effective gain, of the PLL during normal carrier phase tracking for `TRACKING_STRATEGY = TRADITIONAL`. Higher values make the PLL correct measured phase error more quickly, while lower values smooth the carrier phase estimate more heavily and make tracking less sensitive to noise. \ **Practical Tuning Info:** Values around 5–30 Hz are typical, with lower values producing smoother carrier phase estimates and higher values improving tolerance to dynamics. Overall carrier tracking response is also governed by the signal's accumulation time × PLL bandwidth, so shorter accumulation times (lower `NUM_SUBACCUM_PER_ACCUM` values) generally require proportionally higher bandwidth for the same response. ### PLL_HYBRID_LOOP_ORDER **Default:** Same as [`PLL_DEFAULT_LOOP_ORDER`](#pll_default_loop_order) if not explicitly set \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Options:** - `ORDER1` - `ORDER2` - `ORDER3` **Technical Info:** Sets the loop filter order, or how much internal state the PLL uses, after `TRACKING_STRATEGY = HYBRID` begins applying model-predicted Doppler aiding. In hybrid mode, the PLL tracks residual carrier error after subtracting modeled Doppler, so the loop order controls how much residual frequency / frequency-rate behavior the PLL is allowed to estimate. \ **Practical Tuning Info:** `ORDER2` is usually best for hybrid tracking, because the aiding model can be expected to already follow most frequency-rate dynamics, making `ORDER3` less impactful. `ORDER1` may be possible if reliable Doppler aiding is available, but is less performant in most conditions than `ORDER2`. ### PLL_HYBRID_BANDWIDTH_HZ **Default:** Same as [`PLL_DEFAULT_BANDWIDTH_HZ`](#pll_default_bandwidth_hz) if not explicitly set \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Sets the responsiveness, or effective gain, of the PLL after `TRACKING_STRATEGY = HYBRID` begins applying model-predicted Doppler aiding. In hybrid mode, the PLL tracks only the residual carrier frequency error after subtracting modeled Doppler, rather than tracking the full carrier dynamics by itself. \ **Practical Tuning Info:** Use values similar to [`PLL_DEFAULT_BANDWIDTH_HZ`](#pll_default_bandwidth_hz) to begin with, but tune lower if the receiver solution is reliable. Very low values, in the range of 0.5, may be possible for good model estimates and strong signals, which can significantly improve carrier phase noise rejection. ### PLL_ENABLE_LOOP_BANDWIDTH_ADAPTATION **Default:** False \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Enables automatic increase of PLL smoothing, or reduction in responsiveness, when the signal strength is low (below ~40 dB-Hz). When tracking, the PLL uses its configured bandwidth for strong signals, but caps bandwidth at 5 Hz for weak signals. \ **Practical Tuning Info:** Leave disabled for most cases. Enabling may improve the ability to track weak signals, but may slightly reduce responsiveness to real dynamics. ### PLL_DEFAULT_DISCRIMINATOR_TYPE **Default:** AT4_DISC \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Options:** - `AT_DISC` - `AT4_DISC` **Technical Info:** Selects how the PLL converts correlation results into carrier phase error. `AT_DISC` uses a two-quadrant arctangent and is insensitive to data bit changes, while `AT4_DISC` uses a four-quadrant arctangent and can detect both carrier phase and data bit changes. \ **Practical Tuning Info:** Leave at `AT4_DISC` for most cases. Use `AT_DISC` only for the rare case where carrier tracking should ignore possible stored data bit errors and also has a `NUM_SUBACCUM_PER_ACCUM` greater than 20.
Signal health & pruning These parameters govern signal health monitoring and pruning. Tuning generally has marginal impact on performance, with the exception of `FORCE_HEALTHY`, which can improve time-to-first-fix. ### CH_IQSQ_FILTER_TAU_SEC **Default:** 0.5 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Time constant, in seconds, for the low-pass filter used to smooth C/N0 estimates. \ **Practical Tuning Info:** Leave at the default for most cases. Lower values make reported signal strength and signal-strength-related tracking logic respond faster to fades or power changes, but increase C/N0 estimate noise. ### CH_DISTORTION_FILTER_TAU_SEC **Default:** 0.5 \ **Parameter Class:** Display Configuration \ **Technical Info:** Time constant, in seconds, for the low-pass filter used to smooth the channel's distortion statistic. The distortion statistic is based on the delta between early and late correlators, with values closer to 0 indicating a more symmetric/undistorted correlation shape. \ **Practical Tuning Info:** The distortion statistic is not used in tracking loops, so tuning does not affect receiver performance, but the statistic is reported in the GBX output and the `channel.log` file. Lower `CH_DISTORTION_FILTER_TAU_SEC` values make reported distortion respond faster to changes, but increase noise. ### CH_DATA_CORRUPT_THRESHOLD **Default:** 3 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Defines how many data-corruption events from the signal's decoded nav data bits are allowed before the channel is pruned and must be reacquired. Corruption events are signal-specific, but generally come from failed parity/checksum checks in the navigation message. \ **Practical Tuning Info:** Leave at the default in most cases. Lower values make PpRx abandon channels with suspect navigation data more quickly, while higher values tolerate more transient bit errors before forcing reacquisition. ### CH_PRUNE_INTERVAL_SEC **Default:** 1.0 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Sets how often the receiver checks acquired/tracked channels for pruning conditions. This is the check interval only; actual pruning depends on [`CH_PRUNE_THRESHOLD`](#ch_prune_threshold). \ **Practical Tuning Info:** Leave at the default for most cases. Lower values make the receiver detect and recycle failing channels faster, while higher values make pruning less reactive and more tolerant of short fades or brief tracking disturbances. ### CH_PRUNE_THRESHOLD **Default:** 10 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Number of consecutive pruning checks (with an interval set by [`CH_PRUNE_INTERVAL_SEC`](#ch_prune_interval_sec)) a channel may fail before it is pruned. \ **Practical Tuning Info:** Leave at the default for most cases. Lower values prune failing channels sooner and may improve reacquisition latency, but can remove channels more easily during temporary fades. ### CH_PRUNE_CN0_THRESHOLD_MIN **Default:** 23.0 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Minimum allowed C/N0 estimate for an acquired/tracked channel during pruning checks. If a channel remains below this threshold for enough consecutive checks, it is pruned and made available for reacquisition. \ **Practical Tuning Info:** Leave at the default for most cases. Higher values recycle weak channels sooner, which can reduce time spent tracking marginal signals but may drop usable weak signals. ### CH_PRUNE_CN0_THRESHOLD_MAX **Default:** 65.0 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Maximum allowed C/N0 estimate for an acquired/tracked channel during pruning checks. Values above this threshold are treated as unrealistic or evidence of spoofing and cause the channel to be pruned. \ **Practical Tuning Info:** Leave at the default for normal use. If spoofing is expected, lowering to approximately 52 may improve pruning of spoofed signals while preventing pruning of almost all real signals. ### FORCE_HEALTHY_WHEN_TRACQUIRED **Default:** False \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Marks a signal as healthy when it is initialized through direct-to-track acquisition, before the signal's own health indicator has necessarily been decoded. This allows observables from direct-to-track acquired signals to be used sooner when timing and ephemeris are already available from aiding information. \ **Practical Tuning Info:** Enable when using reliable imported ephemeris and faster use of direct-to-track signals is desired. This parameter is narrower than [`FORCE_HEALTHY`](#force_healthy); the forced health indication is intended to be replaced once the signal-borne health indicator is decoded. ### FORCE_HEALTHY **Default:** False \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Forces signals to be treated as healthy, regardless of whether the broadcast health status is unknown or unhealthy. \ **Practical Tuning Info:** Enable cautiously; signals marked unhealthy may still be useful. Enabling `FORCE_HEALTHY` can also improve time-to-first-fix by not forcing a wait for signal health status. ### PLL_PHASE_LOCK_THRESHOLD **Default:** 0.9 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Phase-lock statistic threshold used to decide when the PLL has achieved carrier phase lock. The receiver phase-lock statistic is approximately defined by `cos(2 * phase error)`, so a value of 0.9 corresponds to a carrier phase error threshold of ~12.9 degrees. \ **Practical Tuning Info:** Leave at the default for most cases. Higher values make phase-lock declaration more strict, while lower values can declare phase lock sooner but increase the risk of accepting a poorly aligned carrier phase estimate. ### PLL_PHASE_FLAG_THRESHOLD **Default:** 0.4 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** If the phase-lock statistic falls below this value, the channel sets a phase error flag on the channel. The receiver phase-lock statistic is approximately defined by `cos(2 * phase error)`, so the default value of 0.4 corresponds to a carrier phase error threshold of ~33.2 degrees. Phase error flags temporarily de-weight or remove the signal from participation in the estimator and count as failing a pruning check. \ **Practical Tuning Info:** Leave at the default for most cases. Higher values make the receiver flag possible phase issues more aggressively, which can protect the estimator from questionable carrier-phase / Doppler information, but may increase false alarms. ### PLL_NUM_SUB_PER_PHASELOCK **Default:** 20 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Number of subaccumulations (usually 1 ms) used to compute each phase-lock statistic. \ **Practical Tuning Info:** Leave at the default for most cases. Higher values average over a longer interval and make phase-lock / phase-flag decisions more robust but slower to react to lock changes.
System settings These parameters set the basic signal configuration. Most should be left out of the `.config` file so PpRx can choose the right values automatically; usually only `CIRCBUFF_STREAM_IDX` needs to be set manually for the RF stream layout. ### FRONT_END **Default:** None \ **Parameter Class:** Structural Configuration \ **Technical Info:** Selects which front-end variant supplies samples for this signal bank. The value must match a front-end block defined in the `FRONT_END` section, such as `LION` or `LION_L5`, and that front end must list the signal type in its `SUPPORTED_SIGNAL_TYPES`. \ **Practical Tuning Info:** For , use `FRONT_END = LION` for L1/L2-band signal banks, and `FRONT_END = LION_L5` for L5-band banks. This should normally not be tuned; changing it routes the bank to a different sample stream, so mismatches will prevent normal operation. ### CIRCBUFF_STREAM_IDX **Default:** 0 \ **Parameter Class:** Structural Configuration \ **Technical Info:** Index of RF stream containing data for the given signal type. \ **Practical Tuning Info:** This value must be set according to the location of RF data in the incoming sample stream. For the or any LION bitpacked data, the correct mapping is as follows: - Any L1-band primary antenna signal: `CIRCBUFF_STREAM_IDX = 0` - Any L1-band secondary antenna signal: `CIRCBUFF_STREAM_IDX = 1` - Any L2-band primary antenna signal: `CIRCBUFF_STREAM_IDX = 2` - Any L2-band secondary antenna signal: `CIRCBUFF_STREAM_IDX = 3` - Any L5-band primary antenna signal: `CIRCBUFF_STREAM_IDX = 0` - Any L5-band secondary antenna signal: `CIRCBUFF_STREAM_IDX = 1` ### INHERIT_CONFIG_FROM_PRIMARY **Default:** False \ **Parameter Class:** Structural Configuration \ **Technical Info:** Allows a non-primary signal block, such as `[GPS_L1_CA_ALT1]`, to inherit configuration values from the matching primary block, such as `[GPS_L1_CA_PRIMARY]`, before applying any values explicitly set in the non-primary block. \ **Practical Tuning Info:** Use this for multi-antenna configurations where `ALT1` should mostly match `PRIMARY`, then override only fields that differ such as `CIRCBUFF_STREAM_IDX`. This reduces duplication and keeps primary/alternate signal settings synchronized. ### NOM_CHIPRATE_CPS **Default:** Dependent on the Signal Type selected. \ **Parameter Class:** Structural Configuration \ **Technical Info:** Nominal chipping rate of PRN code, in chips per second. \ **Practical Tuning Info:** This value should normally be omitted from the `.config` file; PpRx will select the correct nominal value for the signal type specified. ### FREQ_CARRIER_HZ **Default:** Dependent on the Signal Type selected. \ **Parameter Class:** Structural Configuration \ **Technical Info:** Nominal carrier frequency, in Hz. \ **Practical Tuning Info:** This value should normally be omitted from the `.config` file; PpRx will select the correct nominal value for the signal type specified. ### NUM_CHIPS_PER_CODE **Default:** Dependent on the Signal Type selected. \ **Parameter Class:** Structural Configuration \ **Technical Info:** Number of chips in PRN code. \ **Practical Tuning Info:** This value should normally be omitted from the `.config` file; PpRx will select the correct nominal value for the signal type specified. ### NUM_CHIPS_PER_SUBACCUM **Default:** Dependent on the Signal Type selected. \ **Parameter Class:** Structural Configuration \ **Technical Info:** Number of chips per subaccumulation. \ **Practical Tuning Info:** This value should normally be omitted from the `.config` file; PpRx will select the correct nominal value for the signal type specified. ### NUM_SUBACCUM_PER_SYMBOL **Default:** Dependent on the Signal Type selected. \ **Parameter Class:** Structural Configuration \ **Technical Info:** Number of subaccumulations per symbol. \ **Practical Tuning Info:** This value should normally be omitted from the `.config` file; PpRx will select the correct nominal value for the signal type specified.
--- ## BASETIME Below is an *example* of the BASETIME block: ```bash [BASETIME] GPS_WEEK_REFERENCE = 2300 ``` The BASETIME block contains the following configuration parameter: ### GPS_WEEK_REFERENCE **Default:** 2300 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Reference GPS week used to resolve truncated navigation-message week numbers into full GPS week numbers. The receiver chooses the full week closest to this reference when decoding navigation data. \ **Practical Tuning Info:** This should rarely be adjusted, but set near the expected collection date; it does not need to be exact, but should be within the correct rollover era. For 10-bit GPS week fields, keep it within roughly 512 weeks (about 10 years) of the true GPS week to avoid decoding navigation data into the wrong epoch. :::note GPS week rollover occurs every 1,024 weeks, or about 19.6 years. Some GPS navigation messages transmit the week number using only 10 bits, so the value can only range from 0 to 1,023 before wrapping back to 0. `GPS_WEEK_REFERENCE` tells the receiver which 1,024-week era to use when converting that truncated week number into a full GPS week. See [here](https://geodesy.noaa.gov/CORS/resources/gpscals.shtml) for a calendar date to GPS week mapping. ::: --- ## BUFFER_LOADER import ProductName from '@site/src/components/ProductName'; Below is an *example* of the BUFFER_LOADER block: ```bash [BUFFER_LOADER] NUM_BUFFER_LOADERS = 1 BL01 = BL_LION [BL_LION] DEVICE = LION TYPE = USB # Set TYPE = FILE to post-process capture files. FRONT_ENDS = LION LION_L5 ``` The BUFFER_LOADER block contains all of the following configuration parameters: ### NUM_BUFFER_LOADERS **Default:** None \ **Parameter Class:** Structural Configuration \ **Technical Info:** Number of buffer loader configurations defined in the `[BUFFER_LOADER]` block. A buffer loader is responsible for reading samples from a file or USB stream and filling the raw data buffers in PpRx. \ **Practical Tuning Info:** For , set this to 1. Use additional buffer loaders only when a receiver has multiple independent sample sources that must be read separately. ### BL01, BL02, … **Default:** None \ **Parameter Class:** Structural Configuration \ **Technical Info:** Ordered names of the buffer-loader configuration sections. Each `BL##` value must match a corresponding config block, such as `BL_LION`, which defines the loader `TYPE`, `DEVICE`, and the `FRONT_ENDS` it feeds. \ **Practical Tuning Info:** For , use only `BL01 = BL_LION`, and then configure `[BL_LION]` with the parameters below. Most front-ends should only have one buffer loader, assuming RF data is coming from a single file or USB stream. Each `BL##` entry points to a named buffer-loader section, which each have the parameters below. In the example above, `BL01 = BL_LION`, so that `.config` file must contain a `[BL_LION]` block with the following parameters: ### DEVICE **Default:** GENERIC \ **Parameter Class:** Operational Configuration \ **Technical Info:** Identifies the bitpacking format used by this buffer loader. \ **Practical Tuning Info:** For , `DEVICE = LION` must be used. For front-ends not outputting data in the LION format, in general use `DEVICE = GENERIC`. ### TYPE **Default:** FILE \ **Parameter Class:** Operational Configuration \ **Options:** - `FILE` - `USB` - `STREAM` **Technical Info:** Selects the input source type for this buffer loader. `FILE` reads samples from an input file or named pipe, while `USB` reads from a live USB stream. `STREAM` reads samples from a named pipe or character device. \ **Practical Tuning Info:** Use `USB` for live operation, and `FILE` for any playback of captured data. Use `STREAM` when the raw data to be sent to PpRx is delivered to a named pipe or character device. In all cases, use `--input-file` in the `.opt` file to specify the filepath of the input data. ### FRONT_ENDS **Default:** None \ **Parameter Class:** Structural Configuration \ **Technical Info:** List of front-end configuration sections fed by this buffer loader. Each name should correspond to a front-end section defined by `FE01`, `FE02`, etc., such as `LION` or `LION_L5`. \ **Practical Tuning Info:** For , use `FRONT_ENDS = LION LION_L5`, so one loader feeds both the L1/L2 and L5 front-end configurations. --- ## CDGNSS The `CDGNSS` block tunes the carrier-phase/Attitude2D measurement subsystem used by dual-antenna heading and IMU-aided pose. It only matters when [`ESTIMATOR_PROFILE`](/pprx/reference-definitions/pprx-configs/estimator#estimator-profiles) is set to `STANDARD_DUAL_ANTENNA_HEADING` or `STANDARD_IMU_DUAL_ANTENNA_HEADING`. For any other profile, the `[CDGNSS]` block is ignored. The `[CDGNSS]` block is optional. When it is omitted, PpRx emits a startup warning and uses internal defaults for every CDGNSS parameter. This block covers satellite and measurement selection, differential measurement noise, process noise, sphere grid construction, integer least-squares behavior, and integer aperture testing for the Attitude2D filter. The sigma-point filter parameters that consume these measurements (`ATTITUDE_2D_SPF_*`) are configured in the "Dual-antenna heading" section of [`[ESTIMATOR]`](/pprx/reference-definitions/pprx-configs/estimator), not here. Below is an *example* of the CDGNSS block, used with `ESTIMATOR_PROFILE = STANDARD_DUAL_ANTENNA_HEADING` or `STANDARD_IMU_DUAL_ANTENNA_HEADING`: ```ini [CDGNSS] ELEVATION_MASK_ANGLE_DEG = 14.3 SQRT_Q_TILDE_POS = 0.2 UNDIFFERENCED_ZENITH_PSEUDORANGE_STD = 1.0 UNDIFFERENCED_ZENITH_PHASE_STD = 0.004 SPHERE_GRID_SPACING_MULT = 0.95 ILS_NUM_THREADS = 1 IA_TEST_TYPE = IALS INNOVATIONS_TEST_PF = 1e-5 ``` :::note This block is shared with PpRx's (not-yet-implemented) RTK profiles internally. Some parameters accepted by the underlying estimator only affect RTK operation and are not documented here, since they have no effect on the currently implemented `STANDARD_DUAL_ANTENNA_HEADING` and `STANDARD_IMU_DUAL_ANTENNA_HEADING` profiles. ::: The CDGNSS block can be configured with the following parameters.
Atmospheric corrections ### USE_IONO_CORR **Default:** True \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Enables ionospheric delay correction when forming CDGNSS measurement predictions. \ **Practical Tuning Info:** Leave enabled for normal operation. For very short baseline dual-antenna operation, ionospheric differences will be negligible, but leaving the correction enabled is still appropriate. ### USE_TROPO_CORR **Default:** True \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Enables tropospheric delay correction when forming CDGNSS measurement predictions. \ **Practical Tuning Info:** Leave enabled for normal operation. For very short baseline dual-antenna operation, tropospheric differences will be negligible, but leaving the correction enabled is still appropriate.
Baseline geometry & measurement selection ### NUM_BASELINES **Default:** 1 \ **Parameter Class:** Tunable \ **Technical Info:** Number of baselines that participate in the CDGNSS solution. \ **Practical Tuning Info:** Leave at 1 for a standard dual-antenna (PRIMARY/ALT1) setup. ### ELEVATION_MASK_ANGLE_DEG **Default:** ~14.3 degrees (0.25 radians) \ **Parameter Class:** Tunable \ **Technical Info:** Minimum satellite elevation angle allowed into the CDGNSS solution. Signals below this angle are excluded. Set to `-90` to disable elevation masking. \ **Practical Tuning Info:** Leave at the default for most cases. This mirrors the equivalent [`ELEVATION_MASK_ANGLE_DEG`](/pprx/reference-definitions/pprx-configs/estimator#elevation_mask_angle_deg) parameter in `[ESTIMATOR]`, but applies only to the CDGNSS/Attitude2D measurement subsystem. ### BORESIGHT_ELEVATION_MASK_ANGLE_RAD **Default:** -Infinity (disabled) \ **Parameter Class:** Tunable \ **Technical Info:** Boresight-relative elevation mask angle, in radians. Only used when vehicle attitude information is provided in the incoming GBX stream. \ **Practical Tuning Info:** Leave at the default (disabled) unless boresight-relative masking is specifically needed. ### ENFORCE_STRICT_SELECTION **Default:** True \ **Parameter Class:** Tunable \ **Technical Info:** When enabled, carrier phase and pseudorange measurements with a phase lock statistic below [`STRICT_SELECTION_PHASE_LOCK_STAT_THRESHOLD`](#strict_selection_phase_lock_stat_threshold) or a C/N0 below [`STRICT_SELECTION_CN0_THRESHOLD`](#strict_selection_cn0_threshold) are excluded from the CDGNSS solution. \ **Practical Tuning Info:** If navigation solution precision is desired, set to `True`. If operating in a challenging RF environment, set to `False`. ### STRICT_SELECTION_CN0_THRESHOLD **Default:** 37.5 \ **Parameter Class:** Tunable \ **Technical Info:** Carrier-to-noise ratio threshold, in dB-Hz, used by [`ENFORCE_STRICT_SELECTION`](#enforce_strict_selection). \ **Practical Tuning Info:** Leave at the default for most cases. Lower to admit weaker signals in degraded RF environments. ### STRICT_SELECTION_PHASE_LOCK_STAT_THRESHOLD **Default:** 0.55 \ **Parameter Class:** Tunable \ **Technical Info:** Phase lock statistic threshold used by [`ENFORCE_STRICT_SELECTION`](#enforce_strict_selection). \ **Practical Tuning Info:** Leave at the default for most cases. ### ELEVATION_DEPENDENT_WEIGHTING **Default:** True \ **Parameter Class:** Tunable \ **Technical Info:** Weights undifferenced observables by `1/sin(el)`, where `el` is the elevation angle. This de-weights multipath-corrupted low-elevation signals. When disabled, all observables are weighted equally. \ **Practical Tuning Info:** Leave enabled for most real RF environments. ### ADMISSIBLE_GENERIC_TYPES **Default:** `GPS_L1_CA SBAS_L1_I GALILEO_E1_BC GPS_L2_CLM` \ **Parameter Class:** Operational Configuration \ **Technical Info:** To avoid mismatched double differences, only one GenericType is admissible per system at each center frequency (for example, at L2 only one of `GPS_L2_CL`, `GPS_L2_CM`, or `GPS_L2_CLM` is allowed). This list defines which GenericTypes are admissible. \ **Practical Tuning Info:** Leave at the default unless a specific GenericType needs to be excluded or substituted. ### TXID_EXCLUDE_LIST **Default:** (empty) \ **Parameter Class:** Operational Configuration \ **Technical Info:** List of TxIds and frequencies to exclude from the CDGNSS solution. Each entry uses the RINEX-style format `[System][Number][Frequency]`, for example `G23L2` (GPS PRN 23, L2 only) or `E13L1` (Galileo PRN 13, L1 only). \ **Practical Tuning Info:** Use to exclude specific known-bad transmitters or frequencies from the solution. ### FORCE_PIVOT_LIST **Default:** (empty) \ **Parameter Class:** Operational Configuration \ **Technical Info:** List of TxIds and frequencies (same format as [`TXID_EXCLUDE_LIST`](#txid_exclude_list)) that are forced to be used as pivots in double differencing. If empty, pivots are chosen by the default internal algorithm. \ **Practical Tuning Info:** Leave empty for most cases.
Measurement noise ### UNDIFFERENCED_ZENITH_PSEUDORANGE_STD **Default:** 1.0 \ **Parameter Class:** Tunable \ **Technical Info:** Standard deviation of undifferenced pseudorange measurements, in meters, assuming a transmitter at zenith. Applies to all frequencies. \ **Practical Tuning Info:** Leave at the default for most cases. ### UNDIFFERENCED_ZENITH_PHASE_STD **Default:** 0.004 \ **Parameter Class:** Tunable \ **Technical Info:** Standard deviation of undifferenced carrier phase measurements, in meters, assuming a transmitter at zenith. Applies to all frequencies. \ **Practical Tuning Info:** Leave at the default for most cases. ### UNDIFFERENCED_ZENITH_STATIONARY_PSEUDORANGE_STD **Default:** Same as [`UNDIFFERENCED_ZENITH_PSEUDORANGE_STD`](#undifferenced_zenith_pseudorange_std) if unset \ **Parameter Class:** Tunable \ **Technical Info:** Undifferenced pseudorange standard deviation at zenith, in meters, used while the rover is stationary (as determined by the standard navigation solution's velocity). Can be set higher than [`UNDIFFERENCED_ZENITH_PSEUDORANGE_STD`](#undifferenced_zenith_pseudorange_std) to account for increased multipath a stationary antenna experiences. \ **Practical Tuning Info:** Leave unset unless stationary-specific multipath behavior is being tuned. ### UNDIFFERENCED_ZENITH_TRANSIENT_PSEUDORANGE_STD **Default:** 2.0 \ **Parameter Class:** Tunable \ **Technical Info:** Undifferenced pseudorange standard deviation at zenith, in meters, used during the tracking loop's initial transient period after a signal is first tracked. \ **Practical Tuning Info:** Leave at the default for most cases. ### SQRT_Q_TILDE_POS **Default:** 0.2 \ **Parameter Class:** Tunable \ **Technical Info:** Square root of the position process noise intensity used by the CDGNSS/Attitude2D filter, in meters/√s. Represents the standard deviation of error induced by process noise over a 1-second propagation step; for a `T`-second step this is approximately `sqrt(T) × SQRT_Q_TILDE_POS`. \ **Practical Tuning Info:** Leave at the default for most cases. Higher values make the filter more responsive to real motion at the cost of noisier solutions.
Innovations testing & outlier rejection ### INNOVATIONS_TEST_PF **Default:** 1e-5 \ **Parameter Class:** Tunable \ **Technical Info:** False-alarm probability for the double-difference pseudorange ("float") innovations test, a chi-squared test on the normalized innovations squared (NIS) statistic. If this test fails for a batch of observables, the Attitude2D estimator reinitializes. \ **Practical Tuning Info:** Leave at the default for most cases. Lower values make the estimator more tolerant of noisy measurements before reinitializing; higher values make it reinitialize more readily. ### FIX_INNOVATIONS_TEST_PF **Default:** 1e-5 \ **Parameter Class:** Tunable \ **Technical Info:** False-alarm probability for the double-difference carrier phase ("fix") innovations test. If this test fails for a batch of observables, the estimator falls back to a float (non-integer-fixed) solution. \ **Practical Tuning Info:** Leave at the default for most cases. Set to a very small value (for example `1e-100`) to effectively disable this test. ### DD_PSEUDORANGE_SCALAR_OUTLIER_THRESH_STD **Default:** +Infinity (disabled) \ **Parameter Class:** Tunable \ **Technical Info:** Threshold, in standard deviations, for scalar double-difference pseudorange outlier rejection. If a DD pseudorange measurement's normalized innovation exceeds this threshold, the corresponding satellite is excluded on all frequencies. \ **Practical Tuning Info:** Leave at the default (disabled) unless outlier rejection on individual satellites is specifically needed. ### OUTLIER_EXCLUSION **Default:** False \ **Parameter Class:** Tunable \ **Technical Info:** Enables N-minus-1 (single-signal-with-replacement) outlier exclusion when integer fixing fails. \ **Practical Tuning Info:** Enable in environments where occasional single-satellite outliers are expected to block integer fixing. ### OUTLIER_EXCLUSION_DEPTH **Default:** 0 \ **Parameter Class:** Tunable \ **Technical Info:** Depth of the [`OUTLIER_EXCLUSION`](#outlier_exclusion) search. Signals are ordered from most to least likely to be causing fixing failure, and single-signal exclusion is attempted on each in turn, up to this depth. A value of 0 disables outlier exclusion regardless of `OUTLIER_EXCLUSION`. \ **Practical Tuning Info:** Set above 0 to enable outlier exclusion once [`OUTLIER_EXCLUSION`](#outlier_exclusion) is enabled. ### MINIMUM_NUMBER_DD_SIGNALS **Default:** 1 \ **Parameter Class:** Tunable \ **Technical Info:** Minimum number of double-differenced signal pairs required to promote a float solution to a fixed solution. Ignored if the previous solution was already fixed, unless [`FORCE_NDD_REQUIREMENT`](#force_ndd_requirement) is enabled. \ **Practical Tuning Info:** Raise to require more redundancy before accepting an integer fix. ### FORCE_NDD_REQUIREMENT **Default:** False \ **Parameter Class:** Tunable \ **Technical Info:** When disabled, a fixed solution with fewer double-differenced signals than [`MINIMUM_NUMBER_DD_SIGNALS`](#minimum_number_dd_signals) can still be accepted if the previous solution was fixed and other criteria are met. When enabled, `MINIMUM_NUMBER_DD_SIGNALS` is strictly enforced on every epoch. \ **Practical Tuning Info:** Leave at the default for most cases.
Sphere grid & integer least-squares ### SPHERE_GRID_SPACING_MULT **Default:** 0.95 \ **Parameter Class:** Tunable \ **Technical Info:** The spherical grid used in constrained-baseline integer least-squares requires grid points spaced no more than half the smallest signal wavelength (the L1 wavelength). This value multiplies that spacing goal; it cannot exceed 1 or be less than or equal to 0. Only relevant to the Attitude2D estimator. \ **Practical Tuning Info:** Leave near the default for most cases. ### USE_POINT_REPELLING_MODEL **Default:** False \ **Parameter Class:** Tunable \ **Technical Info:** Refines the spherical grid used in constrained-baseline integer least-squares by making grid points more uniformly spaced. This can take significant time to run for baselines longer than 1 meter. Only relevant to the Attitude2D estimator. \ **Practical Tuning Info:** Leave disabled unless grid uniformity is specifically limiting performance, since this can be slow for longer baselines. ### ILS_NUM_THREADS **Default:** 1 \ **Parameter Class:** Tunable \ **Technical Info:** Number of threads the integer least-squares solver is allowed to use for parallelizable operations (for example, grid search). The benefit of parallelization is platform-dependent, and requesting too many threads can make switching overhead outweigh the benefit. \ **Practical Tuning Info:** Leave at the default for most cases.
Integer aperture testing ### IA_TEST_TYPE **Default:** IALS \ **Parameter Class:** Tunable \ **Options:** - `IALS`   [integer aperture least-squares test; the optimal test for integer least squares] - `RATIO` - `DIFFERENCE` **Technical Info:** Selects the integer aperture test used to validate an integer-fixed solution before accepting it. \ **Practical Tuning Info:** Leave at the default (`IALS`) for most cases. ### IA_OVERRIDE_TEST_RESULT **Default:** False \ **Parameter Class:** Tunable \ **Technical Info:** When enabled, the integer aperture test still runs (so its statistics remain visible), but its result is overridden by [`IA_OVERRIDE_VALUE`](#ia_override_value) rather than gating the fix. Useful for viewing all-fixed or all-float output for evaluation. \ **Practical Tuning Info:** Leave disabled for normal operation. ### IA_OVERRIDE_VALUE **Default:** False \ **Parameter Class:** Tunable \ **Technical Info:** The fixed/float result used in place of the real test result when [`IA_OVERRIDE_TEST_RESULT`](#ia_override_test_result) is enabled. \ **Practical Tuning Info:** Only relevant when `IA_OVERRIDE_TEST_RESULT` is enabled. ### IA_USE_FIXED_FAILURE_RATE **Default:** True \ **Parameter Class:** Tunable \ **Technical Info:** Enables fixed-failure-rate testing for the selected [`IA_TEST_TYPE`](#ia_test_type). When disabled, the test parameter is held at [`IA_DEFAULT_TEST_PARAM`](#ia_default_test_param) instead. \ **Practical Tuning Info:** Leave at the default for most cases. ### IA_DEFAULT_TEST_PARAM **Default:** 0.8 \ **Parameter Class:** Tunable \ **Technical Info:** The test parameter used when [`IA_USE_FIXED_FAILURE_RATE`](#ia_use_fixed_failure_rate) is disabled. \ **Practical Tuning Info:** Leave at the default unless fixed-failure-rate testing has been specifically disabled and a different static threshold is needed. ### IA_MINIMUM_TEST_PARAM **Default:** -Infinity (disabled) \ **Parameter Class:** Tunable \ **Technical Info:** Minimum test statistic allowed under fixed-failure-rate testing. Protects against the fixed-failure-rate test setting a very low or zero threshold when model strength is overly optimistic, such as from unmodeled multipath bias. \ **Practical Tuning Info:** Leave at the default (disabled) unless the fixed-failure-rate test is producing implausibly permissive thresholds. ### IA_ALLOWABLE_FAILURE_PROBABILITY **Default:** 1e-3 \ **Parameter Class:** Tunable \ **Technical Info:** Maximum allowable failure probability for fixed-failure-rate testing. Some integer aperture tests look up model coefficients from a table indexed partly by this value; if the specified rate is below every table entry, PpRx raises a configuration error. \ **Practical Tuning Info:** Leave at the default for most cases.
Attitude2D solution constraints ### A2D_MAX_ELEVATION_FOR_INTEGER_INITIAL_GUESS_DEG **Default:** -1 (disabled) \ **Parameter Class:** Tunable \ **Technical Info:** Confines the initial relative-position guess to within plus/minus this elevation value. A value of `-1` disables the elevation constraint on the initial guess. \ **Practical Tuning Info:** Leave at the default (disabled) for most cases. ### A2D_SOLUTION_ELEVATION_MASK_RAD **Default:** π/2 (disabled) \ **Parameter Class:** Tunable \ **Technical Info:** If the Attitude2D solution lies outside plus/minus this elevation threshold, the integrity-check-passed flag is lowered. A value of `-1` disables this threshold. \ **Practical Tuning Info:** Leave at the default for most cases. ### DISABLE_AFTER_PPOSE_INIT **Default:** False \ **Parameter Class:** Tunable \ **Technical Info:** When enabled, this estimator stops consuming incoming GBX reports once the attached fused-pose estimator reports it has initialized. Reduces CPU usage when CDGNSS/Attitude2D is only needed to initialize the fused pose solution. \ **Practical Tuning Info:** Enable to save CPU once fused pose initialization is no longer needed from this estimator.
Differential code bias & data validity ### GALILEO_E1_BC_TO_GPS_L1_CA_DD_DCB **Default:** 0 \ **Parameter Class:** Tunable \ **Technical Info:** Differential code bias, in the double-difference pseudorange observation, between a GPS L1 C/A pivot satellite and a Galileo E1 BC non-pivot satellite. If pivot/non-pivot roles are reversed, the negated value is applied. This bias arises when the rover and reference receivers have dissimilar front ends or code replica generator configurations. \ **Practical Tuning Info:** Leave at 0 unless a known DCB between dissimilar front ends needs to be corrected. ### SBAS_L1_I_TO_GPS_L1_CA_DD_DCB **Default:** 0 \ **Parameter Class:** Tunable \ **Technical Info:** Same as [`GALILEO_E1_BC_TO_GPS_L1_CA_DD_DCB`](#galileo_e1_bc_to_gps_l1_ca_dd_dcb), for an SBAS L1 non-pivot satellite. \ **Practical Tuning Info:** Leave at 0 unless a known DCB between dissimilar front ends needs to be corrected. ### FORCE_VALID_REFERENCE_OBSERVABLES **Default:** False \ **Parameter Class:** Tunable \ **Technical Info:** Observables are normally marked invalid if the transmitter is unhealthy or its health status is unknown. When enabled, all processed reference-stream observables are considered valid regardless of health status. Rover-stream observables are unaffected. \ **Practical Tuning Info:** Leave disabled for normal operation. ### FORCE_VALID_GALILEO_14_AND_18_OBSERVABLES **Default:** False \ **Parameter Class:** Tunable \ **Technical Info:** Galileo TxIds 14 and 18 were launched into incorrect orbits; their signals are usable but still marked unhealthy by some receivers. When enabled, observables from these two satellites are treated as valid despite the unhealthy flag. \ **Practical Tuning Info:** Enable if Galileo 14/18 availability is needed and their observables are otherwise being excluded due to health status. ### MAXIMUM_AGE_OF_VALID_REFERENCE_DATA_SEC **Default:** 0.5 \ **Parameter Class:** Tunable \ **Technical Info:** Maximum allowed age, in seconds, of reference data relative to the current rover epoch for the reference data to be considered valid. \ **Practical Tuning Info:** Set below the reference stream's inter-epoch interval to ensure an acceptably small age of data. ### BACKWARD **Default:** False \ **Parameter Class:** Tunable \ **Technical Info:** Configures the estimator to expect and operate on a time-reversed data stream. Does not itself reverse a normal data stream. \ **Practical Tuning Info:** Leave disabled for normal, forward-time operation.
--- ## DISPLAY The `DISPLAY` block controls PpRx's live terminal/status display. These settings affect how receiver status, bank/channel tracking information, and diagnostic messages are formatted and refreshed on screen; they do not affect acquisition, tracking, or estimator behavior. Below is an *example* of the DISPLAY block: ```bash [DISPLAY] DISPLAY_EXTRA_FIELDS = FALSE REDRAW_PERIOD = 2 ``` The DISPLAY block contains all of the following configuration parameters: ### USE_COLOR **Default:** True \ **Parameter Class:** Display Configuration \ **Technical Info:** Enables ANSI color formatting for the terminal display when output is written to stdout. \ **Practical Tuning Info:** Leave enabled for interactive terminal use. Disable if display output is being redirected to a file. ### MESSAGE_PRINTING_PERSISTENCE **Default:** 5 \ **Parameter Class:** Display Configuration \ **Technical Info:** Number of display refreshes that a diagnostic/status message remains visible before being removed from the display cache. \ **Practical Tuning Info:** Increase to display status messages for longer. ### DISPLAY_EXTRA_FIELDS **Default:** False \ **Parameter Class:** Display Configuration \ **Technical Info:** Enables additional per-channel display fields, such as phase-lock and tracking-quality details. \ **Practical Tuning Info:** Leave disabled for the normal compact display. Enable when debugging tracking behavior or when additional channel-level diagnostics are useful. ### MAXIMUM_BANK_COLUMNS **Default:** 2 \ **Parameter Class:** Display Configuration \ **Technical Info:** Maximum number of bank display columns shown in a single display row. \ **Practical Tuning Info:** Increase on wide terminals to show more banks side by side. ### WRAP_BANK_ROWS **Default:** False \ **Parameter Class:** Display Configuration \ **Technical Info:** Controls what happens when multiple banks of the same signal type exceed [`MAXIMUM_BANK_COLUMNS`](#maximum_bank_columns). When true, additional banks wrap to a new row; when false, banks that do not fit are not displayed. \ **Practical Tuning Info:** Enable when all bank displays should remain visible, especially in multi-antenna or multi-signal configurations. ### MIX_BANK_ROWS **Default:** False \ **Parameter Class:** Display Configuration \ **Technical Info:** Controls whether banks with different signal types may share the same display row. When false, different signal types start on separate rows; when true, different signal types may share a row up to [`MAXIMUM_BANK_COLUMNS`](#maximum_bank_columns). \ **Practical Tuning Info:** Enable to make the display more compact. This setting only affects row layout; [`WRAP_BANK_ROWS`](#wrap_bank_rows) separately controls whether same-type banks that exceed [`MAXIMUM_BANK_COLUMNS`](#maximum_bank_columns) are wrapped or hidden. ### REDRAW_PERIOD **Default:** 1 \ **Parameter Class:** Display Configuration \ **Technical Info:** The display is redrawn every `REDRAW_PERIOD` log intervals (with a log interval being set by `--log-interval` in the `.opt` file). \ **Practical Tuning Info:** Leave at `1` for normal use. Increase if display output is too frequent or terminal redraw overhead is significant. --- ## EPHEMERIS The `EPHEMERIS` block controls how PpRx handles satellite correction and differential-correction data. These settings affect whether SBAS-based satellite clock and orbit corrections are applied to measurements and whether decoded correction records are included in the GBX output. Below is an *example* of the EPHEMERIS block: ```bash [EPHEMERIS] APPLY_SBAS_DIFFERENTIAL_CORRECTIONS = TRUE EXPORT_DIFFERENTIAL_CORRECTIONS = TRUE ``` ### APPLY_SBAS_DIFFERENTIAL_CORRECTIONS **Default:** False \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Enables use of SBAS fast and long-term satellite corrections to adjust GNSS satellite clock and orbit modeling. This affects SBAS satellite correction messages only; SBAS ionospheric corrections are handled separately by the [`IONO_ESTIMATOR`](/pprx/reference-definitions/pprx-configs/iono-estimator) block. \ **Practical Tuning Info:** Enable when SBAS is valid for the operating region (e.g. North America). Leave disabled for controlled testing or workflows that already use another precise correction source. ### EXPORT_DIFFERENTIAL_CORRECTIONS **Default:** False \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Enables decoded SBAS/CNAV differential-correction records to be included in the main GBX output, or in messages produced by `--export-ephem`. This controls exported/logged data only and does not by itself cause corrections to be applied to navigation. \ **Practical Tuning Info:** Enable to inspect, log, or forward differential-correction records for diagnostics or downstream processing. Leave disabled for normal operation when exports should contain only primary ephemeris-related data. --- ## ESTIMATOR import ProductName from '@site/src/components/ProductName'; The `ESTIMATOR` block configures PpRx's navigation solution engine. It controls how GNSS measurements are corrected, weighted, accepted or rejected, and how the receiver position, velocity, clock, and related state are propagated over time. Below is an *example* of the ESTIMATOR block: ```bash [ESTIMATOR] USE_IONO_CORR = TRUE USE_TROPO_CORR = TRUE ELEVATION_MASK_ANGLE_DEG = 15 ENFORCE_STRICT_SELECTION = TRUE ALLOW_DELTR_FIXUPS = TRUE MAX_ABS_DELTR_SEC = 0.0001 DYNAMICS_MODEL = STATIC SQRT_Q_TILDE = 0.5 CLOCK_TYPE = TCXO ZENITH_PSEUDORANGE_STD = 0.9 ZENITH_DOPPLER_STD = 0.7 SISRE_DEFAULT_STD = 1.0 SISRE_STD_INFLATION_FACTOR = 1.0 ZERO_VELOCITY_UPDATE_THRESHOLD_MPS = 0.15 ELEVATION_DEPENDENT_WEIGHTING = TRUE ELEVATION_WEIGHTING_KNEE_DEG = 9 INNOVATIONS_TEST_PF = 1e-3 ``` ## Estimator Profiles `ESTIMATOR_PROFILE` selects a complete, supported PpRx navigation pipeline: standard navigation, dual-antenna heading, or IMU-aided pose. If omitted, PpRx defaults to `STANDARD`, so existing `[ESTIMATOR]` configurations continue to work unchanged. The `[CDGNSS]` and `[IMU]` blocks only matter for the profile that requires them. See [CDGNSS](/pprx/reference-definitions/pprx-configs/cdgnss) and [IMU](/pprx/reference-definitions/pprx-configs/imu) for details. For a GUI-based setup walkthrough, see [Configure for Precision Heading in the GUI](/advanced-tutorials/precision-heading). ### Dual-Antenna Heading (No IMU) Set `ESTIMATOR_PROFILE = STANDARD_DUAL_ANTENNA_HEADING` in `[ESTIMATOR]`, and provide exactly one of the following baseline descriptions. `BASELINE_VECTOR_B` is strongly preferred: it's required for IMU-aided pose, and it's what lets the GUI render antenna rotation correctly. Use `BASELINE_LENGTH_CONSTRAINT` only when the full body-frame vector genuinely isn't available. - `BASELINE_VECTOR_B` (full body-frame vector, preferred) - `BASELINE_LENGTH_CONSTRAINT` (scalar length only, fallback) ```ini [ESTIMATOR] ESTIMATOR_PROFILE = STANDARD_DUAL_ANTENNA_HEADING GROUPS = PRIMARY ALT1 DYNAMICS_MODEL = NEARLY_CONSTANT_VELOCITY BASELINE_VECTOR_B = 0 -0.622 0 ``` :::note Heading is defined from 0 to 360 degrees clockwise from North. `BASELINE_LENGTH_CONSTRAINT`/`BASELINE_VECTOR_B` describe the vector from PRIMARY to ALT1. ::: ### IMU-Aided Dual-Antenna Pose For a full fused pose (heading plus IMU-propagated orientation and velocity), set `ESTIMATOR_PROFILE = STANDARD_IMU_DUAL_ANTENNA_HEADING`. This requires the full `BASELINE_VECTOR_B` (not just the scalar length) and an `[IMU]` block: ```ini [ESTIMATOR] ESTIMATOR_PROFILE = STANDARD_IMU_DUAL_ANTENNA_HEADING GROUPS = PRIMARY ALT1 DYNAMICS_MODEL = NEARLY_CONSTANT_VELOCITY BASELINE_VECTOR_B = 0 -0.622 0 [IMU] IMU_TYPE = BMI088 POS_IMU_B = 0 0.311 0 ORIENTATION_IMU_B = 0 0 0 1 ``` `BASELINE_LENGTH_CONSTRAINT` is not sufficient for this mode, since fused pose requires full antenna geometry. PpRx warns and ignores it if both are present. ### Body-Frame Convention Dual-antenna and IMU-aided pose configuration and output use a right-handed forward-left-up body frame centered at the phase center of the PRIMARY antenna: - positive X points forward; - positive Y points left (port); and - positive Z points up. [`BASELINE_VECTOR_B`](#baseline_vector_b) is the directed vector from PRIMARY to ALT1, expressed in this frame in meters. For example, with PRIMARY on the left wing and ALT1 on the right wing, separated by 0.622 meters: ```ini BASELINE_VECTOR_B = 0 -0.622 0 ``` `POS_IMU_B`, [`POS_V0_B`](#pos_v0_b), and other body-frame position vectors use the same axis convention. `ORIENTATION_IMU_B = 0 0 0 1` is appropriate only when the IMU's positive X, Y, and Z axes physically point forward, left, and up, respectively. Fused-navigation body velocities are displayed as forward, left, and up components. Displayed yaw uses the navigation convention: zero degrees is North and angles increase clockwise toward East. Displayed pitch uses the aircraft convention, with nose-up positive. The ESTIMATOR block can be configured with the following parameters.
Initialization & startup robustness These parameters control when the estimator is allowed to form its first navigation solution and how strict it is during startup. ### MIN_UNIQUE_TXS_FOR_UNINITIALIZED_SOLUTION **Default:** 4 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Minimum number of distinct transmitters required before the estimator attempts to form an initial solution without a valid prior state. This protects initialization from relying on too few satellites, even if multiple measurements are available from the same transmitter. \ **Practical Tuning Info:** Leave at 4 for most cases. Raising this value requires more satellite diversity before startup and can improve robustness at the cost of longer time-to-first-fix. Note that [`MIN_MEASUREMENTS_FOR_UNINITIALIZED_SOLUTION`](#min_measurements_for_uninitialized_solution) may gate estimator startup even if this value is low. ### MIN_MEASUREMENTS_FOR_UNINITIALIZED_SOLUTION **Default:** 5 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Minimum number of usable measurement rows required before the estimator attempts to form an initial solution without a valid prior state. This protects initialization from using a barely constrained measurement set, even when enough distinct transmitters are available. \ **Practical Tuning Info:** Leave at 5 for most cases. A value of 5 rather than 4 allows consistency checking in addition to solving a unique solution. Raising this value requires more total observables before startup and can improve robustness at the cost of longer time-to-first-fix. ### INITIALIZATION_TEST_PF **Default:** 1e-5 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Target false-alarm probability for rejecting a good set of measurements while forming an initial estimator solution. The estimator compares the startup pseudorange/Doppler residuals against their expected uncertainty and only accepts the initial solution if the measurement set is statistically self-consistent. \ **Practical Tuning Info:** Leave at the default for most cases. Higher values make initialization stricter and can delay the first solution by rejecting usable startup measurement sets; lower values make initialization more permissive but increase the risk of accepting a biased or low-quality initial solution. ### INITIALIZATION_TEST_THRESHOLD_FACTOR **Default:** 0 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Maximum allowed initialization NIS ratio when forming an initial estimator solution. If set, this fixed threshold is used instead of [`INITIALIZATION_TEST_PF`](#initialization_test_pf); the estimator rejects the initialization attempt if the NIS, used as a measure of statistical self-consistency, exceeds this value. \ **Practical Tuning Info:** Leave unset in most cases. If set, values around 1.5–3 are reasonable starting points, with lower values making startup stricter and higher values making startup more permissive. This value overrides [`INITIALIZATION_TEST_PF`](#initialization_test_pf).
GNSS measurement noise These parameters define the estimator's default assumptions about pseudorange and Doppler measurement quality. ### ZENITH_PSEUDORANGE_STD **Default:** 3 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Assumed pseudorange measurement standard deviation, in meters, for a satellite directly overhead, before elevation weighting, atmospheric uncertainty, and SISRE effects are applied. Larger values reduce pseudorange influence in the estimator; smaller values make pseudorange measurements more trusted. \ **Practical Tuning Info:** The default should be a safe value for most applications, but additional performance may be possible by reducing this value down to the 1 meter range. Setting this value lower will increase the estimator's trust in measurements, making it more responsive to dynamics but also potentially increasing noise in position and velocity estimates. ### ZENITH_DOPPLER_STD **Default:** 1 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Assumed Doppler measurement standard deviation, in Hz, for a satellite directly overhead, before elevation weighting, atmospheric uncertainty, and SISRE effects are applied. Larger values reduce Doppler influence on the estimator solution. \ **Practical Tuning Info:** The default should be a safe value for most applications, but additional performance may be possible by reducing this value down to the 0.3 Hz range. Setting this value lower will increase the estimator's trust in measurements, making it more responsive to dynamics but also potentially increasing noise in position and velocity estimates.
Measurement acceptance & consistency checks These parameters control whether candidate measurements are allowed to participate in an estimator update. ### ENFORCE_STRICT_SELECTION **Default:** True \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** When enabled, allows only signals with a healthy phase lock to participate in the estimation solution. \ **Practical Tuning Info:** If navigation solution precision is desired, set to `True`. If operating in a challenging RF environment, set to `False`. ### INNOVATIONS_TEST_PF **Default:** 1e-3 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Target false-alarm probability for excluding a good set of measurements during an estimator update. The estimator compares the measured pseudorange/Doppler residuals against their expected uncertainty and attempts not to use suspect measurements when updating the navigation solution. \ **Practical Tuning Info:** Leave at the default for most cases. Higher values make the test stricter and can cause good measurements to be excluded during normal noise variation; lower values make excluding good measurements less likely but can allow low-quality measurements to more easily remain in the solution. ### INNOVATIONS_TEST_THRESHOLD_FACTOR **Default:** 0 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Maximum allowed NIS ratio for a measurement set during an estimator update. If the NIS of a group of measurements (nominally 1.0) exceeds this value, the estimator treats the set as inconsistent and attempts not to use suspect measurements when updating the navigation solution. \ **Practical Tuning Info:** Leave unset in most cases. If set, values of 3–6 are reasonable. This value overrides [`INNOVATIONS_TEST_PF`](#innovations_test_pf), which is an alternate statistical method for setting the measurement exclusion threshold.
Elevation-based weighting & exclusion These parameters reduce or remove the influence of low-elevation measurements, which are more likely to be affected by multipath, blockage, or atmospheric modeling error. ### ELEVATION_MASK_ANGLE_DEG **Default:** ~14.3 degrees (0.25 radians) \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Minimum satellite elevation angle allowed into the estimator solution. Signals below this angle are excluded, reducing use of low-elevation measurements that are more likely to suffer multipath, blockage, or atmospheric modeling error. \ **Practical Tuning Info:** Typical values are 5–15 degrees, with higher values often working better in more occluded environments. Higher values produce cleaner but fewer measurements, while lower values increase satellite availability at the cost of admitting more potentially low-quality, low-elevation measurements. ### ELEVATION_DEPENDENT_WEIGHTING **Default:** True \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Enables elevation-based measurement uncertainty inflation. Low-elevation signals are assigned larger pseudorange and Doppler uncertainty, reducing their influence in the estimator. \ **Practical Tuning Info:** Leave enabled for most real RF environments because low-elevation signals are more likely to suffer multipath and atmospheric modeling error. ### ELEVATION_WEIGHTING_KNEE_DEG **Default:** ~9.7 degrees (0.17 radians) \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Sets the elevation angle at which the elevation weighting "bends" significantly when using [`ELEVATION_DEPENDENT_WEIGHTING`](#elevation_dependent_weighting). At this elevation angle, the measurement standard deviation is inflated by about 4.7×, and increases toward the horizon. \ **Practical Tuning Info:** Leave near the default for most cases. Using higher values may slightly improve performance in occluded environments.
Satellite signal-in-space error These parameters control how satellite-side orbit and clock uncertainty contributes to the estimator's assumed measurement uncertainty. ### SISRE_DEFAULT_STD **Default:** 0.00 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Default Signal-in-Space Range Error (SISRE) standard deviation, in meters, used when the ephemeris record does not provide a SISRE value. This term is the expected 1-sigma pseudorange error from satellite-side orbit/clock model inaccuracies, and contributes to assumed pseudorange measurement uncertainty. \ **Practical Tuning Info:** Only relevant for unusual cases where SISRE information is not available from satellite transmissions. If needed, 0.5 meters would likely be a good conservative setting. ### SISRE_STD_INFLATION_FACTOR **Default:** 1.0 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Global multiplier applied to SISRE standard deviation before it is included in the pseudorange measurement variance assumption. Increasing this value reduces the estimator's confidence in pseudorange values. \ **Practical Tuning Info:** Leave at 1.0 for almost all cases. Tune only if ephemeris quality estimates are known to be under- or over-confident.
Receiver motion model These parameters control how the estimator propagates receiver position, velocity, and related motion states between measurement updates. ### DYNAMICS_MODEL **Default:** NEARLY_CONSTANT_VELOCITY \ **Parameter Class:** Tunable \ **Impact of Change:** High **Options:** - `STATIC`   [recommended for static usage] - `NEARLY_CONSTANT_VELOCITY`   [recommended for typical dynamic usage] - `NEARLY_CONSTANT_ACCELERATION` - `LOW_EARTH_ORBIT` **Technical Info:** Selects the motion model used to propagate the receiver state between measurement updates. `STATIC` assumes fixed position, `NEARLY_CONSTANT_VELOCITY` assumes velocity changes slowly, `NEARLY_CONSTANT_ACCELERATION` assumes acceleration changes slowly, and `LOW_EARTH_ORBIT` uses an orbital propagation model. \ **Practical Tuning Info:** Use `STATIC` for stationary receivers and `NEARLY_CONSTANT_VELOCITY` for all moving ground/air platforms. `NEARLY_CONSTANT_ACCELERATION` and `LOW_EARTH_ORBIT` should be used for space-based applications. ### SQRT_Q_TILDE **Default:** 5 \ **Parameter Class:** Tunable \ **Impact of Change:** High \ **Technical Info:** Controls how much the estimator allows the receiver state to change between measurement updates beyond what the selected [`DYNAMICS_MODEL`](#dynamics_model) predicts. Higher values make the estimator more willing to follow new measurements; lower values make it trust the propagated motion model more strongly. \ **Practical Tuning Info:** For `NEARLY_CONSTANT_VELOCITY`, this value should be somewhat greater than the average expected vehicle acceleration, in m/s². Tuning higher will make the estimator more responsive to real motion, but can make the solution noisier. For all other [`DYNAMICS_MODEL`](#dynamics_model) settings, this value should often be much smaller, typically 0.001 to 0.1. Tune toward the higher end of the range when unmodeled acceleration, atmospheric variation, multipath, or other slowly changing bias sources are expected. ### MAX_OPEN_LOOP_PROP_SEC **Version Introduced:** v5.1.0 \ **Default:** -1 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Maximum amount of time, in seconds, the estimator is allowed to propagate the state forward open-loop, without any measurements. Values less than 0 disable this feature.\ **Practical Tuning Info:** Set a finite value when stale propagated solutions are undesirable; shorter values force faster reset/reinitialization after signal loss, while longer values tolerate brief outages but may result in incorrectly propagating state forward. Recommended ranges: -1 (disabled) or 10–20 seconds. ### ZERO_VELOCITY_UPDATE_THRESHOLD_MPS **Default:** 0.0 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Speed threshold, in m/s, below which the estimator treats the receiver as stationary and sets estimated velocity to zero. When active, near-zero velocity updates are prevented from propagating the position forward during estimator prediction. \ **Practical Tuning Info:** Leave at 0 to disable. For receivers where stationary periods are expected, values around 0.03–0.15 m/s can reduce slow position drift caused by noisy velocity estimates. Tune higher to more aggressively enforce stationary position during stops, but avoid values near expected real motion speeds to avoid suppression of slow movement. ### INIT_ACCELERATION_STD **Default:** 1000.0 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Initial acceleration uncertainty, in m/s², used for `NEARLY_CONSTANT_ACCELERATION` and `LOW_EARTH_ORBIT` dynamics models. \ **Practical Tuning Info:** Only relevant for space-based `NEARLY_CONSTANT_ACCELERATION` and `LOW_EARTH_ORBIT` dynamics models. Leave at the default for almost all cases.
Clock & receiver time behavior These parameters control how the estimator models receiver clock behavior and manages receiver-time bookkeeping. Except for ensuring that the `CLOCK_TYPE` is correct for the receiver, these parameters should normally be set to defaults. ### CLOCK_TYPE **Default:** TCXO_LOW_QUALITY \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Options:** - `TCXO_LOW_QUALITY` - `TCXO`   [recommended for ] - `OCXO_LOW_QUALITY` - `OCXO` **Technical Info:** Selects the receiver clock stability model used to propagate receiver clock bias and clock drift uncertainty between estimator updates. Lower-quality clock models allow the estimated clock state to wander more freely, while higher-quality models constrain clock evolution more tightly. \ **Practical Tuning Info:** `TCXO` should be used for . For other front-ends, match this to the receiver oscillator's short-term stability: roughly `TCXO_LOW_QUALITY` for clocks with Allan deviation near `5e-10` at 1 second, `TCXO` near `1e-10`, `OCXO_LOW_QUALITY` near `2e-11`, and `OCXO` near `5e-12`. Use a more conservative/lower-quality model if the oscillator is poorly characterized. ### ALLOW_DELTR_FIXUPS **Default:** True \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Enables estimator-controlled receiver-time fixups that keep receiver time within [`MAX_ABS_DELTR_SEC`](#max_abs_deltr_sec) of true GNSS time. This is only a bookkeeping mechanism and does not affect time measurement quality; it only prevents large receiver time-bias values from accumulating over time. \ **Practical Tuning Info:** Leave enabled for normal operation. Disable for external timing workflows where receiver time discontinuities, even coordinated ones, are undesirable and clock bias is allowed to grow in the estimator state. ### MAX_ABS_DELTR_SEC **Default:** 0.032 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Maximum absolute receiver clock bias allowed before the estimator performs a receiver-time fixup. When the estimated clock bias exceeds this threshold, receiver time, observables, and channel phase/timing state are adjusted together so the receiver clock remains close to true GNSS time. \ **Practical Tuning Info:** Leave at the default for almost all cases. Smaller values cause more frequent clock fixups; larger values reduce fixup frequency but allow receiver time to drift farther before correction. This value must be at least [`DELTR_FIXUP_RESOLUTION_SEC`](#deltr_fixup_resolution_sec). ### DELTR_FIXUP_RESOLUTION_SEC **Default:** 0.0001 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Time quantization used when applying receiver clock-bias fixups. Any fixup applied by the estimator is rounded to an integer multiple of this value before receiver time and channel observables are adjusted. \ **Practical Tuning Info:** Leave at the default for almost all cases. If changed, its value must be chosen such that for any carrier frequency used, multiplying that frequency by `DELTR_FIXUP_RESOLUTION_SEC` results in an integer value.
Atmospheric corrections These parameters control whether the estimator applies standard atmospheric delay corrections when modeling GNSS measurements. ### USE_IONO_CORR **Default:** True \ **Parameter Class:** Tunable \ **Impact of Change:** High \ **Technical Info:** Enables ionospheric-delay correction in the estimator measurement model. When enabled, predicted pseudorange and related modeled quantities include the receiver's available ionospheric correction; when disabled, ionospheric delay is left unmodeled. \ **Practical Tuning Info:** Leave enabled for nearly all use cases. Disable for simulations or cases where ionospheric correction sources are known to be inappropriate. ### USE_TROPO_CORR **Default:** True \ **Parameter Class:** Tunable \ **Impact of Change:** High \ **Technical Info:** Enables tropospheric delay correction in the estimator measurement model. \ **Practical Tuning Info:** Leave enabled for nearly all use cases. Disable for simulations known to lack tropospheric modeling or non-terrestrial applications.
Fixed-position operation These parameters configure operation when the receiver position should be constrained to a known, fixed location. ### CONSTRAIN_ECEF_POSITION **Default:** False \ **Parameter Class:** Tunable \ **Impact of Change:** High \ **Technical Info:** Constrains the receiver position estimate instead of estimating it as a free state. This is useful for fixed receivers with a surveyed or otherwise trusted position. \ **Practical Tuning Info:** Enable only for static receivers in a known position specified by [`KNOWN_ECEF_POSITION`](#known_ecef_position), with [`DYNAMICS_MODEL`](#dynamics_model) set to `STATIC`. This setting can be useful for improved time estimation or measurement quality observations. ### KNOWN_ECEF_POSITION **Default:** [0 0 0] \ **Parameter Class:** Tunable \ **Impact of Change:** High, when `CONSTRAIN_ECEF_POSITION = TRUE` \ **Technical Info:** ECEF receiver position, in meters, used as the fixed position when [`CONSTRAIN_ECEF_POSITION`](#constrain_ecef_position) is enabled. The coordinates should refer to the relevant antenna phase center. \ **Practical Tuning Info:** Set only when using a surveyed or otherwise trusted fixed receiver position.
Dual-antenna operation These parameters configure which antenna groups contribute observations to the estimator and how multiple antenna groups are modeled. ### GROUPS **Default:** PRIMARY \ **Parameter Class:** Tunable \ **Impact of Change:** High \ **Technical Info:** Specifies which antennas are allowed to contribute observations to the estimator. \ **Practical Tuning Info:** Leave as `PRIMARY` for normal single-input/single-antenna operation. Add `ALT1` if an alternate antenna is connected and its signals have been registered in the `[BANK]` block. ### ASSUME_COINCIDENT_GROUPS **Default:** False \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Controls whether signal groups are estimated as separate receiver positions or as one common receiver state. \ **Practical Tuning Info:** Only relevant in dual-antenna setups. Set true to treat all antennas specified in [`GROUPS`](#groups) as coincident and estimate only a single, common position (and velocity, acceleration, etc.). The final position estimate is at the midpoint of the two antennas. Set false to estimate independent positions for each antenna. ### INTERCHANNEL_BIAS_STD **Default:** 0.0 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Controls whether two antenna sources are assumed to share one receiver clock or use separate clocks. A value of 0 uses a common receiver clock bias for both antennas, while positive values allow clock biases to drift relative to each other. \ **Practical Tuning Info:** Only applicable to multi-antenna operation. Leave at 0 for multi-antenna operation with . Use a small positive value only for front-ends in which multiple antennas do not share a common clock, approximately equal to the expected drift between the two clocks, in seconds of drift per second.
Baseline geometry (STANDARD_DUAL_ANTENNA_HEADING / STANDARD_IMU_DUAL_ANTENNA_HEADING) These parameters describe the physical antenna baseline and only apply to `ESTIMATOR_PROFILE = STANDARD_DUAL_ANTENNA_HEADING` or `STANDARD_IMU_DUAL_ANTENNA_HEADING`. `BASELINE_VECTOR_B` is strongly preferred over `BASELINE_LENGTH_CONSTRAINT`: it's required for IMU-aided pose, and it's what lets the GUI render antenna rotation correctly. ### BASELINE_VECTOR_B **Default:** None \ **Parameter Class:** Operational Configuration \ **Technical Info:** Directed vector from the PRIMARY to the ALT1 antenna phase center, in meters, expressed in the [forward-left-up body frame](#body-frame-convention). Required by `ESTIMATOR_PROFILE = STANDARD_IMU_DUAL_ANTENNA_HEADING`, and usable in place of `BASELINE_LENGTH_CONSTRAINT` for `STANDARD_DUAL_ANTENNA_HEADING`. \ **Practical Tuning Info:** Preferred over `BASELINE_LENGTH_CONSTRAINT` in almost all cases. Required for IMU-aided pose, since pose initialization needs full antenna geometry, not only baseline distance. For heading-only operation, providing `BASELINE_VECTOR_B` instead also lets the GUI render antenna rotation correctly. If both `BASELINE_LENGTH_CONSTRAINT` and `BASELINE_VECTOR_B` are set on a profile that only needs the scalar length, PpRx warns and ignores `BASELINE_LENGTH_CONSTRAINT`. ### BASELINE_LENGTH_CONSTRAINT **Default:** None \ **Parameter Class:** Operational Configuration \ **Technical Info:** Constrained antenna separation, in meters, between the PRIMARY and ALT1 antenna phase centers. Used by `ESTIMATOR_PROFILE = STANDARD_DUAL_ANTENNA_HEADING` for heading-only operation. \ **Practical Tuning Info:** Fallback for `STANDARD_DUAL_ANTENNA_HEADING` when the full body-frame vector genuinely isn't available. Exactly one of `BASELINE_LENGTH_CONSTRAINT` or [`BASELINE_VECTOR_B`](#baseline_vector_b) is required; prefer the vector where possible.
Dual-antenna heading (STANDARD_DUAL_ANTENNA_HEADING) These parameters tune the Attitude2D sigma-point filter used by `ESTIMATOR_PROFILE = STANDARD_DUAL_ANTENNA_HEADING` and `STANDARD_IMU_DUAL_ANTENNA_HEADING`. They are ignored, with a startup warning, when `ESTIMATOR_PROFILE = STANDARD`. Satellite/measurement selection, differential noise, and integer least-squares settings for this filter live in the [`[CDGNSS]`](/pprx/reference-definitions/pprx-configs/cdgnss) block, not here. ### ATTITUDE_2D_SPF_ALPHA **Default:** 1e-3 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Attitude2D sigma-point spread parameter. \ **Practical Tuning Info:** Leave at the default for almost all cases. ### ATTITUDE_2D_SPF_BETA **Default:** 2 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Attitude2D sigma-point distribution parameter. \ **Practical Tuning Info:** Leave at the default for almost all cases. ### ATTITUDE_2D_SPF_KAPPA **Default:** 0 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Attitude2D secondary sigma-point scaling parameter. \ **Practical Tuning Info:** Leave at the default for almost all cases. ### ATTITUDE_2D_SPF_NUM_THREADS **Default:** 1 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Number of worker threads used by the Attitude2D sigma-point filter. \ **Practical Tuning Info:** Leave at the default for almost all cases.
IMU-aided pose (STANDARD_IMU_DUAL_ANTENNA_HEADING) These parameters configure the loosely coupled IMU-aided pose estimator used by `ESTIMATOR_PROFILE = STANDARD_IMU_DUAL_ANTENNA_HEADING`. All are optional and retain their internal default when omitted, except [`BASELINE_VECTOR_B`](#baseline_vector_b), which is required. This mode also requires an [`[IMU]`](/pprx/reference-definitions/pprx-configs/imu) block. See the [body-frame convention](#body-frame-convention) below for axis and rotation conventions. ### CONSUME_EXTERNAL_CDGNSS_REPORTS **Default:** TRUE \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Continues ingesting Attitude2D/CDGNSS heading reports into the pose filter after initialization, rather than only during startup. \ **Practical Tuning Info:** Leave enabled for almost all cases. ### INCLUDE_STANDARD_NAVIGATION_SOLUTION_VELOCITY_MEASUREMENT **Default:** FALSE \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Includes the standard navigation solution's velocity as a measurement in the fused pose update. \ **Practical Tuning Info:** Leave at the default unless standard-navigation velocity is known to improve pose stability for a given platform. ### SIGMA_CONSTRAINED_BASELINE_ERROR_RAD **Default:** 0.1 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Angular uncertainty, in radians, assumed for the constrained-baseline measurement used by the pose filter. \ **Practical Tuning Info:** Leave at the default for most cases. Lower values increase the pose filter's trust in the constrained baseline. ### AZIMUTH_ONLY_FROM_CONSTRAINED_BASELINE **Default:** TRUE \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Uses only the constrained baseline's azimuth, rather than its full 2D orientation, in the fused pose measurement. \ **Practical Tuning Info:** Leave at the default for almost all cases. ### OUTPUT_EVENT **Default:** MEASUREMENT_UPDATE \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Options:** - `MEASUREMENT_UPDATE` - `TIME_UPDATE` **Technical Info:** Selects whether fused pose output is emitted on each measurement update or each time update. \ **Practical Tuning Info:** Leave at the default for most cases. ### INTEGRATOR_TYPE **Default:** EULER_METHOD \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Options:** - `EULER_METHOD` - `PIECEWISE_CONSTANT_AW_OMEGAB` **Technical Info:** Selects the integration method used to propagate IMU measurements between updates. \ **Practical Tuning Info:** Leave at the default for most cases. ### SIGMA_P_STANDARD **Default:** 1 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Standard-navigation position-sigma floor, in meters, used by the IMU-aided estimator. \ **Practical Tuning Info:** Values below 1 meter currently behave as 1 meter, since the internal estimator clamps this uncertainty floor to that minimum. ### PRECISE_POS_MEASUREMENT_SIGMA_INFLATION_FACTOR **Default:** 3 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Uncertainty inflation factor applied to precise position measurements used by the pose filter. \ **Practical Tuning Info:** Leave at the default for almost all cases. ### IMU_AIDED_SPF_ALPHA **Default:** 1e-3 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** IMU-aided sigma-point filter spread parameter. \ **Practical Tuning Info:** Leave at the default for almost all cases. ### IMU_AIDED_SPF_BETA **Default:** 2 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** IMU-aided sigma-point distribution parameter. \ **Practical Tuning Info:** Leave at the default for almost all cases. ### IMU_AIDED_SPF_KAPPA **Default:** 0 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** IMU-aided secondary sigma-point scaling parameter. \ **Practical Tuning Info:** Leave at the default for almost all cases. ### IMU_AIDED_SPF_INNOVATIONS_TEST_PF **Default:** 1e-6 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Target false-alarm probability for the IMU-aided estimator's innovations test, similar in purpose to [`INNOVATIONS_TEST_PF`](#innovations_test_pf) but independent of the standard navigation filter. \ **Practical Tuning Info:** Leave at the default for most cases. ### IMU_AIDED_SPF_PERFORM_INNOVATIONS_TESTING **Default:** TRUE \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Enables innovations testing on the IMU-aided estimator. \ **Practical Tuning Info:** Leave enabled for almost all cases. ### IMU_AIDED_SPF_NUM_THREADS **Default:** 1 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Number of worker threads used by the IMU-aided sigma-point filter. \ **Practical Tuning Info:** Leave at the default for almost all cases. ### APPLY_VEHICLE_VELOCITY_CONSTRAINTS **Default:** FALSE \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Enables near-zero lateral and vertical vehicle-velocity constraints in the pose filter. Requires [`ORIENTATION_B2V`](#orientation_b2v) and [`POS_V0_B`](#pos_v0_b). \ **Practical Tuning Info:** Enable for ground vehicles where lateral/vertical slip is expected to be near zero. Leave disabled for platforms where this assumption does not hold, such as aircraft or watercraft. ### ORIENTATION_B2V **Default:** None \ **Parameter Class:** Operational Configuration \ **Technical Info:** Body-to-vehicle quaternion. Required when [`APPLY_VEHICLE_VELOCITY_CONSTRAINTS`](#apply_vehicle_velocity_constraints) is enabled. \ **Practical Tuning Info:** Set only when using vehicle-velocity constraints. ### POS_V0_B **Default:** None \ **Parameter Class:** Operational Configuration \ **Technical Info:** Vehicle center of rotation, in body-frame coordinates. Required when [`APPLY_VEHICLE_VELOCITY_CONSTRAINTS`](#apply_vehicle_velocity_constraints) is enabled. \ **Practical Tuning Info:** Set only when using vehicle-velocity constraints. ### SIGMA_VEHICLE_VELOCITY_CONSTRAINT_MPS **Default:** 0.2 0.3 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Lateral and vertical vehicle-velocity constraint sigmas, in m/s. \ **Practical Tuning Info:** Leave at the default for most ground-vehicle cases. ### POLYNOMIAL_COEFFICIENTS_OMEGABZ_TO_V0VY **Default:** 0 0 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Polynomial coefficients modeling lateral velocity as a function of body yaw rate. \ **Practical Tuning Info:** Leave at the default unless vehicle-specific yaw/lateral-velocity coupling has been characterized. ### APPLY_ZERO_VELOCITY_CONSTRAINT **Default:** FALSE \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Enables IMU-triggered zero-velocity updates when the platform is detected as stationary. \ **Practical Tuning Info:** Enable for platforms with expected stationary periods to reduce pose drift during stops. ### SIGMA_ZERO_TRANSLATIONAL_VELOCITY_CONSTRAINT_MPS **Default:** 0.02 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Translational zero-velocity constraint sigma, in m/s. \ **Practical Tuning Info:** Leave at the default for most cases. ### SIGMA_ZERO_ROTATIONAL_VELOCITY_CONSTRAINT_RPS **Default:** 0.002 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Rotational zero-velocity constraint sigma, in rad/s. \ **Practical Tuning Info:** Leave at the default for most cases. ### ZERO_VELOCITY_UPDATE_DF_MAGNITUDE_THRESHOLD **Default:** 0.8 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Accelerometer-delta stationarity threshold used to detect zero-velocity conditions. \ **Practical Tuning Info:** Leave at the default for most cases. ### ZERO_VELOCITY_UPDATE_DOMEGATILDE_MAGNITUDE_THRESHOLD **Default:** 0.006 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Gyro-delta stationarity threshold used to detect zero-velocity conditions. \ **Practical Tuning Info:** Leave at the default for most cases. ### ZERO_VELOCITY_UPDATE_CONSECUTIVE_COUNT_THRESHOLD **Default:** 10 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Number of consecutive stationary IMU samples required before a zero-velocity update is applied. \ **Practical Tuning Info:** Leave at the default for most cases. Raise it to require more sustained stillness before zero-velocity updates engage.
--- ## FRONT_END import ProductName from '@site/src/components/ProductName'; Below is an *example* of the FRONT_END block: ```bash [FRONT_END] NUM_FRONT_ENDS = 2 FE01 = LION FE02 = LION_L5 [LION] SAMPLE_FREQ_NUMERATOR = 19999830 SAMPLE_FREQ_DENOMINATOR = 2 QUANTIZATION = 2 NUM_SUPPORTED_SIGNAL_TYPES = 8 SUPPORTED_SIGNAL_TYPES = GPS_L1_CA_PRIMARY GPS_L1_CA_ALT1 GPS_L2_CLM_PRIMARY GPS_L2_CLM_ALT1 SBAS_L1_I_PRIMARY SBAS_L1_I_ALT1 GALILEO_E1_BC_PRIMARY GALILEO_E1_BC_ALT1 FREQ_IF_HZ = 2563362.833776 2593365.172749 2560408.601713 2590410.940685 2563362.833776 2593365.172749 2563362.833776 2593365.172749 PLL_SIGN_FPLL = 1 1 1 1 1 1 1 1 CODE_PHASE_BIAS_METERS = -2.5 -2.5 4.5 4.5 -2.5 -2.5 -2.5 -2.5 [LION_L5] SAMPLE_FREQ_NUMERATOR = 19999830 SAMPLE_FREQ_DENOMINATOR = 1 QUANTIZATION = 2 NUM_SUPPORTED_SIGNAL_TYPES = 2 SUPPORTED_SIGNAL_TYPES = GPS_L5_IQ_PRIMARY GPS_L5_IQ_ALT1 FREQ_IF_HZ = 5059956.645689 5089952.626886 PLL_SIGN_FPLL = 1 1 CODE_PHASE_BIAS_METERS = -50 -50 ``` :::note When using a front end, there are three blocks: `[FRONT_END]`, `[LION]`, and `[LION_L5]`. The `[FRONT_END]` block holds the topology parameters, while the `[LION]` and `[LION_L5]` blocks hold the sampling and per-signal calibration parameters. ::: The FRONT_END block contains all of the following configuration parameters:
Topology ### NUM_FRONT_ENDS **Default:** None \ **Parameter Class:** Structural Configuration \ **Technical Info:** Number of front-end configurations defined in the `[FRONT_END]` block. Each front end describes a sample stream configuration, including sample rate, quantization, supported signal types, IF frequencies, and signal-specific biases. \ **Practical Tuning Info:** For , this value should be set to 2. In other cases, set to the number of distinct front-end / sample-stream configurations used by the receiver. ### FE01, FE02, … **Default:** None \ **Parameter Class:** Structural Configuration \ **Technical Info:** Ordered names of the front-end configuration sections to instantiate. Each `FE##` value must match a corresponding config block, such as `[LION]` or `[LION_L5]`. Signal banks reference these names in the `[BANK]` section of the `.config` file using their `FRONT_END` setting. \ **Practical Tuning Info:** For , which has `NUM_FRONT_ENDS = 2`, set as shown below: ```bash [FRONT_END] NUM_FRONT_ENDS = 2 FE01 = LION FE02 = LION_L5 ```
Sampling ### SAMPLE_FREQ_NUMERATOR **Default:** None \ **Parameter Class:** Structural Configuration \ **Technical Info:** Numerator of the front-end sample rate, in Hz, expressed together with [`SAMPLE_FREQ_DENOMINATOR`](#sample_freq_denominator) as `sample_rate = SAMPLE_FREQ_NUMERATOR / SAMPLE_FREQ_DENOMINATOR`. This is the nominal sample rate used throughout PpRx. \ **Practical Tuning Info:** Set to the nominal sample rate for the front end. Do not tune for performance; exact timing is computed in the estimator. :::note This value must be an integer. ::: ### SAMPLE_FREQ_DENOMINATOR **Default:** None \ **Parameter Class:** Structural Configuration \ **Technical Info:** Denominator of the front-end sample rate, in Hz, expressed together with [`SAMPLE_FREQ_NUMERATOR`](#sample_freq_numerator) as `sample_rate = SAMPLE_FREQ_NUMERATOR / SAMPLE_FREQ_DENOMINATOR`. This is the nominal sample rate used throughout PpRx. \ **Practical Tuning Info:** Set based on the nominal sample rate for the front end. Do not tune for performance; exact timing is computed in the estimator. :::note This value must be an integer. ::: ### QUANTIZATION **Default:** None \ **Parameter Class:** Structural Configuration \ **Technical Info:** Number of bits per IQ or IF sample component used by the front-end sample stream. \ **Practical Tuning Info:** This value must be set to match the sample quantization of the front-end. For , use a value of 2.
Supported signals ### NUM_SUPPORTED_SIGNAL_TYPES **Default:** None \ **Parameter Class:** Operational Configuration \ **Technical Info:** Number of signal types listed in [`SUPPORTED_SIGNAL_TYPES`](#supported_signal_types) for this front end. \ **Practical Tuning Info:** Set to the exact number of signals this front-end configuration supports. :::note This value must match the length of all the following arrays: [`SUPPORTED_SIGNAL_TYPES`](#supported_signal_types), [`FREQ_IF_HZ`](#freq_if_hz), [`PLL_SIGN_FPLL`](#pll_sign_fpll), and [`CODE_PHASE_BIAS_METERS`](#code_phase_bias_meters). ::: ### SUPPORTED_SIGNAL_TYPES **Default:** None \ **Parameter Class:** Operational Configuration \ **Technical Info:** List of signal types supported by this front-end configuration. Each listed signal has corresponding entries in the front-end arrays [`FREQ_IF_HZ`](#freq_if_hz), [`PLL_SIGN_FPLL`](#pll_sign_fpll), and [`CODE_PHASE_BIAS_METERS`](#code_phase_bias_meters). \ **Practical Tuning Info:** Include all signals for which tracking is desired. Commonly used signal names are listed below, each of which should be followed by the suffix `_PRIMARY` or `_ALT1` to indicate which antenna is desired for tracking (e.g. `GPS_L1_CA` should be included in `SUPPORTED_SIGNAL_TYPES` as `GPS_L1_CA_PRIMARY` or `GPS_L1_CA_ALT1`): ```text GPS_L1_CA GALILEO_E1_BC BDS_B1_CPD SBAS_L1_I GPS_L2_CLM GPS_L5_IQ GALILEO_E5A_IQ BDS_B2A_PD ```
Per-signal calibration ### FREQ_IF_HZ **Default:** None \ **Parameter Class:** Structural Configuration \ **Technical Info:** Intermediate frequency, in Hz, of each supported signal in the sampled front-end data stream. \ **Practical Tuning Info:** Set this to match the nominal IF frequency of the signal in the front-end. This value should not be tuned. :::note For the , use the following settings: - All primary antenna signals at the L1 band center of 1575.42 MHz: `2563362.833776` - All alternate antenna signals at the L1 band center of 1575.42 MHz: `2593365.172749` - All primary antenna signals at the L2 band center of 1227.60 MHz: `2560408.601713` - All alternate antenna signals at the L2 band center of 1227.60 MHz: `2590410.940685` - All primary antenna signals at the L5 band center of 1176.45 MHz: `5059956.645689` - All alternate antenna signals at the L5 band center of 1176.45 MHz: `5089952.626886` ::: :::note This list must contain one value per entry in [`SUPPORTED_SIGNAL_TYPES`](#supported_signal_types), in the same order. ::: ### PLL_SIGN_FPLL **Default:** None \ **Parameter Class:** Structural Configuration \ **Technical Info:** Defines whether the front end mixes the incoming RF with a wave above or below the carrier (high-side vs. low-side mixing). \ **Practical Tuning Info:** This value is a front-end parameter and should not be tuned; `-1` indicates high-side mixing, and `1` indicates low-side mixing. For , this value should be set to `1` for all signals. :::note This list must contain one value per entry in [`SUPPORTED_SIGNAL_TYPES`](#supported_signal_types), in the same order. ::: ### CODE_PHASE_BIAS_METERS **Default:** None \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Per-signal correction, in meters, for fixed pseudorange offsets introduced by the front-end signal path. The estimator uses this value to align measurements from different signals to a common reference. \ **Practical Tuning Info:** This value is dependent on the differential path delay between signals in the front-end. :::note For , use the following settings: - All L1-band signals: `-2.5` - All L2-band signals: `4.5` - All L5-band signals: `-50` ::: :::note This list must contain one value per entry in [`SUPPORTED_SIGNAL_TYPES`](#supported_signal_types), in the same order. :::
--- ## IMU The `IMU` block describes the IMU used for IMU-aided pose. It only matters when [`ESTIMATOR_PROFILE`](/pprx/reference-definitions/pprx-configs/estimator#estimator-profiles) is set to `STANDARD_IMU_DUAL_ANTENNA_HEADING`. For any other profile, the `[IMU]` block is not used. The `[IMU]` block is required when using `ESTIMATOR_PROFILE = STANDARD_IMU_DUAL_ANTENNA_HEADING`. If it is missing, PpRx treats this as a configuration error. Below is an *example* of the IMU block: ```ini [IMU] IMU_TYPE = BMI088 POS_IMU_B = 0 0.311 0 ORIENTATION_IMU_B = 0 0 0 1 ``` ### IMU_TYPE **Default:** None \ **Parameter Class:** Operational Configuration \ **Technical Info:** Selects the IMU hardware model providing accelerometer and gyroscope data to the pose filter. \ **Practical Tuning Info:** Set to match the IMU hardware in use. ### POS_IMU_B **Default:** None \ **Parameter Class:** Operational Configuration \ **Technical Info:** Position of the IMU, in meters, expressed in the [forward-left-up body frame](/pprx/reference-definitions/pprx-configs/estimator#body-frame-convention) centered at the PRIMARY antenna. \ **Practical Tuning Info:** Measure the physical offset from the PRIMARY antenna phase center to the IMU and set accordingly. ### ORIENTATION_IMU_B **Default:** None \ **Parameter Class:** Operational Configuration \ **Technical Info:** Quaternion describing the IMU's orientation relative to the body frame. \ **Practical Tuning Info:** `ORIENTATION_IMU_B = 0 0 0 1` (identity) is only correct when the IMU's physical X, Y, and Z axes point forward, left, and up, respectively. If the IMU is mounted in a different orientation, set the quaternion to reflect the actual mounting rotation. --- ## PpRx Configuration (.config) Parameters import Link from '@docusaurus/Link'; # PpRx Configuration (.config) Parameters The **Configuration (`.config`) file** controls receiver behavior. It defines signal processing settings such as acquisition, tracking, estimation, signal selection, and other parameters that determine how PpRx processes incoming RF data. PpRx configuration files are organized into blocks. The start of each block is indicated by a block header such as `[ESTIMATOR]`. A PpRx `.opt` file (for example `pprx.opt`) typically points to a corresponding `.config` file (for example `pprx.config`). :::tip Use the Configuration Generator to create a first-pass configuration, then tune individual parameters as needed. ::: Click into a block below to see its parameters. Large blocks (BANK, ESTIMATOR, FRONT_END) are organized by DSP-chain function so you can open just the section you care about. ## Parameter Classification The **Parameter Class** field indicates the purpose of a parameter and whether users are expected to modify it. | Class | Description | |---------|-------------| | **Structural Configuration** | Defines the internal structure and consistency of the receiver configuration. These parameters should rarely be modified and incorrect values may result in an invalid configuration or prevent the receiver from operating correctly. | | **Operational Configuration** | Defines how the receiver is configured and used, including enabled signals, antennas, front ends, and operating modes. Users are expected to configure these parameters to match their application and deployment. | | **Display Configuration** | Controls how diagnostic, logging, monitoring, and visualization data are presented to the user. These parameters do not affect receiver operation, signal processing, or performance. | | **Tunable** | Intended for performance optimization and adaptation to specific operating conditions. These parameters may be adjusted to modify receiver behavior, acquisition performance, tracking performance, or estimator performance. | ### Impact of Change The **Impact of Change** field is provided only for **Tunable** parameters and describes how strongly modifying the parameter affects receiver behavior and performance. | Impact Level | Description | |--------------|-------------| | **High** | Has a significant effect on receiver operation, performance, or stability. Incorrect values can substantially degrade performance or prevent proper operation. | | **Medium** | Has a noticeable effect on receiver performance under certain conditions. Useful for adapting the receiver to specific environments or use cases. | | **Low** | Has a minor effect on receiver behavior and is typically used for fine-tuning or specialized adjustments. | BASETIME Base-time and GPS rollover settings. FRONT_END Hardware front-end configuration. BUFFER_LOADER Data source configuration. BANK Signal bank, acquisition, and tracking configuration. ESTIMATOR Navigation estimator configuration. CDGNSS Attitude2D/carrier-phase tuning. Heading profiles only. IMU IMU description for pose estimation. Heading profiles only. IONO_ESTIMATOR Ionospheric estimator settings. NEUTRAL_DELAY_MODEL Tropospheric delay configuration. DISPLAY Display, diagnostics, and redraw settings. SPECTRUM_MONITOR RF spectrum monitoring and interference detection. EPHEMERIS SBAS differential corrections and ephemeris export. --- ## IONO_ESTIMATOR Below is an *example* of the IONO_ESTIMATOR block: ```bash [IONO_ESTIMATOR] UNCORRECTED_IONO_DELAY_MEAN = 7.25 UNCORRECTED_IONO_DELAY_STD = 2.5 KLOBUCHAR_ZENITH_IONO_DELAY_STD = 3.9 NTCMG_ZENITH_IONO_DELAY_STD = 1.8 IONO_DELAY_STD_INFLATION_FACTOR = 1.0 ``` ### UNCORRECTED_IONO_DELAY_MEAN **Default:** 7.25 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Fallback ionospheric delay correction, in meters-equivalent delay at the L1 frequency. Used only when ionosphere correction is enabled but no SBAS, NTCM-G, or Klobuchar data is available. \ **Practical Tuning Info:** Leave at the default in almost all cases. ### UNCORRECTED_IONO_DELAY_STD **Default:** 2.5 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Assumed standard deviation, in meters-equivalent delay at the L1 frequency, of the fallback ionospheric delay estimate when no ionosphere model is available. This uncertainty is added to the measurement model so pseudorange measurements are weighted less strongly when ionospheric error is not well known. \ **Practical Tuning Info:** Leave at the default in almost all cases. ### KLOBUCHAR_ZENITH_IONO_DELAY_STD **Default:** 3.9 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Assumed zenith-delay uncertainty, in L1-equivalent meters, used when the Klobuchar ionosphere model is available. PpRx computes the ionospheric delay from the broadcast Klobuchar parameters, then uses this value to estimate how much residual error may remain after correction. \ **Practical Tuning Info:** Leave at the default for typical broadcast Klobuchar correction. Increase this value when the Klobuchar model is expected to be less reliable, such as during high ionospheric activity. ### NTCMG_ZENITH_IONO_DELAY_STD **Default:** 1.8 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Assumed zenith-delay uncertainty, in L1-equivalent meters, used when the NTCM-G/NeQuick ionosphere model is available. PpRx computes the ionospheric delay from the broadcast NTCM-G/NeQuick parameters, then uses this value to estimate how much residual error may remain after correction. \ **Practical Tuning Info:** Leave at the default for typical broadcast NTCM-G correction. Increase this value when the NTCM-G model is expected to be less reliable, such as during high ionospheric activity. ### IONO_DELAY_STD_INFLATION_FACTOR **Default:** 1.0 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Global multiplier applied to the ionospheric delay uncertainty from any ionosphere path, including uncorrected fallback, Klobuchar, NTCM-G/NeQuick, and SBAS. Higher values make the estimator treat pseudorange measurements as less certain due to ionospheric activity. \ **Practical Tuning Info:** Leave at 1.0 for most cases. This value can be increased (e.g. up to 2) for periods of high ionospheric activity. :::note When multiple ionosphere models are available, PpRx uses the first model that can provide a correction in the following order: SBAS, NTCM-G/NeQuick, Klobuchar, then the uncorrected fallback values. ::: --- ## NEUTRAL_DELAY_MODEL Below is an *example* of the NEUTRAL_DELAY_MODEL block: ```bash [NEUTRAL_DELAY_MODEL] HYDRO_ZENITH_NEUTRAL_DELAY_STD = 0.002 WET_ZENITH_NEUTRAL_DELAY_STD = 0.01 UNCORRECTED_TROPO_DELAY_STD = 10.0 UNCORRECTED_TROPO_DELAY_MEAN = 0 SURFACE_PRESSURE_PA = 99797 SURFACE_TEMPERATURE_K = 298 RELATIVE_HUMIDITY_PCT = 58 ``` ### UNCORRECTED_TROPO_DELAY_MEAN **Default:** 0.0 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Fallback tropospheric delay correction, in meters, used when troposphere correction is enabled but the neutral delay model has not yet been initialized. This mainly occurs briefly at startup before the receiver has a valid position estimate. \ **Practical Tuning Info:** Leave at the default for almost all cases. This is mainly a bootstrap fallback; once PpRx has a valid navigation solution, the full neutral delay model is used instead. ### UNCORRECTED_TROPO_DELAY_STD **Default:** 10.0 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Assumed standard deviation, in meters, of the fallback tropospheric delay estimate used before the neutral delay model is initialized. \ **Practical Tuning Info:** Leave at the default for almost all cases. This parameter does not affect the receiver once position is known. ### HYDRO_ZENITH_NEUTRAL_DELAY_STD **Default:** 0.002 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Assumed standard deviation, in meters, of the hydrostatic zenith neutral delay. \ **Practical Tuning Info:** Leave at the default when [`SURFACE_PRESSURE_PA`](#surface_pressure_pa) is representative of local receiver pressure. Increase if surface pressure is unknown, or the receiver altitude/weather conditions may make the hydrostatic correction less reliable. If [`SURFACE_PRESSURE_PA`](#surface_pressure_pa) is left at the default across varying receiver altitudes, a value of 0.1 or larger may better represent hydrostatic uncertainty. ### WET_ZENITH_NEUTRAL_DELAY_STD **Default:** 0.010 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Assumed standard deviation, in meters, of the modeled wet zenith neutral-atmosphere delay caused by water vapor. \ **Practical Tuning Info:** Leave at the default for most cases. Increase this value when local humidity or temperature is unknown, rapidly changing, or poorly represented by the configured [`SURFACE_TEMPERATURE_K`](#surface_temperature_k) and [`RELATIVE_HUMIDITY_PCT`](#relative_humidity_pct) values. If [`SURFACE_TEMPERATURE_K`](#surface_temperature_k) and [`RELATIVE_HUMIDITY_PCT`](#relative_humidity_pct) are left at their defaults, a value of 0.1 would be more accurate. ### SURFACE_PRESSURE_PA **Default:** 101325 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Surface pressure, in Pascals, used by the Saastamoinen neutral-atmosphere model to compute the hydrostatic, or dry-air, zenith delay. Higher pressure increases the modeled tropospheric delay. \ **Practical Tuning Info:** Leave at the default only for near-sea-level operation when local weather pressure data is available. For use cases not near sea level, ensure surface pressure is approximately correct for local use. ### SURFACE_TEMPERATURE_K **Default:** 294.26 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Surface temperature, in Kelvin, used with relative humidity to estimate water vapor pressure for the Saastamoinen wet-delay model. \ **Practical Tuning Info:** Leave at the default unless local temperature data is available. Note that temperature should be in Kelvin (`K = C + 273.15`). This value being far from its actual value influences vertical position error roughly at the decimeter scale and horizontal position error roughly at the centimeter scale. ### RELATIVE_HUMIDITY_PCT **Default:** 60 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Relative humidity, in percent, used with surface temperature to estimate water vapor pressure for the Saastamoinen wet-delay model. \ **Practical Tuning Info:** Leave at the default unless local humidity data is available. This value being far from its actual value influences vertical position error roughly at the decimeter scale and horizontal position error roughly at the centimeter scale. --- ## SPECTRUM_MONITOR import ProductName from '@site/src/components/ProductName'; The `SPECTRUM_MONITOR` block trains a model of clean/reference RF data on a given front-end and then compares live RF data to that reference to detect interference. When running with a `SPECTRUM_MONITOR` block, PpRx displays either `Spectrum Monitor: Nominal` or `INTERFERENCE DETECTED` in the terminal display, and sends spectrum messages to the GBX output stream. Below is an *example* of the SPECTRUM_MONITOR block: ```bash [SPECTRUM_MONITOR] LOG2_NFFT = 8 AVERAGING_FACTOR = 400 NUM_PSD_SAMPLES = 4000 PFA = 1e-7 AGC_APPLIED = TRUE NYQUIST_RANGE_FOR_TESTING = 0.03 0.97 ``` ## Workflow ### Training a PSD model on nominal / clean data To train a model on clean/known spectrum for a given RF front-end, add options like the following to the `.opt` file for a run conducted in a clean environment: ```bash --spectrum-monitor 0.1 --export-psd-model example_psd_model.gbx ``` This generates a PSD every 0.1 seconds (the argument to `--spectrum-monitor`). These PSD estimates are collected until `NUM_PSD_SAMPLES` have been accumulated, which are then used to build the reference PSD. When the run completes or is stopped, the reference PSD is written to the specified file (e.g. `example_psd_model.gbx`), assuming at least `NUM_PSD_SAMPLES` PSDs were generated. The `.config` file for the run should include a `SPECTRUM_MONITOR` block like the example above. :::note Training a model to a low false-alarm rate can take many minutes. For the default number of frequency bins, using the fastest `--spectrum-monitor` interval of 0.1 s, training can take ~15 minutes of clean reference data. ::: ### Testing against a reference PSD model To test against a trained model, add options similar to the following to the `.opt` file: ```bash --spectrum-monitor 0.1 --import-psd-model example_psd_model.gbx --exp-interval 60 ``` This performs a spectrum health test every `--spectrum-monitor` seconds and generates periodic detailed PSD reports in the output GBX stream every `--exp-interval` seconds. For best results, use the same `SPECTRUM_MONITOR` block in both the training run and the testing run. --- ### LOG2_NFFT **Default:** 9 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Sets the frequency resolution of the PSD used for both training and testing. For front-ends with complex outputs, the number of bins is `2^LOG2_NFFT`. For real-only front-ends (such as ), the number of bins is `(2^LOG2_NFFT) / 2 + 1`, so the default value of 9 produces 257 bins. \ **Practical Tuning Info:** Larger values improve frequency resolution but are more computationally expensive and require a proportionally larger `NUM_PSD_SAMPLES` to achieve a low false-alarm rate. ### NUM_PSD_SAMPLES **Default:** 500 \ **Parameter Class:** Tunable \ **Impact of Change:** High \ **Technical Info:** Number of PSD estimates collected to train a nominal reference model. PSD estimates are produced at the rate given by `--spectrum-monitor` in the `.opt` file, so for `--spectrum-monitor 0.1` and the default `NUM_PSD_SAMPLES = 500`, a model is produced after 50 seconds of data. \ **Practical Tuning Info:** To avoid false alarms, `NUM_PSD_SAMPLES` should be at least 30× the number of frequency bins. For example, if `LOG2_NFFT = 8`, which produces 129 bins for a real-only front-end like , set `NUM_PSD_SAMPLES` to approximately 4000 to reduce false-alarm probability to near the `PFA` target. ### AVERAGING_FACTOR **Default:** 400 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Number of raw samples used to form each PSD estimate: approximately `2^LOG2_NFFT × AVERAGING_FACTOR` samples per stream. \ **Practical Tuning Info:** Keep at the default for most cases. Larger values produce smoother, lower-variance PSD estimates, but require more computation and use a longer snapshot of input data. ### PFA **Default:** 1e-7 \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Nominal probability-of-false-alarm target used to set the interference detection threshold for the PSD hypothesis test. Also used when finalizing a newly trained PSD model to reject training PSDs that look inconsistent with the nominal spectrum. \ **Practical Tuning Info:** Leave at the default for most cases. Lower values make interference detection less sensitive. Note that the actual false-alarm rate can be much higher than this setting if the PSD model is undertrained; ensure `NUM_PSD_SAMPLES` meets the recommended minimum. ### AGC_APPLIED **Default:** True \ **Parameter Class:** Tunable \ **Impact of Change:** Medium \ **Technical Info:** Indicates whether the front end applies automatic gain control, allowing the spectrum monitor to remove a uniform dB-level shift before training or testing the PSD model. This helps the detector focus on changes in spectral shape rather than overall gain changes. \ **Practical Tuning Info:** Set to `True` for . Otherwise, set according to whether AGC is enabled on the RF front-end. ### NYQUIST_RANGE_FOR_TESTING **Default:** 0.03 0.97 \ **Parameter Class:** Tunable \ **Impact of Change:** Low \ **Technical Info:** Selects the fraction of the Nyquist frequency range included in the interference hypothesis test. Bins outside this range are still part of the PSD estimate and model, but they do not contribute to the final detection statistic. \ **Practical Tuning Info:** Leave at the default for . Narrow this range to ignore band edges or other frequency regions that are known to be unstable. --- ## PpRx Options (.opt) Parameters import ProductName from '@site/src/components/ProductName'; # PpRx Option (.opt) Parameters Definitions The **Options (`.opt`) file** controls all PpRx inputs and outputs. It specifies where RF data comes from (live streams or recorded files) and where receiver outputs are sent, including logs, solution files, network interfaces, and external devices. All PpRx options can be listed by opening up a terminal and running: ```bash pprx --help ``` Additional context for the most commonly used options are below: - `-i /dev/radiolion0` and `--imu-file /dev/radiolion1` are used when the objective is to run PpRx live (PpRx can also process recorded data, see below) - /dev/radiolion0 is connected to the GNSS data stream (could be /dev/radiolion1 depending on PC used check with command `ls /dev/` and change in this .opt file) - /dev/radiolion1 is connected to the IMU data stream (could be /dev/radiolion2 depending on PC used check with command `ls /dev/` and change in this .opt file) - `-i absolute/path/to/a/recorded/gnss/file.bin` this line can be used when the objective is to run PpRx on a prerecorded file. - `-c ./lion_r2.config` corresponds to the (relative or absolute) path to the config file to be used - `-t -1`[sec] can be used while using PpRx to limit the time of data acquisition and processing if it is a live data acquisition, or to limit the time of analysis when it is used in post processing. “-1” is used to process the live data stream indefinitely, or the complete file. - `--skip 10000` [millisec] can be used when post-processing with PpRx to only start processing after a certain time through a data recording. - Initial acquisition search depth is set per-bank via [`INITIAL_ACQ_SEARCH_DEPTH`](/pprx/reference-definitions/pprx-configs/bank#initial_acq_search_depth) in the `.config` file, not via an `.opt` option. - `-T 8`[threads] sets the number of threads to be used for tracking. - `--bitpack lion`[bitpacking convention] sets the bitpacking convention used by the front end. This should always be set to `lion` when using the . - `--import-ephem example_eph.eph`[ephemeris file] allows a warm start by pre-loading satellite ephemeris data. - `--export-ephem example_eph.eph`[ephemeris file] exports the ephemeris data for the PpRx run, which can be used to allow a warm start later. By default, this .eph file will be produced at the end of a PpRx run, either after a file is finished processing or by using Ctrl+C in live processing mode (Note: sudo kill operations will prevent it from being generated when PpRx completes). - `--import-alm example_alm.alm`[almanac file] allows a warm start by pre-loading satellite almanac data. - `--export-alm example_alm.alm`[almanac file] exports the almanac data for the PpRx run, which can be used to allow a warm start later. By default, this .alm file will be produced at the end of a PpRx run, either after a file is finished processing or by using Ctrl+C in live processing mode (Note: sudo kill operations will prevent it from being generated when PpRx completes). - `--import-state0` [estimator state file] Import estimator state at RRT = 0 from specified file - `--exp-interval`[seconds] sets the interval between exports of data bit, ephemeris, almanac, and estimated PSD data. For ephemeris, for example, it will add to the `.eph` file specified in `--export-ephem` at the interval period given, if new ephemeris data is available. - `--log-interval 50`[root bank intervals] sets how frequently to log positioning solution data. An interval of “n” will log every “n” accumulation periods of the root bank. The accumulation period is a function of settings in the .config file. For the typical root bank of GPS_L1_CA_PRIMARY, an accumulation period is equal to 1 ms multiplied by its NUM_SUBACCUM_PER_ACCUM. For example, for NUM_SUBACCUM_PER_ACCUM = 20 and a log interval of 50, PpRx will log every 20 * 50 = 1,000 ms. - `--ref-interval 1`[log intervals] sets how frequently to display updates for the positioning solution data in the console relative to log intervals. - `--acq-interval 200`[root bank intervals] sets how frequently to conduct new signal acquisition, in units of root bank/accumulation intervals. Setting `(=0)` turns off new signal acquisition. Decreasing this value increases computational load. - `--verbose` allows a visualization of the acquired data, in a form of a table with the list of tracked satellites, pseudorange and doppler, etc - `-o pprx.gbx` this specifies where to stream the GBX output from PpRx. The argument needs to be either the full path of a .gbx file, or the path of a named pipe. - `--binary-only`, `-s mat` and `--log-raw-samples` are options to set desired output types: - `--binary-only` will only output to the .gbx file or named pipe specified - `-s mat` will output the .gbx as well as Matlab files to aid in data analysis. [See here](/advanced-tutorials/analyze-gbx#processing-binflate-log-and-mat-files) for .mat and .log file definitions. - `--log-raw-samples` will output .gbx, .mat, and will add .bin file outputs with all raw data from the RF front end. (Warning: the .bin files are heavy, ensure the device has sufficient disk space) [only for live data acquisition] - `--simulate-realtime` enables simulation of realtime operation when processing a data recording - `--rotate-acq` enables performing background acquisition on one signal type only at each acquisition interval (reduces CPU load) - `--debug` produces a diagnostics.log file with various debugging information - `--enable-binary-diagnostics` enable diagnostics output to binary output file - `--log-innovations` outputs pseudorange and doppler innovations for each signal to the diagnostics.log file (must have `--debug` enabled) - `--rel-acq-banks-thresh arg (=-1)` Time threshold [sec] after which acquisition starts on all banks. Overrides the requirement of a minimum number of acquired signals on the root bank pre-navsol before all banks are searched. Values < 0 disables this feature. - `--ignore-buffer-overruns` Disables the CBUFFSIZE assertion error, which occurs if a channel lags more than the buffer size during real-time operation.