Part 1 of RF Scope, a 10-part series on GopherTrunk’s protocol-agnostic RF network analyzer. RF Scope is the middle series of the Lab Bench trilogy — Signal Lab names and measures a single signal, RF Scope maps a whole band, and Crypto Lab breaks what comes out the other end. A mystery signal named Mercury runs through all three.
TL;DR:
rfscopeis Wireshark for the RF physical layer. Point it at a band — a recorded IQ file or a live SDR — with no idea what technology is there, and it segments the span into bursts and builds a structured Scene: a protocol hierarchy, per-channel activity, burst timing, an emitter/conversation graph, an entropy/encryption triage, and an expert-info anomaly list. It adds no DSP of its own — it orchestrates primitives GopherTrunk already ships — and it is not a waterfall UI; the outputs are trees, tables, graphs, and JSON.
Key takeaways
- RF Scope answers “what is on this band and how does it behave?” without you naming a protocol, modulation, or framing first.
- It is not a spectrum scope. For live waterfalls and constellations you want Signal Lab; RF Scope emits structured data, not a scrolling display.
- It orchestrates, it does not invent DSP. The survey classifier, carrier peak detection, spectrum occupancy, siglab identify, and the cryptolab randomness battery all already existed; RF Scope wires them into one Scene.
- It sits between
huntandsiglab.huntmaps known trunked systems,siglabdecodes named protocols, and RF Scope says something structural about a signal even when it is neither.
Cheat sheet
| Command / flag | What it does |
|---|---|
rfscope analyze -in <cap> |
Segment + analyze a recorded IQ capture |
rfscope live -serial <sdr> -freq Hz |
Analyze a live SDR span |
rfscope cockpit |
Full-screen live Scene TUI |
rfscope serve |
Browser console at 127.0.0.1:8098 |
rfscope list |
Print the registered analyzers |
-analyzers hierarchy,timing |
Run a subset (dependencies auto-pulled) |
-out-format summary\|json\|jsonl\|yaml\|csv |
Choose the report shape |
-frames-out frames.jsonl |
Emit a Crypto Lab ks frames file |
In this post
- What RF Scope actually is — and the expectation it is not a UI.
- Where it sits versus
huntandsiglab. - The Scene data model — Burst, Channel, Emitter, Conversation, Hierarchy, Anomaly.
- The five commands you will use across the series.
- The cast, the trilogy, and Mercury — the thread that ties all thirty posts.
What RF Scope is
RF Scope is protocol-agnostic RF network analysis. You point it at a slice of
spectrum — a wideband .cfile on disk, or a live receiver — and it tells you what
is transmitting, on which channels, how often, in what shape, and whether any of it
looks encrypted. Crucially, you supply no prior knowledge. You do not tell it
“this is P25” or “expect 4-level FSK at 4800 baud.” It discovers the carriers,
slices them into bursts, classifies each burst’s modulation blindly, and assembles
the results into a single structured Scene.
That is the same move Wireshark makes one layer up. Wireshark takes a pcap it knows nothing about and produces a Protocol Hierarchy, I/O Graphs, a Conversations table, and Expert Information. RF Scope produces the RF-physical-layer analogs of exactly those views. If you have ever opened a strange capture in Wireshark just to see what is in here, you already understand the workflow.
It is decidedly not a spectrum scope. There is no scrolling waterfall, no live constellation, no eye diagram. Those belong to Signal Lab, the sibling series built for staring at one signal in detail. RF Scope’s outputs are structured: indented hierarchy trees, channel tables, occupancy timelines, an emitter graph, and a JSON Scene you can pipe into other tools. When you want to see a signal, use Signal Lab. When you want to inventory a band, use RF Scope.
And it adds no DSP of its own. This is a design principle, not an accident. The package docstring is blunt about it: RF Scope “imports only downward” and “orchestrates the existing primitives and accumulates their output into one shared, JSON-exportable Scene.” The pieces it wires together already ship in GopherTrunk:
- the
surveyblind modulation classifier, carrierswideband peak detection,spectrumoccupancy metrics (occupied bandwidth, channel power, ACPR, spectral flatness),siglabprotocol identification, and- the
cryptolabrandomness / keystream engines.
Because it reuses proven primitives, a bug in RF Scope is almost always a wiring bug, not a new DSP bug — and every measurement it reports is one you could compute by hand with the underlying tool.
Where it sits: hunt vs siglab vs rfscope
Three GopherTrunk tools look at RF, and it helps to keep their jobs distinct:
| Tool | Question it answers | Needs to know the protocol? |
|---|---|---|
hunt |
“Which known trunked systems are here, and what are their WACN / site / neighbors?” | Yes — it maps named trunking systems |
siglab |
“What named protocol is this one signal, and can I decode its PDUs?” | It identifies among 13 named protocols |
rfscope |
“What is structurally on this band, even if it is nothing I recognize?” | No |
RF Scope is the layer below the other two. An unknown IoT mesh, a telemetry link, a
paging variant, an encrypted data burst, a frequency hopper — none of those decode
as a named protocol, and hunt will never map them, but RF Scope will still tell
you they exist, how wide they are, how bursty they are, and whether they look
random. And when a real trunking control channel does turn up in the band, RF
Scope does not reinvent the map: its topology analyzer defers to hunt’s
authoritative map for that system (Part 6).
Reese’s rule of thumb: “siglab is a microscope, hunt is an atlas, and RF Scope
is the reconnaissance photo you take before you know which one you need.”
The Scene data model
Everything RF Scope produces lives on one struct, Scene. Six views matter:
- Burst — the atom. One onset→offset activity segment on one frequency, with its spectral metrics (occupied bandwidth, channel power in dBFS, ACPR, spectral flatness) and a blindly-classified modulation class. Every other statistic is built from bursts.
- Channel — the per-frequency, time-aggregated row: duty cycle, occupancy percentage, burst rate, dominant class, and a 100-bin activity timeline.
- Emitter — a cluster of bursts sharing an RF fingerprint. A frequency hopper’s scattered bursts collapse into one emitter.
- Conversation — temporally correlated emitters linked together: a hop sequence, a co-active pair, or a request/response exchange.
- Hierarchy — the class → bandwidth → protocol tree, the RF Protocol Hierarchy.
- Anomaly — one expert-info finding, with a severity of
note,warn, oralert.
That pipeline is the shape of the whole series. Part 2 is the Segment box; Parts 3–8 are the analyzers in the registry; Part 9 is how you watch the Scene live; Part 10 is tuning and the export/bridge outputs.
The five commands
gophertrunk rfscope analyze -in <capture> [flags] analyze a recorded IQ capture
gophertrunk rfscope live -serial <sdr> -freq Hz [flags] analyze a live SDR span
gophertrunk rfscope cockpit [-in <cap> | -serial <sdr> -freq Hz] live scene TUI
gophertrunk rfscope serve [-addr host:port] [-open] web console (browser)
gophertrunk rfscope list list registered analyzers
The simplest useful invocation summarizes a wideband capture:
gophertrunk rfscope analyze -in wide.cfile -format f32 \
-sample-rate 2400000 -freq 451000000
That prints a human-readable Scene: the hierarchy tree, a channel table, top
talkers, conversations, and expert info. Swap -out-format json -out scene.json and
you get the whole Scene as machine-readable data instead. Point cockpit at the
same file and you get a live, refreshing terminal dashboard of it. Everything in
this series is a variation on those.
Mercury enters
While testing her new receiver, Ada parks it on 453 MHz in the UHF business band and catches something odd: a short, intermittent burst, roughly a 12.5 kHz channel, that comes and goes with no obvious pattern. Signal Lab could not name it — its best blind guess was around 4800 sym/s and 4-level-FSK-like, but no protocol locked. So she hands the wideband capture to RF Scope. Over Parts 3, 6, and 7 we will watch Mercury show up as an unknown-protocol, frequency-hopper-flagged emitter, get triaged as not-obviously-strong encryption, and then get handed off to Crypto Lab as a frames file. Keep an eye on it.
Series map
| Part | Topic | What you’ll do |
|---|---|---|
| 1 | Wireshark for the RF physical layer (this post) | Understand the Scene model |
| 2 | Segmentation: IQ to bursts | Discover carriers, slice bursts |
| 3 | Protocol hierarchy | Read the class→bw→protocol tree |
| 4 | The I/O graph | Per-channel activity over time |
| 5 | Timing & periodicity | Recover a TDMA frame period |
| 6 | Topology | Cluster emitters, find conversations |
| 7 | Entropy triage | Bridge into Crypto Lab |
| 8 | Expert info | Read the anomaly flags |
| 9 | The Scene cockpit | Live TUI and web console |
| 10 | Advanced tuning | Selective analyzers & pipelines |
The full rfscope docs are the reference this series expands on; the Signal Lab and Crypto Lab hubs are the other two-thirds of the trilogy.
Where this goes next
Part 2 opens the Segment box: how a wideband FFT finds carriers, how a robust noise floor is estimated, how each carrier is downconverted to a narrow baseband, and how a hysteresis state machine slices that baseband into the onset→offset bursts every analyzer downstream consumes. Nothing else in the Scene exists until segmentation runs, so it is the right place to start.
FAQ
Is RF Scope a replacement for a spectrum analyzer or waterfall? No. It produces structured data — trees, tables, a JSON Scene — not a live visual display. For waterfalls, constellations, and eye diagrams, use Signal Lab. The two are complementary: reconnaissance versus close inspection.
Do I need to know the protocol before I run it?
No — that is the entire point. RF Scope discovers carriers, classifies modulation
blindly, and builds the Scene with zero prior knowledge of technology, framing, or
encryption. Naming a protocol is siglab’s job, and RF Scope will call siglab for
you where it helps.
What hardware do I need?
For analyze and offline cockpit, none — just a recorded IQ capture. For live
and live cockpit you need any SDR GopherTrunk supports. RF Scope is
rate-invariant: it normalizes each carrier to a narrow per-channel baseband, so the
capture rate is yours to choose.
How does it relate to Crypto Lab?
The entropy analyzer (Part 7) triages unknown digital payloads and can emit them as
a ks frames file with -frames-out, which feeds cryptolab directly. That is the
hand-off that eventually cracks Mercury.
Series navigation
Part 1 of 10 · Next → Part 2: From IQ to Bursts