TL;DR: A GopherTrunk decoder is done when eleven places agree; FleetSync is the worked example: protocol core + afsk front end (internal/radio/fleetsync), events.KindFleetSyncMessage, storage.FleetSyncLog + the fleetsync_log table + decoderLogTables, GET /api/v1/fleetsync/messages, the /fleetsync panel + nav entry, FleetSyncConfig + the fleetsync tab key, FieldMeta help, the Config Builder types.ts + section, the daemon wiring, the doctor “needs storage.path” list, and the config.example.yaml block + docs/fleetsync.md. Three tests police it — TestFieldHelpCoverage, TestConfigSchemaCoveredByWebBuilder, and the web registry.test.ts / App.panels.test.tsx route lists — plus the web-typecheck CI job, because vitest never typechecks. Trunked protocols take a different route (Protocol enum, pipeline factory, composer voice kind, recorder vocoder map). M17 shows a decoder that stopped short: REST but no panel.

Key takeaways

• The pattern is the product. Twelve physical layers reduce to one shape because everything above the framer — bus, storage, REST, panel, config, help, doctor, example, docs — is identical machinery.
• Tests police places, not behaviour. TestFieldHelpCoverage and TestConfigSchemaCoveredByWebBuilder walk config.Config by reflection; the web route tests walk App.tsx.
• Green npm test is not a built console. vitest never typechecks; only tsc --noEmit catches an unused parameter, so web-typecheck runs it over all five SPAs.
• Wired is not verified. All eleven places can be present and the decoder still synthetic-green; the open list below is the ledger.

Cheat sheet

In this post

• The eleven places — one table, FleetSync’s file at each.
• The three tests that police it — reflection walks and route lists.
• The CI job vitest cannot replace — web-typecheck and TS6133.
• Message decoder or trunked protocol? — the decision table, and M17.
• What’s still open — the honest ledger.
• Where to go from here — the series index and its siblings.

The eleven places

Part 1 introduced the pattern through FleetSync’s landing (Part 4); here it is as the checklist, with the real file at every step and the test that fails when the row is skipped.

Three rows are where earlier landings went wrong. Row 3 is one generic: storage.FleetSyncLog embeds *eventLog[FleetSyncMessage], the shared subscribe → drain → close lifecycle, so a new decoder supplies only its insert and Recent SQL — and must add its table to decoderLogTables, or retention.log_days never sweeps it (Recording Part 10). Row 4 returns a bare array; the History panel once read r.rows from a {"calls": […]} envelope and rendered “No calls” for every query, so the row 5 panel test renders a real burst. Row 10 exists because message decoders surface only through SQLite: with storage.path empty the receiver runs, the route returns 503 and the panel stays empty — a silent failure (#565) that doctor now names:

WRN storage.path is empty but these decoders need it to surface decoded
    messages: paging, fleetsync — they will run, but their REST endpoints
    (e.g. /api/v1/pager/messages) return 503 and the web panels stay empty.
    Set storage.path to enable persistence.

Row 11’s rule dates from 4 September, when diversity_capture_format shipped in code but not in config.example.yaml.

The three tests that police it

The guards walk the structure, so they fail the day a place is skipped. The first walks config.Config by reflection and demands help text for every exported field of every struct in internal/config:

// internal/configbuilder/fieldmeta_test.go (shape)
func TestFieldHelpCoverage(t *testing.T) {
    walk = func(rt reflect.Type) {
        /* only structs whose PkgPath ends in internal/config */
        for i := 0; i < rt.NumField(); i++ {
            f := rt.Field(i)
            if !isRoot && FieldMetaFor(rt.Name(), f.Name).Help == "" {
                missing = append(missing, rt.Name()+"."+f.Name)
            }
            walk(f.Type)
        }
    }
    walk(reflect.TypeOf(config.Config{}))
    /* t.Errorf listing every missing Struct.Field */
}

It is load-bearing for both editors: the terminal and web builders read help from the same registry (the web store fetches /config/fieldmeta), so a FleetSyncChannelConfig.DropBadCRC without a Help ships in neither. The second test reads the web builder’s TypeScript schema off disk — readWebTypes resolves web/configbuilder/src/api/types.ts from runtime.Caller — and fails when a config field has no counterpart there and is not on the round-trip allow-list, “a config change that the web Config Builder would silently drop on save/load”. The TUI has its twin, TestEveryLeafEditable. The third is on the web side: registry.test.ts holds a ROUTED_PATHS list — “every top-level route mounted by App.tsx must have a registry entry, otherwise it becomes unreachable by navigation (the pre-overhaul bug, where six DSP panels were orphaned)” — and App.panels.test.tsx mounts each listed route connected and asserts the error boundary never trips, with vi.mock("./api/fleetsync") supplying the client (Operator Cockpit Part 14). Adding /fleetsync to App.tsx without both lists fails one of them.

The CI job vitest cannot replace

This guard came from the console, not a decoder. npm test runs vitest, which transpiles with esbuild and never typechecks; npm run build is tsc --noEmit && vite build. Three TS6133 unused-parameter errors in web/src/api/reconnectingSocket.test.ts landed on main with green SPA jobs and broke make web-build for an operator. The only job that caught them was “Windows installer (PR)” — not a required check — so the PR merged red and read as passed.

ci.yml now carries web-typecheck, matrixed over web, web/configbuilder, web/siglab, web/rfscope and web/cryptolab — the last two built by no other workflow — running npm run typecheck in each. For a decoder landing: run cd web && npm run typecheck before pushing a panel, remember tsconfig.json sets noUnusedLocals and noUnusedParameters with test files inside include: ["src"] (an unused mock parameter needs a leading underscore), and check the non-required jobs on the PR too.

Message decoder or trunked protocol?

Not every decoder in this series took the eleven-place route. The AFSK, paging, APRS, ADS-B, AIS, DSC, LoRa and M17 decoders are message decoders with their own config section, bus kind, table and panel. The Part 13 trio are trunked protocols: they join the engine, whose Active, History and recorder are their UI. Decide before touching a file:

The routes are exclusive by design: the D-STAR landing touched site.go, pipelines.go, composer.go and recorder.go but no App.tsx. M17 is the reminder that the message route must be walked to the end: it has rows 1–4 and 6–11 — KindM17LinkSetup, m17_log, GET /api/v1/m17/linksetups, M17Config, FieldMeta, M17.tsx, the example block, the doctor entry, docs/m17.md — and no row 5: no /m17 in registry.ts, no panel in App.tsx, no m17 tab key. Nothing fails, because the route tests police routes that exist. That is the one gap the checklist cannot automate, and why the list is written down.

How the checklist shaped the Go code

• One generic per layer. eventLog[T] for storage, FieldMetaFor for help, useDataPoll for panels: a new decoder adds data, not machinery.
• Registries are walked, not listed. The guards reflect over config.Config and scan App.tsx’s routes — the structure is the checklist.
• Optional providers, nil-safe. A nil api.Options.FleetSync disables the route with a 503 that names storage.path.
• The doctor speaks the operator’s language. The preflight WARN names the decoder, the endpoint and the fix, because the failure it prevents was silent.

What’s still open

Each open item sits at a named gate:

• FleetSync on a live Kenwood fleet — offline-verified on the #1184 captures (5/6 and 8/8 CRC-valid, Fleet 107 / Unit 1772); the reporter’s on-air lab test is still open, and #437 with it.
• M17’s row 5 and its voice — no /m17 panel or tab key; no Codec 2 path; Golay matrix and slicer constants synthetic-verified only (Part 12).
• YSF’s FICH caller — DecodeFICHOnAir and ProcessFICH are tested but unjoined on the hot path, so a Fusion repeater locks and never grants (Part 13).
• dPMR’s CSBK channel coding — the cyclic + rate-¾ convolutional + interleave stage is absent; CSBKs are parsed as already-clean bits.
• D-STAR and dPMR voice tables — placeholder deinterleaves, synthetic round-trip only; the D-STAR header scrambler and interleaver await MMDVMHost table confirmation. Each needs a voice capture.
• Rows 10 and 11 have no test. A reflection walk diffing config.Config against config.example.yaml would close that.

None is blocked on effort; each is blocked on a capture, a reporter, or a wiring step whose verification needs one — the closing line of From Spec to Shipping Part 14, because it is the project’s operating principle: green synthetic is not on-air correct.

Where to go from here

The series index lists all fourteen parts. For the machinery every row rests on, SDR Internals is the foundation, starting with Part 11 where events.Kind begins. For the method behind every “unverified on air” above — From Spec to Shipping. Two series launch alongside this one: DMR End to End follows the trunked-protocol route to decrypted voice, and The Field Notebook reads the daemon’s log one line family at a time.

FAQ

What files does a new GopherTrunk message decoder touch? Eleven places: the protocol package and front end, an events.Kind, a storage log with its SQLite table and retention membership, a REST handler, the web client, panel, route and nav entry, the config struct and tab key, FieldMeta help, the Config Builder types.ts and section, the daemon wiring, the doctor preflight list, and config.example.yaml plus docs.

Which tests fail if I forget a config field’s help text? TestFieldHelpCoverage in internal/configbuilder walks every struct reachable from config.Config by reflection and lists each exported field without a non-empty Help in the FieldMeta registry. Both the terminal and web Config Builders read that registry, so the field ships in neither editor until help is written.

Why does npm test pass on code that fails npm run build? vitest transpiles with esbuild and never typechecks; npm run build runs tsc --noEmit first. With noUnusedLocals and noUnusedParameters set, an unused parameter is a TS6133 error the tests never see. Run npm run typecheck before pushing; the web-typecheck job also runs it.

Why does my decoder’s REST endpoint return 503? The daemon started without storage.path. Message decoders surface only through SQLite, so with storage off the receiver runs but nothing persists, and the handler answers 503 naming the fix. gophertrunk doctor warns at preflight for every message decoder that needs storage.

Should a new protocol be a message decoder or a trunked protocol? If it grants voice onto a channel the engine follows, it is a trunked protocol: add a Protocol enum, a pipeline factory, a composer voice kind and a vocoder mapping. If it produces messages to log and list — ANI bursts, pages, positions — it takes the eleven-place route.

Series navigation

Part 14 of 14 · ← Part 13: D-STAR, System Fusion & dPMR · Back to the series index

TL;DR: Debugging DMR in GopherTrunk is deciding which layer a symptom lives in, then reaching for that layer’s instrument. Never syncs → the 4FSK front end and, on a handheld, the carrier gate (Parts 1, 9). Syncs but no grants → cadence and link control (Parts 3, 5). One call for two talkgroups → the two-slot machinery (Part 6). “Call ended” mid-sentence → the forged terminator (Part 4). Missed replies → re-key rules (Part 6). A tap deaf for minutes at steady power → the bin edge and the deaf heal (Part 10). Frames that look scrambled → the Golay histogram (Parts 12, 13). Silent recordings on an encrypted call → the PI header line (Part 12). The running thread is the twin pair: one carrier carries two of everything — TS1/TS2, data/voice polarity, 132/288 cadence, Tier II/III, DDC/channelizer, live/replay — and half the confusing reports were one twin behaving differently from its sibling.

Key takeaways

• Locate the layer before touching anything. Every layer has a distinct counter in the activity line; the costliest mistake in this series was chasing ppm and gain on a receiver blinded by inter-burst gaps.
• Ask “which twin am I on?” early. Tier II never stamped the flag Tier III did; the harness sliced at 132 while production sliced at 288; the channelizer was deaf where the DDC heard.
• Counters beat absolute levels. dibits, sync_hits, beacons, late_entries, rekeys and deaf_heals diagnose; a dBFS figure never does — the deaf tap sat at −51 dBFS throughout.
• The open items are gated on evidence, not effort. Two live runs, one proprietary CSBK train and one unnamed emitter each wait for a capture this playbook names.

Cheat sheet

In this post

• The layer map — the whole stack, one table, symptom → instrument → part.
• Failure signatures — the reports operators actually file, decoded.
• The twin ledger — every pair where a fix touched one sibling, with receipts.
• What’s still open — the honest punch list, each item at a named gate.

The layer map

The series in one table: find the row whose symptom matches, read its instrument, and only then open the code.

Failure signatures

The layer map is for methodical triage; these are the shortcuts — the reports operators filed during this series, matched to their cause.

“It never syncs.” On a handheld, inter-burst noise blinded the receiver throughout #836 — with NoCarrierGate the production receiver yields zero sync words from the reporter’s 446.500 MHz slices (Part 9). On a repeater, the wideband hint strong in-channel signal but no sync names an uncorrected tuner offset, and its overload variant says gain comes first — though the #836 captures decode at 36–40 % of samples on the rail.

“It syncs but never grants.” Ask which cadence the voice decoder slices at: a handheld’s bursts are 288 dibits apart, and the single-slot 132 decoder slices the gaps — bogus ambe_ok, lc_superframes=0, no late entry (Part 3). If headers are lost on a weak tap, late entry grants from two agreeing CRC-valid embedded LCs ~720 ms in — check late_entries. On Tier III, work one LCN through dmr_band_plan (Part 8).

“One call for two talkgroups, and the audio is DJ-scratchy.” dmr_interleaved_voice was computed by the daemon but Tier II’s Options had no field for it, so both slots’ AMBE frames were sliced into one superframe. Fixed with a per-destination map assigning each call a synthetic Timeslot 1/2 and dmrSameCarrierTaps = 2 (Part 6). With no embedded LC, both slotRouters fall back to phase parity.

“GT said the call ended, but the conversation continued.” A forged terminator: Golay(20,8) decodes roughly a third of arbitrary words to some codeword, so about one voice burst A in twelve read as Terminator-with-LC. Slot types now come only from data-sync bursts, and an undecodable terminator needs a BPTC-valid payload (Part 4).

“Calls completely missed while the radios decode.” A re-key within hangtime: the slicer decoded the terminator 0.8–6.5 s after the composer, so the reply’s header was deduped as a repeat. A header more than headerRekeyDibits (0.25 s) past the call’s anchor re-grants; a fresh embedded LC after superframeRekeyGapDibits (2 s) re-grants by late entry — watch rekeys. Its mirror: ten header copies over 0.6 s are one keyup, anchored on the last copy (Part 5).

“A wideband tap goes deaf for minutes at normal power.” Two mechanisms (Part 10): the channelizer bin was −6 dB at its edge until channelizer.Oversampled, and the coarse acquirer froze on a −20.1 kHz neighbour in every idle gap. healDeafTier2 resets a tap that sees no sync for three windows within 6 dB of the level it last synced at — never an absolute dBFS — and rejects an engage the channel never synced under; deaf_heals counts.

“The frames look scrambled.” Count Golay corrections before any cipher theory: random words need exactly three ~73 % of the time, the shape the #1187 bursts showed when a simplex radio was sliced at 132 (Part 13).

“An encrypted call records silence.” Read composer: dmr PI header — call is encrypted: algorithm, key_id, key_configured. A key under a different key_id is never applied; Hytera, DES and AES are identified, not decrypted (Part 12).

The twin ledger

The series’ running thread, settled as a checklist. Every entry is a real divergence with a receipt — ask which side you are on before concluding anything:

The lesson has its own postmortem: every fix needs an explicit answer to “and the twin?” — in the PR, not in the next bug report.

How the twin thread shaped the Go code

• One flag, threaded through both tiers. InterleavedVoice rides tier2.Options and both constructors (ccdecoder/pipelines.go, widebandt2/engine.go).
• Per-polarity predicates, not a global sync table. SyncIsDataAtPolarity makes the data/voice question exact.
• Cadence is a default, not a config key. DMRVoiceCadenceDetected is true for every DMR protocol.
• Harnesses call the production constructors. TestDMRIPSCReplay builds tier2.New as the daemon does.

What’s still open

An honest playbook ends with its open items, each at a named gate, in the repo’s own verified-language:

• Direct mode on a live build — verified on the reporter’s 15 Sep captures; the live daemon run on a fixed build is the gate on #836.
• Enhanced Privacy through the daemon — capture-verified (b0 continuity 0.77 / 0.74); a live call with encryption_keys recording intelligible audio closes #1187.
• The cc=7 CSBK-CRC-fail train — a 30 ms-cadence train of BPTC-clean, CRC-failing CSBKs on the 443.2375 MHz repeater of a cc=12 system; real, not noise. Parked with info_hex; a capture of that frequency idle pins it.
• The −20 kHz emitter — ≈442.3675 MHz, dominating the Fire2 tap only in the repeater’s idle gaps. A ±100 kHz capture centred on 442.3875 MHz over one idle cycle names it; do not add a frequency bound to the acquirer.
• Two-slot audio on air — synthetic-verified; the A/B of two simultaneously recorded talkgroups still needs a decodable capture.
• srcList: [] — the per-call JSON shipped an empty talker list where trunk-recorder listed two radios; not investigated.

Every item is blocked on evidence, not effort — the sentence the P25 playbook closed on, because it is the project’s operating principle.

Where to go from here

For the same protocol-length treatment of the other trunking families, cross to TETRA End to End and P25 End to End. Two series launch alongside this one: Beyond Voice follows everything GopherTrunk decodes that is not a trunked call through one eleven-place wiring pattern, and The Field Notebook reads debug.log one line family at a time — its Part 5 is the DMR activity line. The Cookbook’s Tier III and two-slot conventional recipes run every layer mapped here; the DMR reference is the glossary.

FAQ

My DMR system won’t decode — where do I start? At the bottom of the layer map, with counters: is dibits climbing while sync_hits stays at zero? Is the radio a handheld or a repeater? Does the wideband hint name a tuner offset or an overloaded front end? A “no” at any row names your layer.

Why does GopherTrunk grant one call but I hear two conversations? The conventional path once folded a repeater’s two timeslots into one call because Tier II never stamped the interleaved-voice flag. Since the two-slot fix each concurrent talkgroup gets its own synthetic Timeslot and same-carrier tap; the two-slot A/B on a decodable capture is still pending.

What does a burst of “CSBK CRC mismatch” lines mean? Usually between-beacon noise, parked to one line per 10 s with a suppressed_repeats count. A sustained 30 ms-cadence train at a colour code your system does not use (cc=7 on a cc=12 repeater) is a real proprietary train that is still unpinned — its info_hex is the evidence to file.

Is DMR direct mode supported? Yes, and verified on the reporter’s 15 Sep captures: the carrier gate, feed-forward timing acquisition and header-train anchoring let a simplex handheld decode from its first burst. Still open is the reporter’s live daemon run on a build with those fixes (#764/#771).

Does this playbook transfer to TETRA or P25? The method does — locate the layer, read its counter, ask which twin you are on. The rows differ: P25’s twins are C4FM/CQPSK and Phase 1/2, TETRA’s are slot-grid and scramble-seed questions. Their playbooks close the TETRA and P25 series.

Series navigation

Part 14 of 14 · ← Part 13: Testing DMR Without a Repeater · Back to the series index

TL;DR: On any report, read five lines first: the daemon: WARNs in the startup block, the protocol’s cc locked line, its periodic status line (tetra: decode status, widebandt2: channel decode activity, tetra dmo: decode status, the MRC health line), the soapyremote: SDR overruns / ccdecoder: decode can't keep up WARNs, and recorder: call ended … reason=. Then the family tables give each line’s healthy shape, its worry-when, and the part that explains it. Keep noise meters apart from traffic counters — dnb_total vs dnb_qualified, bsch_ok vs sch_pdus, dibits vs sync_hits, coherence vs lock_gate, updates vs holds. And know what the log cannot yet say: the −20 kHz emitter, the cc=7 CSBK train, and the on-air gates (#836, #1003, #1187).

Key takeaways

• Five lines settle most reports. Startup WARNs, lock, status line, host WARNs, teardown reason — in that order, before any DSP theory.
• Every family has a noise meter and a traffic counter. The card names the pair; reason from the one that means decode.
• “Worry when” is relative, never absolute. Deaf is judged at the channel’s own last-decoding level, coherence against its own lock_gate.
• The card ends where the log does. Some symptoms are open questions with an instrument waiting for a capture; the card says which.

Cheat sheet

In this post

• The five lines to read first — the order that settles most reports.
• The card — one table per family: line → healthy → worry → open this.
• Noise meters vs traffic counters — the pairs that mislead.
• What the log still cannot tell you — the honest list.

The five lines to read first

Every report in this series’ source material was settled faster by this reading order than by any theory.

1. The startup WARNs. daemon: gain looks like dB, not tenths-of-dB — radio may be effectively deaf explained a −70 dBFS control channel before anyone measured anything. Two systems on one role: control tuner, dead channels:, a missing band plan — all announced here.

2. The lock line. tetra cc locked freq= mcc= mnc= la=, control channel locked nac= freq= (P25), dmr cc locked freq= cc= sysid=, tetra dmo cc locked. Without one, nothing downstream can be judged; cchunt: hunt failed — no control-channel lock with iq_observed= says whether IQ even arrived.

3. The status line. The protocol’s periodic DEBUG line is the instrument. Read its trend across intervals, never one line.

4. The host WARNs. soapyremote: SDR overruns … host_drops= and ccdecoder: decode can't keep up with real time … dropped_since_last= are downstream signals — the consumer stopped draining (Part 7).

5. The teardown reason. recorder: call ended … reason=timeout on every call means the voice chain decoded nothing that refreshed liveness — a decode problem in a recorder’s clothes (Part 11).

Healthy, on a TETRA rig:

INF tetra cc locked freq=467912500 mcc=250 mnc=1 la=1021 system=Metro-TETRA
DBG tetra: decode status system=Metro-TETRA locked=true carrier_off_hz=-412.5 baud=18000 baud_dev_pct=0.01 sb_bursts=72 bsch_ok=72 bsch_fail=0 sysinfo=18 sch_pdus=340 sch_pdus_fail=6 frag_abandons=1 grants=3 colour_code=1
INF recorder: call ended device=cc:same-carrier:1 wav=../recordings/Metro-TETRA/2001/... duration=5.6s reason=normal

Unhealthy — three lines, three different parts:

WRN daemon: gain looks like dB, not tenths-of-dB — radio may be effectively deaf serial=32B0A4C configured=50 parsed_db=5 did_you_mean=500
DBG tetra: decode status system=Metro-TETRA locked=true carrier_off_hz=4950.0 baud=17998 baud_dev_pct=0.02 sb_bursts=70 bsch_ok=69 bsch_fail=1 sysinfo=0 sch_pdus=0 sch_pdus_fail=58 frag_abandons=0 grants=0 colour_code=1
INF recorder: call ended device=cc:same-carrier:1 wav=../recordings/Site-DMO/0/... duration=7.0s reason=timeout

The middle line is the 19 Aug “locked but deaf” signature — bsch_ok ~100 %, sch_pdus=0, carrier_off_hz one alias bucket (4500 Hz) off (Part 4).

The card

Every field below is a real slog key; every “open” is the part or deep dive that explains the mechanism.

Startup & lock — all protocols

TETRA TMO

TETRA DMO

DMR — wideband and conventional

Host & front end

Captures, recorder, voice chain

Web

Noise meters vs traffic counters

Five pairs recur through the series; in each, the first moves on noise and the second means decode. Reason from the second.

• dnb_total vs dnb_qualified (DMO). The DNB correlator false-fires ~18/s on a silent channel by design arithmetic; only slot-grid-qualified bursts mean traffic.
• bsch_ok vs sch_pdus (TETRA). BSCH survives a 4-rotation search and heavy FEC, so it decodes through a wrong AFC alias bucket; sch_pdus does not.
• dibits vs sync_hits (DMR). Dibits prove the stream flows, not that any of it is DMR; the 12 Sep tap produced dibits for minutes with sync_hits=0.
• Wideband coherence vs lock_gate (MRC). |ρ| is diluted by every hertz of noise-only bandwidth — 0.16 on a rig decoding 1425 CRC-clean BSCH — so it only means something against the logged gate.
• updates vs holds (MRC). updates frozen with holds climbing is a combine running on a gain measured minutes ago.

Two rules of the same shape: never judge a channel by absolute dBFS (Analog Edge 13), and CRC yield is the only trustworthy metric; EVM is a trap (Weak-Signal 2).

What the log still cannot tell you

An honest card ends with the rows that have no “healthy” column yet.

• The −20 kHz emitter near 442.3675 MHz (15 Sep). The deaf heal rejects the false coarse engage it caused, but what transmits there is unknown; a ±100 kHz capture centred on 442.3875 MHz over one idle cycle is the instrument.
• The cc=7 CSBK-CRC-fail train on a cc=12 IPSC system (9 Sep). Parked with csbko/fid/info_hex in the DEBUG line.
• Three on-air gates. DMR direct mode is capture-verified but not yet run live on the fixed build (#836); the DMO pre-roll and grant-on-adoption pair is capture-validated only (#1003); DMR Enhanced Privacy decrypts the known-key captures and the live call is still owed (#1187). Those rows read “capture-verified, live run pending”.
• P25 Phase 1 weak-signal voice. The one C4FM path with neither equalizer nor soft FEC; no fix without a marginal voice capture (P25 12).

How this card shapes operator practice

• Read in order, stop at the first failure. The checks are ranked by how often they ended a thread.
• Quote the pair, not the number. bsch_ok=72 sch_pdus=0 is a diagnosis; bsch_ok=72 alone is a reassurance.
• Judge every “worry” relatively. Against the channel’s own level, its own gate, its own previous interval.
• Treat the open rows as invitations. Each names the capture that would close it; Part 13 says how to make and paste it.

Where to go from here

The notebook read the log; the rest of the blog explains the machinery. The series index is the card’s table of contents. For the recipes that produce these logs, The Operator’s Cookbook; for when a fix is verified, From Spec to Shipping. Two series launch alongside this finale: DMR End to End follows one carrier from 4FSK to decrypted Enhanced Privacy, and Beyond Voice walks the eleven-place pattern behind every non-voice decoder. When a row sends you to a capture, the Analog Edge tells you how to record it well.

FAQ

What are the first lines to check in a GopherTrunk log? In order: the daemon: WARNs in the startup block, the protocol’s cc locked line, the trend of its periodic status line, the soapyremote: SDR overruns / ccdecoder: decode can't keep up WARNs, and recorder: call ended … reason=. The first one that fails names the family table — and the part — to open.

Which log counters are noise meters rather than traffic? dnb_total (DMO), dibits (DMR), bsch_ok on its own (TETRA), wideband coherence read without its lock_gate, and calibrated=true without updates moving. Their partners — dnb_qualified, sync_hits, sch_pdus, lock_gate, updates — are the numbers that mean decode.

What does “locked but deaf” look like in the TETRA status line? locked=true, bsch_ok near 100 % of sb_bursts, sch_pdus=0, and carrier_off_hz about ±4500 Hz from where it sat — the AFC latched an alias bucket. The payload heartbeat forces a resync after 12 s and escalates to MarkLost after three fruitless ones.

Why does the card give no dBFS thresholds? Because every absolute-power gate in the project’s history became a gain-staging trap: a −56 dBFS control channel decoded every C_ALOHA while a WARN called it too weak, and MRC once demanded −40 dBFS to calibrate. The card judges everything relative to the channel’s own level or gate.

Which parts of GopherTrunk are still awaiting on-air verification? DMR direct mode’s live run on the fixed build (#836), the DMO pre-roll and grant-on-adoption pair in the live daemon (#1003), a live DMR Enhanced Privacy call with encryption_keys (#1187), and P25 Phase 1 weak-signal voice, which needs a marginal capture first.

Series navigation

Part 14 of 14 · ← Part 13: From Log to Issue — What to Paste, What to Capture · Back to the series index

TL;DR: Three packages, one shape, three verification states. D-STAR (internal/radio/dstar): GMSK at 4800 bps, BT 0.5, a 24-bit Frame Sync 0xEAA060, a 41-byte PCH header (flags, RPT2, RPT1, UR, MY1, MY2, CRC-CCITT) whose 660-bit FEC shell — framing.DecodeDStarHeaderFEC: K=5 ½-rate Viterbi, PN15 descramble, 22×30 deinterleave — runs under dstar_fec_mode: "on"; a CQCQCQ or /-routed UR becomes a trunking.Grant with Protocol "dstar". YSF (internal/radio/ysf): C4FM 4800 baud, 40-bit FSW 0xD471C9634D, a full FICH codec (DecodeFICHOnAir: 10×10 deinterleave, puncture {0,1,102,103}, ViterbiK5, CRC init 0x0000) that only tests call — the live pipeline locks on the FSW and stops. dPMR Mode 3 (internal/radio/dpmr): 4FSK at 2400 sym/s, FS3 → 80-bit CSBK → grants resolved through a LinearBandPlan; the CSBK FEC is not implemented. The D-STAR and dPMR voice chains (v1.1.2) decode AMBE 3600×2400 and AMBE+2 3600×2450 on placeholder deinterleave tables — unverified on air.

Key takeaways

• The same sync → slice → parse → grant shape covers all three. SyncDetector, a countdown Process adapter, a ControlChannel publishing lock and grant — D-STAR merely runs it on bits.
• D-STAR’s FEC chain is complete but self-consistent. Matching MMDVMHost’s exact scrambler and interleaver tables “is a follow-up calibration step”.
• YSF is one wiring step from a real decoder. DecodeFICHOnAir survives every single-bit flip, yet ProcessFICH has no caller outside its tests.
• A placeholder table is a placeholder, not a guess. Both voice chains deinterleave with a sequential split labelled PLACEHOLDER, so the swap is one function — and the first capture confirms it.

Cheat sheet

In this post

• One shape, three modulations — where the protocols enter.
• D-STAR — the GMSK header and its 660-bit shell.
• System Fusion — a FICH codec waiting for its caller.
• dPMR Mode 3 — CSBKs, band plans and the FEC that is not there.
• The voice chains — two AMBE paths and their placeholder tables.

One shape, three modulations

All three are trunking-engine protocols rather than message decoders: ProtocolDPMR, ProtocolYSF and ProtocolDStar live in internal/trunking/site.go, each has a ccdecoder pipeline factory, and all three run at the 48 kHz ddcTargetRateHz the C4FM family shares. That is the shape Protocol Decoders Part 1 laid down: a SyncDetector finds frame boundaries, a Process adapter counts out the payload after each match, a ControlChannel parses it and publishes events.KindCCLocked and events.KindGrant.

What differs is the physics. YSF is 4800-baud C4FM with RRC α = 0.20 — the P25 Phase 1 receiver with a different sync word. dPMR is the same 4-level scheme at 2400 sym/s with 900 Hz peak deviation. D-STAR is GMSK at 4800 bps, BT 0.5: one bit per symbol, so its receiver emits a BitSink. D-STAR and YSF are conventional — a “grant” announces a transmission on the monitored repeater; only dPMR Mode 3 has a real control channel and a band plan.

D-STAR: a GMSK header and its 660-bit shell

internal/radio/dstar/receiver composes demod.FM → demod.GFSK (a Gaussian matched filter and 2-level slicer) → sync.MuellerMuller → dstar.BitSink (reference). ControlChannel.Process runs a SyncDetector on the 24-bit Header Frame Sync at tolerance 2, then counts down a header window whose size FECMode chooses: HeaderBits (328) under FECOff, or framing.DStarHeaderChannelBits (660) under FECOn, where framing.DecodeDStarHeaderFEC recovers the 41 bytes first. Either way ParseHeader and a ComputeCRC check follow.

FECOff is the default and reads 328 information bits straight off the wire — right for synthesised fixtures. FECOn, selected per system with dstar_fec_mode: "on" and threaded through dstar.ParseFECMode in newDStarPipeline, is “the path that lights up on a live-air capture”. Its chain (reference): 328 info bits plus a 4-bit tail → K=5 rate-½ convolutional code (G1=0x19, G2=0x17, the ViterbiK5 pair) → 664 channel bits → puncture four → 660 → PN15 scramble → 22×30 block interleave, inverted on receive; TestProcess_FECOnSurvivesSingleBitError and TestDaemonCCDecodesDStarFECOn pin it. The file’s own caveat: the scrambler and interleaver are “self-consistent encode/decode pairs” whose match to MMDVMHost’s exact tables “is a follow-up calibration step” — the self-consistent trap named in advance, and why FECOff stays the default.

The 41 recovered bytes are the PCH header (reference): three flag bytes, four 8-character callsigns — RPT2, RPT1, UR, MY1 — a 4-character MY2, and a CRC-16-CCITT (poly 0x1021, init 0xFFFF), pinned by TestComputeCRCKnownVector to the standard "123456789" → 0x29B1 vector. Ingest decides everything from the header: a data header (Flag1Data) is ignored; the first valid header locks with RPT2 as the repeater; a UR of CQCQCQ or any /-prefixed routing publishes a grant with Protocol "dstar", the trimmed UR hashed into GroupID and MY1 into SourceID (hashCallsign). LockedNAC packs two bytes of the RPT2 callsign into the NAC slot as a stable per-repeater identity.

System Fusion: a FICH codec waiting for its caller

YSF’s frame is 480 dibits — 100 ms at 4800 baud (reference): 20 dibits of Frame Sync Word (FSWBits 0xD471C9634D), 100 of FICH, 360 of DCH. ysf.SyncDetector matches the 20-dibit FSWPattern within a tolerance of 2, and ControlChannel.Process does one thing with a hit: maybeLock, logging ysf cc locked. That is the whole live path.

The FICH is where the interesting code sits (reference): 32 information bits — frame type, call type, block and frame counters, data type, squelch mode and a 7-bit squelch code — plus a CRC-CCITT computed with framing.CRCCCITTWithInit(b[:4], 0x0000), the XMODEM initial value (TestFICHCRCUsesXMODEMInit). On the air those 48 bits pass through a K=5 ½-rate trellis with four tail bits (FICHChannelBits 104), lose the punctured positions {0, 1, 102, 103} (FICHOnAirBits 100) and are permuted by a column-major 10×10 interleaver — MMDVMHost’s schedule. DecodeFICHOnAir inverts it: deinterleave, depuncture with framing.DepunctureMark, framing.ViterbiK5 to 48 info bits plus a metric. TestFICHOnAirRecoversFromSingleBitFlip confirms every one of the 100 on-air positions is corrected. And ControlChannel.ProcessFICH knows what to do with a decoded FICH: a Header frame with CallTypeGroup publishes a trunking.Grant with Protocol "ysf" and GroupID = the squelch code (the DG-ID) when SquelchMode is set, else 0; a Terminator clears the dedup state.

The gap is the join. newYSFPipeline wires the receiver’s DibitSink to cc.Process only; nothing slices the 100-dibit FICH region, runs DecodeFICHOnAir and calls ProcessFICH — its only callers are in control_test.go. So a live YSF repeater locks, and no grant, call or recording follows; the control comment says so: “A future PR closes the IQ → dibit → FICH gap on the hot path”. samples/ysf/README.md names the fallback if MMDVMHost’s schedule fails a real FICH CRC: DSDcc’s spread puncture {0, 51, 52, 103}.

dPMR Mode 3: CSBKs, band plans and the FEC that is not there

Protocol Decoders Part 6 introduced dPMR’s three sync words and its 80-bit CSBK. internal/radio/dpmr/receiver is the C4FM chain at SymbolRate 2400 with DeviationHz 900 (reference). The control path in process.go runs one SyncDetector on FS3Dibits() at tolerance 1 and, after each match, collects 40 dibits, converts them with framing.DibitsToBits, parses with CSBKFromBits and calls Ingest (sync, CSBK).

Ingest is the state machine: MsgIdle is dropped; MsgStandingServiceStatus locks the channel with the broadcast’s DestID as SystemID (dpmr cc locked); MsgVoiceServiceAllocation or MsgIndividualVoiceAllocation locks if needed and publishes a grant. The 16-bit opcode-specific field carries the channel number, and a Resolver turns it into hertz: LinearBandPlan applies BaseHz + (channel + Offset) × SpacingHz — for PMR446, base 446 006 250 Hz, 6 250 Hz spacing, offset −1 — and TableBandPlan maps explicit entries. With no resolver the grant carries FrequencyHz 0. SetStrictValidation drops any CSBK whose 5-bit type is outside the documented set (TestStrictValidationDropsUnknownMessageType), the defence against a misaligned-but-passing window producing a phantom grant.

What is not there is the channel coding (reference): Mode 3 CSBKs carry a short-block cyclic code under a rate-¾ convolutional outer code plus an interleaver, and the package doc says “the parsing here assumes the upstream caller has already corrected errors”. The 40 dibits after FS3 are read as 80 clean bits — which is why strict validation exists and why TestDaemonCCDecodesDPMR is a synthetic lock, not a field result.

The voice chains and their placeholder tables

Both voice chains landed in v1.1.2 (2026-09-12) labelled “experimental, unverified on air”.

D-STAR voice is the original AMBE 3600×2400 — exactly the base internal/voice/ambe2 decoder, so the recorder’s map has "dstar": "ambe2" (Voice Coding, AMBE). VoiceChannel free-runs a 96-bit DV cadence — 72 voice bits then 24 slow-data bits — anchored on the 24-bit Slow Data sync (0x552D16) that every 21st DV frame carries; it re-anchors on every match and drops the anchor after two sync-less cycles. DecodeDVVoiceBits then runs the AMBE FEC shared with DMR and NXDN: Golay(23,12) over C0, a C0-seeded keystream XORed onto C1 before its own Golay, and the 12 + 12 + 11 + 14 = 49-bit ambe_d assembly.

dPMR voice is AMBE+2 3600×2450 — the DMR/NXDN codec — so "dpmr" maps to "ambe2-dmr" (AMBE+2 FEC) — v1.1.2 fixed a map that had pointed at the 2400 codebook. TrafficChannel runs FS1 and FS2 detectors, collects 168 dibits per 80 ms frame — 24 of CCH, skipped, then 144 of TCH — and ExtractTCHFrames carves four 72-bit AMBE+2 frames. runDPMRVoiceChain and runDStarVoiceChain decimate to 48 kHz and feed the recorder 7-byte frames.

The placeholder is the same in both: the function that maps 72 on-air bits into the C0..C3 sub-vectors. dstarAMBEDeinterleave and dpmrAMBEDeinterleave are direct sequential splits — C0 = bits 0..23, C1 = 24..46, C2 = 47..57, C3 = 58..71 — each marked PLACEHOLDER, to be replaced “once a capture is available to verify against”. TestDVVoiceBitsRoundTrip and TestTCHFrameRoundTrip are green — and prove only that the encoder inverse matches the decoder. The source cites CLAUDE.md’s TETRA-CRC lesson for why the real tables are not guessed: a wrong table that round-trips is the worst bug, because nothing in the tree can disagree with it (From Spec to Shipping Part 7). A voice capture confirms the table first and, for dPMR, the 2450-versus-2400 codebook second.

How these three shaped the Go code

• FECMode as a per-window latch. Process samples the D-STAR FEC mode at each Frame Sync match, so a mid-window flip cannot desynchronise the bit count.
• Voice trackers independent of the header. VoiceChannel and TrafficChannel anchor on their own syncs; a lost header costs a grant, never the audio cadence.
• Placeholders isolated to one function each, with encoder inverses in lock-step, so the capture-driven swap is a one-function change.
• Strictness as a knob, not a default. SetStrictValidation and the FECOff default keep fixtures green with the live-air posture one config line away.

Where this goes next

Twelve physical layers later, the pattern is the story. Part 14 closes the series with the checklist: the eleven places a new decoder touches, the three tests that police them, and the honest open list — including the FICH caller and the placeholder tables above.

FAQ

Does GopherTrunk decode D-STAR voice? Experimentally. The dstar voice chain anchors a 96-bit DV cadence on the Slow Data sync, FEC-decodes 72-bit AMBE frames and renders them through the base ambe2 (3600×2400) vocoder. Its deinterleave table is a documented placeholder validated only by synthetic round-trip, so the path is unverified on air until a real capture lands.

What does dstar_fec_mode do? It selects how many bits follow a Frame Sync. Off (the default) reads 328 information bits and parses them directly — right for pre-decoded fixtures. On reads the 660 on-wire bits and runs framing.DecodeDStarHeaderFEC (deinterleave, PN15 descramble, depuncture, K=5 Viterbi) first, which a live JARL DV-mode header needs.

Why does a System Fusion repeater lock but never record? Because the live YSF pipeline stops at the Frame Sync Word. The FICH codec (DecodeFICHOnAir) and the grant logic (ProcessFICH) both exist and are tested, but nothing on the hot path slices the FICH region and joins them, so YSF produces cc.locked and nothing else until that wiring lands.

How does dPMR turn a channel number into a frequency? Through a Resolver. LinearBandPlan applies base + (channel + offset) × spacing — for PMR446, base 446.006250 MHz, 6.25 kHz spacing, offset −1 so channel 1 lands on the base — and TableBandPlan maps explicit entries. Without a resolver the grant carries frequency 0.

Are the D-STAR and dPMR AMBE interleave tables correct? Unknown — that is the point of labelling them placeholders. Both use a sequential C0|C1|C2|C3 split so the FEC machinery can be exercised end to end; the real D-STAR dW/dX schedule and the dPMR TS 102 658 §6 table await a capture, because a guessed table that round-trips would hide the bug.

Series navigation

Part 13 of 14 · ← Part 12: M17 — The Open Digital Voice Link Layer · Next → Part 14: Adding a Decoder in a Day — The Checklist

TL;DR: GopherTrunk tests DMR in four layers. Literal vectors pin constants against sources that are not this code — real off-air CSBKs prove the 0x5A5A CRC mask, MMDVMHost’s DMR_IDLE_DATA BPTC-decodes to IdleInfoPattern, an independent CRC pins the PI header, and ep_issue1187_ptt1.json holds on-air Enhanced Privacy frames. Synthetic streams now transmit like a handheld — one 132-dibit burst per 288-dibit frame with receiver noise in the gaps — because every earlier fixture laid bursts back-to-back like a base station and hid #836 for its whole life. Committed slices (dmr-*.cfile, dmr-directmode-446500-*.cs16) replay real air in CI. Replay harnesses (TestDMRIPSCReplay with GT_DMR_DROP_HEADERS / GT_DMR_DROP_TERMINATORS, TestDMRIPSCWidebandReplay) turn an operator’s capture into an A/B. A C0/C1 Golay histogram is the first instrument when frames look scrambled: 73 % at exactly three corrections means mis-slicing, not a cipher.

Key takeaways

• A fixture that models the wrong transmitter validates the wrong receiver. Back-to-back bursts hid the direct-mode blindness; a header framed with the voice sync passed only because the slicer parsed slot types on every sync match.
• Constants need a witness that is not you. Off-air CSBKs, an MMDVMHost template, a Python CRC and a reporter’s frames each caught what a round-trip could not.
• Scrubs turn a capture into a counterfactual. Deleting every header or terminator from a real dibit stream models the fade or the missed release — and the harness must still grant.
• Read the Golay histogram before any cipher theory. Random words need exactly three corrections ~73 % of the time; real frames mostly need none.

Cheat sheet

In this post

• The fixture that transmitted like a repeater — how self-consistency hid #836.
• Literal vectors — constants pinned against witnesses outside the repo.
• Honest synthetic streams — gaps, header trains, phase sweeps, deaf taps.
• Committed real air — the slices CI replays every run.
• Replay harnesses and scrubs — the operator’s capture as an argument.
• What only air can prove — the open items and the histogram habit.

The fixture that transmitted like a repeater

The founding bug of this part is the one Part 9 fixed. A simplex handheld transmits one 27.5 ms burst per 60 ms frame — 132 dibits on, 156 off — and in the gap the discriminator of receiver noise is uniform over ±π, several times the signal’s swing. That noise inflated the symbol AGC, decayed the AFC, halved the coarse acquirer’s window mean and random-walked the timing loop, so no sync word ever matched. Every synthetic DMR fixture had laid its bursts back to back like a base station, so the receiver was never asked the question it failed.

That is the self-consistent trap in its transmitter-model dress, and DMR has two more specimens. The siglab Tier I fixture framed a Voice LC Header — a data burst — with the DM voice sync, and passed because the old slicer parsed a slot type on every sync match; once slot types were read only from data-sync bursts (Part 4), the fixture had to be corrected to DMData1. And the idle beacon (Part 7) read beacons=0 because no fixture ever contained an Idle burst — IngestBurst dropped slot type 9 and nothing objected. Each time, encoder and decoder written from one reading of the air agreed with each other and disagreed with the radio. The layers below are the countermeasures, in increasing power of proof.

Literal vectors: constants with an outside witness

The cheapest defence is a test whose expected bytes came from outside this code.

Off-air CSBKs. TestParseCSBKRealOffAirVectors holds 12-byte info blocks from 2 MS/s captures of two live Tier III control channels (440.5625 and 440.2625 MHz) that BPTC-decode with zero corrections. Under the previous CRC convention every one failed and the control channel never locked; under init 0x0000 with the 0x5A5A mask they validate — and their opcode bytes pinned the corrected table.

A template from another project. IdleInfoPattern (ff83df1732094ed1e7cd8a91) was measured on a beacon-only capture (2402 of 2416 Idle bursts). The independent witness is TestIdleInfoPatternMatchesMMDVMHostConstant, which BPTC-decodes MMDVMHost’s DMR_IDLE_DATA template from DMRDefines.h and requires the same 12 bytes with zero corrections — two codebases, one constant.

An independent CRC. TestParsePIHeaderReferenceLiteral pins the PI header’s 0x9696 mask with a Python-computed vector, because AssemblePIHeader’s round-trip agrees with any mask (Part 12).

A reporter’s frames. TestEPCaptureIssue1187 loads the PI header and three on-air superframes from voice/testdata/ep_issue1187_ptt1.json and asserts what no synthetic could: each embedded IV equals AdvanceMI of the MI before it, and the chain yields speech while the old semantics stay at ciphertext — the literal-vector rule at its strongest.

Honest synthetic streams

Vectors test parsers; demodulators need signal that models the transmitter the reporter owns. The direct-mode fixture in receiver/receiver_burst_test.go is the template. directModeIQ lays bursts on a dmFrameDibits = 288 grid with dmOffDibits = 156 of transmitter-OFF per frame, renders the OFF time as AWGN when gapped, applies a carrier offset and per-axis noise, and gates on the grid delayed by the RRC filter’s modSpan·sps samples; dmHeaderBursts cycles the source ID from burst to burst.

Three lessons are encoded there. Gaps are noise, not filler — the point of #836. Repetition is a bias: one identical burst repeated for seconds carries a symbol-mean bias the open-loop AFC reads as drift (the #402 failure mode), so the source ID varies, and the pipeline fixture directModeTransmissionIQ models a PTT as 3 headers plus random voice bursts, two PTTs apart, at the reporter’s −1.2 kHz offset. Group delay is real: gate on the undelayed grid and every burst loses its tail.

TestReceiverDecodesDirectModeBurstCadence is the failing-first pin — with NoCarrierGate the production receiver yields zero sync words from a 27 dB stream — and TestReceiverCarrierGateIsNoOpOnContinuousCarrier keeps the repeater path byte-identical. Around it: timing_acq_test.go cold-starts a keyup at every sub-symbol phase; conventional_headertrain_test.go lays ten header copies 60 ms apart and requires one grant; conventional_lateentry_test.go forges a terminator from voice bits (TestConventionalVoiceBurstCannotForgeTerminator) and parks the CSBK failure log (100 identical failures → one line, suppressed_repeats=99); conventional_rekey_test.go and conventional_twoslot_test.go cover re-keys and two-slot calls. Above the protocol, engine_deafheal_test.go stands a resetCountingReceiver in for the Tier II receiver and feeds scaledIQ at −51 dBFS: a tap that synced and then sees three windows with no sync at its own level is reset once; one whose carrier drops to −70 dBFS is idle and never reset. coarse_reject_test.go pins that a rejected engage reverts and never re-engages nearby.

Committed real air

The third layer embeds the reporter’s air in CI. dmr-t3-cc.cfile and dmr-voice-term.cfile are channelized slices of a live 441 MHz Tier III system; TestReplayDMRTier3ControlDecodesRealAir requires the production receiver plus ControlChannel to lock on a CRC-valid Aloha, and TestReplayDMRVoiceLCFECDecodesRealAir decodes Terminator-with-LC bursts through the exact BPTC(196,96) → RS(12,9) → FLC stack the Voice LC Header uses (TG 24 / source 4209000), the confirmation issue #527 called blocking.

The direct-mode pair is newer. dmr-directmode-446500-keyup-48k.cs16 (a ten-copy header train, then voice) and dmr-directmode-446500-ptt2-48k.cs16 (the second PTT’s onset) are 48 kHz slices of the #836 reporter’s 446.500 MHz captures through the production ccdecoder.Downconverter. They pin what only that air could: TestDMRDirectModeRealAirKeyup requires the ungated receiver to find zero sync words (the gate is load-bearing) and the gated one at least 8 MS-Data and 2 MS-Voice syncs; TestDMRDirectModeRealAirOnsetAtEveryPhase cold-starts the second PTT at ten sub-sample offsets and requires each to decode — the pre-fix receiver took 1.3–2.8 s at three. With 36 % of raw samples at the ADC rail it decodes anyway, which retired “clipped ⇒ undecodable” as too strong.

Replay harnesses and scrubs

Committed slices are seconds long; the reporter’s problem is minutes long. The fourth layer is the skip-gated harness that takes an operator’s whole capture: TestDMRIPSCReplay (GT_DMR_IQ; raw cs16/f32 take a rate and format, wav and flac are content-sniffed). It mirrors the daemon’s Tier II decode — DDC, receiver, then the dibits to both the conventional state machine and the voice superframe decoder — and prints one ledger:

grants=5 late_entries=0 rekeys=4 fec_pass=… csbk_crc_fail=… beacons=… scrubbed_headers=0
superframes=… lc_superframes=… ambe_ok=… ambe_uncorrectable=…

The two consumers are the triage: zero superframes is a receiver problem; superframes with AMBE decoding but no grants is a control-path problem. The scrubs make the harness a counterfactual engine. GT_DMR_DROP_HEADERS=1 deletes every Voice LC Header burst from the real dibit stream — the on-air model of a keyup lost to a fade — and late entry (Part 5) must still grant every transmission from its embedded LC: 5/5 with late_entries=5 on the 9 Sep captures. GT_DMR_DROP_TERMINATORS=1 deletes every Terminator-with-LC instead — the 10 Sep condition where the control path never saw the release — and each reply must be re-granted: old code 1 grant for 5 transmissions, new 5 with rekeys=4 (Part 6). GT_DMR_INTERLEAVED=1 selects the cadence-detecting voice decoder — the harness asks for it when it sees MS-sourced sync words, because the single-slot decoder’s ambe_ok on a simplex capture is bogus and lc_superframes reads 0 (Part 3).

TestDMRIPSCWidebandReplay (GT_DMR_WB=1) is the two-pipelines instrument: it interpolates a 25 kS/s slice to the field bin geometry (8 bins of 6.25 MS/s ÷ 32, the tap at +687.5 kHz, 0.48 bins off centre) and feeds a ChannelizerBank and a DDCBank from the same stream (GT_DMR_WB_CHUNK for live-sized chunks). It reproduced the 12 Sep deafness exactly — polyphase 1991 beacons / 2 grants versus DDC 6103 / 7 over 300 s — and after channelizer.Oversampled the arms match window for window (Part 10). A clean synthetic carrier at residual 0.48 still granted through the old bank, so the regression is a tone-flatness pin (TestChannelizerBankBinEdgeChannelIsFlat), never a grant count. TestDMREnhancedPrivacyReplay completes the set, all following the capture-driven method.

What only air can prove

The histogram habit first, because it settled #1187 in one pass. When frames look scrambled, dump them (GT_DMR_EP_DUMP, golay_errs per frame) and count Golay corrections per C0/C1 word before any cipher theory. Random input needs exactly 3 corrections most of the time — the #1187 bursts B–F showed 73 % at exactly 3, 12 % at exactly 2 while burst A was clean: a slicer reading inter-burst gaps, not encryption. Real frames cluster at zero.

Then the honest list — no layer here proves on-air behaviour, the #764/#771 rule this repo carries as policy. Direct mode is verified on the reporter’s 15 Sep captures and the live run on a fixed build is still open; Enhanced Privacy is capture-verified, live daemon call open; the cc=7 CSBK-CRC-fail train and the −20 kHz emitter beside the IPSC repeater are unresolved, waiting for the capture that names them.

How the fixtures shaped the Go code

• Fixtures model the transmitter the reporter owns. directModeIQ and directModeTransmissionIQ carry the frame grid, gaps, header train and RRC delay as named constants.
• Every constant has a second source. IdleInfoPattern, the CSBK mask and the PI mask each ship with a test whose expected value came from elsewhere.
• Harnesses skip, never rot. Each GT_DMR_* harness t.Skips without its input, so a contributed capture slots into an existing socket.
• Scrubs are first-class. Header and terminator deletion live in the harness — a field condition is one env var away.

Where this goes next

Thirteen parts down, one to go. Part 14 folds the series into what you want at the bench: the layer map from antenna to WAV, the failure signatures operators report, the twin ledger and the open list with its gates.

FAQ

How do I test a DMR decoder without a repeater? In layers: pin wire formats with vectors from independent decoders (off-air CSBKs, MMDVMHost templates), synthesise carriers that model a real transmitter’s gaps and header trains, replay the committed real-air slices, and run your own capture through TestDMRIPSCReplay with GT_DMR_IQ.

Why did synthetic DMR tests pass while direct mode never decoded? Because every fixture laid bursts back-to-back like a base station. A handheld transmits one burst per 60 ms frame with receiver noise between, and that noise wrecked the AGC, AFC and timing loops. The fixture had to model the gaps before the failure could be observed.

What do the header and terminator scrubs prove? Counterfactuals on real air. GT_DMR_DROP_HEADERS=1 deletes every Voice LC Header from a captured dibit stream and late entry must still grant every transmission; GT_DMR_DROP_TERMINATORS=1 deletes every release and each reply must be re-granted. Both reproduce field reports from one capture.

How can I tell scrambled frames from mis-sliced frames? Count Golay corrections per frame (GT_DMR_EP_DUMP writes golay_errs). Random words need exactly three corrections about 73 % of the time and two about 12 %; real frames need almost none. A histogram peaked at three means the slicer is reading inter-burst gaps, not that the payload is encrypted.

What still needs on-air confirmation for DMR? The reporter’s live direct-mode run on a build with the #836 fixes, a live Enhanced Privacy call through the daemon with encryption_keys configured, the cc=7 CSBK-CRC-fail train, and the −20 kHz emitter near the IPSC repeater. Each waits for a capture (#764/#771).

Series navigation

Part 13 of 14 · ← Part 12: Enhanced Privacy — RC4 & the IV That Names the Next Superframe · Next → Part 14: The DMR Playbook

TL;DR: A report that gets fixed pastes three blocks — the startup block (banner to first cc locked, WARNs included), the protocol’s status-line family across the event (tetra: decode status, the DMR activity line, the MRC health line), and 30 s around the event with the siglab: capture started/ended bracket so the file maps onto log time. Then the capture that matches the question: gophertrunk capture (IQ + .metadata.json, with ppm and clipping verdicts), baseband.auto_record.on_cc_sync_loss for a lock that drops, sdr.soapy_remote[].diversity_capture for anything about MRC — every other tap is post-combine. IQ, never audio, honest rate. The close: only when a failing-first regression passes and the reporter confirms; .claude/hooks/guard-issue-close.py asks a human first, and PRs say Refs #N, not Closes #N, until then (#764 / #771).

Key takeaways

• Paste the family, not the line. One WARN is a symptom; the status lines around it are the instrument reading.
• Align clocks before anyone reasons. capture started plus the file’s elapsed turns “the deaf stretch” into a sample offset.
• The right capture is taken at the right tap. Post-combine cannot answer a combiner question; audio cannot answer a phase question.
• “Fixed” and “verified” are different words on purpose. A merged PR is a hypothesis; the issue closes when the symptom is gone.

Cheat sheet

In this post

• What a report is telling the maintainer — a claim and its evidence.
• What to paste — three blocks; a healthy and an unhealthy report.
• Aligning a capture to the log — the bracket fields.
• Which capture to make — from question to tap.
• The words that close an issue — the verified-language policy.

What a report is telling the maintainer

An issue is a claim — the rig did X when it should have done Y — and GopherTrunk’s verification culture (From Spec to Shipping Part 14) accepts no claim above its evidence. The log turns the claim into a measurement, and it was designed to be pasted: Part 13 of that series argued for branch-complete counters and persistent WARNs so a field log answers the next question without a round trip. The log cannot supply the version, or the config with secrets stripped (Cookbook 14’s hygiene rule).

What to paste

Three blocks; each exists because a real thread stalled without it.

1. The startup block — banner to first lock, WARNs included. The 13 Sep DMO operator’s CC sat at −70 dBFS because gain: 50 meant 5 dB, and the daemon had said so:

WRN daemon: gain looks like dB, not tenths-of-dB — radio may be effectively deaf serial=32B0A4C configured=50 parsed_db=5 did_you_mean=500 hint="gain: is in TENTHS of a dB (\"320\" = 32 dB). ..."

Omit it and you invite a week of DSP theory (Part 1).

2. The status-line family across the event — the protocol’s periodic line from minutes before the symptom to minutes after, so the trend shows: tetra: decode status, widebandt2: channel decode activity, the MRC health line, tetra dmo: decode status. These are DEBUG lines — run at log.level: debug or the report describes a symptom nobody can measure.

3. Thirty seconds around the event, with the siglab: capture started/ended bracket if you recorded IQ, and the nearest runtime: heartbeat so CPU starvation can be ruled in or out (Part 7).

A report that answers, from a TETRA rig losing lock:

DBG tetra: decode status system=Metro-TETRA locked=true carrier_off_hz=-412.5 baud=18000 baud_dev_pct=0.01 sb_bursts=72 bsch_ok=72 bsch_fail=0 sysinfo=18 sch_pdus=340 sch_pdus_fail=6 frag_abandons=1 grants=3 colour_code=1
INF siglab: capture started serial=32B0A4C center_hz=467912500 sample_rate_hz=144000 bandwidth_hz=100000 requested_center_hz=467912500 tuner_center_hz=467700000 tuner_rate_hz=2000000 format=flac seconds=60 protocol=tetra path=../captures/tetra_467.9125MHz_144k.flac
DBG tetra: decode status system=Metro-TETRA locked=true carrier_off_hz=-418.0 baud=17998 baud_dev_pct=0.02 sb_bursts=70 bsch_ok=61 bsch_fail=9 sysinfo=14 sch_pdus=88 sch_pdus_fail=41 frag_abandons=4 grants=0 colour_code=1
DBG tetra: dsp resync (signal-time decode drought; reacquiring symbol timing from centre) system=Metro-TETRA
INF siglab: capture ended serial=32B0A4C center_hz=467912500 sample_rate_hz=144000 format=flac samples=8640000 elapsed=1m0.012s path=../captures/tetra_467.9125MHz_144k.flac recorded_seconds=60

bsch_fail climbing, sch_pdus collapsing, a resync, sixty seconds of IQ around it. The unhealthy twin arrives more often:

WRN tetra: payload drought persists across resyncs (sync bursts decoding, no SCH payload) — declaring lock lost to force a re-hunt system=Metro-TETRA attempts=3

One WARN, no status lines, no capture. It says the lock was declared lost, not whether the carrier faded, the AFC latched an alias bucket (Part 4) or the host starved. The next comment will ask for block 2.

Aligning a capture to the log

A capture and a log are two clocks; the bracket fields map one onto the other:

The alignment is one subtraction: capture started is the file’s sample zero, so a log event at T sits (T − started) × sample_rate_hz samples in. The 12 Sep IPSC investigation was decided this way — a 20-minute FLAC aligned to the live log at offset 23:41:31.28 showed the Fire2 tap logging sync_hits=0 for six stretches of 180–210 s while the same seconds decoded every transmission offline. That split “the capture is bad” from “the live tap went deaf”; dibits and healDeafTier2 followed from it. One trap: the log is local time while the API and sidecars are UTC (Part 12).

Which capture to make

The expensive mistakes happen before recording starts (From Spec to Shipping 11): wrong tap, wrong content, wrong physics.

gophertrunk capture heads the table because it grades its recording. Samples pinned at the ADC rail print capture: WARNING — N% of the recorded samples are pinned at the ADC rail: the front end was overloaded … NO receiver … can decode this file plus the remedy. A carrier off centre prints capture: WARNING — the recorded carrier sits N kHz above/below centre (≈N ppm at this frequency); the probe reads only the first ~11 ms, so a momentarily-strong neighbour can fool it (#1143).

Physics, then rate, then metadata. docs/decoder-capture-needs.md puts physics first: for anything carrying information in phase or 4-level amplitude — TETRA, NXDN, YSF, DMR, M17, P25 — demodulated audio is useless. IQ or nothing, .cfile or cs16 — the #1187 “RC4 audio” files failed discriminatorAudioSanity. Rate next: TETRA wants ≥ 72 kHz; 48 kHz cannot lock. Then the sidecar: neither format embeds a rate or centre, so <stem>.metadata.json with protocol, sample_rate_hz and center_freq_hz is mandatory — gophertrunk test -capture grades against it, and -sigmf emits a SigMF twin (Analog Edge 10 is the full treatment). Content matters too: a 25 s silent DMO PTT was a poor vector; the ask that worked was known colour, actually talking.

The words that close an issue

The maintainer writes the last part, under the repo’s strictest rule — CLAUDE.md’s issue-closing policy:

• Never close an issue as completed until the fix is verified: a failing-first regression test passes and the reporter has confirmed it, or the original symptom was reproduced and shown resolved.
• When you can’t verify, leave it open — post a concise status comment saying what was found and what is blocking.
• Address the latest follow-up, not the original report.
• In PRs, prefer Refs #N over Closes #N until verified, so a merge cannot auto-close. not_planned and duplicate are ungated.

It exists because #764 was closed twice on an unverified fix while the symptom stayed live (#771) — the two-pipelines trap of Issue Tracker Part 22 — and a PreToolUse hook gives it teeth:

# .claude/hooks/guard-issue-close.py (shape)
is_close_completed = (
    ti.get("method") == "update"
    and ti.get("state") == "closed"
    and ti.get("state_reason") in (None, "", "completed")
)
if not is_close_completed:
    return 0  # comments, labels, reopens, not_planned, duplicate pass
# else: emit an "ask" decision restating the bar

The PR template’s last line is literally Closes #NNN / Refs #NNN; Refs is the default. For a reporter this means your confirmation is the last gate: when a maintainer asks you to run the fix, or to replay your capture through a harness such as TestTETRADMOReplay or TestDiversityCombinerReplay, that is the step nobody may skip on your behalf. “Capture-verified, live run pending” is the same discipline, spoken carefully.

How this line shapes operator practice

• Run at debug when something is wrong. The status-line families are DEBUG; an INFO log has no counters to trend.
• Bracket every capture. Start it from the daemon so the bracket lands in the symptom’s log.
• Never reason from a lone WARN. Find its family first.
• Say what you verified, exactly. Capture-verified and live-verified are different claims.

Where this goes next

Thirteen parts have read the log one family at a time; the finale folds them into one page. Part 14 is the field card — one table per protocol family, the noise-meter list, and the five lines to read first on any report.

FAQ

What should I include in a GopherTrunk bug report? The version, the config with secrets stripped, and three log blocks from a log.level: debug run: the startup block through the first lock, the protocol’s periodic status line for minutes either side of the event, and thirty seconds around the event with any capture bracket. Attach or link IQ, not audio.

How do I line up an IQ capture with the daemon log? The siglab: capture started timestamp is the file’s sample zero, and capture ended carries samples, elapsed and recorded_seconds; a log event at time T sits (T − started) × sample_rate_hz samples in. The log is local time; sidecars are UTC.

Which GopherTrunk capture do I use for a diversity or MRC problem? Only sdr.soapy_remote[].diversity_capture. It taps both branches before the combiner and writes <prefix>.br0.cs16, .br1.cs16 and a .diversity.json sidecar; every other recording path is downstream of the combine and has one combiner baked in.

Why won’t GopherTrunk close my issue when the PR is merged? Because the policy separates fixed from verified: a close claims the symptom is gone, earned by a failing-first regression passing and the reporter confirming. PRs say Refs #N so a merge cannot auto-close, and a hook asks a human before any close-as-completed.

Can I send a WAV of the audio instead of IQ? For FM-audio formats — MPT 1327, and as a fallback for POCSAG/FLEX/DSC — yes. For TETRA, DMR, P25, NXDN, YSF and M17, no: the information is in phase or 4-level amplitude and demodulated audio has destroyed it. Record IQ with a .metadata.json sidecar.

Series navigation

Part 13 of 14 · ← Part 12: Web Symptoms That Are Really Log Stories · Next → Part 14: The One-Page Field Card

TL;DR: internal/radio/m17 decodes the M17 link layer: who is transmitting to whom, in what mode. The receiver (internal/radio/m17/receiver) is the P25 Phase 1 front end re-tuned — FM demod → resample to 48 kHz (BaudHz 4800 × Oversample 10) → C4FM matched filter with rrcAlpha 0.5 → Mueller-Müller timing → 4FSK slice → symbolToDibit (+1→00, +3→01, −1→10, −3→11). Decoder.Push hunts the stream sync 0xFF5D, collects the 96-bit LICH (four Golay(24,12) codewords → 40 LSF bits + a 3-bit counter), skips the 272-bit payload, and LICHAssembler stitches six chunks into the 240-bit LSF — DST 48 · SRC 48 · TYPE 16 · META 112 · CRC 16, base-40 callsigns, CRC-16 poly 0x5935. Each LSF becomes events.KindM17LinkSetup, an m17_log row and GET /api/v1/m17/linksetups. Not decoded: the Codec 2 voice payload, the dedicated LSF frame (0x55F7), packet frames (0x75FF) — and there is no /m17 web panel yet. Everything is spec-derived and synthetic-verified only (#479).

Key takeaways

• M17 is the one digital-voice mode with no closed layer. 4FSK, framing, FEC and the Codec 2 vocoder are all published, so the decoder’s boundary is a milestone line, not a licensing line.
• The LICH is a late-entry mechanism, and GopherTrunk uses it as the primary route. Every stream frame carries one sixth of the LSF under Golay(24,12); six frames — about 240 ms — reassemble it, no Viterbi.
• The decoder is a three-state machine that reads 96 bits per frame and skips 272. stHunt → stLICH → stSkip.
• Synthetic-green is the honest status. TestDecodeLSFFromLICHStream proves the chain against GopherTrunk’s own encoder; the source says the Golay matrix “should be confirmed against a capture”.

Cheat sheet

In this post

• The friendly protocol — why openness changes what a decoder can promise.
• Two roads to the LSF — the dedicated frame versus the LICH.
• 4FSK to bits — the receiver constants and the dibit map.
• The three-state decoder — sync hunt, LICH collect, payload skip.
• Inside the Link Setup Frame — base-40 addresses, TYPE bits, the CRC.
• Where the decoder stops — Codec 2, packet mode, panel, capture gate.

The friendly protocol

Every digital-voice mode this blog has covered ends at a vocoder somebody else owns — IMBE, AMBE+2, the AMBE variants of Part 13. The M17 Project instead published a 4FSK air interface at 4800 symbols per second, a framing layer, a convolutional-plus-Golay FEC stack and the royalty-free Codec 2 vocoder (reference). No layer is closed to a pure-Go receiver.

That changes the honest claim. For D-STAR the line between decoded and not-decoded is partly a licensing line; for M17 it is purely a milestone line, and the internal/radio/m17 package doc draws it in its first paragraph: the package “owns the metadata path” and “the Codec2 voice payload is a later milestone”. M17 runs in two link modes, both visible in the LSF’s TYPE field: stream for real-time voice and/or data, packet for connectionless data. Callsigns are base-40 integers in 48 bits, so a source and a destination fit in twelve bytes.

Two roads to the Link Setup Frame

The LSF is 240 bits — a 48-bit destination, a 48-bit source, a 16-bit TYPE, a 112-bit META block and a 16-bit CRC (reference) — and it reaches a receiver two ways. Choosing between them is the package’s central design decision.

The first road is the dedicated LSF frame at the head of a transmission, sync word 0x55F7. Its payload is convolutionally coded and punctured, so decoding it needs a K=5 Viterbi decoder and a depuncture table, which the M17 package deliberately does not use.

The second road is the LICH — the Link Information CHannel in every stream frame. Each frame carries one sixth of the LSF, 40 bits, under four Golay(24,12) codewords, plus a 3-bit counter naming which sixth. Six consecutive frames reassemble the whole LSF. This is M17’s late-entry mechanism, and it needs only framing.GolayDecode24_12:

// internal/radio/m17/lich.go (shape)
const LICHBits = 96  // four Golay(24,12) codewords per stream frame
const lichChunks = 6 // six 40-bit fragments per 240-bit LSF

func (a *LICHAssembler) Push(lich []byte) (LSF, bool) {
    var chunk uint64
    for i := 0; i < 4; i++ {
        data, errs := framing.GolayDecode24_12(cw) // cw: 24 wire bits
        if errs < 0 {
            a.golayErrors++
            return LSF{}, false // uncorrectable — drop this LICH
        }
        chunk = chunk<<12 | uint64(data&0x0FFF)
    }
    frag := chunk >> 8              // top 40 bits: the LSF fragment
    cnt := int((chunk >> 5) & 0x07) // next 3 bits: which sixth
    /* store frag at lsf[cnt*5:], mark have[cnt]; when all six: ParseLSF */
}

A stream frame is 40 ms, so six are ~240 ms. A LICH with an uncorrectable codeword is simply dropped: the assembler keeps its fragments and waits for that sixth to repeat, because the LSF repeats for the life of the transmission.

4FSK to bits

The receiver is the C4FM chain from P25 End to End Part 1 with M17’s numbers dropped in:

// internal/radio/m17/receiver/receiver.go (shape)
const (
    BaudHz      = 4800   // symbols/s
    Oversample  = 10     // matched-filter samples per symbol
    AudioRateHz = BaudHz * Oversample // 48 000
    rrcAlpha    = 0.5    // M17 RRC roll-off
    deviationHz = 2400.0 // peak (outer-symbol) deviation
    mmGain      = 0.05
)

New builds demod.NewC4FM(Oversample, 8, rrcAlpha, dev) where dev is 2π·deviationHz/AudioRateHz — the outer symbol’s phase step per sample, the slicer’s scale — and a MuellerMuller loop at gain 0.05 (SDR Internals Part 7). Two numbers differ from the P25 chain: roll-off 0.5, not 0.2, and 2400 Hz deviation at the outer symbol. feedSymbol slices each symbol, maps it with the M17 convention (+1→00, +3→01, −1→10, −3→11) and pushes the two bits into the decoder MSB first. The package doc calls these constants nominal: “like the POCSAG frontend, on-air calibration against a real capture is a follow-up”. receiver_test.go pins construction and the dibit map (TestSymbolToDibit) — not decode yield on real IQ.

The three-state decoder

m17.Decoder consumes one bit at a time. stHunt shifts bits into a 16-bit register until it equals SyncStream; stLICH collects 96 bits for the assembler; stSkip counts out the rest of the 368-bit payload — 272 bits of frame number and Codec 2 — and returns to the hunt:

// internal/radio/m17/decoder.go (shape)
const (
    SyncStream uint16 = 0xFF5D // stream frame
    SyncLSF    uint16 = 0x55F7 // dedicated link-setup frame
    SyncPacket uint16 = 0x75FF // packet frame
)
const streamPayloadBits = 368 // 96 LICH + 272 skipped

case stHunt:
    d.reg = (d.reg << 1) | uint16(b)
    if d.reg == SyncStream {
        d.syncs.Add(1); d.st = stLICH; d.n = 0
    }
    // LSF / packet syncs are recognised but their payloads need the
    // convolutional path; the LICH route carries the same metadata.

That comment is the architecture in two lines: the LSF and packet sync words are known, but a match on either does nothing. Stats exposes Syncs and LSFDecoded — the counters to read first if a configured M17 channel stays silent.

Inside the Link Setup Frame

ParseLSF takes the 30 assembled bytes and never errors — a bad CRC sets CRCOK=false while the fields stay populated, so a marginal decode is shown flagged rather than swallowed:

// internal/radio/m17/m17.go (shape)
type LSF struct {
    Dst, Src string // callsign / "BROADCAST" / "#RESERVED"
    Meta     []byte // 14-byte META block
    CRCOK    bool
    Stream   bool   // TYPE bit 0: stream (vs packet) mode
    DataMode uint8  // TYPE bits 1..2: 1 = data, 2 = voice, 3 = voice+data
    CAN      uint8  // TYPE bits 7..10: channel access number
}

DecodeAddress treats the 48-bit value as a base-40 integer over the alphabet " ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-/.", taking addr % 40 as the next character, dividing, and reversing at the end. Zero decodes to the empty string, all-ones to BROADCAST, and anything above 40⁹ (0xEE6B28000000) to #RESERVED. The CRC is polynomial 0x5935, initial value 0xFFFF, MSB-first, no final XOR, over DST through META. TestCRC16DetectsCorruption flips one bit and asserts the check fails; TestDecodeLSFFromLICHStream pushes six encoded LICH frames through the decoder and asserts AB1CDE → M17-USA decodes with CRCOK true and DataMode 2.

The receiver’s publish then builds a storage.M17LinkSetup — Src, Dst, Mode (ModeString: voice / data / voice+data / packet), CAN, hex Meta, CRCOK, a display Body — and publishes events.KindM17LinkSetup (m17.linksetup over SSE). storage.M17Log, one instantiation of the generic eventLog[T] writer, lands rows in m17_log, indexed on received_at and src and swept by retention.log_days (Recording Part 10); GET /api/v1/m17/linksetups?limit=N reads them back newest first.

Where the decoder stops

Four things are not decoded today, each a different kind of gap.

The Codec 2 voice payload. The 272 bits after the LICH are consumed by stSkip and discarded. Decoding them needs the K=5 Viterbi plus depuncture path and a pure-Go Codec 2 port that does not exist in the tree; the vocoder registry from SDR Internals Part 12 has no Codec 2 entry.

The dedicated LSF frame and packet mode. SyncLSF and SyncPacket are recognised; their payloads need the convolutional decoder the package omits. docs/m17.md defers the standalone LSF decode “since the LICH route already covers it”, but packet frames carry data the LICH never sees, so packet M17 is invisible beyond its sync word.

The web panel. This is the eleven-place pattern from Part 1 with a hole in it. M17 has the config struct, FieldMeta help, a Config Builder section (web/configbuilder/src/sections/M17.tsx), the config.example.yaml block, the doctor entry, bus kind, storage table, retention membership and REST route — but web/src/nav/registry.ts has no /m17 entry, App.tsx mounts no M17 panel, and the web.tabs key list has no m17. Decoded LSFs are reachable over REST and nowhere in the console — Part 14’s example of a decoder that stopped two places short.

The capture. Everything is transcribed from the specification and validated against GopherTrunk’s own synthetic encoder; the package doc says the Golay matrix “should be confirmed against a capture”, and docs/decoder-capture-needs.md says that capture must be IQ. This is the self-consistent trap in its mildest form: nothing is known wrong, but the passing tests share an author with the code. The status is synthetic-verified only.

How the LICH route shaped the Go code

• One decoder, no Viterbi dependency. The LICH route kept internal/radio/m17 to three files and one framing import.
• Never-erroring parse, flagged instead. ParseLSF populates every field and sets CRCOK, so marginal decodes stay visible.
• Per-frame drop, per-sixth retry. An uncorrectable Golay codeword costs one LICH, not the transmission.
• Counters over logs. Decoder.Stats and Receiver.Stats are the instruments the first field report will need (From Spec to Shipping Part 13).

Where this goes next

M17 is the open end of the amateur digital-voice spectrum; the other end is three modes built on AMBE. Part 13 takes D-STAR’s GMSK header and its 660-bit FEC chain, System Fusion’s FICH trellis, and dPMR Mode 3’s CSBKs — three decoders at three distances from on-air verification.

FAQ

Does GopherTrunk decode M17 voice? No. It decodes the M17 link layer — source and destination callsigns, stream versus packet mode, data mode and channel access number — from the LICH in every stream frame. The Codec 2 payload is skipped; decoding it needs the convolutional path and a pure-Go Codec 2 port, both pending in docs/m17.md.

Why decode the LICH instead of the Link Setup Frame itself? The dedicated LSF frame is convolutionally coded and punctured, so it needs a Viterbi decoder. The LICH carries the same 240 bits one sixth per stream frame under Golay(24,12), needing only a Golay decoder, and supports late entry: a receiver joining mid-transmission has the full LSF after six frames, about 240 milliseconds.

How are M17 callsigns encoded on the air? As base-40 integers in a 48-bit field over the alphabet space, A–Z, 0–9, hyphen, slash and dot. DecodeAddress repeatedly takes the value modulo 40 and divides. All-ones is BROADCAST, zero is the reserved empty address, and values above 40⁹ decode as #RESERVED.

Where do decoded M17 link setups show up? On the events bus as m17.linksetup, in the m17_log SQLite table, and at GET /api/v1/m17/linksetups?limit=N. Both require storage.path; gophertrunk doctor warns when m17.channels is configured without it. There is no /m17 web panel yet, so REST is the operator-facing surface.

Has the M17 decoder been verified on air? Not yet. The sync words, LSF layout, CRC-16 polynomial 0x5935, base-40 alphabet and LICH structure come from the M17 specification and are proven against GopherTrunk’s own synthetic encoder. The exact Golay matrix, slicer deviation and timing constants await an IQ capture of real M17 traffic, per docs/decoder-capture-needs.md.

Series navigation

Part 12 of 14 · ← Part 11: LoRa — A Pure-Go Chirp Receiver · Next → Part 13: D-STAR, System Fusion & dPMR

TL;DR: DMR “Enhanced Privacy” (DMRA algorithm 0x21) is RC4 keyed with key‖MI — the operator’s key followed by the 32-bit Message Indicator — with 256 keystream bytes discarded and 7 bytes per 49-bit AMBE+2 frame applied across a superframe (EPKeystream, DescrambleSuperframe in internal/radio/dmr/voice/ep.go). The MI arrives in the Privacy Indicator header (dmr.ParsePIHeader, CRC mask 0x9696) and advances per superframe through the LFSR x³²+x⁴+x²+1 (AdvanceMI). Every superframe also embeds an IV as three Golay(24,12) codewords — and that IV is the NEXT superframe’s MI. EPTracker applied it to the current one, so everything after the first superframe decoded on the wrong MI; that fix plus RewindMI for late entry lifted the #1187 captures from ciphertext (b0 continuity ≈0.15) to speech (0.77 / 0.74). Capture-verified; the live daemon call is still the open gate.

Key takeaways

• Encryption is announced in a data burst, then hidden in the voice. The PI header carries algorithm, key ID and MI at keyup; afterwards the voice bursts carry the chain, a nibble per frame.
• The keystream construction was right the whole time. Both defects that hid a working decrypt were receiving-side: an IV applied one superframe too early, and a harness slicing bursts out of the gaps.
• A Golay-verified IV is weak evidence on its own. The radius-3 sphere covers ~57 % of 24-bit words, so clear vocoder bits “verify” ~1 % of the time — a disagreeing IV is trusted only when it decoded clean.
• Judge a decrypt by pitch continuity, never loudness. Random AMBE+2 parameters are loud; only a slowly moving fundamental says the key was right.

Cheat sheet

In this post

• The header that says how — twelve octets and a CRC mask.
• Key‖MI, drop 256, seven bytes a frame — the RC4 construction.
• The IV that names the next superframe — embedded MIs, the tracker, the rewind.
• Composer to recorder — key resolution, events, the crypto-frame bridge.
• The capture that settled it — two receiving-side defects, one verdict.

The header that says how

Authorized use only. Everything here is known-key decryption: the operator supplies a key they are authorized to hold, and GopherTrunk performs no key recovery of any kind — the same model as SDRTrunk, DSD-FME and OP25. Decrypting traffic you are not permitted to touch is illegal in most jurisdictions; the Crypto Lab framing applies unchanged — measure your own deployment, or one you have written permission to assess.

P25 announces encryption twice — a grant bit and an in-call Encryption Sync. DMR is similar: the Full Link Control’s service options carry a privacy bit (Part 5), and the how rides a dedicated data burst — the Privacy Indicator header, slot type 0x0 (DTPIHeader), sent after the Voice LC Header. Its BPTC(196,96)-recovered block is twelve octets, pinned against SDRTrunk and DSD-FME: algorithm (0x21 RC4, 0x22 DES, 0x24/0x25 AES), feature-set ID (0x10 DMRA, 0x68 Hytera, 0x0A Kirisun), key ID, the 32-bit MI in octets 3–6, a 24-bit destination, and a CRC-CCITT (poly 0x1021, init 0) XORed with the PI-header mask.

That mask costs newcomers an afternoon. ETSI writes it as 0x6969 but defines the CRC with its output inverted; framing.CRCCCITTWithInit is the plain form, so piHeaderCRCMask is ^0x6969 = 0x9696 — the relation csbkCRCMask (0x5A5A) bears to ETSI’s 0xA5A5 in Part 4. TestParsePIHeaderReferenceLiteral pins it with an independent Python CRC’s vector — the literal-vector rule, since a round-trip through AssemblePIHeader agrees with either mask.

Two choices are deliberate. IsRC4 keys on the low three bits of the algorithm octet, as DSD-FME does — but only under feature set 0x10: Hytera’s Enhanced Privacy (FID 0x68, 40-bit MI) is a different construction and is not claimed. And the header has no RS(12,9) trailer, so its CRC is the only integrity check: a BPTC-clean block that fails it is dropped, never guessed, and PIHeaderDetector.Rejects keeps its hex as the instrument for an unnamed vendor layout. The detector runs beside the voice Decoder exactly like the terminator detector: data-sync slice, both polarities, slot type, BPTC, ParsePIHeader.

Key‖MI, drop 256, seven bytes a frame

The construction is short, and every line is a protocol fact two open decoders agree on. EPKeystream appends the four MI bytes (MSB first) to the key, seeds Go’s rc4.NewCipher, discards EPKeystreamDrop = 256 bytes and returns the next n; AdvanceMI clocks a 32-bit LFSR with feedback (l>>31)^(l>>3)^(l>>1) thirty-two times — x³²+x⁴+x²+1.

DescrambleSuperframe XORs those 126 bytes onto the eighteen FEC-decoded payloads in place. Two rules keep alignment honest: a frame that failed FEC (nil) is skipped but still consumes its 7-byte slot, and a frame carrying the AMBE+2 silence vector (0xF801A99F8CE080, Part 11’s subject) is sent in clear and passes through untouched while consuming its slot — DSD-FME’s silence guard.

The kinship with P25 is close: internal/radio/p25/phase1/adp.go keys RC4 with the key plus the first 8 octets of P25’s 72-bit MI, drops 256, and lays the stream onto IMBE frames from absolute byte 267 (LDU1) and 368 (LDU2) — OP25’s layout, verified on the same reporter’s ADP call (pitch track 0.13 → 0.57). One cipher, one warm-up, and — next — one convention.

The IV that names the next superframe

If the header were the only MI source, a scanner tuning in late — grant, retune, DDC settle, frame lock — would never decrypt anything. So every superframe also carries an MI: each of the 18 on-air frames donates one nibble in its unprotected C3 sub-vector — bits 71, 67, 63, 59, C3[0..3] after deinterleave. The 72 bits form three Golay(24,12) codewords — codeword j takes data from bursts A, B, C and parity from D, E, F — whose 36 data bits are the 32-bit MI plus a CRC-4 (x⁴+x+1, output inverted). That is ExtractEmbeddedIV.

Now the convention. The embedded IV is the NEXT superframe’s MI — the P25 LDU2 Encryption Sync rule. On the #1187 radio every superframe’s IV equals AdvanceMI of the one before, and the first equals AdvanceMI of the header’s; DSD-FME agrees (dmr_alg_refresh LFSR-advances at burst F before dmr_late_entry_mi compares).

EPTracker.Next is the rule as a switch. A verified IV equal to AdvanceMI(next) confirms the chain; with no chain at all, a verified IV yields the current MI by RewindMI, so late entry decrypts the very superframe it verified on. A verified IV that disagrees is where the Golay gate matters: a radius-3 sphere covers ~57 % of all 24-bit words, so clear vocoder bits pass all three codewords plus the CRC-4 about 1 % of the time, whereas three clean codewords plus CRC are ~2⁻⁴⁰ by chance. A clean disagreement means a missed superframe and the MI is re-derived from it; a corrected one holds the prediction (Mismatches counts both).

Composer to recorder

The per-call state (dmrEPState, composer/dmr_ep.go) never guesses a key and never acts on an embedded IV for a call with no other encryption evidence unless that IV decoded perfectly clean. onPIHeader seeds the tracker (SetHeaderMI), resolves the key through KeyResolver when IsRC4, and publishes events.KindCallEncryption with Protocol: "dmr"; superframe runs ExtractEmbeddedIV → EPTracker.Next → DescrambleSuperframe in place.

KeyResolver is built from trunking.systems[].encryption_keys (buildKeyResolver, logging daemon: in-process decryption keys configured (DMR enhanced privacy / P25 ADP)); algorithm must be rc4 / arc4 / adp (DES and AES fail at load with “not supported yet”), key is 1–32 hex bytes, and a key under a different ID is never applied. The header lands at INFO as composer: dmr PI header — call is encrypted, and the counters — pi_headers, iv_verified, mi_predicted, mi_mismatches, descrambled_frames, no_key — ride the debug composer: dmr enhanced privacy line.

The event is the same KindCallEncryption P25 publishes, so the engine’s follow / metadata / ignore policy and its configured-key exemption apply unchanged, and recordings.skip_encrypted (Recording & Streaming Part 7) still decides whether a keyless call reaches disk. Independently of any key, recordings.crypto_capture_path hands every superframe’s ciphertext plus its MI to the cryptocap bridge for the keystream-reuse workflow. TestComposerDMREnhancedPrivacyDecryptsWithConfiguredKey runs the full composer and requires the recorder’s .raw sidecar to hold clear payloads.

The capture that settled it

The #1187 reporter posted two known-key discriminator captures — key IDs 11 and 22, colour code 2, TG 582743, simplex — and TestDMREnhancedPrivacyReplay judged them: production DDC → dmrrx receiver → PIHeaderDetector + superframe decoder → EPTracker → DescrambleSuperframe → ambe2-dmr, printing every header, the IV/MI timeline and a one-line VERDICT. Knobs: GT_DMR_EP_IQ or GT_DMR_EP_AUDIO (a discriminator WAV, FM re-modulated), GT_DMR_EP_KEY, GT_DMR_EP_KEYID, GT_DMR_EP_OUT, and GT_DMR_EP_DUMP, which writes every superframe before descrambling so a keystream hypothesis is testable offline.

Both runs failed at first, for opposite reasons; neither was the cipher. First, the harness sliced voice with the back-to-back 132-dibit single-slot decoder; a simplex handheld sends one burst per 60 ms frame, 288 dibits apart (Part 3), so bursts B–F were read out of the gaps: burst A decoded FEC-clean, B–F carried the random-word Golay signature — 73 % needing exactly 3 corrections, 12 % exactly 2 — which looks exactly like post-FEC scrambling and is not — the same defect #1192 had fixed in production the day before. The harness now defaults to the cadence-detecting decoder, and a C0/C1 Golay histogram is the first instrument to read when frames look scrambled. Second, the IV convention: correctly sliced frames decoded on the wrong MI while the wrongly sliced ones had decoded on the right one.

The verdict metric matters because loudness would have lied: random AMBE+2 parameters through the vocoder are loud, so the harness reports RMS but never trusts it. It measures pitch continuity, the fraction of consecutive frame pairs whose fundamental index moves by at most 10: speech ≳0.5, ciphertext ≈0.15. Post-fix the captures score 0.77 and 0.74. TestEPCaptureIssue1187 pins it against literal on-air frames (voice/testdata/ep_issue1187_ptt1.json): the header→IV chain yields continuity ≥ 0.55, late entry rewinds to the header’s MI, and decrypting each superframe with its own IV stays ≤ 0.35 — the old semantics fail it.

Verified-language, as the repo states it: Enhanced Privacy is capture-verified. Open on #1187 is the daemon path on air — a live call with encryption_keys configured recording intelligible audio (the #764/#771 discipline). Not decoded: Hytera EP, Kirisun, DES/AES; the DMR encryption reference and RC4 page cover the landscape, and docs/dmr-encryption.md has the capture-contribution recipe.

How the IV convention shaped the Go code

• The tracker decodes on what it already knows. Next returns the current MI from the header, the previous IV or the prediction, and lets the embedded IV steer only next — the convention lives in control flow.
• Verification strength is a parameter, not a boolean. ExtractEmbeddedIV returns corrected beside ok; a clean triple and a ~1 % false verify are treated differently.
• Instruments outlive the fix. Mismatches, PIHeaderDetector.Rejects and GT_DMR_EP_DUMP pin the next vendor variant.

Where this goes next

Twice here a receiving-side defect masqueraded as a cipher problem, and instruments caught both. Part 13 makes that the subject: testing DMR without a repeater — committed real-air slices, the replay harnesses and their scrubs, and the fixture lessons that hid direct mode.

FAQ

Can GopherTrunk decrypt DMR Enhanced Privacy? Yes, with a key the operator supplies under trunking.systems[].encryption_keys whose key_id matches the Privacy Indicator header. The voice chain descrambles RC4 “Enhanced Privacy” in process and records clear audio; without a key the call is recorded as ciphertext with algorithm and key ID surfaced.

Where does a DMR call carry its Message Indicator? Twice: in the Privacy Indicator header sent after the Voice LC Header at keyup (32 bits, octets 3–6), and embedded in every voice superframe as 18 nibbles forming three Golay(24,12) codewords plus a CRC-4 — the late-entry copy, which names the next superframe’s MI, not the one carrying it.

Why did a working keystream produce garbage at first? Two receiving-side defects. The tracker applied each embedded IV to its own superframe instead of the next, so every superframe after the first used the wrong MI; and the replay harness sliced a simplex handheld’s bursts with the back-to-back single-slot decoder, reading bursts B–F out of the gaps.

How do I know a decrypt actually worked? Not by ear or level — random vocoder parameters are loud. The harness measures pitch continuity, the fraction of consecutive AMBE+2 frames whose fundamental index (bits 0..3 and 37..39) moves by at most 10: speech ≳0.5, ciphertext ≈0.15. The #1187 captures score 0.77 and 0.74.

Is DMR Enhanced Privacy verified on air in GopherTrunk? Capture-verified: two known-key captures decode to speech through TestDMREnhancedPrivacyReplay, with literal on-air frames pinned in TestEPCaptureIssue1187. The remaining gate on #1187 is a live daemon call with encryption_keys configured that records intelligible audio.

Series navigation

Part 12 of 14 · ← Part 11: AMBE+2 Voice & the Silence-Frame Bug · Next → Part 13: Testing DMR Without a Repeater

TL;DR: The web console renders what /api/v1/* returns, so when a panel lies the referee is the daemon log — recorder: call started and call ended reason=… are the truth a table must agree with. Five field reports, five seams: History “stopped at 00:15” while the feed said 03:15 (a UTC string slice — lib/formatTime.ts now owns every timestamp); an empty History for every query (r.rows read off a {"calls":[…]} envelope); a stale tab reconnecting 2–4×/s forever (the daemon upgraded the WebSocket before resolving the SDR — now a 404 via api.ErrUnknownDevice plus reconnectingSocket.ts); symbol: poor next to decode: clean on a TETRA rig (a P25 C4FM receiver on a π/4-DQPSK carrier — fixed by symbol_proto); and a silent 0.1 s WAV row (a DMO voice chain with speech_frames=0 torn down by reason=timeout). Meta-lesson: npm test never typechecks, so a green ci.yml did not mean the console built.

Key takeaways

• A panel renders an API response; the log records what happened. When they disagree, curl the endpoint and read the daemon line for the same second before touching React.
• Timestamps are the first suspect for “stale” data. The API returns UTC RFC3339; a panel that slices the string shows GMT, and UTC+3 reads it as “History stopped updating”.
• Silent mismatches hide behind ?? []. A mistyped envelope key and an empty result look the same to a panel — only the API and the recorder: lines can prove rows exist.
• A badge is only as right as the receiver behind it. The symbol panels graded a TETRA carrier with a P25 receiver; the decode: chip, fed by the real counters, was right the whole time.

Cheat sheet

In this post

• What these symptoms are telling you — a panel is downstream of the log.
• What healthy looks like — the recorder lines a History row must match.
• Five stories, one table — symptom → log evidence → seam → fix.
• When the panel and the log disagree — four checks, plus the CI lesson.

What these symptoms are telling you

Every operator-facing surface is a client of the same daemon: the SPA reads /api/v1/* over REST, the live feed over the WebSocket twin of the event stream (Cockpit Part 4), the DSP scopes over /api/v1/diag/symbols (Cockpit Part 8). Nothing in the browser decodes. A web symptom is a claim about one of three seams — data, transport, render — and the log sits upstream of all three. The habit: find the daemon line for the same second, ask which seam turns that line into this panel.

What healthy looks like

A History row renders a call the recorder finished; healthy means it agrees with these lines on time, talkgroup and duration:

INF recorder: call started device=cc:same-carrier:1 wav=../recordings/Metro/805/2026-09-10T12-17-27Z_805.wav tg=805 provoice=false vocoder=imbe
INF recorder: call ended device=cc:same-carrier:1 wav=../recordings/Metro/805/2026-09-10T12-17-27Z_805.wav duration=5.6s reason=normal

The wav= path carries the UTC start; History should show it in your clock with duration matching. The unhealthy twin from the 20 Aug DMO run — same lines, wrong numbers (that run printed the older colour= field names):

INF composer: tetra DMO voice follow started — DNB TCH/S decode + ACELP vocoder serial=cc:same-carrier:1 seed_hint=0x00000000 rate_hz=18000
INF recorder: call started device=cc:same-carrier:1 wav=../recordings/Site-DMO/0/2026-08-20T19-41-02Z_0.wav tg=0 provoice=false vocoder=tetra-acelp
INF composer: tetra DMO voice follow ended serial=cc:same-carrier:1 dnb_bursts=242 speech_frames=0 bfi_count=242 seed=0x00000000 seed_known=false
INF call ended device=cc:same-carrier:1 grant=tetra-dmo tg=0 438900000Hz reason=timeout
INF recorder: call ended device=cc:same-carrier:1 wav=../recordings/Site-DMO/0/2026-08-20T19-41-02Z_0.wav duration=7.0s reason=timeout

speech_frames=0 with bfi_count=242 is a call that decoded nothing; reason=timeout follows — nothing refreshed its liveness, so hangtime tore it down. The web row is the consequence.

Five stories, one table

Three more from the same batch were really recorder or shell stories. “Duration 30 s, recording 4 s” was segment rolls: the recorder publishes one CallComplete per over, stamped with the over’s own StartedAt, and the call log keyed on it — only the first over matched. CallComplete.CallStartedAt/Segment plus the call_recordings table fix the keying, and /calls/{id}/audio concatenates the segments (concatRecordingSegments) — the seam Recording Part 9 describes. Cyrillic folders as _______: sanitize allowed [A-Za-z0-9._-]; it now keeps Unicode letters, marks and digits. And the AudioPlayer docked over the pager — DataTable now renders one top and bottom.

When the panel and the log disagree

Four checks, in order, settle almost any web report without a debugger.

1. Compare clocks. The API returns UTC RFC3339. A panel behind by exactly your UTC offset is a render bug, not staleness; formatLocalDateTime/formatClock are the only way to render a timestamp. Grep for replace("T", " ") before shipping a panel.

2. curl the endpoint the panel reads. /api/v1/calls/history with the same filter shows the envelope key and the rows. Rows there, panel empty ⇒ the client (History had no test; it has one now). In reverse, an empty API answer with recorder: call ended lines in the log points at the call log or its retention window (Recording Part 10).

3. Read the decode counters before trusting a badge. The decode: and symbol: chips are deliberately different axes — frame-error rate versus raw constellation — but they must look at the same receiver. On the TETRA rig they did not: the Histogram panel with Mode forced to TETRA showed SNR (MER) — and balance ±5.7% (clean) while the auto-selected panels sat at ~9 dB on a C4FM receiver. Two receivers on one carrier is the tell; the tetra: decode status line from Part 3 is the authority; a poor pill against bsch_fail=0 is the pill’s problem. Every /diag/symbols subscriber also builds its own full-rate Downconverter; nothing is pooled.

4. Count the reconnects. A stale tab reconnecting several times a second is a line per attempt in the log, and the mechanism was a handshake that could not fail: the handlers resolved the serial after upgrader.Upgrade, so an unknown device got a 101 then a 1011 close, and every client reset its backoff in onopen. Three fixes were all needed — resolve the device first and return 404, reset the backoff only once a frame arrives (or the socket held OPEN_GRACE_MS = 2 s), and reconcile the selected serial against a refreshed device list. reconnectingSocket.ts also fixes the onerror+onclose double-bind that scheduled two timers per failure — the storm’s sibling from Issue Tracker Part 19. GONE_AFTER_FAILURES (6) frameless attempts ⇒ gone.

A fifth check is for whoever ships a fix. A green ci.yml did not mean the console built: npm test (vitest) never typechecks, so three TS6133 errors in reconnectingSocket.test.ts landed on main and broke npm run build (tsc --noEmit && vite build) for an operator; the one job that caught them, “Windows installer (PR)”, was not a required check. ci.yml now runs web-typecheck per SPA, and any web diff runs cd web && npm run typecheck before pushing — Cockpit Part 14 covers the tests; this was the gap they left.

How this line shapes operator practice

• Report the daemon line, not the screenshot. A History row with its recorder: call started / call ended reason= pair is diagnosable; a screenshot alone is not.
• Trust the decode counters over the badge. bsch_fail, fec_pass, speech_frames come from the receiver doing the work; a quality pill from a second receiver may be the wrong one’s.
• A ?? [] is a place to look, not a safety net. Where a client defaults a missing key to empty, only the log can prove data existed.
• Typecheck what CI doesn’t. npm run typecheck separates a green PR from an operator who cannot build.

Where this goes next

Every story here ended the same way: a log line and the API answer for the same second, pasted beside the symptom. Part 13 makes that the whole method — what to paste, how to align a capture to the log, which capture answers which question, and the wording that lets an issue close as verified rather than merely fixed.

FAQ

Why is the GopherTrunk History panel hours behind the activity feed? Because it rendered UTC. The daemon returns RFC3339 UTC strings, and several panels sliced them as text — always GMT — while the feed formatted locally. Tables lagging by exactly your UTC offset is that bug; web/src/lib/formatTime.ts now renders every timestamp in local time.

How do I tell a web bug from a decode bug? Find the daemon lines for the same second — recorder: call started, call ended reason=…, the protocol’s decode-status line — and curl the endpoint the panel reads. Log and API agree, panel disagrees ⇒ a render or client seam. Log shows speech_frames=0 ⇒ the panel is honest.

What does symbol: poor next to decode: clean mean? Two receivers. The decode: chip reads the real decoder’s counters; the symbol: chip grades a diagnostic receiver, which on TETRA and DMR rigs used to be a P25 C4FM one. The daemon now publishes a per-device symbol_proto so the scopes open the right receiver.

Why did a browser tab hammer the daemon after I swapped SDRs? The diag WebSocket handlers completed the handshake before checking the device, so a stale serial got an open and an immediate close, and the client reset its backoff on every open. The daemon now answers 404 before upgrading, and reconnectingSocket.ts resets backoff only after a real frame.

Why does History show a 0.1-second silent recording after a DMO PTT? The voice chain decoded no speech (speech_frames=0) and hangtime ended the call (reason=timeout); the recorder only discards zero-byte or zero-voice calls, and ACELP is neither, so a tiny row lands. The cause is upstream — colour adoption in the voice chain — and DMO remains on-air-gated under #1003.

Series navigation

Part 12 of 14 · ← Part 11: Voice-Chain Lines — Frames, Colours & Teardown Reasons · Next → Part 13: From Log to Issue — What to Paste, What to Capture

TL;DR: internal/radio/lora is a pure-Go LoRa modem (#586). A symbol is the base upchirp (GenChirp) cyclically shifted by its value, N = 2^SF chips, SF 7–12, BW 125/250/500 kHz, DefaultOversample 2. The dechirper multiplies a window by the downchirp, FFTs, folds the osf copies and takes the peak bin; syncFrame locks four stable preamble peaks, finds the SFD, and solves cfo = bd/2. Bits come out through grayDecode → Deinterleave → HammingDecode4 → Whiten (LFSR 0xB8) → PayloadCRC (0x1021). The header is a compact self-consistent layout; bit-exact Semtech interop is gated on golden vectors not yet committed. lora/receiver channelizes one SDR into sub-channels, one demodulator per candidate SF, and on sync word 0x34 parses LoRaWAN 1.0.x, verifying the AES-CMAC MIC and decrypting with operator-held keys. Output: KindLoRaFrame → lora_log → GET /api/v1/lora/frames → /lora. Synthetic-verified only.

Key takeaways

• Dechirp turns modulation into a bin index. Multiply by the conjugate chirp and every symbol collapses to a tone; the folded FFT’s processing gain decodes SF12 at 0 dB SNR in the tests.
• Preamble and SFD together separate offset from timing. Upchirps peak at timing + cfo, SFD downchirps at cfo − timing; realign on the first and the second reads 2·cfo.
• The bit chain is exact inverse pairs, and that is also its limit. Round-trips prove consistency; Semtech interop waits on a golden packet.
• LoRaWAN decrypts only with keys you hold. KeyStore.Decode verifies the MIC under NwkSKey and decrypts under AppSKey — no key recovery.

Cheat sheet

In this post

• Chirps and spreading factors — what the receiver has to find.
• Dechirp, fold, FFT — a window becomes a bin.
• The bit chain — Gray, interleave, Hamming, whitening, CRC, LDRO.
• One SDR, many sub-channels — the streaming receiver.
• LoRaWAN — MIC and decryption with keys you already hold.
• From bus event to the /lora panel — the eleven places, with gaps.

Chirps and spreading factors: what the receiver has to find

LoRa is chirp spread spectrum: a symbol is an upchirp sweeping −BW/2 to +BW/2, and the value is where the sweep starts — a cyclic shift of the base chirp by v of N = 2^SF chips. Bandwidth (BW125, BW250, BW500) sets the sweep width; the spreading factor (7–12) sets its length and the processing gain. (The reference page’s “Not decoded” line predates #586, which landed the decoder in v0.3.8.)

GenChirp defines the waveform at Fs = osf·BW, so it depends only on SF and osf: phase(n) = 2π(−n/2·osf + n²/2·N·osf²), conjugated for the downchirp reference; GenSymbolChirp rotates it by v·osf samples. DefaultOversample is 2 — enough to resolve the peak and a fractional offset with a small FFT — and SF6 is out of scope (MinSF/MaxSF pin 7..12).

Dechirp, fold, FFT: from a symbol window to a bin

The kernel is dechirper.peakOf. Multiply a symbol-length window by the reference chirp (downchirp for data, upchirp for the SFD), FFT the sps = N·osf product, and fold: bin b aliases with b + r·N for each osf copy, so summing their powers puts a symbol’s energy in one of N bins.

// internal/radio/lora/demod.go (shape)
for i := range window { d.y[i] = window[i] * ref[i] }        // dechirp
d.out = d.plan.Forward(d.out, cmplx128(d.y))                  // FFT, size sps
for b := 0; b < d.n; b++ {                                     // fold osf copies
    for r := 0; r < d.osf; r++ { sum += power(d.out[b+r*d.n]) }
    d.mags[b] = sum
}
/* argmax → bin; interpolation → frac; peak/runner-up → snr; peak/mean → conc */

Two confidence figures come out with the bin: snr, peak over runner-up (the panel’s Frame.SNRdB), and conc, peak over the per-bin mean — the detection gate, because a tone straddling two bins still dwarfs the mean where a peak/runner-up ratio would collapse.

syncFrame slides one chip at a time until preambleSyms = 4 consecutive windows exceed concThresh = 16 at the same bin (±1): the preamble dechirps to a stable bu = (timing + cfo) mod N. It realigns the grid by bu·osf samples, then steps symbol by symbol until a window dechirps better against the upchirp: the SFD. On the realigned grid the residual timing equals −cfo, so the SFD peak reads bd = cfo − timing = 2·cfo. The header begins 2.25 symbols after the SFD, nudged by cfo chips; mix removes the fractional offset as a phase ramp, with SDR Internals Part 8’s FFT plan doing the heavy lifting.

The tests state the envelope: TestModDemodClean decodes every SF 7–12 at every CR 1–4; TestModDemodNoise decodes SF7, 9 and 12 at 0 dB SNR; TestModDemodCFO survives offsets of −3, 1.5 and 4 bins; TestModDemodSFAutoDetect proves an SF7 demodulator does not decode an SF9 frame — what the streaming receiver’s per-SF probing relies on.

The bit chain: Gray, interleave, Hamming, whitening, CRC

decodeFrameFromSymbols decodes the header block first, learns the payload geometry, then exactly that many payload blocks of (4+CR) symbols; decodeBlock reverses exact-inverse transforms:

TestHammingSingleErrorCorrection flips every bit of every CR 3/4 codeword and expects the nibble back. The explicit header is one block at HeaderCR = 4 — the payload’s rate is not yet known — of four nibbles: payload length, CR | hasCRC<<3, an XOR checksum (ParseHeader). The source calls this “a compact, self-consistent header layout”; a bit-exact Semtech header is a follow-up, and the same caveat covers the interleaver’s rotation sign, whitening sequence and CRC seed — “validated separately against captured golden vectors”, none committed. In From Spec to Shipping Part 3’s terms: round-trips, no literal vectors.

LDRO is the one place the payload geometry changes. At high SF clock drift can smear the peak across the two lowest bins, so Low Data Rate Optimize carries ppm = SF − 2 bits per symbol in bins that are multiples of four (reducedRateShift). AutoLDRO applies Semtech’s Ts ≥ 16 ms rule (SF11/SF12 at 125 kHz, SF12 at 250 kHz), low_data_rate_optimize overrides it, and TestLDROMismatchFailsToDecode proves the mode changes the wire format — the header still parses, the payload does not.

One SDR, many sub-channels: the streaming receiver

lora/receiver is the only decoder in this series that owns its own tuner bank. newBank picks a tuner.NewChannelizerBank at channelizerThreshold = 7 or more sub-channels and a tuner.NewDDCBank otherwise — the channelizer versus per-tap DDC trade-off — and each tap delivers narrowband IQ at osf·BW to a subChannel.

// internal/radio/lora/receiver/receiver.go (shape)
sfs := []int{cfg.SF}
if cfg.SF == 0 { for sf := lora.MinSF; sf <= lora.MaxSF; sf++ { sfs = append(sfs, sf) } }
for _, sf := range sfs {
    sc.demods = append(sc.demods, lora.NewDemodulatorMode(sf, osf, bw, cfg.LDRO))
}
sc.minDecode = maxSps * 700   // a 255-byte CR 4/8 frame must be fully buffered

A sub-channel with spreading_factor: 0 runs six demodulators and bestDecode tries each, preferring a CRC-valid frame — “this trades CPU for coverage; pinning a single SF per sub-channel in config avoids the parallel probes.” decodeReady decodes only while minDecode samples sit past the cursor, so a truncated frame is never mistaken for a corrupt one. TestWidebandTwoChannels sums an SF7 packet at −200 kHz and an SF9 packet at +180 kHz into one 1 MS/s stream and expects both on the bus with the right SF; TestWidebandLDROChannel proves the override reaches the demodulator.

On a waterfall the diagonal ramps are unmistakable — the signature Signal Lab Part 8 names in the wideband survey and The Hunt Part 4 classifies. This receiver turns that identification into rows.

LoRaWAN: MIC and decryption with keys you already hold

When a sub-channel’s sync_word is 0x34 (LoRaWAN; 0x12 is private), emit hands the payload to KeyStore.Decode. lorawan.Parse reads the LoRaWAN 1.0.x MAC layer: MHDR’s top three bits are the MType; data frames carry DevAddr, FCtrl, FCnt, FOpts, optional FPort and FRMPayload, then the 4-byte MIC; a join-request carries JoinEUI, DevEUI and DevNonce. Without keys for the DevAddr it stops there; the cleartext fields still publish.

With keys, VerifyMIC recomputes the MIC: AES-CMAC (RFC 4493) over a B0 block (0x49, direction, DevAddr, FCnt, length) plus MHDR|FHDR|FPort|FRMPayload, keyed under NwkSKey, compared in constant time. TestAESCMACVectors pins the primitive against RFC 4493 §4’s vectors — the package’s one literal-vector test — and TestLoRaWANRoundTrip decrypts temp=21.5C and confirms a wrong NwkSKey fails the MIC. DecryptFRMPayload is the §4.3.3 AES-CTR-style scheme: encrypt A blocks (0x01, direction, DevAddr, FCnt, block index) into a keystream and XOR, under AppSKey for FPort > 0 and NwkSKey for FPort 0.

FCnt32 assumes the upper 16 bits are zero (no session state is kept), and join-accept bodies are left raw. The posture is the trunking one from Trunking Engine Part 11: “GopherTrunk decrypts only with keys the operator already holds and is authorised to use — it performs no key recovery.” Keys arrive as lorawan_keys (dev_addr, nwk_skey, app_skey); the lora_log row carries mic_ok, decrypted and the plaintext as decoded.

From bus event to the /lora panel

The Part 1 pattern, walked for LoRa — with two places the walk finds empty:

1. Front end + framer: lora/receiver and lora.
2. Bus event: events.KindLoRaFrame ("lora.frame"), payload storage.LoRaFrame.
3. Storage: storage.LoRaLog → lora_log, indexed on (received_at) and (dev_addr, received_at).
4. REST: GET /api/v1/lora/frames?limit=N.
5. Panel: LoRa.tsx polls every 5 s — SF/CR/BW, SNR, CFO, a crc badge, the LoRaWAN envelope.
6. Config: lora.channels[] — serial, center_hz, bandwidth, sub_channels[], lorawan_keys[].
7. Field help: LoRaConfig.* through LoRaWANKeyConfig.*.
8. Route tests: "/lora" in web/src/nav/registry.test.ts.
9. Preflight: absent — preflight.go names every other message decoder as needing storage.path, not lora.
10. Retention: absent — lora_log is not in storage.decoderLogTables, so retention.log_days never sweeps it.
11. config.example.yaml: the commented lora: block.

A third soft spot: the web Config Builder has no typed LoRa editor — webRoundTripAllow in configbuilder/webschema_test.go records Config.LoRa as round-tripping through “the generic index-signature editor; a bespoke typed editor in types.ts is a follow-up.” Such gaps are what the pattern exists to make visible.

Verification is where Parts 9 and 10 left it: synthetic only. Every LoRa test drives LoRaModulate into the package’s own demodulator; the one independent anchor is RFC 4493’s CMAC vectors. No captured LoRa packet is committed.

How LoRa shaped the Go code

• A modem, not just a receiver. LoRaModulate and Demodulator are exact inverses in one package; every transform is round-trip testable.
• The dechirper is the reusable kernel. One struct owns the chirps, FFT plan and scratch buffers per (SF, osf); offline Demodulator and streaming subChannel both run on it.
• Confidence travels with the symbol. peak carries bin, frac, snr and conc; sync gates on concentration, the panel shows SNR.
• Decoders never guess with keys. HasKeys, MICOK and Decrypted are separate flags; a frame with no keys still reaches the log.

Where this goes next

LoRa was data with no voice at all. The next decoder brings voice back, open-source: M17’s 4FSK link layer, its Link Setup Frame, Golay and convolutional coding, and the Codec 2 payload. Part 12 follows it from the 4800-baud carrier to stream and packet modes.

FAQ

Which LoRa settings does GopherTrunk decode? Spreading factors 7 through 12 (auto-detected when spreading_factor: 0), coding rates 4/5 to 4/8 from the explicit header, bandwidths 125, 250 and 500 kHz, with or without payload CRC, and Low Data Rate Optimize by the Semtech rule or an override. SF6 and implicit headers are out of scope.

Does GopherTrunk decode real Semtech LoRa packets bit-exactly? Not yet verified. The chain is round-trip tested against its own modulator, and the source marks the header layout, interleaver rotation sign, whitening sequence and CRC seed as calibration steps gated on captured golden vectors, none committed. Treat interop as synthetic-verified only.

How does the receiver estimate carrier offset? From two dechirp peaks. The repeated preamble upchirps peak at timing + cfo; after realigning the grid on that bin, the SFD downchirps peak at 2·cfo. Halving it gives the offset, which mix removes before demodulation.

Can GopherTrunk decrypt LoRaWAN traffic? Only for devices whose session keys the operator supplies under lorawan_keys (DevAddr, NwkSKey, AppSKey). The MIC is verified by AES-CMAC under NwkSKey and the payload decrypted under AppSKey (NwkSKey for FPort 0). No key recovery; frames without keys publish their cleartext header fields.

Why does lora_log grow without limit? Because lora_log is not in the retention sweeper’s decoderLogTables list, retention.log_days never deletes its rows — an omission the eleven-place walk surfaces. Until it is added, prune it by hand.

Series navigation

Part 11 of 14 · ← Part 10: DSC — Marine Digital Selective Calling · Next → Part 12: M17 — The Open Digital Voice Link Layer