TL;DR: On a live P25 Phase 2 system, 66 of 66 encrypted calls were flagged encrypted: true while algorithm_id/key_id never populated (#813). The flag and the metadata come from different places, so one can be right while the other is structurally impossible. Underneath sat a four-stage chain: an encryption-sync MAC opcode (0x70) that doesn’t exist on real air, a plausible-but-wrong carrier-recovery diagnosis disproven by a TCXO source failing identically, a 48-bit sync-word constant silently truncated into a 40-bit field, and a missing 2↔3 dibit remap that let superframes lock while every payload decoded to garbage. The technique that cracked the ordering was an unconditional per-call census that logs stage counters even at zero — and the last line of defense is a validity gate that refuses to publish an algorithm ID the standard has never heard of.

Cheat sheet

In this post

• The symptom as reported — the flag is right; the metadata is structurally impossible.
• Stage zero: the opcode that never existed — 0x70 was a working model, unit-tested against itself.
• The census: a log line that fires at zero — the three-way stage disambiguator.
• The plausible wrong theory: carrier recovery — the right bug class, the wrong bug.
• Root cause one: a 48-bit constant in a 40-bit field — hunting for a sync word never transmitted.
• Root cause two: the 2↔3 remap — superframes lock while every payload decodes to garbage.
• The numbers, and the gate — 89% vs 0.5%, and refusing to publish nonsense.
• What we keep — the durable rules and their Field Guide entries.

The symptom as reported

The reporter’s setup was deliberately clean: an Airspy on the control channel, a dedicated RTL-SDR voice follower, recordings.skip_encrypted: false so encrypted calls are actually followed, and a generous 5-second metadata window. Thirty minutes of live traffic, then straight to the API rather than the logs:

{"id": 9367, "system": "MMR", "protocol": "p25-phase2", "group_id": 3202,
 "frequency_hz": 468612500, "encrypted": true,
 "end_reason": "encrypted", "talkgroup_alpha": "22-02 WD2"}

66 calls flagged encrypted: true. Zero with an algorithm_id or key_id key at all — omitempty was hiding zero values. The reporter had already ruled out the obvious: not the follow window (1500 → 5000 ms changed nothing), not the recorder short-circuiting (confirmed via log lines that calls were followed), not a logging gap (the API is the stored value).

Why can the flag be right while the metadata never arrives? Because they are unrelated. encrypted: true comes from the grant’s ServiceOptions “protected” bit on the control channel. The algorithm and key IDs must be recovered from the voice channel’s MAC layer. One path worked perfectly; the other, it turned out, had never worked at all.

Stage zero: the opcode that never existed

The extraction code existed and was unit-tested: a MAC PDU handler keyed on OpEncryptionSync = 0x70, wired all the way through to the engine. Every test passed — because every test synthesized a 0x70 PDU. The constant was an explicit working model; the source even carried a note that the relevant spec PDF wasn’t available. On real Phase 2 (TIA-102.BBAC), ALGID/KID/MI don’t ride a standalone opcode: they ride the MAC_PTT message that begins each transmission, identified by slot type, not by MAC opcode. AsEncryptionSync could never match anything on air.

That explained the shape of the symptom — flagged but never populated — and produced fix number one: parse MAC_PTT at the documented offsets. It did nothing, which is how the real diagnostic entered the story.

The census: a log line that fires at zero

The first instrumentation pass added detail to the existing composer: p25p2 mac pdu line. The reporter ran ~19 minutes of live traffic: 202 voice chains started with valid configuration, 33 encrypted calls — and zero of those log lines, for any slot type.

Here is the trap: that line only fires on a successful MAC decode. Its silence is identical whether superframe sync never locked, the ISCH never classified a MAC slot, or the MAC FEC failed every time. The silence of a success-only log line carries no diagnostic information.

The replacement was an unconditional per-call census — one line at the end of every call, even when every counter is zero:

composer: p25p2 call census serial=… system=… superframes=N \
    voice_subframes=N mac_subframes=N mac_pdus=N  slot_Voice4V=… slot_Unknown=…

Read as a three-way stage disambiguator:

The next run returned superframes=0 on 67 of 67 calls. Not one superframe ever locked, encrypted or not — on the same dongle that recorded Phase 1 voice cleanly the same night. The MAC_PTT byte-offset question was moot; the failure was upstream of MAC entirely.

The plausible wrong theory: carrier recovery

The Phase 2 H-DQPSK receiver was MatchedFilter → Gardner timing → differential decode — no NCO, no AGC, no Costas loop. A differential decoder cancels a constant carrier phase but not the per-symbol rotation 2π·Δf/baud left by a real tuner’s frequency offset. At 6000 baud, ~750 Hz of offset rotates every symbol a full π/4 into the wrong quadrant. And the hardware split matched perfectly: the Airspy control channel (TCXO, low offset) decoded; the RTL-SDR voice follower (no TCXO) never locked. It was even the same bug class already fixed twice on sibling paths — Phase 1 C4FM got coarse AFC in #275, Phase 1 CQPSK got an NCO seed and Costas loop in #492. Every Phase 2 test had synthesized zero-offset IQ, so CI never noticed.

Carrier recovery was added — coarse seed, NCO, AGC, a rotation-aware Costas loop — and the synthetic stream went from ~72% symbol errors at 1500 Hz offset to 0% across ±5 kHz. A genuine defect, genuinely fixed.

The field result: superframes=0, 56 of 56 calls. Unchanged.

The clincher came later, unprompted: the reporter re-ran with the Airspy R2 — a TCXO source — as the voice follower and got superframes=0 on 20 of 20 unencrypted follows too. A low-offset source failing identically to a high-offset one rules out carrier recovery entirely, and rules out hardware with it. Whatever was broken was hardware-independent.

Root cause one: a 48-bit constant in a 40-bit field

// internal/radio/p25/phase2/sync.go — before
OutboundSyncHex uint64 = 0x575F7DFF77FF  // 48 bits…
SyncDibits             = 20              // …into a 20-dibit (40-bit) field

hexToDibits silently used only the low 40 bits, so the correlator hunted for 0x5F7DFF77FF — neither the standard sync word nor anything that has ever been transmitted. No superframe could lock, on any tuner, ever. And every round-trip test passed, because the test encoder injected sync from the same wrong constant it decoded with. A self-consistent fiction.

The authoritative P25 Phase 2 outbound sync is 0x575D57F7FF (cross-checked against OP25’s frame_sync_magics.h and SDRtrunk, per TIA-102.BBAC). The regression test that pinned it synthesizes the sync independently of the project’s own modulator — the only kind of test that can expose a bad shared constant: zero locks on the old value, locks on the correct one.

Root cause two: the 2↔3 remap

Fixing the sync constant surfaced the fourth layer. The shared DQPSK quadrant slicer assigns the two negative-phase symbols the dibit values 3 and 2 where TIA-102 says 2 and 3. The Phase 1 CQPSK path — verified on real air in #492 — already documents and corrects exactly this transposition:

// internal/radio/p25/phase1/receiver/cqpsk.go
var lsmDibitRemap = [4]uint8{0, 1, 3, 2} // swaps 2↔3 → canonical TIA-102

Phase 2 was missing the equivalent remap. The swap is its own inverse, which made for a satisfying sanity check: applying [0,1,3,2] to the transposed sync 0x565956A6AA yields exactly the authoritative 0x575D57F7FF, and vice versa. The failure signature is distinctive and worth remembering: superframes lock, but every payload decodes to garbage — the regression test reproduces the field symptom precisely, recovering alg=0x75 key=0x555d where 0x84/0x1234 was encoded. The fix canonicalizes the receiver’s dibit output right after the slicer (one point covers sync, ISCH, MAC FEC, and diagnostics together) and restores the standard sync constant, leaving the shared demodulator — used by TETRA and Phase 1 CQPSK — untouched.

The numbers, and the gate

A 7-day quantification from the completed-call webhook made the before/after brutal and the residual honest:

The Phase 1 column is the control group, and it explains why the asymmetry went unnoticed for so long: Phase 1 recovers ALGID and key ID from the LDU2 encryption-sync fields mid-call, a decode path verified on air long before this issue — so anyone spot-checking “does encryption metadata work?” against a Phase 1 call saw it working. The Phase 2 path had never produced a correct value, and even after these fixes, the mid-call KindCallSourceUpdate that backfills a Phase 2 call’s source and encrypted flag carries no algorithm or key — those arrive only through the MAC_PTT chain this post walked.

Worse than “omitted”: the Phase 2 fields were populating with bit-error values — a uniform algorithm-ID smear across 0x00–0xFF, a different key ID every call. A wrong value published confidently is worse than an absent one.

The mitigation is a validity gate, p25.AlgorithmKnown(id), checked against the TIA-102 algorithm registry (0x80, 0x81, 0x83, 0x84, 0x85, 0x86, 0x89, 0x9F, 0xAA) and applied at the composer — the single point that both the recorder (webhooks, call history) and the engine (SSE, TUI) draw from, so every consumer is covered at once. An out-of-set value is provably a mis-decode and is dropped; the fields stay absent rather than lying. One deliberate scope call: the gate does not whitelist the classified Type-1 block (0x00–0x41) — admitting 66 low values would let a large slice of the smear straight through, and a real Type-1 sighting is a one-line registry addition.

One process footnote: the reporter’s raw IQ capture sat as a release asset on a fork, which the project’s offline-replay tooling couldn’t fetch — so every fix in this chain had to be verified against spec-conformant synthetics and code-internal cross-checks against the on-air-verified Phase 1 CQPSK path instead of the reporter’s own air. Host captures somewhere plain; it matters.

What we keep

• A flag and its metadata can have different truth values. encrypted: true came from the grant; the algorithm ID needed the voice channel’s MAC layer. See encrypted call handling for how the two paths relate.
• Silence of a success-only log line carries no information. The unconditional per-call census — counters logged even at zero — is the single most transferable technique in this story, and it’s now in the diagnostic playbook.
• A self-consistent synthetic proves nothing about air. The truncated sync constant survived every round-trip test because encoder and decoder shared the fiction. Regression tests for on-air constants must synthesize independently — the pinned values live in P25 on-air constants.
• A wrong theory can be a real bug. The carrier-recovery work was correct and necessary — it just wasn’t this bug. The disproof (a TCXO source failing identically) is as valuable as the fix.
• Never publish a value you can’t validate. The registry gate turns a bit-error smear back into honest absence, at the one choke point every consumer shares.

FAQ

How can encrypted: true be reliable while the algorithm ID never arrives? Because they come from different places. The flag is the grant’s ServiceOptions “protected” bit, decoded on the control channel — a path that worked. The algorithm and key IDs must be recovered from the voice channel’s MAC layer, which had never worked. A flag and its metadata can have entirely different truth values.

The carrier-recovery theory fit perfectly — what disproved it? The hardware split (Airspy TCXO decoded, RTL-SDR didn’t) matched the theory, the fix measurably repaired synthetic offsets, and the field census still read superframes=0. The clincher was the reporter re-running with the Airspy — a low-offset TCXO source — as the voice follower and failing identically. When a low-offset source fails the same way as a high-offset one, carrier recovery is exonerated, and so is the hardware.

Why didn’t unit tests catch the truncated sync constant? Every round-trip test injected sync from the same wrong constant it decoded with, so encoder and decoder agreed perfectly. The regression test that pinned the fix synthesizes the sync word independently of the project’s own modulator — the only kind of test that can expose a bad shared constant.

What does the validity gate actually block? Any algorithm ID outside the TIA-102 registry (0x80–0x86, 0x89, 0x9F, 0xAA). An out-of-set value is provably a mis-decode and is dropped at the composer, the one point both the recorder and the engine draw from. It deliberately does not whitelist the classified Type-1 block (0x00–0x41): admitting 66 low values would let a large slice of the bit-error smear straight through.

Is a wrong published value really worse than an absent one? Yes. An absent field says “unknown”; a smeared field says “algorithm 0x75, key 0x555d” with full confidence to every webhook, API consumer, and UI panel downstream — and no consumer can tell it from a real decode. Honest absence is recoverable; confident garbage propagates.

Series navigation

Part 3 of 22 · ← Part 2: The Talker-Alias Hunt — Three Wrong Transports and an Architectural Gate · Next → Part 4: The Dongle That Heard Nothing — One Line in a Register Table

TL;DR: The TUI is an Elm-architecture Bubbletea program. Its root Model holds a SharedState snapshot; Init kicks off a fan of polling commands (health, systems, talkgroups, active calls, metrics, devices, scanner, hunt, …) plus one long-lived SSE pump. Update is the reducer: root keys (quit, help, palette, panel nav) win first, then poll/SSE messages fold into SharedState and reschedule themselves, then the active panel gets the message. The thirteen panels are pure renderers over SharedState. It reconnects SSE with backoff, hides the same web.tabs panels the SPA hides, and gates writes on the same /api/v1/mutations capability. Same daemon, same contract, different renderer.

Key takeaways

• It’s the same API, not a parallel one. The TUI calls the identical REST endpoints and consumes the identical SSE event stream the browser does — the through-line of the series, made literal.
• One reducer, one SharedState. Update folds every poll and event into a single snapshot; panels never fetch — they read SharedState and render.
• Polls reschedule themselves; SSE is a pump. Each poll message re-arms its own timer, and a single SSE goroutine feeds events into the reducer, reconnecting with backoff on drop.
• Consistency with the web is enforced, not hoped for. The same web.tabs keys hide a panel in both UIs, and the same /api/v1/mutations snapshot gates writes — the TUI and SPA can’t drift on what’s visible or writable.

Cheat sheet

In this post

• The Elm model — Init, Update, View, and why it fits a live console.
• The polling fan — one self-rescheduling Cmd per read endpoint.
• The SSE pump — the same event stream the browser gets, parsed in Go.
• SharedState + panels — snapshot in the middle, renderers on the edge.
• Parity with the web — same tabs hidden, same writes gated.

The Elm model

Bubbletea is The Elm Architecture in Go: a Model, an Init that returns startup commands, an Update reducer that folds messages into new state and returns more commands, and a View that renders the model to a string. GopherTrunk’s root Model is exactly that — it holds the current panel selection, the thirteen panels, and the SharedState every panel reads:

// internal/tui/app.go (shape)
type Model struct {
    cli    *client.Client
    active state.PanelKind
    panels []panels.Panel
    shared *state.SharedState

    eventCh    <-chan client.Event // the live SSE feed
    sseCancel  func()
    sseRetries int
    // …palette, modals, tab hit-rects, toast
}

func (m *Model) View() string {
    tabs := m.renderTabs()
    status := m.renderStatusBar()
    body := m.panels[m.active].View(m.width, bodyH, true, m.shared)
    return lipgloss.JoinVertical(lipgloss.Left, tabs, body, status)
}

View composes chrome (a tab strip and a status bar) around the active panel’s own render, using Lipgloss for layout. The panel gets the width, a body height, and a pointer to SharedState — that’s the whole contract. Everything the panel needs to draw is already in the snapshot; it never reaches for the network.

The polling fan

Init is where the console comes alive. It returns a tea.Batch of one polling command per read endpoint, plus the SSE connect — a fan of concurrent fetches that mirrors, one-for-one, the set of things the browser polls:

// internal/tui/app.go (shape)
func (m *Model) Init() tea.Cmd {
    return tea.Batch(
        cmdPollHealth(m.cli), cmdPollVersion(m.cli),
        cmdPollSystems(m.cli), cmdPollTalkgroups(m.cli),
        cmdPollActive(m.cli), cmdPollMetrics(m.cli),
        cmdPollHistory(m.cli, client.HistoryFilter{Limit: 100}),
        cmdPollDevices(m.cli), cmdPollScanner(m.cli), cmdPollHunt(m.cli),
        cmdPollAudio(m.cli), cmdPollRuntime(m.cli),
        cmdMutationStatus(m.cli),
        connectSSE(m.cli),
    )
}

Each poll’s result message re-arms its own timer inside Update, so the fan is self-sustaining — there’s no central scheduler, just each stream keeping itself alive:

// internal/tui/app.go (shape) — inside Update
case pollActiveMsg:
    if msg.err == nil {
        m.shared.ActiveCalls = msg.calls
        m.shared.LastPoll = time.Now()
    } else {
        m.toast(fmt.Sprintf("active: %v", msg.err))
    }
    cmds = append(cmds, scheduleAfter(pollActiveEvery, cmdPollActive(m.cli)))

That “fold the result, then reschedule myself” shape repeats for every endpoint. The active-calls list refreshes on its own cadence, the systems list on its own, metrics on theirs — each an independent, self-healing loop. A poll error becomes a toast, not a crash, and the next tick tries again.

The SSE pump

Polling gives the console a steady heartbeat; the SSE stream gives it reactions. The TUI subscribes to GET /api/v1/events — the identical Server-Sent-Events feed the browser’s EventSource consumes — and parses it in Go. The parser is a faithful little SSE implementation: dispatch on a blank line, accumulate event: and data: fields, ignore : comments:

// internal/tui/client/sse.go (shape)
func (c *Client) Stream(ctx context.Context) (<-chan Event, <-chan error) {
    // …GET /api/v1/events with Accept: text/event-stream, no per-request timeout
    // parseSSE(resp.Body, out) → one Event per dispatched block
}

// The data line is itself a JSON envelope {kind, timestamp, payload};
// parseSSE decodes it and forwards the payload as Event.Raw so panels can
// type-decode it — the same envelope the web UI consumes.

Inside Update, a single event both lands in the ring buffers and triggers targeted refreshes — a call.start re-polls active calls, an sdr.attached re-polls devices — so the console reacts inside one SSE round-trip instead of waiting for the next poll tick:

// internal/tui/app.go (shape) — inside Update
case eventMsg:
    m.shared.EventLog.(*RingBuf[client.Event]).Push(msg.ev)
    switch msg.ev.Kind {
    case "call.start", "call.end":
        cmds = append(cmds, cmdPollActive(m.cli), cmdPollScanner(m.cli))
    case "sdr.attached", "sdr.detached":
        cmds = append(cmds, cmdPollDevices(m.cli))
    // …cchunt.*, cc.locked/lost, audio.state
    }
    cmds = append(cmds, listenSSE(m.eventCh)) // keep pumping

case sseDownMsg:
    m.sseRetries++
    backoff := min(1<<m.sseRetries * time.Second, 30*time.Second)
    m.toast("event stream disconnected — reconnecting in " + backoff.String())
    cmds = append(cmds, tea.Tick(backoff, func(time.Time) tea.Msg { return connectSSE(m.cli)() }))

The reconnection policy lives in the reducer, exactly as sse.go’s doc comment promises (“reconnection is the caller’s responsibility”): a dropped stream becomes an sseDownMsg, the retry count grows an exponential backoff capped at 30 s, and a toast tells the operator what’s happening. It’s the same jittered-backoff instinct the browser’s WebSocket clients use, expressed as Bubbletea messages.

SharedState and the panels

The reducer’s whole job is to keep one struct current. SharedState is the snapshot of daemon-derived data all panels read — the exact analogue of the browser’s shared store:

// internal/tui/state/state.go (shape)
type SharedState struct {
    Health      client.Health
    Systems     []client.SystemDTO
    Talkgroups  []client.TalkgroupDTO
    ActiveCalls []client.ActiveCallDTO
    Scanner     client.ScannerStatusDTO
    Runtime     client.RuntimeDTO
    EventLog    RingReader[client.Event]
    ToneAlerts  RingReader[client.Event]
    // …Devices, Hunt, Audio, Metrics, History + their *Err fields
    WriteEnabled bool                   // --write AND daemon capability
    Mutations    client.MutationStatus  // per-subsystem writability
}

The panels are correspondingly dumb — in the best way. The Dashboard panel is a pure renderer: it owns no local state and simply lays four cards over SharedState, collapsing the 2×2 grid to a vertical stack below 80 columns:

// internal/tui/panels/dashboard.go (shape)
type DashboardPanel struct{} // no fields — no state to get wrong

func (p *DashboardPanel) View(width, height int, _ bool, s *state.SharedState) string {
    if width < 80 { /* stack Health / Active / Events / Tones vertically */ }
    // …else a 2×2 grid of dashboardCard(...) over s
}

Because the snapshot is the single source and the panels don’t fetch, the panels compose trivially: Update forwards each message to the active panel after it has folded the poll/event data, so a panel always renders the freshest state. The root handles the cross-cutting concerns — window resize, quit, help, the command palette (ctrl+p), theme toggle (ctrl+t), and the numeric/tab panel jumps in keys.go — before a message ever reaches a panel.

Parity with the web is enforced

The series’ claim is “one API, two renderers,” and the TUI backs it with two concrete parity mechanisms rather than good intentions.

First, the same tabs hide in both UIs. The runtime snapshot carries the web.tabs hidden set, and visiblePanels filters the tab strip, cycling, jump keys, and mouse hit-testing off it — using the same keys the SPA uses (a panel’s Key() is its web route minus the leading slash):

// internal/tui/app.go (shape)
func (m *Model) visiblePanels() []state.PanelKind {
    hidden := setOf(m.shared.Runtime.HiddenTabs)  // same web.tabs keys as the SPA
    // …keep every panel whose Key() isn't hidden; never strand the operator
}

Second, the same capability gates writes. WriteEnabled is the AND of the TUI’s --write flag and the daemon’s /api/v1/mutations allow_mutations — the identical snapshot the browser reads in Part 10 — so a write keybinding either fires the same mutation the web console would, or shows a toast explaining exactly why it can’t. Neither UI can decide on its own what’s visible or writable; the daemon is the authority, and both renderers obey it. The finished terminal surface is documented on the TUI operator page.

Where this goes next

Part 13 digs into the one place the browser and terminal share more than an API — a single reflect-driven schema that generates the config editor for both the web form and a Bubbletea form, so the two config builders can’t drift from the struct or from each other.

FAQ

Does the TUI use a different backend than the web console? No. It calls the identical REST endpoints and consumes the identical SSE event stream (GET /api/v1/events) the browser uses. There’s no TUI-only API — it’s a second renderer over the same contract.

How does it stay live without a browser’s event loop? Bubbletea’s message loop plays that role. A fan of polling commands re-arm their own timers, and one long-lived SSE goroutine pushes events in as messages; the Update reducer folds both into SharedState. A dropped stream schedules a backoff reconnect.

Are the panels fetching data themselves? No — panels are pure renderers over SharedState. Only the root model fetches (via commands) and folds results into the snapshot; the active panel reads that snapshot to draw. It’s the terminal version of components reading a shared store.

Why do the same panels hide in the TUI and the web UI? Because both read the web.tabs hidden set using the same keys (a panel’s key is its web route). Hiding a tab in config removes it from the SPA nav and the TUI tab strip, so the two surfaces can’t disagree on what’s visible.

Can the TUI change the daemon, or is it read-only? It can write, but it’s gated: WriteEnabled is the AND of the --write flag and the daemon’s /api/v1/mutations capability — the same snapshot the browser uses. Without both, write keybindings show a “mutations disabled” toast instead of firing.

Series navigation

Part 12 of 14 · ← Part 11: The Mobile Shell, Command Palette & PWA · Next → Part 13: The Reflect-Driven Config Form

TL;DR: The Dockerfile is a two-stage, zero-CGO build — stage one compiles the daemon with CGO_ENABLED=0 (no C toolchain, no librtlsdr/libusb), stage two carries just the binary on debian:bookworm-slim as a non-root user. The hard part is USB: a dongle needs three things to work inside a container — host udev rules granting a non-root group access to the device node, a DVB blacklist so the kernel doesn’t claim it first, and container privileges that map the device (devices: / --device), join the right group (group_add), and add just DAC_OVERRIDE so the non-root user can open the node. The shipped docker-compose.yml does all of it — no --privileged required.

Key takeaways

• Zero CGO makes the image tiny and the build boring. No C libraries to install or link, so the runtime stage is a slim base plus one static binary and ca-certificates.
• USB access is the host’s job first. The udev rule and DVB blacklist are host configuration; no container flag can substitute for them.
• Map one device, not the whole bus. --device /dev/bus/usb/<bus>/<dev> gives the container exactly one dongle; /dev/bus/usb (or --privileged) is the over-broad shortcut to avoid.
• Least privilege still works. cap_drop: ALL plus cap_add: DAC_OVERRIDE and a group_add is enough for a non-root container user to claim the radio — you never need --privileged.

Cheat sheet

In this post

• The zero-CGO image — why the build is two short stages and a slim base.
• Why a container sees no radio — the boundary, stated plainly.
• The three requirements — udev, DVB blacklist, container privileges.
• Least privilege over --privileged — the capability that’s actually needed.
• Verifying the dongle crossed — the one command that proves it worked.

The zero-CGO image

Most SDR software drags a C toolchain and libusb/librtlsdr into its container, which makes the image large and the build fragile. GopherTrunk’s pure-Go design means neither. The Dockerfile is two stages: build, then carry the binary.

# Dockerfile (shape) — stage 1: pure-Go build, no C toolchain
FROM golang:1.25-bookworm AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download          # cache deps before the source
COPY . .
ARG VERSION=docker
ENV CGO_ENABLED=0
RUN go build -trimpath \
        -ldflags "-s -w -X .../internal/version.Version=${VERSION}" \
        -o /out/gophertrunk ./cmd/gophertrunk

# stage 2: carry only the binary on a slim base
FROM debian:bookworm-slim AS runtime
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates \
 && rm -rf /var/lib/apt/lists/*
RUN useradd --system --create-home --shell /usr/sbin/nologin gopher
USER gopher
COPY --from=builder /out/gophertrunk /usr/local/bin/gophertrunk
ENTRYPOINT ["/usr/local/bin/gophertrunk"]
CMD ["run", "-config", "/etc/gophertrunk/config.yaml"]

Three operating properties fall out of CGO_ENABLED=0. The runtime image needs no SDR system libraries — the daemon talks to the dongle through a pure-Go USBDEVFS backend, so there’s nothing to apt-get install but ca-certificates (for the outbound HTTPS the broadcast feeds need). The build caches cleanly — deps download in their own layer before the source is copied, so a code change doesn’t re-fetch the module cache. And the daemon runs as a non-root user (gopher) by default, which matters the moment we talk about USB permissions: the container user has to be granted device access, it doesn’t have it for free.

Why a container sees no radio

Here’s the boundary, stated plainly: a container gets its own device namespace, and by default that namespace contains no USB devices at all. The daemon inside can enumerate all it likes and find nothing, because /dev/bus/usb simply isn’t there. So “run it in Docker” for a scanner is really “run it in Docker and thread one physical dongle across the isolation boundary” — and that thread has three strands, two of which are host configuration that no container flag can replace.

The three requirements

The hardening guide and the Linux install guide spell these out; here they are as one operating checklist.

1. Host udev rules. The device node has to be openable by the group the container user will join. On the host:

# /etc/udev/rules.d/20-rtlsdr.rules
SUBSYSTEM=="usb", ATTRS{idVendor}=="0bda", ATTRS{idProduct}=="2838", \
    MODE="0660", GROUP="plugdev"

then sudo udevadm control --reload && sudo udevadm trigger and replug the dongle. This is host config — it sets the permissions on the node before it’s ever mapped into a container.

2. DVB blacklist. An RTL-SDR presents as a DVB-T TV tuner, and the kernel’s dvb_usb_rtl28xxu driver will grab it on plug-in. Stop that:

# /etc/modprobe.d/blacklist-dvb_usb_rtl28xxu.conf
blacklist dvb_usb_rtl28xxu

The daemon auto-detaches the DVB driver at open time, so this is belt-and-braces — but one less moving part, and on a headless box you want the device clean before the container ever touches it.

3. Container privileges. Now, and only now, the container flags matter. The shipped docker-compose.yml maps exactly one device, joins the host group, and adds exactly one capability:

# docker-compose.yml (shape)
services:
  gophertrunk:
    restart: unless-stopped
    devices:
      - "/dev/bus/usb/003/002:/dev/bus/usb/003/002"  # match your lsusb
    group_add:
      - "46"          # plugdev GID on Debian — check getent group plugdev
    cap_drop:
      - ALL
    cap_add:
      - DAC_OVERRIDE  # let the non-root user open the device node
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--spider", "http://127.0.0.1:8080/api/v1/health"]
      interval: 30s

devices: maps the specific node in; group_add: 46 puts the container’s non-root user in the same plugdev group your udev rule granted; cap_add: DAC_OVERRIDE lets that user open the node. That’s the complete recipe.

How that principle shaped the Go code

• The USBDEVFS backend needs no kernel driver. The daemon reads and writes /dev/bus/usb/<bus>/<dev> directly, which is exactly why mapping that node — not installing a driver in the container — is all it takes. The pure-Go transport and the container recipe are two sides of the same design choice.
• Non-root by default forces the permission story to be explicit. Because the image runs as gopher, not root, you can’t accidentally rely on root’s blanket device access; the udev group + DAC_OVERRIDE path is the only way in, and it’s the least-privilege one.
• ca-certificates is the only runtime dependency. It’s there for the outbound HTTPS the broadcast feeds (Parts 9–11) need — the SDR path pulls in nothing.

Least privilege over --privileged

The temptation, when a dongle won’t show up, is to reach for --privileged or to map all of /dev/bus/usb. Both work, and both are wrong for a service that runs for months: --privileged hands the container the entire host device space and most capabilities, turning a scanner into a much larger blast radius than a scanner needs. The recipe above proves you don’t have to. A cap_drop: ALL container with a single DAC_OVERRIDE and one mapped node can claim the radio and do nothing else — the daemon inside can’t touch another device, can’t load a module, can’t escalate. The broader /dev/bus/usb mapping is only for cases where the dongle’s bus/device path shifts on every replug and you can’t pin it; even then, prefer a udev SYMLINK and map the symlink over opening the whole bus.

One more operating wrinkle worth pre-loading: USB autosuspend. On a headless host the kernel may power-manage an idle-looking dongle mid-stream, which the daemon sees as usb: device disconnected. Pin it on the host with echo on > /sys/bus/usb/devices/<id>/power/control (or a udev TEST rule) so a long-running container stream isn’t cut by power management it can’t see.

Verifying the dongle crossed

After docker compose up -d, one command settles whether all three strands landed — you run the daemon’s own SDR enumeration inside the container:

docker exec gophertrunk gophertrunk sdr list
# should print the dongle: index, serial, tuner type, supported gains
curl -s http://localhost:8080/api/v1/health   # daemon serving

If sdr list shows the dongle, the whole chain is good: host permissions, device mapping, group, and capability. If it prints nothing, work the layers in order — check dmesg on the host for a DVB driver claim (blacklist didn’t take), ls -l /dev/bus/usb/... from inside the container (mapping or udev permission wrong), and getent group plugdev against your group_add GID (group mismatch). The compose healthcheck closes the loop for the orchestrator: it hits /api/v1/health every 30 seconds, so a daemon that wedges gets restarted by restart: unless-stopped without you watching — the containerized equivalent of the watchdog we reach in the finale.

Where this goes next

Containers are one way to run a service; a native system daemon is the other. Part 13 takes the same daemon to a hardened systemd unit — the sandboxing directives that box in a native process the way a container isolates a containerized one, including the DeviceAllow line that’s the systemd analogue of everything we just did — and to the Windows service, installer, and launcher for operators not on Linux at all.

FAQ

Do I need libusb or librtlsdr in the image? No. The build is CGO_ENABLED=0 and the daemon talks to the dongle through a pure-Go USBDEVFS backend, so the runtime stage carries only the static binary and ca-certificates. That’s the whole reason the image is small and the USB recipe is “map a device node,” not “install a driver.”

Why isn’t --privileged the simplest answer? It works but it’s the wrong trade for a months-long service — it grants the container the entire host device space and nearly every capability. A cap_drop: ALL container with one mapped node, a group_add, and DAC_OVERRIDE claims exactly one radio and nothing else. Least privilege costs three lines of config and bounds the blast radius.

My container’s sdr list is empty — where do I start? Layer by layer. dmesg on the host for a DVB driver claim (blacklist), ls -l /dev/bus/usb/... inside the container (device mapping + udev mode), and getent group plugdev against your group_add GID (group match). One of those three is almost always the culprit; the udev rule and blacklist are host config no flag can replace.

The stream drops after a while with device disconnected — why? USB autosuspend. The kernel power-manages a dongle it thinks is idle, which the daemon sees as a disconnect. Pin power on the host with echo on > /sys/bus/usb/devices/<id>/power/control or a udev rule so a long-running container stream isn’t cut by power management inside a namespace it can’t reach.

How does the orchestrator know the daemon is alive? The compose healthcheck polls /api/v1/health every 30 seconds; a failing probe plus restart: unless-stopped gets the container restarted automatically. That endpoint reports more than “process up” — attached SDR count, active calls, DB connectivity — which the finale (Part 14) uses to distinguish “running” from “actually working.”

Series navigation

Part 12 of 14 · ← Part 11: Grant Webhooks & External Integrations · Next → Part 13: systemd Hardening & the Windows Installer

TL;DR: On a busy P25 Phase 2 system most grants never get a voice tuner, and encrypted calls are torn down before hangtime — so the talker-alias decode wired inside the voice composer almost never runs (issue #376). internal/sigfollow fixes that by decoupling alias capture from voice following: a Manager subscribes to the bus, and for each in-window Phase 2 grant it borrows a signalling-only DDC tap on the wideband IQ broker, decodes the traffic channel’s MAC PDUs through the same MACDispatcher the voice composer uses, and publishes any completed talker alias. Two SDRs, no voice pool, aliases harvested off the signalling stream — mirroring how SDRTrunk does it. And when the alias is the proprietary Motorola FACCH-S kind, it harvests the ciphertext as cryptanalysis ground truth.

Key takeaways

• Alias capture is decoupled from voice. A signalling follow needs only to decode the MAC signalling on the traffic channel — no vocoder, no recording — so it runs on grants the voice pool never covers.
• One dispatcher, two callers. MACDispatcher is the exact decode the voice composer runs; the follower reuses it, so the two paths never diverge on what an alias means.
• RS parity gates trust. A mis-framed superframe decodes random bytes that almost never verify, so only an RS-valid PDU is trusted to set a call’s source — a wrong RID is worse than an absent one.
• The Motorola alias is still unread — so harvest the ciphertext. The proprietary alias cipher is unverified, so the decoded name is usually empty; the follower logs the reassembled ciphertext (paired with source RID and talkgroup) as the corpus the cryptanalysis needs.

Cheat sheet

In this post

• The alias that voice-following misses — why the composer’s decode rarely runs.
• A signalling-only follow — a tap, a dispatcher, an idle timer.
• The shared dispatcher — one decode for the composer and the follower.
• RS parity as a trust gate — why a wrong RID is worse than none.
• The ciphertext we can’t read — harvesting Mercury’s corpus.

The alias that voice-following misses

A P25 talker alias rides the traffic channel, interleaved with the voice as MAC signalling (FACCH-S). The obvious place to decode it is inside the voice composer — you’re already demodulating that channel to record the call, so read the alias while you’re there. And that works, when it runs. The problem is how often it runs. The package doc is blunt about it:

// internal/sigfollow/dispatcher.go (shape) — package doc
// On a busy multi-site Phase 2 system most grants never get a voice tuner (the
// voice pool can't cover the full voice spread), and encrypted calls are torn
// down before hangtime — so the talker-alias FACCH-S decode wired inside the
// voice composer almost never runs (issue #376). SDRTrunk harvests these aliases
// from the traffic channel's signalling stream with just two SDRs, without
// following the call as voice. This package mirrors that.

Two failure modes stack. First, the voice pool is finite: on a busy system there are more simultaneous calls than voice tuners, so most grants are never followed as voice at all, and their aliases are never seen. Second — and worse for the interesting traffic — encrypted calls are the ones most likely to be torn down before hangtime, and hangtime is exactly when the alias burst arrives. The result is that the aliases you most want ride right past a voice-only decoder.

The fix is to stop coupling the two. You don’t need to record a call to read its signalling — you only need to demodulate the channel’s MAC stream, which is far cheaper than running a vocoder. So GopherTrunk spins up a decode that does only that.

A signalling-only follow

sigfollow.Manager subscribes to the event bus and reacts to grants. For each in-window Phase 2 grant that isn’t already being followed and isn’t covered by a voice call, it borrows a signalling tap — a standalone wideband DDC tap that is not registered in the voice pool — and starts a follow:

// internal/sigfollow/manager.go (shape) — onGrant
func (m *Manager) onGrant(ctx context.Context, g trunking.Grant) {
    if g.Protocol != "p25-phase2" || g.FrequencyHz == 0 {
        return
    }
    m.mu.Lock()
    if _, following := m.active[g.FrequencyHz]; following {
        m.mu.Unlock(); return
    }
    if m.voiceFreqs[g.FrequencyHz] > 0 {
        m.mu.Unlock(); return // a voice chain already harvests aliases here
    }
    vt := m.allocTunerLocked(g.FrequencyHz) // free tap whose window covers the grant
    if vt == nil {
        m.mu.Unlock(); return // outside every tap's window, or all taps busy
    }
    fctx, cancel := context.WithCancel(ctx)
    m.active[g.FrequencyHz] = cancel
    m.mu.Unlock()
    m.wg.Add(1)
    go m.follow(fctx, vt, g)
}

The follow goroutine tunes the tap to the grant frequency, opens its IQ stream, builds a Phase 2 receiver, and pipes decoded superframes into a MACDispatcher. Crucially, it carries the grant’s own Phase 2 FEC configuration — trellis, RS, interleave, scrambler mode, seed, soft-decision — so it decodes the traffic channel with exactly the same parameters the control channel stamped onto the grant:

// internal/sigfollow/manager.go (shape) — follow
macCfg := p25p2.MACDecodeConfig{
    Trellis: p25p2.TrellisMode(g.P25Phase2Decode.Trellis),
    RS:      p25p2.RSMode(g.P25Phase2Decode.RS),
    // …Interleave, Scrambler, Seed, SoftDecision, Equalizer — all from the grant
}
dispatcher := NewMACDispatcher(MACDispatcherOptions{
    Bus: m.bus, System: g.System, Serial: vt.Serial(), LogPrefix: "sigfollow",
    // No OnCallSource / OnCallEncryption: a signalling follow has no bound call to
    // backfill, so it harvests talker aliases only.
})

The follow ends on one of three bounds: an idle timeout (4 s of no decoded superframe — the call dropped, and aliases arrive within a few seconds of voice end, so a short idle covers the gap), a max duration cap (30 s, so a stuck decode can’t pin a tap forever), or context cancellation. That last one is how the system yields gracefully: if a voice chain later starts recording the same frequency, onVoiceStart cancels the redundant signalling follow because the voice chain harvests aliases itself. No frequency is ever decoded twice for the same reason.

The shared dispatcher

The follow doesn’t reimplement alias decoding — it can’t be allowed to, because then the aliases harvested off a traffic channel might disagree with the ones the voice composer reads on the same channel. Both drive the same MACDispatcher, which decodes every MAC PDU in a superframe and routes it: a group-voice PDU carries the source RID, a MAC-PTT slot carries the encryption sync, and the alias fragments reassemble into a name. The follower simply leaves the call-bound hooks (OnCallSource, OnCallEncryption) nil, because a signalling follow has no bound call to backfill — it publishes talker aliases and nothing else. One decode, two callers, guaranteed agreement.

How that principle shaped the Go code

• The dispatcher is stateful per channel, so construct one per follow. The alias assemblers buffer fragments per source unit for the life of the channel; a fresh dispatcher per follow means a new call never inherits a stale half-alias.
• Hooks, not branches, carry the difference. The composer wires OnCallSource/OnCallEncryption to its engine-backfill publishers; the follower passes nil. The decode is identical — only what happens to a call-bound PDU differs, and that’s a function pointer, not a code path.
• The follower borrows taps, it doesn’t own SDRs. Signalling taps are DDC taps on the wideband IQ broker — the same virtual-tuner mechanism the wideband engine uses — so alias harvesting rides existing hardware, not a dedicated radio.

RS parity as a trust gate

There is a sharp edge here that the code handles carefully. A mis-framed Phase 2 superframe doesn’t fail loudly — it decodes a stream of random bytes, and an opcode byte that happens to land on the group-voice value would inject a plausible-but-wrong source RID. That RID is indistinguishable downstream from a real one, and it would poison the completed-call metadata. The only signal that separates a genuine PDU from garbage is the outer Reed–Solomon parity, so the dispatcher gates on it:

// internal/sigfollow/dispatcher.go (shape) — Dispatch, group-voice PDU
if u, ok := pdu.AsGroupVoiceChannelUser(); ok {
    // The outer RS parity is the only signal that separates a genuine
    // GROUP_VOICE_CHANNEL_USER from garbage (the opcode alone can't), so only an
    // RS-verified PDU is trusted to set the call's source. A wrong RID is worse
    // than an absent one (issue #915).
    if dec.RSValid && d.onCallSource != nil {
        d.onCallSource(u)
    }
    continue
}

Dispatch returns both a decoded-PDU count and an RS-valid count, and a caller feeds that ratio into a per-call census: on a correctly framed, descrambled channel nearly every PDU verifies, whereas rs_valid=false across the board is the fingerprint of a mis-framed superframe rather than an unhandled opcode. It’s the same discipline the naming post drew for talkgroups — refuse to assert what you can’t verify — applied to a single source RID.

The ciphertext we can’t read

And then there is the alias GopherTrunk reassembles perfectly and still can’t read. The real Motorola FACCH-S alias runs through a proprietary per-byte cipher, and that cipher is unverified — motorola.CipherVerified is false — so the decoded name comes out empty on real traffic. Rather than throw the burst away, the follower harvests the ciphertext:

// internal/sigfollow/dispatcher.go (shape) — completeMotorolaAlias
func (d *MACDispatcher) completeMotorolaAlias(res p25p2.MotorolaAliasResult) {
    if len(res.Encoded) > 0 {
        d.log.Info(d.logPrefix+": p25p2 alias ciphertext",
            "system", d.system, "serial", d.serial,
            "rid", res.SourceID, "talkgroup", res.TalkgroupID,
            "encoded_hex", hex.EncodeToString(res.Encoded),
            "crc_ok", res.CRCOK, "reliable", res.Reliable)
    }
    d.publishTalkerAlias(res.SourceID, res.Alias, res.Reliable) // empty until the cipher is cracked
}

That log line is the whole point. The reassembled ciphertext — the encoded alias bytes paired with the known source RID and talkgroup — is exactly the record the cipher cryptanalysis needs, and the repo’s chosen-plaintext capture procedure names GopherTrunk as a valid capture receiver. Surfacing it here means an operator can harvest the rid,talkgroup,encoded_hex,alias corpus from live air with GopherTrunk alone, instead of falling back to SDRTrunk. This is the same emitter the Protocol Decoders series planted as its central mystery — the field that reassembles cleanly and decodes to noise — and the same one the Crypto Lab series calls Mercury. The hunt doesn’t crack it; it feeds the machine that will.

Where this goes next

We’ve now pulled everything the air will give us: a mapped, named system, activity counts, whatever aliases and ciphertext its traffic carried. The find is complete. Part 13 is about getting it out — exporting the DiscoveredSystem to a RadioReference submission package, a TrunkRecorder config, GopherTrunk’s own import bundle, and a SigMF-tagged capture bundle — so the work leaves your machine.

FAQ

Why not just decode aliases inside the voice recorder? Because on a busy system most grants never get a voice tuner, and encrypted calls — the interesting ones — are torn down before the hangtime alias burst. A voice-only decode misses the aliases you most want. A signalling follow decodes the MAC stream without recording, so it runs on grants the voice pool never covers.

Does harvesting aliases need extra hardware? It needs a signalling tap, which is a DDC tap on an existing wideband IQ broker — the same virtual-tuner mechanism the wideband engine uses — not a dedicated radio. Two SDRs can run a whole system’s control-plus-signalling harvest, which is how SDRTrunk does it too.

Why gate the source RID on RS parity? A mis-framed Phase 2 superframe decodes random bytes, and a stray opcode match would inject a wrong-but-plausible RID that’s indistinguishable downstream from a real one. Only the outer RS parity separates a genuine PDU from garbage, so only an RS-verified PDU sets a call’s source. A wrong RID is worse than none.

Why does a Motorola alias come out empty? Its per-byte cipher is unverified (motorola.CipherVerified is false), so the decode can’t be trusted to produce a real name. Rather than emit a wrong one, the follower publishes an empty alias and logs the reassembled ciphertext — the corpus the cryptanalysis needs. It’s the Mercury cipher from the decoder and crypto series.

What stops two decoders fighting over one frequency? The manager tracks active follows and voice-followed frequencies. A grant already being followed is ignored; a grant on a voice-followed frequency is skipped; and onVoiceStart cancels a signalling follow the moment a voice chain takes the same channel, because the voice chain harvests aliases itself.

Series navigation

Part 12 of 14 · ← Part 11: Naming the Unknown · Next → Part 13: Exporting Your Finds — RadioReference, TrunkRecorder, SigMF

TL;DR: Radio IDs populated fine, but the talker alias stayed blank for every radio — while SDRTrunk showed aliases on the same system, even on encrypted calls. Three successive transport theories (standard voice LCOs, a control-channel vendor TSBK, a speculative Phase 2 opcode) each shipped a decoder for a message format that doesn’t exist on air. A per-(opcode, MFID) census with raw payload dumps proved the alias was not on the control channel; SDRTrunk’s decode logs then pinned the two real transports. The final root cause was architectural: alias decode lived inside the voice composer, so it only ran when a call won a voice tuner — which, on a busy system, almost never happens. The fix was a signalling-only follower that decodes traffic-channel signalling without following the call as voice.

Cheat sheet

In this post

• The report — a modest feature request becomes a month-long hunt.
• Three wrong transports — three shipped decoders for messages that don’t exist on air.
• Detours that paid rent — the fictional OpMACPTT and the dead Phase 2 path.
• The diagnostic that cracked it: a census, then the bytes — instrumenting instead of guessing.
• Ground truth from another decoder — SDRTrunk’s logs pin both real transports.
• The real root cause was architectural — metadata welded to media capture.
• The fix: a signalling-only follower — decoding signalling without following voice.
• What we keep — the durable rules and their Field Guide entries.

The report

The issue opened modestly: source RIDs were showing up in grant payloads (TG 20202 ← 207545), could radios become first-class entities with alias support? The entity work shipped quickly — an alias table, /api/v1/rids endpoints, a Radio IDs panel. Then the field note that turned a feature request into a month-long hunt:

SDRTrunk currently displays Talker Alias on MMR, including encrypted Ambulance talkgroups.

The aliases were on the air. RID tracking confirmed the plumbing worked — one radio showed 18 observed calls with its last talkgroup — but talker_alias stayed blank for every radio, run after run, build after build. Something was transmitting aliases that GopherTrunk structurally could not see.

Three wrong transports

The hunt shipped three alias decoders before discovering none of them matched the air.

Theory 1: the standard voice-channel LCOs. TIA-102.AABF defines talker-alias link-control opcodes 0x15/0x16/0x17 on the voice channel. A reassembler for the standard form landed and produced nothing — the field test showed RIDs populating and aliases blank. Motorola systems don’t use the standard form.

Theory 2: the Motorola voice-LC form — plus a control-channel working model. The next round implemented Motorola’s vendor variant (LCO 0x15 header + 0x17 data blocks, MFID 0x90) on the LDU1 voice path, alongside a working model that assumed a plain-ASCII vendor TSBK on the control channel. Zero fragments were ever observed — including on the clean site where decode quality was excellent, which mattered: a missing message on a clean channel is evidence about the transport, not the RF.

Theory 3: a speculative Phase 2 opcode. The Phase 2 MAC path carried an alias placeholder keyed to opcode 0x82 with plain-ASCII payloads — a guess, and another decoder for a message nobody transmits.

Each theory was plausible, each shipped with passing tests, and each was falsified only by field data. The common flaw: all three described what the alias might look like, with no captured bytes saying what it did look like.

Detours that paid rent

Two side discoveries along the way were real bugs in their own right:

• OpMACPTT was a fiction. The Phase 2 MAC dispatcher named opcode 0x01 “MAC PTT” — a constant that exists in no spec. Opcode 0x01 is GROUP_VOICE_CHANNEL_USER_ABBREVIATED, the in-call broadcast carrying the source RID and service options on the traffic channel. Real PDUs were being parsed as “MAC PTT” and discarded, which is why encrypted-talkgroup grants surfaced as src=0 enc=false while SDRTrunk showed both correctly. Fixing it required a KindCallSourceUpdate backfill path so metadata arriving mid-call patches the active call.
• The Phase 2 alias path was dead code on hybrid systems. MMR runs a Phase 1 control channel with Phase 2 TDMA traffic channels — the most common P25 hybrid layout. The Phase 1 CC tagged every grant Protocol="p25", so the composer never entered the Phase 2 voice chain at all: none of the newly added MAC dispatch ever executed. The fix propagates an AccessTDMA flag from the TDMA identifier update through the band plan, so TDMA-channel grants publish as p25-phase2 with their scrambler seed derived from (WACN, SystemID, NAC).

Both were found because the reporter grepped for the promised log lines and reported their absence — a null result stated precisely enough to act on.

The diagnostic that cracked it: a census, then the bytes

After three wrong transports, the next step was deliberately not a fourth theory. It was instrumentation: one Info line per distinct (opcode, MFID) pair the control channel emits that GopherTrunk doesn’t dispatch —

p25: unhandled tsbk mfid=144 opcode=Opcode(16) nac=353
p25: unhandled tsbk mfid=0 opcode=Opcode(30) nac=353

— followed, one round later, by raw payload dumps capped at 8 samples per pair:

p25: unhandled tsbk payload mfid=144 opcode=0x16 lb=false payload=c23f3040ffff0000 nac=353

Two implementation details mattered more than they look. First, the census prints the numeric opcode, because Go’s stringer had been mislabeling vendor opcodes with standard-namespace names — Motorola opcode 0x15 printed as UnitToUnitAnswerRequest, sending everyone reading the logs down the wrong row of the wrong table. Second, the payloads could be cross-checked against ground truth: SDRTrunk supplied known RID↔alias pairs (202438 MBR02 2438, 206806 AGP 6806, 203530 ZR5 3530), and the Motorola alias format embeds the 24-bit RID — so printf '%06x' turned each known radio into a grep pattern (202438 → 031ad6).

The census answered the question definitively, in both directions:

• No alias anywhere on the control channel. No payload contained a known RID or alias ASCII. A control-channel mfid=0 opcode=0x15 hit turned out to be SNDCP_DAT_PAGE_REQ — same number as the alias LCO, unrelated namespace, pure red herring.
• Two of the unknown opcodes were decodable wins. Motorola MFID 0x90 opcodes 0x02 and 0x03 decoded as patch-group voice grants — e.g. payload 401001006904e2cc carried the encryption bit, a channel, super-group 105, and source RID 320204. GopherTrunk had been silently dropping those calls; wiring them through the grant path (PR #692) fixed src=0 enc=false on patch calls and made the super-group traffic followable.

A diagnostic built to find one thing found two others and ruled out a theory — the hallmark of instrumenting instead of guessing.

Ground truth from another decoder

With the control channel exonerated, the reporter went to SDRTrunk’s decode logs on the same system — roughly 600 alias-bearing traffic-channel messages per hour — and came back with the actual bytes of both real transports:

NAC:361/x169 TDULC MOTOROLA TALKER ALIAS HEADER TG:30583 SEQUENCE:9 BLOCKS TO FOLLOW:7
    FORMAT:1-UNICODE MSG:159077770701009902
TS1 FACCH-S HANGTIME MOTOROLA TALKER ALIAS HEADER TG:20208 RADIO:ISSI 781824.356.200062
    SEQUENCE:0 BLOCKS TO FOLLOW:2 FORMAT:1-UNICODE MSG:9190114EF002010006BEE00164030D7E24CC8

Two details explain months of confusion. The Phase 1 alias rides the terminator — a decoder that only scans LDU1 link control returns before ever seeing it. And the consistent BEE00164… prefix in every fragment is not noise: it’s the system’s own identity (WACN BEE00, SysID 164) leading the encoded frame. The aliases decode on encrypted calls because the alias link control sits entirely outside the AES voice payload.

The real root cause was architectural

Even with the correct transports known, one more test run produced zero aliases — voice chains started, calls followed, nothing else. The reporter then read the source and found the actual root cause, and it wasn’t a parser:

Alias decode lived inside the voice composer. The FACCH-S dispatch ran only when a grant was followed to a voice tuner and the Phase 2 voice chain spun up. On a busy multi-site system that gate almost never opens:

• most grants get no voice device available — the voice pool can’t cover the system’s full frequency spread, so the composer never runs for them;
• encrypted calls are torn down at reason=encrypted the moment encryption is detected — before hangtime, which is exactly when the alias is transmitted;
• and even clear, fully followed calls surfaced no FACCH signalling decode.

SDRTrunk harvests aliases from the traffic channel’s signalling stream, without following the call as voice — which is why it collects them across a busy system with two dongles, encrypted or not. GopherTrunk had welded metadata extraction to media capture, so the metadata inherited every constraint of recording: tuner availability, encryption policy, call priority. The blank column was never a decode bug. It was a dependency graph bug.

The fix: a signalling-only follower

PR #762 landed internal/sigfollow: a follower that subscribes to the event bus and, for each in-window Phase 2 grant, opens a signalling-only DDC tap on the wideband IQ broker — decoding FACCH-S MAC PDUs and publishing aliases with no voice tuner, no audio path, and no interaction with the encrypted-call teardown.

The design points that made it stick:

• One dispatcher, two callers. The FACCH-S MAC dispatch (alias reassembly plus the per-PDU census) became a shared MACDispatcher used by both the voice composer and the follower, so the two paths cannot drift apart on what they decode.
• Opt-in and bounded. signalling_taps: N per role: wideband device (0 disables; 2–4 suits a busy multi-site system); each tap is an independent DDC, so cost scales linearly and visibly.
• No double work. Per-frequency dedupe plus a voice-call skip mean a channel already being recorded isn’t followed twice.
• Fail-safe by default. The FACCH-S bit packing was still unverified against captures when the follower shipped, so the decoder publishes nothing unless the frame yields a coherent radio identity — a wrong offset produces silence, not a garbled alias bound to a real radio.

Decoded aliases bind onto the RID through the existing affiliation tracker, so the column the issue opened about fills in with no further wiring.

What we keep

• Never gate metadata extraction behind media capture. Identity, encryption state, and aliases ride signalling; if decoding them requires winning a voice tuner, a busy system guarantees you lose them. The follower pattern and the encrypted-hangtime interaction are written up in encrypted call handling.
• When theories keep missing, stop theorizing and take a census. One log line per unhandled (opcode, MFID) plus capped payload dumps falsified a theory, found two droppable-call bugs, and named the next step — the pattern is in the diagnostic playbook.
• Log numeric opcodes. A stringer that maps vendor opcodes onto standard-namespace names is actively misleading; 0x15 meant three different things in this one thread.
• Another decoder’s output is legitimate ground truth. SDRTrunk’s decode logs pinned both real transports — TDULC and FACCH-S — after three GopherTrunk decoders had been written for formats that don’t exist on air. The system-identity fields that anchored the fragments (WACN | SysID | RID) are covered in P25 site identity semantics.
• A precise null result is a contribution. “The promised log line did not fire” found dead code twice. Grep patterns belong in the fix announcement, so the field tester can report absence as sharply as presence.

FAQ

Why could SDRTrunk see aliases GopherTrunk couldn’t? It harvests them from the traffic channel’s signalling stream without following the call as voice. GopherTrunk’s alias decode was gated behind winning a voice tuner — a gate that a busy multi-site system keeps closed for most grants, and that the encrypted-call teardown slams shut before hangtime, which is exactly when the alias is transmitted.

Why do talker aliases work on encrypted calls at all? The alias link control rides outside the AES voice payload. Encryption protects the speech; the signalling around it — including the Motorola alias header and data blocks — stays decodable, which is why SDRTrunk showed aliases on encrypted ambulance talkgroups.

Why did three plausible transport theories all miss? All three described what the alias might look like with no captured bytes saying what it did look like. The standard TIA forms aren’t what Motorola systems transmit; the vendor form doesn’t ride LDU1 or the control channel. The Phase 1 alias rides the terminator (TDULC) and the Phase 2 alias rides FACCH-S during hangtime — neither of which the shipped decoders ever looked at.

What did the census find besides ruling out the control channel? Two real bugs. Motorola MFID 0x90 opcodes 0x02/0x03 decoded as patch-group voice grants that GopherTrunk had been silently dropping, and the payload dumps exposed that Go’s stringer was mislabeling vendor opcodes with standard-namespace names — which is why the census prints numeric opcodes.

Does the follower double-decode channels that are already being recorded? No. Per-frequency dedupe plus a voice-call skip mean a channel already followed as voice isn’t tapped twice, and signalling_taps: N bounds the total cost per wideband device.

Series navigation

Part 2 of 22 · ← Part 1: The First P25 Lock — Eleven Fixes Between ‘Trying’ and ‘Locked’ · Next → Part 3: Encrypted, Says Who — Four Layers Between a Flag and Its Metadata

TL;DR: One AppShell renders four navigation surfaces — a desktop sidebar, a mobile top bar, a mobile bottom nav, and a full drawer — all driven by a single nav registry, so every panel is reachable on every device. A global ⌘K / Ctrl-K command palette fuzzy-jumps to any panel and is the discovery safety net for the deep ones. The SPA ships as an installable PWA: Vite’s PWA plugin emits a manifest and a Workbox service worker that precaches the whole bundle for offline-first loading — with a navigate-fallback denylist so the console’s service worker never shadows the daemon’s sibling apps (Config Builder, Signal Lab, RF Scope, Crypto Lab).

Key takeaways

• One shell, four nav surfaces. AppShell composes a sidebar, top bar, bottom nav, and drawer; all four read the same registry, so a hidden or new tab appears consistently everywhere.
• The command palette is the universal shortcut. ⌘K opens a fuzzy switcher over every nav item — the fastest path to any panel, and how the deep panels stay discoverable without cluttering the primary nav.
• The console installs like an app. Vite-Plugin-PWA emits the manifest and a Workbox SW that precaches the bundle, so it opens instantly and runs offline (the connect screen still needs a live daemon).
• The service worker knows its lane. A navigate-fallback denylist keeps the main console’s SW from answering /config/, /siglab/, /rfscope/, /cryptolab/, or /api/ with its own cached index.html.

Cheat sheet

In this post

• One shell, four nav surfaces — desktop and phone from one layout.
• The registry as the single source — why nav is data, not markup.
• The command palette — ⌘K, fuzzy ranking, keyboard-first.
• Installing as a PWA — manifest, precache, offline-first.
• The denylist — how the service worker avoids shadowing siblings.

One shell, four nav surfaces

AppShell is pure chrome. It owns no connection or data state — it composes the navigation surfaces around whatever page the router hands it as children, and manages exactly three bits of local UI state: the drawer, the palette, and the sidebar’s collapsed flag.

// web/src/components/shell/AppShell.tsx (shape)
export function AppShell({ children }: Props) {
  const [drawerOpen, setDrawerOpen] = useState(false);
  const [paletteOpen, setPaletteOpen] = useState(false);
  const isDesktop = useIsDesktop();

  // Global ⌘K / Ctrl-K toggles the palette from anywhere.
  useEffect(() => { /* window keydown → setPaletteOpen(o => !o) */ }, []);
  // The drawer is mobile-only; close it if the viewport grows to desktop.
  useEffect(() => { if (isDesktop && drawerOpen) setDrawerOpen(false); }, [isDesktop, drawerOpen]);

  return (
    <div className="min-h-full flex">
      <Sidebar collapsed={collapsed} onToggleCollapse={toggleCollapse} /> {/* desktop */}
      <div className="flex-1 flex flex-col min-w-0">
        <TopBar onOpenMore={() => setDrawerOpen(true)} onOpenPalette={() => setPaletteOpen(true)} />
        <main id="main" className="flex-1 p-3 sm:p-4 pb-24 sm:pb-4">{children}</main>
      </div>
      <BottomNav onOpenMore={() => setDrawerOpen(true)} />       {/* mobile */}
      <MobileDrawer open={drawerOpen} onClose={() => setDrawerOpen(false)} />
      <CommandPalette open={paletteOpen} onClose={() => setPaletteOpen(false)} />
      <ToastViewport />
    </div>
  );
}

The responsiveness is entirely Tailwind breakpoints, not JS branching: the Sidebar is hidden below sm, the BottomNav and TopBar hamburger are hidden at sm and up. The same DOM serves both; CSS decides which surface shows. That’s why a phone rotating to landscape, or a browser window growing, just works — and why the drawer-close effect exists at all, to tidy up the one case CSS can’t (a mobile-only overlay left open when the viewport crosses into desktop).

Note the accessibility bones baked into the frame: a “Skip to content” link that appears on focus, a semantic <main id="main">, and pb-24 bottom padding so the fixed bottom nav never covers the last row of a scrolling panel. The shell is small, but it carries the whole app’s keyboard and screen-reader story.

The registry as the single source

None of these four surfaces hard-code a list of panels. They all read a shared nav registry, and each surface asks it a slightly different question. The bottom nav takes the primary items and filters hidden ones:

// web/src/components/shell/BottomNav.tsx (shape)
export function BottomNav({ onOpenMore }: Props) {
  const hidden = new Set(useShared((s) => s.hiddenTabs));
  const items = PRIMARY_ITEMS.filter((i) => !hidden.has(tabKey(i)));
  // …render four primaries + a fifth "More" button that opens the drawer
}

The drawer asks for the grouped view (useVisibleNavGroups), the palette asks for the flat visible list (useVisibleNavItems), and the top bar looks up the current route’s label in NAV_ITEMS. One data source, four projections. The payoff is the same one the whole series keeps hitting: a tab hidden via config (web.tabs) disappears from every surface at once, and a new panel is a new registry entry, not four edits. It’s the exact discipline the TUI applies to its own tab strip — the same web.tabs keys hide a panel in both UIs, a thread we pick up in Part 12.

The command palette

The palette is the fastest path to any panel and the discovery net for the deep ones — the panels that don’t earn a slot in the primary nav still turn up the moment you type. It’s a ⌘K-triggered dialog over the flat visible nav list, with arrow keys to move, Enter to activate, Escape to close, and a focus trap so the keyboard stays inside it:

// web/src/components/CommandPalette.tsx (shape)
export function CommandPalette({ open, onClose }: Props) {
  const items = useVisibleNavItems();
  const results = useMemo(() => filterItems(items, query), [items, query]);
  // …ArrowUp/Down move `active`; Enter → choose(results[active]); Esc closes
  function choose(item) {
    onClose();
    if (item.external) window.open(item.to, "_blank", "noopener");
    else navigate(item.to);
  }
}

// filterItems ranks: label startsWith (3) > label includes (2) > keyword hit (1).
function filterItems(items, query) {
  // …empty query returns everything in registry order; else score + sort desc
}

The ranking is intentionally simple and predictable: a label that starts with your query beats one that merely contains it, which beats a keyword match. Empty query lists everything in registry order, so ⌘K with no typing is a full index. External items (the sibling consoles) open in a new tab; internal ones navigate in place. It’s a small component, but it’s the single control that makes a twenty-something-panel console feel small — you never hunt through nav, you type two letters.

Installing as a PWA

The console is a static bundle with no runtime Node dependency and no CDN fetches, which is exactly what makes it installable. Vite-Plugin-PWA emits the manifest and a Workbox service worker at build time:

// web/vite.config.ts (shape)
VitePWA({
  registerType: "autoUpdate",
  manifest: {
    name: "GopherTrunk", short_name: "GopherTrunk",
    display: "standalone", start_url: "./", scope: "./",
    theme_color: "#0f172a", background_color: "#0f172a",
    icons: [ /* favicon.svg, purpose any + maskable */ ],
  },
  workbox: {
    // Precache the whole SPA so it installs offline-first and loads instantly.
    globPatterns: ["**/*.{js,css,html,svg,png,ico,webmanifest}"],
    navigateFallbackDenylist: SW_NAVIGATE_FALLBACK_DENYLIST,
  },
});

display: "standalone" and the relative start_url/scope are what let a phone “Add to Home Screen” the console and launch it chromeless, pointed at whatever daemon it was installed from. The Workbox globPatterns precache the entire bundle, so the UI itself loads instantly and works without a network round-trip for its assets — the connect screen still needs a live daemon to do anything useful, but the app is always there. The base path defaults to ./, so the same dist/ works opened via file://, hosted at a static path, or rooted at /. One build, every deployment shape.

How that principle shaped the front-end

• Everything is inlined at build. No CDN scripts, no external fonts — the precache list is meaningful because the whole app is genuinely self-contained.
• autoUpdate keeps installs fresh. A new daemon build ships a new SW that updates the installed app on next load, so a field phone doesn’t drift.
• API responses are never cached. The SW precaches assets only; /api/* and /metrics are always fetched live, so the console never shows stale daemon state from a cache.

The denylist: knowing its lane

There’s a sharp edge to a service worker scoped at /: by default its navigateFallback answers any navigation with the cached index.html. But the daemon mounts sibling consoles at subpaths — Config Builder at /config/, Signal Lab at /siglab/, RF Scope at /rfscope/, Crypto Lab at /cryptolab/. Without a guard, opening one of those in a new tab would get the main console’s index.html, and the tab would boot at a route React Router doesn’t know — a blank page. The denylist is the fix:

// web/src/lib/swDenylist.ts (shape)
export const SW_NAVIGATE_FALLBACK_DENYLIST: RegExp[] = [
  /^\/api\//, /^\/metrics/,
  /^\/config\//, /^\/siglab\//, /^\/rfscope\//, /^\/cryptolab\//,
];

Any navigation matching one of these is not served the main SPA’s fallback — it goes to the network, so the sibling app loads. This list is kept in sync with the external console links in the nav registry, and a unit test (swDenylist.test.ts) enforces that sync so a new sibling console can’t be added without teaching the service worker to stay out of its way. It’s a tiny file that encodes an important boundary: one console’s offline cache must never eat another console’s front door.

Where this goes next

Part 12 leaves the browser entirely for the terminal — the Bubbletea TUI that drives the same REST + SSE API from an SSH session. It’s the other half of the series’ through-line made concrete: an Elm-model reducer, a polling fan plus an SSE pump, and a tab strip that hides the same panels the web web.tabs config hides here.

FAQ

How does the same UI serve a desktop and a phone? AppShell renders all four navigation surfaces into one DOM; Tailwind breakpoints show the sidebar on desktop and the top bar + bottom nav + drawer on mobile. There is almost no JS branching — CSS decides which surface is visible, so resizing or rotating just works.

What powers the command palette? The shared nav registry. ⌘K opens a fuzzy quick-switcher over every visible nav item, ranked by how the query matches the label (startsWith > includes > keyword). It’s the fastest route to any panel and how the deep panels stay discoverable.

Does the PWA work offline? The app shell does — Workbox precaches the whole bundle, so the console loads instantly and runs without a network round-trip for its assets. But it’s an operator console for a live daemon: the connect screen still needs a reachable daemon to show real data. API responses are never cached.

Why is there a service-worker denylist? Because the console’s SW is scoped at /, and the daemon mounts sibling apps at /config/, /siglab/, /rfscope/, /cryptolab/. The denylist stops the SW from answering those navigations (and /api/, /metrics) with its own cached index.html, which would otherwise open those tabs blank.

Can I install it pointed at any daemon? Yes — start_url/scope are relative (./), so installing from a given daemon’s web console launches the app pointed back at that daemon. The bundle is fully self-contained, so it also works served from any static path or even file://.

Series navigation

Part 11 of 14 · ← Part 10: Write Mode — Mutating Config Safely · Next → Part 12: The TUI Cockpit — The Same API in Your Terminal

TL;DR: Five backends, five wire protocols behind one Send(ctx, *Call) error interface. Broadcastify is a two-step handshake: POST metadata, get a one-time upload URL, PUT the MP3 to it. RdioScanner and OpenMHz are single multipart/form-data POSTs built by a shared buildMultipart helper. Icecast is different in kind — a persistent, paced source socket topped up with pre-encoded silence so it never starves. The webhook is a stable JSON schema, audio opt-in. All five are verified end to end with httptest servers, in-memory WAVs, and a temp SQLite call log — no CGO, no network, no fixtures.

Key takeaways

• Broadcastify uploads in two steps because the audio never touches the API host: the metadata POST returns a one-time URL (often on object storage) that the MP3 is PUT to directly.
• RdioScanner and OpenMHz share the multipart machinery but not the field names — buildMultipart writes the body, each backend supplies its own field set (RdioScanner’s key/system/dateTime, OpenMHz’s source_list/patch_list).
• Icecast is a live stream, not an upload. A background goroutine holds a source connection open and a ticker writes paced chunks; between calls it cycles one second of pre-encoded silence so the server never times the source out.
• The whole system is pure Go. MP3 encode, WAV I/O, and SQLite are all CGO-free, so the tests run the real encode/decode/persist path in memory against httptest backends — the strongest possible evidence the wire formats are right.

Cheat sheet

In this post

• Broadcastify — why one upload is two HTTP round trips.
• RdioScanner & OpenMHz — one multipart helper, two field vocabularies.
• Icecast — a paced source connection kept alive with cycled silence.
• The webhook — a stable JSON schema and a call-type classifier.
• The pure-Go coda — how zero-CGO makes the whole path testable in memory.

Broadcastify: two round trips for one upload

Every other audio backend POSTs the MP3 in a single request. Broadcastify Calls splits the upload in two, and the reason is architectural: the API host answers metadata, but the audio goes somewhere else — typically object storage behind a signed, one-time URL. So Send does a metadata POST first, reads back a URL, and PUTs the audio to it:

// internal/broadcast/broadcastify.go (shape)
func (b *broadcastifyBackend) Send(ctx context.Context, c *Call) error {
    audio, err := c.MP3()
    if err != nil {
        return fmt.Errorf("%s: encode mp3: %w", b.name, err)
    }
    uploadURL, err := b.requestUploadURL(ctx, c) // step 1: metadata POST
    if err != nil {
        return err
    }
    return b.putAudio(ctx, uploadURL, audio) // step 2: PUT to the one-time URL
}

Step one, requestUploadURL, is a application/x-www-form-urlencoded POST carrying apiKey, systemId, callDuration, ts (the Unix start time), tg, src, and freq. The API answers with a small text body, and parseBroadcastifyUploadURL teases the URL out of it:

// internal/broadcast/broadcastify.go (shape)
func parseBroadcastifyUploadURL(body string) (string, error) {
    fields := strings.Fields(strings.TrimSpace(body))
    if len(fields) == 0 {
        return "", errors.New("broadcastify: empty metadata response")
    }
    if fields[0] == "0" && len(fields) >= 2 {
        return fields[1], nil // "0 <url>" — success + the upload URL
    }
    if strings.HasPrefix(fields[0], "http") {
        return fields[0], nil // bare URL
    }
    return "", fmt.Errorf("broadcastify: metadata response rejected: %s", body)
}

The "0 <url>" convention — a 0 status token, whitespace, then the URL — is the Broadcastify Calls protocol’s success shape; anything else is treated as a rejection and surfaced as an error (which the Manager will then retry). Step two, putAudio, is a plain PUT of the MP3 bytes with Content-Type: audio/mpeg and an explicit ContentLength, to the URL step one handed back. A non-2xx on either leg returns an error, and the Manager’s sendWithRetry handles the backoff.

RdioScanner and OpenMHz: one multipart helper, two vocabularies

Both of these are single multipart/form-data POSTs, and both build the body with the same tiny helper. buildMultipart (internal/broadcast/multipart.go) takes a slice of multipartField — a text field carries Value, a file part carries Filename + Data — and returns the encoded buffer plus the Content-Type header with its generated boundary:

// internal/broadcast/multipart.go (shape)
type multipartField struct {
    Name     string
    Value    string // text field
    Filename string // set → written as a file part
    Data     []byte // the file bytes
}

func buildMultipart(fields []multipartField) (*bytes.Buffer, string, error) {
    // …CreateFormFile for parts with a Filename, WriteField otherwise
}

What differs is the field vocabulary each service expects. RdioScanner wants key, system, dateTime, talkgroup, source, frequency, and the audio as audio; OpenMHz wants api_key, freq, start_time, stop_time, call_length, talkgroup_num, and — the interesting ones — source_list and patch_list:

// internal/broadcast/openmhz.go (shape)
sourceList := fmt.Sprintf(`[{"src":%d,"time":%d,"pos":0}]`, c.Source, c.StartedAt.Unix())
patchList := "[]"
if len(c.PatchedGroups) > 0 {
    // "[201,212]" — the patched talkgroups on this call
}
fields := []multipartField{
    {Name: "api_key", Value: b.apiKey},
    {Name: "talkgroup_num", Value: strconv.FormatUint(uint64(c.Talkgroup), 10)},
    {Name: "source_list", Value: sourceList},
    {Name: "patch_list", Value: patchList},
    {Name: "call", Filename: audioFilename(c, "mp3"), Data: audio},
    // …freq, start_time, stop_time, call_length, emergency
}

source_list is a JSON array OpenMHz expects even when there is only the single granting unit to report — GopherTrunk sends the one source it knows with pos:0. patch_list carries the patched talkgroups when the call is a patch, [] otherwise. Both backends name their audio part with the shared audioFilename helper (<talkgroup>-<unixstart>.mp3), and RdioScanner stamps its dateTime with rfc3339In so the timestamp renders in the operator’s configured display timezone with an explicit offset — the same helper the webhook uses, so a call carries one consistent wall-clock time across every feed.

Icecast: a live stream that never starves

Icecast is the odd one out. The other four backends upload a finished call; Icecast maintains a continuous live audio stream that a listener can tune into at any moment. That changes everything about its shape. There is no per-call request — instead, NewIcecast starts a background goroutine that holds a source connection open, and Send just appends the call’s MP3 onto a shared queue:

// internal/broadcast/icecast.go (shape)
func (b *icecastBackend) Send(_ context.Context, c *Call) error {
    audio, err := c.MP3()
    if err != nil {
        return fmt.Errorf("%s: encode mp3: %w", b.name, err)
    }
    b.mu.Lock()
    defer b.mu.Unlock()
    if len(b.queue)+len(audio) > b.maxQueue {
        b.log.Warn("broadcast: icecast queue full, dropping call", "tg", c.Talkgroup)
        return nil // best-effort: drop, don't fail (no pointless Manager retry)
    }
    b.queue = append(b.queue, audio...)
    return nil
}

Note Send returns nil even when it drops — a live feed is best-effort, and returning an error would trigger Manager retries that make no sense for streaming audio. The real work is in runStream, which dials the server, does the Icecast source handshake (a SOURCE <mount> HTTP/1.0 request with basic auth and Ice-* headers), then loops on a ticker writing paced chunks:

// internal/broadcast/icecast.go (shape)
ticker := time.NewTicker(icecastTick) // 200ms
chunk := b.bytesPerSec * int(icecastTick) / int(time.Second)
silenceOff := 0
for {
    select {
    case <-ctx.Done():
        return nil
    case <-ticker.C:
    }
    payload := b.takeChunk(chunk, &silenceOff)
    conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
    if _, err := conn.Write(payload); err != nil {
        return err // triggers reconnect in run()
    }
}

The pacing is the point. Icecast expects a source to feed audio at roughly its real byte rate; feed too fast and buffers bloat, too slow and the server times the source out. So each tick writes exactly bytesPerSec * tick bytes. When there is real call audio queued, takeChunk serves it; when the queue is empty — the gap between calls — it pads the chunk with pre-encoded silence, cycling through one second of MP3-encoded digital silence over and over:

// internal/broadcast/icecast.go (shape)
func (b *icecastBackend) takeChunk(n int, silenceOff *int) []byte {
    out := make([]byte, 0, n)
    // …drain up to n bytes of real queued call audio under the lock
    for len(out) < n { // shortfall → top up with cycled silence
        if *silenceOff >= len(b.silence) {
            *silenceOff = 0 // wrap around the one-second silence buffer
        }
        // …append b.silence[silenceOff:end], advance silenceOff
    }
    return out
}

The silence is encoded once at construction (mp3.Encode(make([]int16, rate), rate)) and reused forever, so the pacer costs nothing between calls. If the connection drops, run reconnects after a fixed backoff and re-handshakes — the source stays up across network blips without dropping the listener’s stream.

The webhook: a stable schema, audio opt-in

The generic webhook is the escape hatch — the backend for everyone whose sink isn’t one of the four named services. It POSTs one application/json object per call against a documented, stable schema (webhookPayload) so a downstream consumer can rely on it:

// internal/broadcast/webhook.go (shape)
type webhookPayload struct {
    Event       string   `json:"event"` // always "call"
    System      string   `json:"system"`
    Protocol    string   `json:"protocol"`
    CallType    string   `json:"call_type"` // "group" | "unit" | "data"
    Talkgroup   uint32   `json:"talkgroup"`
    Source      uint32   `json:"source,omitempty"`
    FrequencyHz uint32   `json:"frequency_hz"`
    // …P25 site identity (channel_id, rfss_id, site_id, nac), encryption,
    //   emergency, patched_groups — all omitempty so presence means "known"
    StartedAt   string   `json:"started_at"` // rfc3339In
    EndedAt     string   `json:"ended_at"`
    DurationMs  int64    `json:"duration_ms"`
    AudioBase64 string   `json:"audio_base64,omitempty"` // only when opted in
}

Two design details are worth calling out. callType classifies the call so a consumer never mistakes a unit-to-unit call’s destination radio ID for a talkgroup — a group call reads "group", an individual call "unit", a data grant "data". And audio is opt-in: unless IncludeAudio is set, Send never calls c.MP3(), so a metadata-only webhook pays no encode cost and the payload stays lightweight. When it is set, the MP3 is base64-encoded into audio_base64 alongside an audio_format. Fields that don’t apply to a given call — site identity on non-P25, encryption params on a clear call — are dropped via omitempty, so a consumer can treat presence as “this value is known”.

The coda: pure Go is what makes it testable

The reason this series could describe each wire format with confidence is that every one of them is exercised by a real test — and those tests run because GopherTrunk’s entire output half is pure Go, zero CGO. The MP3 encoder (Shine), the WAV reader/writer, and the SQLite call log are all CGO-free, so a test can stand up the real encode → upload → persist path entirely in memory with nothing mocked but the network endpoint.

The pattern repeats across the suite:

• In-memory WAV. internal/voice/wav_test.go writes and header-patches a WAV through an in-memory io.WriteSeeker — no tempfile, no disk. The broadcast tests’ writeWAV helper (internal/broadcast/broadcast_test.go) makes a real short WAV that the real encoder turns into real MP3 bytes.
• httptest backends. internal/broadcast/backends_test.go stands up httptest.NewServer handlers that assert on exactly what this post described — TestBroadcastifyTwoStepUpload checks the metadata form and that the second leg is a PUT whose body begins with the MP3 frame sync 0xFF; TestRdioScannerUpload and TestOpenMHzUpload parse the multipart body and check the field names; TestIcecastSourceHandshakeAndStream speaks the raw source protocol over a net.Listener.
• Behavioural Manager tests. internal/broadcast/manager_test.go drives the full Part 13 machine with a fakeBackend: TestManagerSkipsStreamFalseTalkgroup and TestManagerDropsShortCalls pin the two gates, TestManagerRetriesTransientFailure and TestManagerGivesUpAfterMaxRetries pin the backoff budget.
• Timezone and schema. internal/broadcast/timezone_test.go pins rfc3339In to a fixed offset; internal/broadcast/webhook_test.go decodes the posted JSON back into a webhookPayload and checks the site identity and call_type.
• Temp SQLite. internal/storage/calllog_test.go opens a real database at t.TempDir()/calls.db and asserts the start/end rows — the same pure-Go SQLite the daemon uses, no external server.

That is the quiet payoff of the whole architecture. Because nothing links C, go test ./... builds and runs the real recording, encoding, and streaming code on any machine with a Go toolchain — no libsndfile, no lame, no sqlite3 dev package. The wire formats in this post aren’t described from a spec; they’re described from tests that send the real bytes and check what a real server receives.

The 3 p.m. dispatch, delivered

Fourteen posts ago we picked up one call — the 3 p.m. dispatch on talkgroup 101 — as it arrived from the vocoders as PCM. The recorder wrote its crash-safe WAV; the call log indexed it; loudness leveled the distributed copy; the CallComplete event carried its path to the broadcast Manager; the Manager gated it on Stream and MinDuration, encoded it to MP3 once, and handed it to a worker. That worker calls broadcastifyBackend.Send. A form POST goes out with the talkgroup, the source, the frequency, and the start time; Broadcastify answers "0 <url>"; the MP3 bytes PUT to that URL; a 200 comes back; sent["broadcastify"] ticks to one. The call is live in the feed. That is the whole output half, end to end — four independent subsystems, one bus, and a call that made it all the way out.

FAQ

Why does Broadcastify need two requests when everyone else uses one? Because the audio doesn’t go to the API host. The metadata POST returns a one-time upload URL — usually pointing at object storage — and the MP3 is PUT directly to it. parseBroadcastifyUploadURL reads the "0 <url>" success response; a rejection returns an error the Manager retries.

Do RdioScanner and OpenMHz share code? They share buildMultipart and audioFilename but not their field sets. Each backend assembles its own []multipartField — RdioScanner’s key/system/ dateTime, OpenMHz’s source_list/patch_list/talkgroup_num — and hands it to the same encoder. The helper writes the body; the backend owns the vocabulary.

Why does the Icecast backend send silence between calls? An Icecast source connection must feed audio continuously or the server times it out and drops the mount. Between calls there is no audio, so the pacer tops each timed chunk up from a one-second buffer of pre-encoded silence, cycling it. This keeps the source alive and the listener’s stream unbroken without re-encoding.

How can the tests be sure the uploads are correct without hitting real servers? They stand up httptest servers that assert on the exact bytes each backend sends — the two-step Broadcastify handshake, the multipart field names, the raw Icecast source protocol — while the encode and WAV paths run for real in memory. Because the whole stack is pure Go with zero CGO, go test ./... exercises the genuine code path on any machine with a Go toolchain.

Series navigation

Part 14 of 14 · ← Part 13: Outbound Streaming — The Broadcast Manager · This is the finale — back to the series index.

Where to next? The pure-Go, zero-CGO story that made this series’ tests possible runs deeper in the SDR Internals series — see SDR Internals ch. 14, “APIs, Testing & the Pure-Go Story.”

TL;DR: GrantWebhook POSTs one JSON object per decoded control-channel grant to your endpoint as it lands — the push form of GET /api/v1/grants, same schema, plus an "event": "grant" discriminator and a decode timestamp. It subscribes to the bus at construction (so grants decoded before Run starts aren’t lost), delivers on a single worker with retry/backoff, and — the load-bearing property — sits behind a bounded 256-deep queue that drops the overflow rather than blocking the event loop and the decoder behind it. It carries no audio: a grant is a control-channel fact, not a recording, and the source RID is reported exactly as decoded (never backfilled), which makes it distinct from the completed-call webhook.

Key takeaways

• Fires at call setup, not call end. The grant webhook pushes the instant the control channel decodes a grant — seconds before the completed-call webhook, which waits for the voice decode.
• One schema across three surfaces. The payload mirrors the GrantDTO that GET /api/v1/grants and the KindGrant SSE stream already publish, so a consumer reads one shape whether it snapshots, subscribes, or receives a push.
• A wedged consumer can’t hurt the decoder. The bounded queue drops overflow grants and increments a counter; it never applies backpressure to the event loop.
• Source RID is reported, not invented. A grant whose TSBK carried src=0 is POSTed with source_id=0 — the feed reports what the control channel actually saw, unlike the completed-call webhook whose source depends on a separate voice decode.

Cheat sheet

In this post

• Grant vs call — two webhooks, two moments, two truths about the source.
• The schema — one shape shared with the REST snapshot and the SSE stream.
• The bounded queue — the rule that keeps a bad consumer off the decoder.
• Delivery — subscribe-at-construction, single worker, retry/backoff.
• Operating it — auth, filtering, and the counters that flag a dead endpoint.

Grant vs call: two webhooks, two moments

GopherTrunk has two JSON webhooks and it’s worth being precise about the difference, because they answer different questions. The completed-call webhook (covered in Recording, Composition & Streaming Part 14) fires when a call finishes — it can carry the audio, base64-encoded, opt-in. The grant webhook fires when the control channel decodes a grant — at call setup, before a single voice frame exists. If you’re driving a live board or a low-latency alert, you want the grant; if you’re archiving finished audio to a custom sink, you want the call.

That timing difference produces a subtle but real semantic difference in the source radio ID, and the code comments it deliberately:

// internal/broadcast/grantwebhook.go (shape)
// Grants are surfaced exactly as decoded off the control channel: the source
// RID rides the grant at call-setup time for every protocol, and a grant whose
// TSBK carried src=0 is POSTed with source_id=0 (never backfilled), so the feed
// reports what the control channel actually saw — the way SDRtrunk's grant log
// does. That makes it distinct from the completed-call webhook, whose source
// RID depends on a separate voice-side decode landing.

So the grant webhook is honest about the control channel: source_id=0 means “the grant didn’t carry a source,” not “we don’t know yet.” The completed-call webhook, by contrast, may fill the source from the voice-side decode. Neither is wrong — they’re reporting different facts at different moments, and knowing which you’re consuming keeps a dashboard from mislabelling a call.

One schema, three surfaces

The grant payload isn’t a bespoke shape — it’s the same GrantDTO that the REST snapshot and the live SSE stream already publish, plus a discriminator and a timestamp. That’s a deliberate integration property: a consumer that already parses GET /api/v1/grants needs no new code to consume the push:

// internal/broadcast/grantwebhook.go (shape)
type grantWebhookPayload struct {
    Event       string `json:"event"` // always "grant"
    System      string `json:"system"`
    Protocol    string `json:"protocol"`
    GroupID     uint32 `json:"group_id"`
    SourceID    uint32 `json:"source_id"`
    FrequencyHz uint32 `json:"frequency_hz"`
    ChannelID   uint8  `json:"channel_id,omitempty"`
    RFSSID      uint8  `json:"rfss_id,omitempty"`
    SiteID      uint8  `json:"site_id,omitempty"`
    NAC         uint16 `json:"nac,omitempty"`
    Encrypted   bool   `json:"encrypted,omitempty"`
    Emergency   bool   `json:"emergency,omitempty"`
    DataCall    bool   `json:"data_call,omitempty"`
    Individual  bool   `json:"individual,omitempty"`
    AlgorithmID uint8  `json:"algorithm_id,omitempty"`
    KeyID       uint16 `json:"key_id,omitempty"`
    At          string `json:"at"` // RFC3339 decode time
}

Two fields carry most of the automation value. Emergency is true when the grant flagged an emergency — the natural trigger for a page or an alert. Encrypted (with AlgorithmID / KeyID) lets a dashboard mark a call it can hear about but can’t hear. The P25 site-identity fields (nac, rfss_id, site_id) are omitempty, so their presence means “this value is known” — a consumer treats a missing nac as “not a P25 grant,” not “NAC zero.” And at is an offset-bearing RFC3339 in the operator’s configured timezone, so a grant’s timestamp is unambiguous even across zones — the same timezone helper the audio webhooks and the call log use, so one call reads with one wall-clock everywhere.

The bounded queue: the rule that protects the decoder

This is the part that makes a grant webhook safe on a 24/7 daemon rather than a liability. A busy control channel emits thousands of grants an hour. If your webhook endpoint wedges — the receiving service restarts, its disk fills, the network partitions — a naive design would block on the POST, and that backpressure would climb straight back through the event loop into the decoder. So the grant webhook is built to fail forward:

// internal/broadcast/grantwebhook.go (shape)
func (w *GrantWebhook) enqueue(g trunking.Grant) {
    if !w.filter.Accepts(g.System) {
        return
    }
    p := grantWebhookPayloadFrom(g, at, w.loc)
    select {
    case w.jobs <- p: // room in the 256-deep queue
        w.mu.Lock(); w.queued++; w.mu.Unlock()
    default: // queue full — a wedged endpoint — drop the OLDEST discipline
        w.mu.Lock(); w.dropped++; w.mu.Unlock()
        w.log.Warn("broadcast/grantwebhook: queue full, dropping grant",
            "name", w.name, "system", g.System, "tg", g.GroupID)
    }
}

The default branch is the whole point: a non-blocking send onto a bounded jobs channel means a full queue drops the grant and moves on instead of stalling. This is the exact same discipline the call Manager uses — bound the backlog, shed load under pressure, never let an outbound sink apply backpressure to decode. The queue is 256 deep, which absorbs a brief endpoint hiccup without dropping anything; past that, a chronically dead endpoint costs you dropped grants (counted, logged) but never a missed control-channel decode or a stalled recorder.

How that principle shaped the Go code

• Subscribe at construction, not at Run. NewGrantWebhook calls Bus.Subscribe() and starts the worker before returning, so grants decoded in the window between wiring the sink and calling Run are queued, not lost. Start-up ordering can’t drop the first grants of a session.
• One worker, serial delivery. A single goroutine drains jobs and calls sendWithRetry, so grants are delivered in order and a slow endpoint can’t spawn unbounded in-flight POSTs — the queue is the only buffer, and it’s bounded.
• Drop is a counter, not a panic. Overflow increments dropped and warns; there’s no error path back to the caller, because the caller is the event loop and it must never block.

Delivery: subscribe, retry, back off

Once a grant is on the queue, delivery is the same retry discipline you saw for the audio backends, scaled to a single worker. sendWithRetry attempts the POST up to maxRetries+1 times (default 4) with exponential backoff (default 2s, doubling), each attempt bounded by a 30-second timeout:

// internal/broadcast/grantwebhook.go (shape)
func (w *GrantWebhook) sendWithRetry(p grantWebhookPayload) {
    backoff := w.retryBase
    for attempt := 0; attempt <= w.maxRetries; attempt++ {
        ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
        err := w.post(ctx, p)
        cancel()
        if err == nil {
            w.mu.Lock(); w.sent++; w.mu.Unlock()
            return
        }
        // …warn, then sleep backoff and double it
    }
    w.mu.Lock(); w.failed++; w.mu.Unlock()
    w.log.Error("broadcast/grantwebhook: giving up on grant", ...)
}

There’s a design tension worth naming here. The worker is single and delivery is serial, so while sendWithRetry is backing off (2s + 4s + 8s = up to 14 seconds for one wedged grant), it isn’t draining the queue. That’s intentional: it couples “the endpoint is slow” to “the queue fills,” which trips the bounded-queue drop — so a dead endpoint self-limits to dropped grants rather than an ever-growing backlog of doomed retries. The retry budget handles a flaky endpoint; the bounded queue handles a dead one. Together they mean the grant webhook needs no operator intervention when a consumer misbehaves.

Operating it: auth, filtering, and health

The config surface is small. url is required; auth_header is sent verbatim as the Authorization header — so auth_header: "Bearer <token>" authenticates to your endpoint, and (as with every credential in this series) it belongs in an environment file the systemd unit references, not inline in config.yaml. The systems list scopes the feed to named trunked systems; empty pushes every system. A feed with enabled: false is parsed but skipped, so you can stage a webhook before turning it on.

Health reads through the same door as the audio backends — GET /api/v1/broadcast, which returns {"enabled": false} when nothing is configured so a UI renders a stable shape — and the grant webhook contributes its own four counters:

// internal/broadcast/grantwebhook.go (shape)
type GrantWebhookStats struct {
    Name    string `json:"name"`
    Queued  int    `json:"queued"`
    Dropped int    `json:"dropped"` // overflow — a wedged endpoint
    Sent    int    `json:"sent"`
    Failed  int    `json:"failed"`  // exhausted retries
}

The operating read: sent climbing with your grant rate is healthy. A rising dropped means the endpoint is chronically slow and the queue is overflowing — the consumer can’t keep up. A rising failed means individual POSTs are exhausting their retries — usually a wrong auth_header or a 4xx from the endpoint. As everywhere in this series, these are numbers you alert on, because a grant webhook that stops firing is otherwise completely silent — the decoder keeps decoding, the counters just stop moving.

Where this goes next

We’ve now built the whole outbound surface — audio to four aggregators, grants to a webhook — on top of a daemon that so far runs wherever you launch it. The last three posts make where it runs robust. Part 12 containerizes the daemon and passes an RTL-SDR through to it — the udev rules, the --device mapping, and the USB-reset dance that separate a container that sees a dongle from one that just thinks it should. Cross-reference the Containers & Deployment module for first principles.

FAQ

When exactly does the grant webhook fire relative to the call? At call setup — the instant the control channel decodes the grant, before any voice frame is processed and seconds before the completed-call webhook. If you want the earliest possible signal that a talkgroup keyed up (for a live board or a low-latency alert), it’s the grant webhook, not the call webhook.

Why does a grant sometimes have source_id: 0? Because the grant genuinely carried no source RID. The feed reports the control channel exactly as decoded and never backfills, so source_id: 0 means “not present in the grant,” not “unknown, check back later.” The completed-call webhook may fill the source from the voice decode instead — a different fact at a different moment.

What happens to grants if my endpoint goes down? Individual POSTs retry up to four times with exponential backoff. If the endpoint stays down, the single delivery worker stalls on backoff, the 256-deep queue fills, and further grants are dropped (counted in dropped, logged as warnings) — never queued unbounded and never allowed to stall the decoder. When the endpoint recovers, delivery resumes; the dropped grants are gone, by design.

Can I consume the same data without a webhook? Yes — that’s the point of the shared schema. GET /api/v1/grants gives the snapshot and the KindGrant SSE stream gives a live feed, both in the same GrantDTO shape plus the webhook’s event/at fields. The webhook is the push option for consumers that can’t poll or subscribe.

Does the grant webhook carry audio? No. A grant is a control-channel event with no recording attached — audio doesn’t exist yet at call setup. If you need the audio, use the completed-call webhook with include_audio: true, which base64-embeds the finished MP3.

Series navigation

Part 11 of 14 · ← Part 10: Broadcast Backends II — RdioScanner, OpenMHz, Icecast · Next → Part 12: Docker & RTL-SDR USB Pass-Through

TL;DR: A discovery arrives as numbers, and GopherTrunk names as much of it as the RF can justify. A system gets a synthesized handle from its protocol and identity (Unknown-p25-<WACN>-<SYSID>) until an operator assigns a real Name. Every classified carrier gets a Name / Service / Purpose triple — Service/Purpose from the frequency allocation table, Name from the decoded protocol, else a best-guess from the signal reference catalog, else the modulation class. But talkgroups stay numeric: a blind decode sees a talkgroup’s id and activity, never its meaning, so those fields are left blank for the operator or RadioReference to fill. Naming is aliasing, and the honesty is knowing where aliasing stops.

Key takeaways

• A system always has a stable handle. DisplayName() returns the operator’s Name when set, otherwise a synthesized Unknown-<proto>-<WACN>-<SYSID> — so an unnamed discovery still round-trips and diffs cleanly.
• Every carrier is named three ways. nameSignal fills Name (what it is), Service (what the frequency is allocated to), and Purpose (what that service does) — a consolidated “what is this” for decodable and undecodable signals alike.
• Naming falls back, never guesses wildly. Decoded protocol → reference-catalog best guess (above a score floor) → modulation class. An undecoded carrier only earns a catalog name when the match clears nameRefFloor (0.40).
• Talkgroups are deliberately unnamed. A blind discovery knows a talkgroup’s decimal, hex, and activity count — never its alpha tag — so those fields ship blank for a human or RR to complete.

Cheat sheet

In this post

• The two things a discovery is missing — a system name and talkgroup names.
• Naming a system — the synthesized handle and why it’s shaped that way.
• Naming a carrier — the Name / Service / Purpose triple and its fallbacks.
• Why talkgroups stay numeric — the honest limit of a blind decode.
• Rendering the named system — flattening it for the report.

The two things a discovery is missing

Walk back through the series and notice what naming is not. The sweep gave us frequencies. The identify gave us a protocol. The map gave us identity fields — WACN, System ID, NAC — and a talkgroup list. All of that is measured: it came off the air as bits. Names don’t come off the air. There is no RF field that says “this is the county fire dispatch system” or “this talkgroup is Engine 12.” Naming is the layer where measured numbers meet a human catalog, and the discipline is to name only what the catalog can actually justify from what we measured.

Two things want names: the system as a whole, and each talkgroup. GopherTrunk handles them very differently, and the difference is the whole lesson.

Naming a system

A DiscoveredSystem always needs a label — golden tests diff on it, exports name files after it, the cockpit lists it. So DisplayName never returns empty. It returns the operator’s Name if one was assigned, and otherwise synthesizes a stable handle from the identity we did measure:

// internal/hunt/system.go (shape)
func (s *DiscoveredSystem) DisplayName() string {
    if s.Name != "" {
        return s.Name
    }
    proto := s.Protocol
    if proto == "" {
        proto = "unknown"
    }
    switch {
    case s.WACN != 0 && s.SystemID != 0:
        return fmt.Sprintf("Unknown-%s-%05X-%03X", proto, s.WACN, s.SystemID)
    case s.SystemID != 0:
        return fmt.Sprintf("Unknown-%s-%03X", proto, s.SystemID)
    default:
        return fmt.Sprintf("Unknown-%s", proto)
    }
}

Three things are true about this handle and all three are deliberate. It is stable — the same system produces the same string every run, so it diffs and re-imports without churn. It is honest — the leading Unknown- says nobody has confirmed a real name yet. And it degrades — with full P25 identity you get Unknown-p25-BEE00-2A9; with only a system id you get Unknown-p25-2A9; with neither, just Unknown-p25. It carries exactly as much identity as we have and no more. The moment an operator (or a RadioReference match) supplies a real name, Name is set and the synthesized handle disappears — but until then, the system has a stable, self-describing identity.

Naming a carrier: Name, Service, Purpose

Down at the individual-carrier level — the survey inventory, every detected signal — naming is richer, because a frequency is not just a number: it sits in an allocation table. nameSignal fills a three-part label on every DetectedSignal, decodable or not:

// internal/hunt/naming.go (shape)
// nameSignal fills the consolidated inventory fields — Name, Service, Purpose —
// for any signal. Service/Purpose come from the frequency allocation; Name
// prefers the decoded protocol, then a best-guess from the reference catalog,
// then the modulation class.
func nameSignal(ds *DetectedSignal) {
    if a, ok := sigref.Lookup(ds.FreqHz); ok {
        ds.Service = a.Service   // what the frequency is allocated to
        ds.Purpose = a.Purpose   // what that service is used for
    }
    switch {
    case ds.Trunking != nil && ds.Trunking.Protocol != "":
        // decoded → the protocol's display name (P25, DMR, …)
    case len(ds.Pages) > 0:
        ds.Name = ds.Pages[0].Protocol
    default:
        // undecoded → rank against the signal reference catalog on baud,
        // modulation, bandwidth, and centre; take the top match only if it
        // clears the keep floor, else fall back to the modulation class.
    }
}

The precedence is the interesting part. Service and Purpose come from where the carrier lives — the frequency allocation, which is known for a band whether or not we decoded anything. Name comes from what the carrier is, and it walks a strict ladder: a decoded protocol names itself outright; a paging carrier is named by its page protocol; and an undecoded carrier is ranked against the signal reference catalog on its measured features (baud, modulation, bandwidth, centre) and named only if the best match clears a floor:

// internal/hunt/naming.go (shape)
const nameRefFloor = 0.40 // below this, name by modulation class instead
if m := sigref.Rank(obs, 1); len(m) > 0 && m[0].Score >= nameRefFloor {
    ds.Name = m[0].Entry.DisplayName
    if ds.Confidence == 0 { // fill confidence for an undecoded/wideband row
        ds.Confidence = m[0].Score
    }
} else if ds.Wideband {
    ds.Name = "wideband signal"
} else {
    ds.Name = string(ds.Class) // e.g. "nbfm" — the honest floor
}

That floor is the guard against confident nonsense. A weak, ambiguous carrier whose best catalog match scores 0.2 is not named “P25 control” — it is named nbfm, its modulation class, which is all we actually know. Naming here is a best guess with a confidence attached, and below the floor the honest label is the mechanism, not the meaning.

Why talkgroups stay numeric

Here is where naming refuses to overreach. A DiscoveredTalkgroup carries a decimal, a hex, an encrypted flag, an activity count, and a first-seen time — and nothing else:

// internal/hunt/system.go (shape)
// DiscoveredTalkgroup is one talkgroup observed on the control channel. On a
// blind discovery only the numeric id and activity are known; the descriptive
// fields are left blank for the operator (or RR) to fill in.
type DiscoveredTalkgroup struct {
    Dec       uint32    `json:"dec"`
    Hex       string    `json:"hex"`
    Encrypted bool      `json:"encrypted,omitempty"`
    Count     int       `json:"count"`
    FirstSeen time.Time `json:"first_seen"`
}

There is no AlphaTag, no Description, no Group — because a talkgroup’s name is nowhere in the RF. The control channel broadcasts that talkgroup 101 was granted a channel; it never broadcasts that 101 is “Fire Dispatch.” That mapping lives in a human database, and inventing it would be lying. So the exporter emits those columns blank for the operator or RadioReference to fill — the same reason the RR submission package says, right at the top, “a blind discovery cannot name talkgroups.” The system counts a talkgroup’s activity so you know which ids matter most; it will not pretend to know what they are.

This is also why the Trunking Engine and RadioReference import exist on the other side: naming is the seam where an operator’s knowledge joins the machine’s measurements. GopherTrunk names what it can prove and leaves a clearly-marked blank for what it can’t.

How that principle shaped the Go code

• nameSignal never overrides. It only fills fields the router left unset and is safe to call once per signal, so a decoded protocol’s own name always wins over a catalog guess.
• The floor is a constant, not a mood. nameRefFloor (0.40) is the single knob separating “named best guess” from “modulation class,” matching the wideband survey’s keep floor so the two agree.
• Missing identity degrades the handle, it doesn’t crash it. DisplayName’s switch means a system with partial identity still produces a usable, stable string — the exporters never see an empty name.

Rendering the named system

Once the system carries whatever names it has earned, NetworkReport flattens it into the protocol-neutral trunking.NetworkReport the shared renderer consumes — one ReportSite per discovered site under a shared identity header and band plan, with neighbour frequencies resolved from the accumulated band plan:

// internal/hunt/report.go (shape)
func (s *DiscoveredSystem) NetworkReport() trunking.NetworkReport {
    r := trunking.NetworkReport{
        Name:     s.DisplayName(), // the named (or synthesized) handle
        Protocol: s.Protocol, WACN: s.WACN, SystemID: uint32(s.SystemID), NAC: s.NAC,
    }
    // …one ReportSite per site: primary CC, secondaries, neighbours (with
    //   uplink derived from the band's TX offset), then the band plan
    return r
}

This is the same NetworkReport the live daemon renders for a configured system, so a discovered system’s summary reads exactly like a known one’s — just with an Unknown- handle and blank talkgroup names where a human hasn’t filled them in yet. The report is honest about its gaps by construction.

Where this goes next

Talkgroups have numbers but no names — and the units riding them are the same story. But there is one place a real, human name does travel over the air: the talker alias, the display name a radio broadcasts for itself. Part 12 is about harvesting those aliases off a system’s traffic channels without following the voice — the one naming the RF actually hands you.

FAQ

Why does an unnamed system print Unknown-p25-… instead of blank? Because everything downstream needs a stable handle — golden diffs, export filenames, the cockpit list. DisplayName synthesizes one from the measured identity (WACN/SystemID), prefixed Unknown- to say it’s unconfirmed. Assign a real Name and the synthesized handle vanishes.

Where do a carrier’s Service and Purpose come from? The frequency allocation table (sigref.Lookup). They describe what the frequency is allocated to and what that service does — known for a band whether or not the carrier decoded — so even an unidentified signal shows a meaningful band context.

Why won’t GopherTrunk name my talkgroups? Because the name isn’t in the RF. The control channel says talkgroup 101 was granted a channel; it never says 101 is “Fire Dispatch.” That mapping lives in a human database, so the discovery ships the id, hex, and activity count and leaves the descriptive fields blank for you or RadioReference to complete.

What is nameRefFloor protecting against? Confident nonsense. An undecoded carrier is only named from the reference catalog when its best match scores at least 0.40; below that it’s named by its modulation class (nbfm, psk, …), which is all we actually measured. The floor keeps a weak guess from masquerading as a firm identification.

Does naming change the decode at all? No. Naming is a pure labelling pass over already-measured results — nameSignal runs once per signal before it’s stored, and never touches the DSP or the accumulation. It’s the human-catalog layer on top of the measurements, not part of them.

Series navigation

Part 11 of 14 · ← Part 10: Offline vs Live Surveys — Hunting a Recording · Next → Part 12: Alias Harvesting — Following Traffic for Talker Aliases

TL;DR: A reporter’s P25 control channel locked in SDRTrunk, OP25, and p25-survey within seconds, while GopherTrunk logged cc-hunt: trying forever with nothing after it. The failure turned out to be eleven bugs deep: an unprogrammed sample rate, a missing channelizer, four separate chunk-boundary and timing-loop bugs, a receive filter that didn’t match the P25 spec, unstripped status symbols, a collapsed slicer — and at the very bottom, a wrong BCH(63,16,11) generator polynomial and the wrong CRC-CCITT variant. Every single one had been masked by encoder/decoder round-trip tests agreeing with each other. Fifteen seconds of real IQ from the reporter’s antenna was what finally broke the spell.

Cheat sheet

In this post

• The report — the ideal bug report: same hardware, other decoders lock in seconds.
• The ladder — all eleven fixes, in the order the failures surfaced.
• Rung 1: the radio was never told its sample rate — the pool programmed everything but the resampler.
• Rungs 2–3: channelize, then let frames cross chunks — 427 samples per symbol, then 19-symbol USB transfers.
• Rungs 4–7: the same bug class, one stage at a time — Gardner, coarse AFC, scale invariance, Mueller-Müller.
• Rungs 8–9: the spec the code had never read — the sinc receive filter and status symbols.
• The wrong turns, named honestly — CQPSK pushed twice, phantom search convergence, stale builds.
• The capture that ended the guessing — replay turns each hypothesis into a measurement.
• The bottom of the ladder: two constants — the BCH generator polynomial and the augmented CRC.
• The meta-lesson — why a self-consistent system can only be falsified from outside.
• What we keep — the durable rules and their Field Guide entries.

The report

The issue arrived as close to ideal as bug reports get. Two NESDR SMArt v5 dongles, a high-gain Yagi, a busy P25 Phase 2 system (MMR, control channel 420.0875 MHz), a minimal config — and one observation:

time=2026-05-19T14:59:11.416+10:00 level=INFO msg="cc-hunt: trying" system=MMR freq_hz=420087500

Every 10–15 seconds, the same line again. No sync attempts, no framing failures, no decode errors. Nothing downstream, ever. And the kicker: the same dongles and antenna decoded the same system in SDRTrunk. OP25-based p25-survey locked it within ~5 seconds at BER 0.00%.

The first community theory was PPM drift — reasonable, wrong, and the cheapest of the wrong theories this thread would collect. The real answer was that almost the entire receive chain between the USB port and the trunking engine had never met a real signal.

The ladder

Eleven fixes, in the order the failures surfaced. Each rung was invisible until the one above it was fixed.

Rung 1: the radio was never told its sample rate

The pool programmed PPM, gain, and bias-tee on every device — but never the resampler. The chip stayed at whatever divisor it powered up with while every decoder did symbol-timing math against the configured 2.048 MS/s. SDRTrunk works on the same hardware because librtlsdr’s rtlsdr_open() ends with a default rtlsdr_set_sample_rate call; GopherTrunk’s pure-Go driver had no such safety net.

The fix (#281) also closed the diagnostic black hole: the P25 Process paths now throttle-log no FSW hits in chunk instead of staying silent, and a new IQ-power gauge (#282) let the reporter confirm healthy IQ (~−18 dBFS) before the decoder was even involved. From here on, every failure at least left a fingerprint.

Rungs 2–3: channelize, then let frames cross chunks

With the rate fixed, the decoder was still being fed the full un-channelized 2.048 MHz swath — roughly 427 samples per symbol against a ±1 MHz window: dibits at about the right rate, with values that were noise. A digital down-converter (#289) now decimates every per-protocol pipeline to the narrowband rate its matched filter expects (~48 kHz for the 4800-baud C4FM family). A negative result from that PR is worth keeping: an IQ-domain DC blocker was rejected, because C4FM carries real energy at 0 Hz — a complex DC block measured over 60% RMS error on a round-tripped stream.

Then the shape of real USB delivery bit. An RTL-SDR hands over IQ in 16 KiB transfers — about 19 P25 symbols per decoder call. The control-channel state machine discarded every frame-sync hit unless the entire 154-dibit frame (FSW + 32-dibit NID + 98-dibit TSBK) landed inside a single call. Nineteen is less than even the NID, so every hit was dropped. The synthetic tests fed ~819 dibits per chunk and never saw it. #292 made frames accumulate across calls, and the regression test now pumps real 8192-sample chunks.

Rungs 4–7: the same bug class, one stage at a time

The chunk-boundary theme repeated up the DSP chain like a drumbeat:

• Gardner (#300): the CQPSK timing loop re-walked its cross-call look-back buffer and emitted roughly one surplus symbol per call — a ~5% inflation that kept desynchronizing the dibit stream, so the decoder could reach NID parsing but never hold it.
• Mueller-Müller (#311): the C4FM clock started its walk at src[1] on every call, so src[0] never advanced the loop — one dropped sample per chunk. Fed the whole signal in one block, the dibit error rate was 0.04; fed RTL-realistic ~19-symbol chunks, 0.66 — near-random. The fix carries look-back so the chunked stream is byte-identical to the one-shot stream, and it repaired the same latent bug in the DMR, NXDN, YSF, and dPMR receivers for free.
• Coarse AFC (#303): a residual tuner offset becomes a DC bias on the FM discriminator, and the fixed 4-level slicer thresholds have no defense — at ≥500 Hz the FSW stops correlating entirely. This is why the reporter’s ±2 ppm sweep never changed anything: once the offset exceeds the slicer margin, no small correction recenters it.
• Scale invariance (#307): after a CMA equalizer landed on the CQPSK path (more on that below), lock suddenly depended on RTL gain — 197 broken, 49 partial framing, 28 broken. Both the Gardner and CMA update terms scale with amplitude², so the loops only converged when the front-end gain happened to land in a narrow band. A feed-forward AGC on the matched-filter output restored scale invariance, guarded by a regression test across a 0.05–20× amplitude range.

Rungs 4–7 also mark where the process changed: #299 added a harness driving the real receiver chain against deliberately impaired IQ — carrier offset, DC spike, IQ imbalance, AWGN — in RTL-realistic small chunks, replacing the ideal large-block synthesis every earlier fix had been verified against. The Gardner bug fell out of that harness on day one.

Rungs 8–9: the spec the code had never read

With timing solid, the C4FM path pegged at a new wall: nid corrected errs=11 — exactly the BCH(63,16,11) correction ceiling — with clearly bogus NACs (0xFF5) surfacing as miscorrections.

The filter was wrong (#316). GopherTrunk modeled P25 C4FM as a root-raised-cosine matched pair. RRC × RRC is raised-cosine and ISI-free — so the chain was perfectly self-consistent in tests — but per TIA-102.BAAA (cross-checked against OP25’s c4fm_const.py), a real P25 transmitter shapes with raised-cosine α=0.2 cascaded with an inverse-sinc, and the receiver’s job is a plain sinc that cancels it. An RRC receive filter on a spec signal leaves about 5.75% residual ISI — quietly corrupting dibits at exactly the level that keeps BCH at its ceiling.

The status symbols were never stripped (#318). P25 interleaves a 2-bit status symbol into the on-air stream every 70 information bits, through every data unit including TSDUs. The 24-dibit FSW is contiguous — the first status symbol lands at dibit 35, just after it — which is precisely why FSW detection worked while the NID behind it was garbage: the decoder read the NID as 32 contiguous dibits, swallowed a status symbol as data, and misaligned ~21 of the 32. The give-away was that C4FM and CQPSK failed identically — the bug lived downstream of both demodulators, in the one stage they shared.

The wrong turns, named honestly

• CQPSK/LSM was pushed twice for a site that SDRTrunk labels C4FM. The theory — simulcast sites transmit LSM, so add a linear demod path (#288) and then a CMA equalizer (#306) — was plausible and the code was eventually valuable, but the reporter’s site was a strong standalone C4FM transmitter. The equalizer’s first contribution was the gain-window regression of rung 6.
• delta=2, rot=3 looked like a clue and was two artifacts. When a bounded NID-alignment search (#320) went in, the diagnostics converged on closest marginal errs=10 at delta=2 strip=true rot=3 every frame. delta=2 was the edge of the ±2 search grid — the textbook signature of a bounded search pegged at its boundary — and rot=3 is non-physical on an FM-discriminator stream, where only rotations 0 and 2 correspond to real signal symmetries. Both “signals” were the search machinery talking to itself; #326 widened the span to ±6 and restricted C4FM rotations to {0, 2}, and the phantom convergence vanished.
• Two retest cycles were wasted on stale builds — one binary was eight commits older than the fix it was testing. The countermeasures outlived the bug: the pipeline startup line now advertises demod / rotations / nid_search_span / build=, and internal/version falls back to runtime/debug.ReadBuildInfo() so even a bare go build produces a self-identifying binary.
• The first capture was mislabeled. Its symbol clock measured ~160 samples per symbol — inconsistent with the stated 2.048 MS/s — and decoded to nothing at every plausible rate. The lesson became a feature: the replay tool now reports effective baud at EOF, so a mislabeled file diagnoses itself.

The capture that ended the guessing

The turning point of the whole thread was 30 seconds of raw IQ captured with a known command line: mt-anakie-420087500-960k-g49.iq, replayed offline through the new gophertrunk replay subcommand. The failure reproduced identically off-air:

no NID corroborated over 28 guesses; closest marginal errs=11 at delta=6 strip=true rot=0,
TSBK uncorroborated — best alignment at search boundary (±6); true offset may exceed span;
err_pattern=00100001102010200100000000100100

From here every hypothesis became a measurement instead of a field trip:

• Alignment was ruled out by bisection (#334): widening the search to ±36 still produced 253 NID-BCH failures with closest-miss errors flat at 9–11 across the whole range. Whatever was wrong, it wasn’t framing.
• The slicer had collapsed (#335): a new replay -diag histogram showed the dibit distribution was 50/0/50/0 — only outer symbols, ever. The C4FM matched filter is normalized to a DC gain of one symbol period, which on real captures put every sample past the slicer’s outer threshold. The FSW still correlated because it uses only outer symbols — which is exactly why the failure hid behind a working sync detector. A symbol-domain AGC between clock recovery and the slicer opened the eye: histogram 28/22/27/23, and suddenly ~200 perfect distance-0 FSW hits at exact 360-dibit intervals.
• The NID was constant, and that was the smoking gun (#336): across all 197 frames in the capture, the 32 NID dibits were byte-identical while the TSBK payload varied frame to frame. That’s a real control channel — same NAC and DUID every frame, different payload — being decoded consistently and rejected consistently. The first 16 info bits even read out plausibly: NAC 0x164, DUID 7 (TSDU). The remaining failure had to be a systematic transform — not noise.

The bottom of the ladder: two constants

Bug 1 — the BCH(63,16,11) generator polynomial was wrong (#337). The constant in internal/radio/framing/bch.go was off by ten exponents from the TIA-102.BAAA Annex A generator. The correct value — derived from first principles by multiplying the binary minimal polynomials of α, α³, α⁵, …, α²¹ over GF(2⁶) with primitive polynomial x⁶ + x + 1 — is 0xCD930BDD3B2B. Cross-verified by running OP25’s syndrome decoder against the captured Mt Anakie NID: 0 of 22 syndromes non-zero. The on-air NID had been a valid spec codeword all along; GopherTrunk was checking it against a code that exists nowhere but its own tests.

Bug 1b — the 64th NID bit is not a parity bit. The code computed the trailing bit as even parity over the 63-bit codeword. Per spec (and OP25’s p25_framer), it’s a fixed per-DUID flag: 0 for HDU/TDU/TSDU/PDU/TDULC, 1 for LDU1/LDU2. For a TSDU the on-air bit is 0 — which the “even parity” computation produced as 1, flagging every otherwise-clean decode as a parity failure.

Bug 2 — the wrong CRC-CCITT variant (#338). With the BCH fixed, the trellis decoder reported metric=0 — zero bit errors in the 196-bit channel block — and 195 of 197 TSBKs still failed CRC. Trellis right, verifier wrong: P25 uses the “augmented codeword” CRC-CCITT for the TSBK trailer (init=0, MSB-first, final XOR 0xFFFF, evaluated over all 12 bytes, expecting 0), while the code used CRC-CCITT/FALSE. Same 0x1021 polynomial, different answer on the same bytes. metric=0 plus a CRC failure is now a recognized signature: the FEC says the bits are perfect, so suspect the checker.

The capture’s full arc:

And on air, the line the thread had been chasing for five days:

time=2026-05-24T07:16:10.555+10:00 level=INFO msg="control channel locked" nac=356 freq=420087500 rot=0 delta=0
time=2026-05-24T07:16:10.555+10:00 level=INFO msg="cc-hunt: locked" system=MMR freq_hz=420087500 nac=356

Followed within seconds by decoded TSBKs, Motorola vendor messages, and live patch activity. Both constants are pinned by regression tests built from the capture’s actual on-air bytes (TestEncodeNIDBitsMtAnakieVector, TestTSBKAcceptsMtAnakieOnAirVector), so a future regression names the byte that changed.

The meta-lesson

The maintainer’s closing note on the thread deserves to be quoted rather than paraphrased:

Without 15 seconds of real ground-truth bits, every one of these bugs would have stayed silently masked by the encoder + decoder agreeing with each other inside synthetic round-trip tests.

Every rung of the ladder shares that anatomy. The wrong sample rate passed tests that never touched hardware. The chunk-boundary bugs passed tests that fed generously sized chunks. The RRC filter passed because the test modulator was also RRC. The status symbols passed because the test frames were built without them. And the wrong BCH polynomial and wrong CRC variant passed hundreds of round trips, because an encoder and decoder that share the same wrong constant agree with each other perfectly. A self-consistent system can only be falsified from outside — and the outside, for a radio decoder, is 15 seconds of IQ from somebody’s antenna.

What we keep

• Round-trip tests can’t catch a shared wrong constant. Validate codecs against external ground truth — a reference implementation, a captured on-air vector, or both. The spec constants this hunt corrected are recorded in the P25 on-air constants Field Guide entry.
• A capture plus offline replay beats any number of on-air retests. The gophertrunk replay subcommand — with -diag histograms, effective-baud reporting, and per-failure err_pattern strings — turned each hypothesis into a measurement. The workflow is written up in the diagnostic playbook.
• Learn the signatures. A bounded search pegged at its boundary (delta=2 on a ±2 grid), a non-physical rotation “winning” (rot=3 on an FM discriminator), a dibit histogram of 50/0/50/0, metric=0 with a failing CRC — each of these names its own cause, and they’re cataloged in signal signatures.
• Make staleness self-evident. Two retest cycles died on old binaries. Every pipeline now logs its decode parameters and build stamp on startup, so the first line of any pasted log answers “which code was this?”
• A silent failure is a bug in its own right. The original report’s defining feature was no logs at all. Every stage that can produce nothing now says so, at a throttled cadence.

FAQ

Why did SDRTrunk and OP25 lock the same hardware in seconds? Their receive chains had met real signals for years. librtlsdr sets a default sample rate as part of opening the device, their DSP tolerates real USB transfer sizes, and their filters follow the TIA-102 pulse shapes. GopherTrunk’s chain had only ever been validated against its own synthetic output, so every divergence from real air was invisible until a real antenna was attached.

How can eleven distinct bugs hide behind one symptom? Because they were stacked: each rung fully masked everything below it. With the sample rate unprogrammed, the channelizer gap couldn’t surface; with the slicer collapsed, the wrong BCH polynomial couldn’t surface. Stacked failures are only ever visible one at a time, which is why the thread reads as a ladder rather than a list.

What is the “augmented codeword” CRC-CCITT, exactly? Same 0x1021 polynomial as CRC-CCITT/FALSE, different procedure: initial value 0, MSB-first, final XOR 0xFFFF, evaluated over all 12 TSBK bytes including the trailer, expecting a result of 0. On the same bytes the two variants produce different answers — which is how a trellis decode with metric=0 (zero channel bit errors) can still “fail CRC” for 195 of 197 frames.

Did any of this help other protocols? Yes. The Mueller-Müller look-back fix repaired the same latent chunk-boundary bug in the DMR, NXDN, YSF, and dPMR receivers for free, and the replay tooling with -diag histograms became the standard investigation workflow for every postmortem that follows in this series.

What would have caught these bugs before a user did? External ground truth — a reference implementation’s vectors or a captured on-air frame — used as the test input instead of the project’s own encoder. The two constants at the bottom of the ladder are now pinned by regression tests built from the capture’s actual on-air bytes, so they can never again be “verified” by a round trip against themselves.

Series navigation

Part 1 of 22 · Next → Part 2: The Talker-Alias Hunt — Three Wrong Transports and an Architectural Gate