Run PpRx from the CLI

Phase 4 of 6·Advanced tutorials

1. 1Data path
2. 2Install
3. 3Beginner tutorials
4. 4Advanced tutorials
5. 5Prototype
6. 6Production

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 via typical editor applications (vim, nano, and so on). 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).
pprx.mat / pprx.log	When -s mat or -s log is set	MATLAB or log-format output files. Suppressed by --binary-only.

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.

LogInterval 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.

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, reduce CPU load by:

• Decreasing --threads
• Increasing --acq-interval (less frequent background acquisition)
• Using --binary-only to suppress .mat/.log file writes
• Reducing MAXCHANNELS in the .config file