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:

  1. 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.
  2. Bins per line. -crop 0.25 drops 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.
  3. 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

  • power reads no config file. Name a network radio on the command line (-iio, -rtltcp). If power finds no local SDR and the config file the daemon would load lists network radios, the error names the flag for each, for example sdr.iio lists a Pluto / PlutoSky at 192.168.1.179: run gophertrunk power -iio 192.168.1.179 .... capture does 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 (or wmbus / 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.

    power now 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-dc leaves the spike in if you need to check. With an -i so 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.

    power tells 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: with auto, 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-dc is 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-dc erases 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-report prints 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 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. power prints a note on stderr when a sweep averages under 90 % of what real time delivered, and the samples column 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 example 1024000) 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 -rate won’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.

  • 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 -w window choice (Hann is used) or -F downsampling filter.