SPECTRUM_MONITOR
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:
[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:
--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.
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:
--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 RadioLion), 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 RadioLion, 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 RadioLion. 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 RadioLion. Narrow this range to ignore band edges or other frequency regions that are known to be unstable.