GopherTrunk

Pure-Go digital-trunking radio scanner engine for RTL-SDR · HackRF · Airspy · Airspy HF+.
P25 · DMR · TETRA · NXDN · Motorola Type II · EDACS · LTR · MPT 1327 · dPMR · D-STAR · YSF.
Zero CGO, single static binary, headless daemon + Bubbletea TUI cockpit + browser web console.

---

What is this?

GopherTrunk is a software-defined-radio scanner that follows digital trunked-radio voice calls and decodes them to audio. It runs on a pool of RTL-SDR (every osmocom tuner), HackRF (One / Jawbreaker / Rad1o), Airspy R2 / Mini, and Airspy HF+ dongles, has no C dependencies at build or runtime (no librtlsdr / libhackrf / libairspy / libairspyhf / libusb / libasound2 / libmp3lame), and ships as a single ~10 MB static binary for Linux, macOS, and Windows.

Completed calls stream to Broadcastify Calls, RdioScanner, OpenMHz, and live Icecast / ShoutCast mountpoints out of the box. Why does this exist? Read The Story of GopherTrunk.

Quick start

# Linux x86_64 — see https://gophertrunk.org/downloads.html for macOS, Windows, ARM64.
VERSION=v0.3.8
curl -L -o gophertrunk.tar.gz \
  https://github.com/MattCheramie/GopherTrunk/releases/download/${VERSION}/gophertrunk-${VERSION}-linux-amd64.tar.gz
tar xzf gophertrunk.tar.gz && cd gophertrunk-${VERSION}-linux-amd64
cp config.example.yaml config.yaml
./gophertrunk version
# Plain `./gophertrunk` (no subcommand, on a TTY) drops into the
# interactive launcher: pick [1] TUI, [2] Web, or [3] Headless.
# Skip the prompt with -tui / -web / -headless.
./gophertrunk -config config.yaml

Windows users get a one-click installer that bundles Zadig for WinUSB driver setup; macOS users get notarised tarballs for Apple Silicon and Intel. Full per-OS recipes at gophertrunk.org/downloads.html.

Features

• Trunked control-channel decoders — P25 Phase 1 + Phase 2 (full TIA-102 chain), DMR Tier II + Tier III (vendor-aware: Capacity Plus / Capacity Max grants and rest-channel tracking), NXDN, Motorola Type II / SmartZone, EDACS / GE-Marc, LTR, MPT 1327, dPMR Mode 3, TETRA TMO. Amateur-radio: D-STAR and Yaesu System Fusion.
• POCSAG + FLEX paging — protocol + DSP for the two dominant pager protocols, both decoding straight off the air and sharing the pager_log table / /pager panel (tagged by protocol). POCSAG (CCIR 584): BCH(31,21) FEC, batch carve-up, numeric (5 BCD/codeword) + alphanumeric (7-bit packed ASCII), 512 / 1200 / 2400 bps. FLEX: 1600 bps / 2-level mode — 32-bit sync + mode code → frame-info word → block de-interleave → BCH(31,21) → BIW / address / vector / message-word walk → alphanumeric / numeric pages. Pin SDRs via paging.pocsag / paging.flex. Foundation for fire / EMS dispatch text alongside the trunked-voice pipeline. See docs/pocsag.md.
• APRS / AX.25 packet — end-to-end pipeline for the amateur-radio APRS metadata bus (position beacons, messages, bulletins, status, Mic-E mobile-tracker compressed format). Bell-202 AFSK DSP frontend (FM demod → FFSK tone discriminator → symbol-time recovery → NRZI → HDLC framer), AX.25 frame parser with CRC-16-CCITT, APRS info-field decoders including full Mic-E (lat/lon, speed, course, altitude, message code), plus events.KindAPRSPacket bus event, SQLite aprs_log, GET /api/v1/aprs/packets, and /aprs web panel. See docs/aprs.md.
• AIS marine — end-to-end pipeline for the Automatic Identification System every commercial vessel broadcasts on marine VHF 87B / 88B (161.975 / 162.025 MHz). 9600 Bd GMSK DSP frontend (FM demod → GFSK matched filter at BT = 0.4 → symbol-time recovery → NRZI → HDLC framer → CRC-CCITT validation), ITU-R M.1371-5 message-type dispatch (Class A position reports 1/2/3, Class B 18 + 19 extended, base-station 4, static + voyage 5, Class B static 24 A + B), signed-integer lat/lon decoder (1/600000 minute resolution), 6-bit ASCII text fields (vessel name, call-sign, destination), spec "not-available" sentinels. Plus events.KindAISMessage bus event, SQLite vessel_log, GET /api/v1/ais/vessels, and /ais web panel. See docs/ais.md.
• MDC1200 signaling — end-to-end pipeline for Motorola's analog FFSK data burst keyed at the head / tail of a transmission on conventional VHF / UHF voice channels. 1200-baud CCIR FFSK DSP frontend (FM demod → FFSK discriminator at 1200 / 1800 Hz → Mueller-Müller timing → NRZ slicer), 40-bit sync framer with polarity tolerance, 16×7 de-interleave, op / arg / unit-ID decode with CRC-16-CCITT check, and an op/arg table (PTT ANI, emergency, status, radio check, call alert, selective call). Plus events.KindMDC1200Message bus event, SQLite mdc1200_log, GET /api/v1/mdc1200/messages, and /mdc1200 web panel. See docs/mdc1200.md.
• DSC marine distress — protocol layer for the GMDSS Digital Selective Calling system that fires every marine VHF channel- 70 distress alert. ITU-R M.493-15 format dispatch (Distress, All-Ships, Individual, Group, Geographic, Auto-Individual), BCH(10,7) syndrome check, position decoder with quadrant hemisphere flip, nature-of-distress table. Plus events.KindDSCMessage bus event, SQLite dsc_log, GET /api/v1/dsc/messages, and /dsc web panel (rows tint by category — distress=red, urgency=orange, safety=blue). DSP frontend decodes straight off the air: FM demod → FFSK discriminator (1200 Bd, 1300/2100 Hz tones) → symbol-timing recovery → direct-FSK slicer → BCH(10,7) character sync → ITU-R M.493 parser. Pin an SDR via dsc.channels. See docs/dsc.md.
• ADS-B aviation — end-to-end pipeline for the 1090 MHz Mode-S transponder broadcasts every commercial flight emits. ICAO Annex 10 Vol IV / DO-260B parser (CRC-24 + DF dispatch + type-code dispatch for identification, airborne / surface position with 12-bit Q-bit altitude, airborne velocity); globally-unambiguous CPR position decoder + per-ICAO even+odd pair tracker. BEAST upstream consumes Mode-S frames from any dump1090 / readsb / BeastSplitter via TCP — most 1090 MHz receive chains already run one, GopherTrunk decodes its output. Native PPM DSP frontend is the alternative: pin an SDR (>= 2 Msps) to 1090 MHz via adsb.channels and GopherTrunk demodulates Mode-S itself — magnitude envelope → 8 µs preamble correlation → PPM bit slice → CRC/DF dispatch — feeding the same decode/track path the BEAST upstream uses. Plus events.KindAircraftReport bus event, SQLite aircraft_log, GET /api/v1/adsb/aircraft, and /adsb web panel. See docs/adsb.md.
• M17 link layer — metadata decoder for the open, Codec2-based M17 digital voice mode (4FSK, 4800 sym/s). C4FM demod → symbol timing → 4FSK slice → sync hunt → LICH reassembly (Golay(24,12), six chunks) → Link Setup Frame parse: source / destination base-40 callsigns, mode (voice / data / packet), channel-access number, CRC-16. Recovers "who's talking to whom" from an in-progress transmission without decoding audio (Codec2 voice is a planned follow-up). events.KindM17LinkSetup bus event, SQLite m17_log, GET /api/v1/m17/linksetups. Pin an SDR via m17.channels. See docs/m17.md.
• Live map — Shared Leaflet map at the top of each position-bearing panel (APRS / AIS / DSC / ADS-B) renders decoded positions over OpenStreetMap tiles, colour-coded per protocol (blue / cyan / red-distress / purple), with marker tooltips and camera auto-fit. Same <PositionMap> component drives all four panels.
• Pure-Go voice path — IMBE (P25 Phase 1) and AMBE+2 (P25 Phase 2 / DMR) vocoders in Go, no DVSI / mbelib dependency. Per-call WAV + raw-frame sidecars; live PCM playback via direct ALSA / WASAPI / CoreAudio.
• Pure-Go SDR drivers — RTL-SDR, HackRF, Airspy R2 / Mini, Airspy HF+ family. USB transport on Linux (USBDEVFS), Windows (WinUSB), macOS (IOKit). USB-disconnect self-healing recovers dongles that drop off the bus and re-enumerate without restarting the daemon. See docs/hardware.md.
• Remote rtl_tcp SDRs — Mount any number of rtl_tcp endpoints as virtual tuners alongside local USB dongles. The SDR can live on a Raspberry Pi at the antenna while the daemon runs on a beefier host; one entry per remote in sdr.rtl_tcp.
• Remote SoapySDRServer SDRs — Mount professional / high-bit-depth hardware (USRP, LimeSDR, bladeRF, HackRF, Airspy, SDRplay, …) over the network via the SoapyRemote protocol, in pure Go with no CGO. Carries 16/32-bit IQ with native frequency / sample-rate / gain control; one entry per remote in sdr.soapy_remote. See docs/hardware.md.
• Live spectrum / waterfall — In-browser FFT waterfall served off the same IQ stream the trunking decoder consumes. New internal/sdr/iqtap multi-consumer fan-out lets future trunking-adjacent decoders (paging, AIS, ADS-B, ...) tap the same source without disturbing CC decode. GET /api/v1/spectrum/devices
  • WS /api/v1/spectrum/stream; web panel under /spectrum.
• CC Activity panel — focused web view of the trunked control- channel chatter (grants, affiliations, registrations, patches, talker aliases, CC lock / loss). Pure filter over the events stream with per-row payload rendering; web panel at /cc. RIDs in the feed are clickable chips that pivot into the per-radio detail view.
• Radio IDs panel — per-radio (subscriber-unit) entity browser with the same shape as Talkgroups. Merges the operator-configured alias catalogue (per-system rid_alias_file CSV or JSON: alias, owner, tag, group, priority, lockout, watch) with the live affiliation tracker (last talkgroup, last seen, call count, decoded talker alias). Detail modal pulls the last 50 calls for the RID from the persisted call log. Web panel at /rids; REST at /api/v1/rids; gRPC RIDService. Talker-alias decoders cover the Motorola vendor TSBK form (control channel) and the Motorola voice-channel LCs (P25 Phase 1 LDU1 LCO 0x15 header
  • N × LCO 0x17 data blocks, run through Motorola's reverse-engineered alias cipher).
• Constellation viewer — live IQ scatter visualization that taps the same broker the trunking decoder reads. Useful for identifying signal shape (PSK / QPSK / FSK / C4FM / AM / noise), spotting frequency offset, and checking demod / equalizer health. Decimated to 2 ksps for the wire; canvas scatter with energy banner. Web panel at /constellation.
• Symbol scope — live oscilloscope of the demodulated symbol stream (OP25's "Symbol" plot): the pre-slicer soft waveform for P25 C4FM and the sliced dibit decisions for CQPSK, driven off the production receiver. Shares the constellation's offset / Hold / follow-active-call controls. Web panel at /symbols; offline view in SigLab. See docs/symbol-scope.md.
• Bookmarks / frequency manager — UI-managed conventional channel list (marine VHF, NOAA weather, FRS/GMRS, repeater outputs, public-safety fall-back channels) stored in the daemon's SQLite database. Edit / create / delete from the web panel under /bookmarks; REST at /api/v1/bookmarks.
• One dongle, many carriers — role: wideband pins a single SDR to a centre frequency and runs an internal channelizer so one dongle decodes every DMR Tier II conventional repeater, DMR Tier III control channel, P25 Phase 1 control channel, AND P25 Phase 2 control channel that fit inside its IQ bandwidth (e.g. several 12.5 kHz carriers inside a 2.4 MHz IQ window). Mix protocols on the same dongle.
• One dongle, control + voice — with voice_taps: N on a wideband entry, the daemon allocates per-grant DDC tuners from the dongle's IQ stream so trunked voice grants (DMR T3, P25 Phase 1, P25 Phase 2) decode inline on the same SDR that's already hosting the control channel — no separate role: voice dongle needed for grants inside the wideband window. Out-of- window grants spill over to a physical voice SDR when present. DMR Tier III is 2-slot TDMA, so a single carrier can run two simultaneous calls — TS1 and TS2 are tracked, recorded (with a _ts1 / _ts2 filename suffix), and logged as distinct calls, each binding its own voice tap. See docs/hardware.md and samples/dmr-tier2-multichannel/.
• DSP — Polyphase channelizer, Kaiser / RRC / Gaussian FIRs, FM / C4FM / GFSK / FFSK / DQPSK / π/4-DQPSK / π/8-H-DQPSK demods, Mueller-Müller + Gardner clock recovery, LMS + CMA equalizers, diversity combining.
• APIs — gRPC + HTTP/SSE + WebSocket; optional TLS + bearer-token auth on mutations; Prometheus /metrics; pure-Go SQLite call log; in-process pub/sub event bus.
• Hamlib rigctld integration — optional TCP server speaking the standard Hamlib wire protocol so loggers, satellite trackers, and amateur-radio tooling (Cloudlog, GridTracker, PSTRotator, rigctl(1)) can read and set the control SDR's frequency. RX-only backend; see docs/rigctld.md.
• Outbound call streaming — Broadcastify Calls, RdioScanner, OpenMHz, live Icecast / ShoutCast with pre-encoded silence keep-alive. Pure-Go MP3 encoder. See internal/broadcast.
• Baseband recording + offline replay — Two-channel 16-bit WAV capture and a replay driver that mounts captures back into the SDR pool as virtual tuners. Looping replay simulates a continuous source.
• Operator surfaces — Bubbletea TUI cockpit with 12 panels, pure-browser React SPA web console, runtime config editing via PATCH /api/v1/settings, RadioReference PDF / CSV importer with a config-builder wizard.
• Site/system hunting — gophertrunk hunt maps a previously undocumented trunked system from one or more control-channel IQ captures: auto-identifies the protocol, accumulates identity (P25 NAC / WACN / SYSID / RFSS / Site, and per-protocol ids), per-site control channels and observed talkgroups, then exports a GopherTrunk import bundle, a trunk-recorder config stanza, and a ready-to-paste RadioReference submission package — with an optional read-only RadioReference duplicate check so you don't submit a system that already exists. See docs/hunt.md.
• Location + affiliation — NMEA-0183 GGA / RMC over the air decoded into a SQLite location_log; protocol-agnostic affiliation tracker fed from grants / registrations / affiliation events.

For the full per-protocol FEC chain reference, receiver internals, frame layouts, and API routes, see docs/architecture.md and docs/opt-in-features.md.

Status snapshot

Once a grant event lands on the bus, the engine + recorder pipeline runs end-to-end: voice device is allocated, the composer pulls IQ → PCM, the recorder writes a WAV, the call is logged to SQLite, and the API + TUI surfaces all light up. Every trunked control modulation in the Features list has an end-to-end IQ → CC chain shipping. SDRtrunk-parity subsystems (outbound streaming, baseband recording, GPS / location, affiliation tracking, decoded-message log, per-talkgroup policy) all ship.

Remaining gaps:

• Digital-voice composer chains. FM, DMR, P25 Phase 1 / 2 decode to audio. NXDN, dPMR, TETRA, YSF, D-STAR voice (plus EDACS ProVoice) are followed and logged but not yet turned into PCM.
• DMR 2-slot interleaved voice + embedded-LC labelling. Both timeslots of a carrier are tracked, recorded, and logged as separate calls; a stride-2 interleaved superframe decoder (voice.NewInterleavedDecoder) separates the two slots and reassembles each slot's embedded Link Control (EMB → variable BPTC(128,72) → talkgroup/source) so a slot is routed to its call by talkgroup. The whole path is wired through the voice composer behind a per-system opt-in (dmr_interleaved_voice: true) and unit-tested end-to-end against synthetic modulated IQ. Each slot's calls are visible per-timeslot in the TUI / web active-call views and in the gophertrunk_dmr_voice_calls_total{system,timeslot} metric. It defaults off: confirming the exact on-air dibit cadence (CACH/guard) and the ETSI embedded-signalling interleave / EMB FEC / CRC against a real IQ capture is what's needed before it becomes the production default — see docs/status.md.
• Additional SDR validation. HackRF / Airspy / HF+ drivers exercise the documented USB vendor protocols under unit tests against a mock transport; on-air validation against attached hardware is the documented follow-up.
• FEC inner-layer real-air validation. NXDN per-protocol interleaver and TETRA on-air recovery margins need live captures to characterise.
• Vocoder level calibration awaits reference WAVs in internal/voice/{imbe,ambe2}/testdata/.

The long-form status, per-protocol detail, and shipping-vs-pending checklist live in docs/status.md. Near-term plans live in docs/roadmap.md. Released work lives in CHANGELOG.md.

Build from source

make dist     # SPA + daemon — single binary that serves the web console at /
make build    # Go-only — fast iteration; daemon shows a helpful 404 at / until bundled
make test     # go test -race ./...
make vet      # go vet ./...
make integration  # daemon end-to-end test (no SDR required)

The per-protocol "lights up" integration tests (make integration-cc-<proto>) and the DVSI hardware-backend tests (make test-dvsi) are documented in CONTRIBUTING.md.

A bare go build ./cmd/gophertrunk works too — the binary auto-stamps its version line from Go's built-in VCS info. Useful when attaching a log to an issue and you want the commit hash in the build-info line.

Docker

docker compose up -d
curl -s http://localhost:8080/api/v1/health
curl -s http://localhost:8080/metrics | grep gophertrunk_build_info

USB pass-through recipe and the operator hardening playbook (TLS, bearer-token auth, Prometheus catalogue, smoke tests) live in docs/hardening.md.

Documentation

Operator-facing docs live at gophertrunk.org (rendered from this docs/ tree):

• Install — Downloads · Hardware · Linux · macOS · Windows
• Operate — Launcher · Windows user guide · TUI · Web console · Live config editing · Import (PDF / CSV) · Hunt (discover unknown systems) · Constellation · Symbol scope · Hardening
• Reference — Architecture · Vocoders · Voice calibration · DMR encryption · Opt-in features · Status · Roadmap · Cutting a release
• Project metadata — CHANGELOG · CONTRIBUTING · SECURITY · THIRD_PARTY_LICENSES

Support the project

GopherTrunk is developed in the open and powered entirely by community support. If it's useful to you, please consider chipping in:

• Sponsor on GitHub
• Tip on Ko-fi

More ways to help: docs/support.md.

License

See LICENSE.