Run PpRx from the CLI

Phase 4 of 6·Advanced tutorials

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:

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.

warning

Manual .opt and .config tuning is complex. As a starting point, use the GUI Configuration Generator 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:

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:

# 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

# Temporarily enable verbose display without editing the .opt file
pprx -f ./autogen_01.opt --verbose

tip

Adding the --verbose argument enables the 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 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. For real-time performance issues, see Troubleshooting Tips.