Subsystem

Substation configuration: bands

The 23 settings under bands, each with the type, default and limits its schema declares.

The bands to scan, keyed by band name. At least one band is required.

One band to scan.

A band sets a frequency range, the spacing of its radio channels, and how the scanner treats them. The scanner monitors every radio channel in the band at once.

freq_start in bands.<name>

Type
number
Required
yes
Limits
above 0

Start of the band's frequency range in Hz, for example 446.00625 MHz for PMR446.

freq_end in bands.<name>

Type
number
Required
yes
Limits
above 0

End of the band's frequency range in Hz, for example 446.19375 MHz for PMR446. Must be above freq_start.

channel_spacing in bands.<name>

Type
number
Required
yes
Limits
above 0

Spacing between radio channel centre frequencies, in Hz, for example 12.5 kHz. The scanner places radio channels from freq_start to freq_end at this spacing.

sample_rate in bands.<name>

Type
number
Required
yes
Limits
above 0

SDR sample rate in Hz. Must be high enough to cover the band's span plus one radio channel's width and margins, for example 2 MHz for PMR446.

channel_width in bands.<name>

Type
number or null
Default
null
Limits
above 0

Occupied bandwidth of each radio channel, in Hz. When null, the scanner uses 84% of channel_spacing, which leaves 16% as guard bands.

type in bands.<name>

Type
string or null
Default
null

Name of a template in band_defaults, such as DMR or TETRA, whose settings the band inherits.

modulation in bands.<name>

Type
string or null
Default
null

Modulation the scanner demodulates: NFM, AM, USB, or LSB, in any letter case. Recording needs one; without it, the scanner only detects activity in the band. USB and LSB are for HF voice: amateur convention is LSB below 10 MHz and USB above, and HFGCS, VOLMET, and marine HF use USB.

recording_enabled in bands.<name>

Type
boolean or null
Default
null

Whether the scanner records audio from active radio channels. When not set, a band records only if its reception_class is general and its modulation has a demodulator. Set it to true to record a band where your law allows it, or to false for detection only, with no audio files.

reception_class in bands.<name>

Type
string or null
Default
null
Limits
one of general, not_general, unsettled

How UK law treats listening to this band. general is what Ofcom calls general reception, which anyone may receive: licensed broadcasting, amateur and CB radio, and weather and navigation transmissions. not_general is a service outside general reception, such as PMR446, business radio, marine, military airband, and emergency services, which Ofcom says it is illegal to listen to. unsettled is for bands where the position is unclear, such as civil airband. A band that does not set recording_enabled records only when it is general. This describes UK law and is not legal advice: the law where you are decides what you may receive and record.

exclude_channel_indices in bands.<name>

Type
list of integer
Default
[]

Radio channel numbers the scanner skips, counting from 1, as shown in log output and filenames. Use it for known interference or out-of-band radio channels: [1, 2] skips the first two.

snr_threshold_db in bands.<name>

Type
number
Default
12

Signal-to-noise ratio in dB at which a radio channel turns on. Lower values, such as 8-10 dB, detect weaker signals and trigger more often on noise.

hysteresis_db in bands.<name>

Type
number
Default
3
Limits
at least 0

Margin in dB between the on and off thresholds. A radio channel turns on when its SNR rises above snr_threshold_db, and off when it falls below snr_threshold_db minus this margin, which stops it toggling while the SNR hovers near the threshold. Use a lower value, such as 1.5 dB, when scanning weak signals with a low snr_threshold_db.

sdr_gain_db in bands.<name>

Type
number or string or null
Default
auto

SDR gain in dB, or auto for automatic gain control. auto is convenient, but a manual gain, for example 20-40 dB on RTL-SDR, often works better.

sdr_gain_elements in bands.<name>

Type
map of names to number or null
Default
null
Example
{LNA: 10, MIX: 5, VGA: 12}

Gain in dB for each gain stage, on devices with several, keyed by stage name: the AirSpy R2, for example, has LNA, MIX, and VGA. Stage names depend on the device, and the scanner logs the available stages and their ranges at startup. When set, it takes priority over sdr_gain_db.

sdr_device_settings in bands.<name>

Type
map of names to string or null
Default
null
Example
{biastee: "true"}

Device-specific settings the scanner passes to the SDR through SoapySDR's writeSetting(), such as bias tee control, an external clock, or device calibration. Keys and values are device-specific strings. With --log-level DEBUG, the scanner logs the settings a device offers when it starts.

activation_variance_db in bands.<name>

Type
number or null
Default
3
Limits
at least 0

Power variance in dB, across a detection slice, that a radio channel must show to turn on. It suppresses triggers from stationary noise that crosses the SNR threshold with no real signal: voice and data vary by 5-15 dB or more over a slice, and stationary noise by under 2 dB. It applies whether or not the band records. Set to 0 to turn the check off.

device_overrides in bands.<name>

Type
map of names to sections or null
Default
null
Example
{airspy: {sample_rate: 2.5e+6, sdr_gain_elements: {LNA: 14, MIX: 5, VGA: 12}}}

Settings that replace this band's own on one family of SDR device, keyed by family: rtlsdr, hackrf, airspy, airspyhf, or a SoapySDR driver name. A key can use any --device-type spelling of its family, in any letter case. When the scanner runs with a matching --device-type, it merges those settings onto the band's. A key that names no family the scanner knows logs a warning, unless it is written as soapy: followed by a SoapySDR driver name.

Settings that replace a band's own when the scanner runs on one family of SDR device.

Every setting is optional. Only the settings given here replace the band's, and only when the device selected with --device-type is in that family.

sample_rate in bands.<name>.device_overrides.<name>

Type
number or null
Default
null
Limits
above 0

SDR sample rate in Hz on this device. Must cover the band's span.

sdr_gain_db in bands.<name>.device_overrides.<name>

Type
number or string or null
Default
null

SDR gain in dB on this device, or auto for automatic gain control.

sdr_gain_elements in bands.<name>.device_overrides.<name>

Type
map of names to number or null
Default
null
Example
{LNA: 10, MIX: 5, VGA: 12}

Gain in dB for each of this device's gain stages, keyed by stage name, for example LNA, MIX, and VGA.

sdr_device_settings in bands.<name>.device_overrides.<name>

Type
map of names to string or null
Default
null
Example
{biastee: "true"}

Device-specific settings on this device, such as bias tee control, as string keys and values. With --log-level DEBUG, the scanner logs the settings a device offers when it starts.

snr_threshold_db in bands.<name>.device_overrides.<name>

Type
number or null
Default
null

Signal-to-noise ratio in dB at which a radio channel counts as active on this device.

activation_variance_db in bands.<name>.device_overrides.<name>

Type
number or null
Default
null
Limits
at least 0

Power variance in dB that a radio channel must show to count as active on this device. Set to 0 to turn the check off.