Power sweep logger (gophertrunk power)
gophertrunk power steps an SDR across a frequency range, averages an FFT
power spectrum at each step, and writes the result as CSV in rtl_power’s
layout. Tools built for rtl_power, such as heatmap.py and flatten.py,
read it unchanged.
Unlike rtl_power, it can sweep a dongle on another machine through an
rtl_tcp server, as well as a local USB SDR. That includes an rtl_tcp driver
app on an Android phone (Termux guide).
Quick start
# FM broadcast band in 10 kHz bins, one sweep every 10 s, until Ctrl-C
gophertrunk power -f 88M:108M:10k -out fm.csv
# The same from a remote dongle behind rtl_tcp
gophertrunk power -rtltcp 192.168.1.50:1234 -f 88M:108M:10k -out fm.csv
# From an ADALM-Pluto / PlutoSky over its own iiod (no SoapySDR or libiio)
gophertrunk power -iio 192.168.2.1 -f 88M:108M:10k -gain 400 -out fm.csv
# One sweep of the 2 m band to the terminal, integrating for 1 s
gophertrunk power -f 144M:148M:5k -i 1 -1
# Log 446 MHz PMR for an hour, a sweep every 30 s
gophertrunk power -f 446.0M:446.2M:1k -i 30s -e 1h -out pmr.csv
Output
One CSV line per tuning step (a “hop”), with the same fields as rtl_power:
date, time, Hz low, Hz high, Hz step, samples, dB, dB, ...
2026-10-03, 21:30:05, 88000000, 89800000, 9375.00, 4000000, -61.20, -60.95, ...
- date, time: local time when the sweep started. Every hop of one sweep carries the same stamp.
- Hz low: the frequency of the line’s first value. Value k is at
Hz low + k × Hz step. - Hz high:
Hz low + (number of values) × Hz step. - Hz step: the bin width. It is the requested bin size rounded down to
sample rate / FFT size, where the FFT size is a power of two. - samples: IQ samples averaged for this hop. A CPU that keeps up
averages about
(interval ÷ hops − settle) × rate: the samples real time delivers after the retune settle (50 ms on a local dongle, 250 ms over rtl_tcp). On a CPU too slow to FFT every sample (see below) it is lower. - dB: averaged power per bin in uncalibrated dBFS. A carrier’s power reads 1.8–3.2 dB low here (Hann window), so compare levels with each other, not against an absolute reference.
Hops abut exactly, so concatenating a sweep’s lines gives one continuous spectrum from the lower edge to the upper edge. A signal that sits right on a hop boundary is therefore split: half of it ends one line and the rest opens the next.
Why “10k” gives 192 values of 9375 Hz
As with rtl_power, the bin size in -f is a maximum. For
-f 88M:108M:10k at the default 2.4 MS/s:
- Bin width. The FFT is the smallest power of two whose bins are no wider than 10 kHz. 2,400,000 ÷ 128 = 18,750 Hz is too wide, and 2,400,000 ÷ 256 = 9375 Hz fits, so the FFT has 256 points.
- Bins per line.
-crop 0.25drops a quarter of the FFT (an eighth at each edge, where the tuner’s filter rolls off), leaving 256 × 0.75 = 192 bins, or 192 × 9375 Hz = 1.8 MHz per hop. - Hops. 20 MHz is 2134 bins of 9375 Hz, which takes 12 hops, so a sweep is 12 lines. The first 11 have 192 values each and the last has the remaining 22, ending at 108 MHz.
power prints this breakdown on stderr whenever the bins come out narrower
than you asked for. For exactly 10 kHz bins, pick a rate that divides into
them, for example -rate 2560000 (2,560,000 ÷ 256 = 10,000 Hz), provided
your dongle runs that rate without dropping samples.
Flags
| Flag | Default | Meaning |
|---|---|---|
-f lower:upper:bin |
(required) | Range and bin size, with k / M / G suffixes. |
-i |
10s |
Integration interval. One sweep starts every interval, and each hop integrates interval ÷ hops of it, less the retune settle. A bare number is seconds. |
-e |
(none) | Stop after this long. It is checked between sweeps, so a sweep is never cut short: -i 30 -e 5m gives exactly 10 complete sweeps. Without it, sweeps run until Ctrl-C. |
-1 |
off | Run one sweep, then exit. |
-out |
stdout | CSV path. A trailing positional file name also works, as with rtl_power. |
-rtltcp host:port |
(none) | Sweep the dongle behind an rtl_tcp server instead of a local SDR. |
-iio addr |
(none) | Sweep an ADALM-Pluto / PlutoSky through the iiod on the board (192.168.2.1 on the USB link, or its LAN address) instead of a local SDR. The one-shot tools read no config file, so an sdr.iio entry in config.yaml does not apply here; name the board on the command line. |
-serial |
(none) | Pick a local SDR when several are attached. |
-gain |
auto |
auto, or tenths of a dB as everywhere in GopherTrunk: 280 is 28 dB, and 28.0 also reads as 28 dB. |
-ppm |
0 |
Frequency correction. |
-rate |
2400000 |
Sample rate. Each hop covers rate × (1 − crop) Hz. |
-crop |
0.25 |
Fraction of each FFT dropped at the edges, where the tuner’s filter rolls off. |
-settle |
50 ms local, 250 ms rtl_tcp / iio | Samples discarded after each retune. |
-keep-dc |
off | Leave the tuner’s DC spike at the centre of every hop in the output (see below). |
-fill-dc |
off | When part of that spike is still at a hop’s centre after the removal, fill those three bins in from the bins beside them, as rtl_power does. It also hides a narrowband signal that sits exactly on a hop’s centre (see below). |
-dc-report |
off | Print, on stderr, what each hop measured of the tuner’s DC spike. |
-bias-tee |
off | Power an LNA through the antenna port. |
Each sweep’s lines are flushed as soon as the sweep finishes, so you can
tail -f a long log, and Ctrl-C loses at most the sweep in progress.
Things to know
powerreads no config file. Name a network radio on the command line (-iio,-rtltcp). Ifpowerfinds no local SDR and the config file the daemon would load lists network radios, the error names the flag for each, for examplesdr.iio lists a Pluto / PlutoSky at 192.168.1.179: run gophertrunk power -iio 192.168.1.179 ....capturedoes the same.- Only one program can use the dongle. Stop the daemon, or any other rtl_tcp client, before sweeping the same SDR.
- An rtl_tcp server serves one client at a time. If
power(orwmbus/capture -rtltcp) reports that the server accepted the connection but sent no header, another client or an earlier run still holds it, or the server has lost its dongle. If it reports that the server closed the connection, the server ended the session, for example because a phone’s rtl_tcp driver app lost the dongle or was stopped. Either way, restart the rtl_tcp server or driver app, then run the command again. - rtl_tcp needs a longer settle. The server keeps streaming while the
retune command crosses the network, so samples from the previous frequency
are still in flight. If a strong carrier shows up one hop away from where
it belongs, raise
-settle. -
The tuner’s DC spike is removed. A tuner leaks a little of its own local oscillator into its output, which a spectrum shows as a narrow carrier at exactly the tuned frequency. A sweep retunes for every hop, so that carrier used to appear at the centre of every line, three bins wide, although nothing was transmitting there: a PlutoSky sweep of the FM band in #1230 had one every 3.6 MHz, 11 dB over the noise.
powernow removes it. The spike is the same value in every FFT it averages, where anything received changes from one FFT to the next, so for the three centre bins it reports only the part that changed. Noise and real signals there read as before.Two things it also takes out, because they look the same: an unmodulated carrier that sits within about a sixteenth of a bin of a hop’s centre frequency, or exactly one bin either side of it. A modulated signal is not affected.
-keep-dcleaves the spike in if you need to check. With an-iso short that a hop averages a single FFT, the three centre bins are filled in from the bins beside them, as rtl_power does with its DC bin. -
If the spike is still there, the tuner’s offset moved. The removal takes out what holds still from one FFT to the next. On a tuner whose offset jumps while a hop is being measured, part of the spike stays. An AGC that keeps changing its gain does this: a PlutoSky in #1230 came out clean in hops with one strong station and kept the whole spike, 7 dB over the noise, in a hop with two equally strong ones. That it was the AGC is inferred from the sweep, not confirmed on the board.
powertells you when it happens, once per run:power: note — sweep 1: after the tuner's DC line was removed, a line of its shape is still at the centre of 1 of 6 hops (100.6000 MHz; up to 7.3 dB over the bins beside it). …There are two ways to get rid of it:
- A fixed gain, for example
-gain 400. The gain no longer moves, so the offset holds still and the removal takes all of it. This also makes the hops comparable with each other: withauto, every hop is measured at whatever gain the AGC chose for it. -fill-dc. The three bins at the centre of such a hop are filled in from the bins beside them, as rtl_power does with its DC bin.
-fill-dcis not the default because it cannot tell the leftover spike from a narrowband signal that sits exactly on a hop’s centre: both are narrow, both are alike from one FFT to the next, and neither turns. A recording in this repository has such a signal, 12 dB over the bins beside it, and-fill-dcerases it. A carrier off the centre turns from one FFT to the next and is left alone: from about a hundredth of a bin for a steady carrier on a hop of a few thousand FFTs, and from about a tenth of a bin for a modulated one. Anything wider than the spike, such as a broadcast station, is left alone too.-dc-reportprints one line per hop with the measurements: how much held still and was removed, how far the centre still stands over the bins beside it, and whether what is left turns. Post those lines with a report and the cause can usually be read from them. - A fixed gain, for example
- A slow CPU averages fewer samples; it doesn’t slow the sweeps. Each hop
gets its share of the interval. If the FFT can’t keep up with the sample
rate, as on older phones, the hop stops at that time limit with whatever
it averaged, so sweeps still start every
-i.powerprints a note on stderr when a sweep averages under 90 % of what real time delivered, and thesamplescolumn shows how many each hop used. The note names the cause:- “the FFT can’t keep up … (N IQ chunks dropped)”: samples arrived
faster than the CPU could take them. A lower
-rate(for example1024000) needs less CPU but takes more hops. - “no IQ was dropped on the way to the FFT, so the CPU kept up: the SDR
delivered fewer samples than its rate”: the CPU took every sample the
dongle sent, and the dongle sent too few: a slow USB link or driver,
not the CPU, so a lower
-ratewon’t help.
The FFT was rewritten for speed (about 3–4× faster, measured on 32-bit and 64-bit x86). Measured on phones in #1230: a Galaxy S5 kept up at 2.4 MS/s from its fourth hop on, while a Galaxy S5 Neo managed about 38 % and needs a lower
-rate. - “the FFT can’t keep up … (N IQ chunks dropped)”: samples arrived
faster than the CPU could take them. A lower
- Differences from rtl_power: the default crop is 0.25 (rtl_power’s is
0), gain is in tenths of a dB, and there is no
-wwindow choice (Hann is used) or-Fdownsampling filter.