TL;DR: A good public repo does two jobs — it sells itself and it
protects itself. Optimize discoverability with a filled-in About box, topics,
a social-preview image, and honest status badges. Harden it with branch
protection / required checks, secret scanning + push protection, automated
dependency-CVE scanning (Dependabot / SCA), a SECURITY.md disclosure policy,
checksummed releases, and least-privilege GITHUB_TOKEN permissions in your
Actions. Most of this is free and takes an afternoon.
Key takeaways
main.SECURITY.md tells people
how to report what you missed.This is Part 12 of Build in the Open, a 14-part series on taking a software project from a blank idea to a public release using GitHub and Claude Code. Each post teaches a technique you can apply to any project in any language, then shows how the open-source GopherTrunk scanner does it for real.
SECURITY.md should say.GITHUB_TOKEN.A repo nobody can find or understand is a tree falling in an empty forest. These are low-effort, high-leverage fixes.
The little gear next to “About” on your repo’s homepage controls three things that GitHub search and Google both index:
golang, sdr, cli. These power GitHub topic pages
and “explore” discovery. Add 5–10 relevant ones.Settings → General → Social preview. Upload an image and every time your repo is shared on social media, Slack, or Discord it renders a rich card instead of a bare URL. This is a one-time upload that pays off forever.
Badges at the top of your README communicate health at a glance: is CI passing, what’s the latest release, what license, what language version. Keep them truthful — a green CI badge that’s actually broken is worse than no badge. Good additions include a code-quality/report-card badge and a docs link.
Discoverability is also legibility. A clear directory structure, the standard
“repository health” files (README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT,
SECURITY, issue/PR templates), and a .gitignore that keeps build junk out all
make the repo feel maintained — which is itself a signal to potential users and
contributors.
Optimization gets people in the door. Security keeps the door from being kicked off its hinges.
Protect main so nobody (including you on a bad day) can push broken code or
force-push history away. The essentials:
On GitHub this is “branch protection rules” or the newer, JSON-defined rulesets — which have the advantage that you can commit them to the repo and review changes to your protection policy like any other code.
Secret scanning watches for committed credentials (API keys, tokens) and alerts you. Push protection goes further — it blocks the push before the secret ever lands in history. Turn both on (free for public repos). The best secret is the one that never gets committed; the second best is one you’re told about within seconds.
Your code is only as secure as its dependencies. Software Composition Analysis (SCA) means scanning your dependency tree for known CVEs. Two complementary tools:
When someone finds a vulnerability, they need a private way to tell you.
SECURITY.md documents that path. Good ones include: which versions are
supported, how to report privately (GitHub’s private security advisories are the
standard), what’s in and out of scope, and rough response timelines. This turns
a scary surprise into a managed process.
Every workflow run gets a GITHUB_TOKEN. By default it can be broad. Set
permissions: to the minimum each workflow needs — read-only for CI, contents:
write only for the job that publishes releases. A leaked or exploited workflow
with read-only scope can do far less damage than one with write-everything.
GopherTrunk treats both halves as first-class. Here’s the real configuration.
Honest badges. The README header carries six: a live CI status badge
(actions/workflows/ci.yml/badge.svg), a release badge
(shields.io/github/v/release with include_prereleases&sort=semver — so it
honestly shows the 0.x pre-release state), an Apache-2.0 license badge, a
Go-version badge pulled from go.mod, a Go Report Card code-quality badge,
and a docs badge linking to gophertrunk.org. Every one is a live signal, not a
static image.
Protection as committed rulesets. Branch and tag protection live in the repo as JSON, reviewable like code:
.github/rulesets/main-branch-protection.json targets the default branch and
requires pull requests, resolves review threads
(required_review_thread_resolution: true), blocks deletion and
non_fast_forward, and — crucially — requires three status checks to pass
before merge: build-test, usb-windows, and usb-macos..github/rulesets/release-tags-protection.json (from
Part 11)
matches refs/tags/v* and blocks both deletion and update, so published
release tags are immutable.CVE scanning is a required check. The CI workflow has a dedicated vulncheck
job that installs and runs govulncheck ./... — Go’s official vulnerability
scanner — enumerating known CVEs across the direct and transitive dependency
graph. Because build-test and the USB jobs are required, a failing security
scan keeps a PR from merging. There’s also a licenses job that regenerates the
third-party license inventory with go-licenses, backstopping the hand-curated
table.
A real disclosure policy. SECURITY.md is not boilerplate — it opens with a
threat model (an operator running the daemon on a private network or single
host they own), lists supported versions, and routes reports through GitHub’s
private security advisory workflow with explicit “do not open a public issue”
guidance. It enumerates what’s in scope (auth bypass, path traversal, SQL
injection, DoS, memory-safety bugs) and out (operator misconfiguration,
auth.mode: disabled), and publishes a severity-based response timeline
(critical: ≤7 days initial, ≤30 days fix).
Crypto and secrets done right. The API uses bearer-token auth with
constant-time comparison (crypto/subtle.ConstantTimeCompare), so
token-comparison side channels are out of scope by construction, per
SECURITY.md. And the one real build secret — the RadioReference app key — is
never committed; it’s injected at build time via ldflags
(-X ...radioreference.DefaultAppKey=${RR_APP_KEY}) from a GitHub Actions
secret. The release.yml workflow also declares permissions: contents: write
explicitly rather than inheriting broad defaults, and ships SHA-256 checksums
with every release.
The portable lesson: commit your protection rules, make a CVE scan a required
check, write a real SECURITY.md, keep secrets out of source, and scope your
tokens tight.
Are these features free?
For public repositories, yes — branch protection, rulesets, secret scanning,
push protection, and Dependabot are all free on GitHub. CVE scanners like
govulncheck are free open-source tools you run in CI.
What’s the difference between Dependabot and a CVE scanner like govulncheck?
Dependabot proactively opens PRs to update vulnerable or outdated
dependencies. A scanner like govulncheck runs in CI and fails the build when
a known-vulnerable dependency is present. They’re complementary: one fixes,
one gates.
Why use rulesets instead of classic branch protection?
Rulesets can be exported as JSON and committed to the repo, so changes to your
protection policy are reviewable and versioned like any other code. GopherTrunk
keeps both main and tag protection under .github/rulesets/.
What belongs in SECURITY.md? Supported versions, a private reporting channel (GitHub advisories are standard), what’s in and out of scope, and rough response timelines. A short threat model up front helps reporters know what you actually care about.
How do I keep secrets out of my repo? Never commit them. Store them as GitHub Actions secrets and inject them at build or runtime, turn on push protection to block accidental commits, and prefer build-time injection (like GopherTrunk’s ldflags app-key) over checked-in config.
Part 12 of 14 · ← Part 11: Releases — SemVer & Changelogs · Next → Part 13: Advanced Git & GitHub Features
]]>TL;DR — The SDR pool owns every opened dongle behind one interface, assigning each a role (control, voice, wideband) and keeping the fleet alive through USB hotplug via a 30-second watchdog that reacquires devices under new bus addresses. A scanner retune that raced stream teardown (issue #686) is fixed by serializing re-open behind an idempotent stop.
internal/sdr/pool.go) — a fleet of opened devices, each with a
role: control, voice, or wideband.config.yaml selects exactly the dongles they named.KindSDRAttached / KindSDRDetached, and reacquires a device after the
kernel re-enumerates it with a new address.A single dongle is one Device. A trunked system needs more than one: a radio
camped on the control channel decoding grants, and one or more radios that follow
those grants onto voice frequencies. A wideband Airspy might cover a whole site’s
worth of channels at once. The pool is the thing that owns all of them.
Its job is narrow but load-bearing. At boot it enumerates every registered driver, opens the devices the operator selected, programs a known-good sample rate on each, and assigns each one a role. After boot it answers a single question for the rest of the engine — “give me the device with role X” — and it keeps that fleet healthy while USB does what USB does: drop a stick mid-stream, re-enumerate it under a new device number, and expect the software to cope.
Roles matter because the engine never reaches for a specific dongle. The
control-channel decoder asks for RoleControl; the voice composer asks the pool
to find a RoleVoice device by serial when the engine binds a call. That
indirection is what lets the same code run on a one-stick hobby setup and a
four-stick site without a branch anywhere in the engine.
A Pool is a slice of opened entries behind a mutex, plus an optional event bus:
// internal/sdr/pool.go
type Pool struct {
mu sync.RWMutex
entries []*PoolEntry
log *slog.Logger
bus *events.Bus
}
type PoolEntry struct {
Driver Driver
Device Device
Info Info
Role Role
Hint Hint
}
OpenWith is the heart of bring-up. It sweeps every registered driver, opens the
selected devices, programs the IQ rate, and assigns roles. Role assignment is one
simple rule: the first opened device that isn’t otherwise claimed takes
RoleControl; everything after it defaults to RoleVoice. A Hint can override
that per serial.
// internal/sdr/pool.go (shape)
role := RoleAuto
if hinted {
role = hint.Role
}
if role == RoleAuto {
if !controlClaimed {
role = RoleControl
controlClaimed = true
} else {
role = RoleVoice
}
}
Programming the sample rate at open time isn’t optional housekeeping — it’s a
fix for issue #275. Without an explicit SetSampleRate, the chip streams at
whatever rate its resampler powered up at, while the decoder runs its
symbol-timing math against the configured rate. The result is a silent failure
to lock, the worst kind of bug in a radio. So a device whose SetSampleRate
fails is closed and skipped: a wrong-rate radio is worse than no radio at all.
By default the pool opens every dongle it finds. The moment an operator lists
specific devices in config, that’s their signal that they want only those —
so the daemon engages strict mode, where Hints becomes an allowlist:
// internal/sdr/pool.go (shape)
if opts.Strict && !hinted {
p.log.Info("skipping non-configured SDR; add its serial to sdr.devices to use it",
"driver", d.drv.Name(), "serial", d.info.Serial)
continue
}
Matching a hint to a device means matching serials, and serials aren’t always
clean. Airspy reports a legacy form — AIRSPY SN:35ac63dc2d701c4f — that an
operator might write a dozen ways. serialKey normalizes them so the config and
the wire agree:
// internal/sdr/pool.go
func serialKey(s string) string {
s = strings.TrimSpace(s)
s = strings.ToLower(s)
switch {
case strings.HasPrefix(s, "airspy sn:"):
return strings.TrimPrefix(s, "airspy sn:")
case strings.HasPrefix(s, "airspy_sn:"):
return strings.TrimPrefix(s, "airspy_sn:")
default:
return s
}
}
TestPoolMatchesAirspySerialAliases pins this: a hint written
AIRSPY SN:35ac63dc2d701c4f opens the device whose raw serial is
35AC63DC2D701C4F, and FindBySerial resolves all three spellings to the same
entry.
The pool also runs a supervisor loop. RunWatchdog ticks every interval — 30
seconds by default — re-enumerates every driver, and acts only on transitions:
// internal/sdr/watchdog.go
const DefaultWatchdogInterval = 30 * time.Second
func (p *Pool) RunWatchdog(ctx context.Context, interval time.Duration, sampleRateHz uint32) error {
if interval <= 0 {
<-ctx.Done()
return ctx.Err()
}
tick := time.NewTicker(interval)
defer tick.Stop()
missing := map[string]bool{}
for {
select {
case <-ctx.Done():
return ctx.Err()
case <-tick.C:
p.watchdogTick(missing, sampleRateHz)
}
}
}
The missing map is the state machine. A pool serial that the enumerate stops
seeing flips to missing and emits one KindSDRDetached — the API, TUI, and web
snapshot all show the gap. When that same serial reappears in a later enumerate,
the watchdog deletes it from missing and calls Reacquire:
// internal/sdr/watchdog.go (shape)
if missing[serial] {
delete(missing, serial)
p.log.Info("sdr: watchdog: device reappeared; reacquiring", "serial", serial)
if _, err := p.Reacquire(serial, sampleRateHz); err != nil {
p.log.Warn("sdr: watchdog: reacquire failed", "serial", serial, "err", err)
}
}
Reacquire is where the hotplug story gets real. When a dongle browns out and
comes back, the kernel assigns it a new device number — but it reports the same
serial. So Reacquire closes the (likely dead) handle best-effort, re-enumerates
the driver, finds the serial under its new index, opens a fresh handle,
re-programs the rate, and re-applies the original Hint (PPM, gain, bias-tee).
Crucially it swaps the Device in place on the existing PoolEntry —
Role, serial identity, and any pointer a consumer is holding all survive; only
Info.Index updates to the new enumeration. TestPoolReacquireSwapsDeviceHandleInPlace
asserts exactly that: same PoolEntry, new *fakeDevice, stale handle closed,
bias-tee re-applied, index refreshed to 7.
The watchdog handles the idle case — a device nobody is streaming. The in-use case is harder, and it bit us in scanner mode.
Symptom. In scanner mode a fast retune cancels the IQ stream’s context and immediately
re-opens it on the new frequency. But USB drivers don’t tear a stream down
synchronously — the bulk-IN reaper goroutine runs cancelStream asynchronously,
draining URBs and closing the consumer channel on its own schedule. So the
sequence that should have been “stop, then start” became “start while the
previous stop is still in flight.” The second StreamIQ found the bulk-IN
endpoint still claimed and failed with stream already active — surfacing to the
operator as conv: StreamIQ failed and a dead capture.
Root cause. The race was structural, not a missing lock. The teardown path is idempotent via
a sync.Once:
// internal/sdr/rtlsdr/purego/device.go
func (d *Device) cancelStream() {
d.stopOnce.Do(func() {
_ = d.transport.StopBulkIn()
// ...close the consumer channel
})
}
stopOnce guarantees teardown runs exactly once — but it didn’t guarantee the
next StreamIQ waited for it. The fix was to make re-open serialize behind the
in-flight teardown: a new stream resets stopOnce only after the previous stop
has actually completed, so a retune can never out-run the reaper.
// internal/sdr/rtlsdr/purego/stream.go (shape)
out := make(chan []complex64, streamChanDepth)
d.out = out
d.stopOnce = sync.Once{} // only reachable once the prior teardown finished
The lesson is a recurring one in this series: with USB, “stop” is a request, not an event. Anything that re-opens has to wait on the teardown completing, not on having asked for it.
Two patterns share the load here. The pool is a supervisor (a fleet manager):
it owns the lifecycle of every device, restarts the ones that fail, and presents
the survivors as a roster the engine can query by role. The watchdog is the
supervisor’s health check, and Reacquire is its restart strategy.
The second pattern is observer. The pool never calls into the daemon, the
API, or the TUI. It Publishes KindSDRAttached / KindSDRDetached to an
optional bus and lets whoever cares subscribe:
// internal/sdr/pool.go
func (p *Pool) publish(kind events.Kind, payload any) {
if p.bus == nil {
return
}
p.bus.Publish(events.Event{Kind: kind, Payload: payload})
}
NewPool takes only a logger; SetBus is a separate,
idempotent step. The gophertrunk sdr list CLI and every unit test run the
pool with bus == nil, and publish short-circuits — the same fleet code, no
daemon required.missing map is owned solely
by the watchdog goroutine and passed in by value-reference, so attach/detach
transitions need no extra lock. Only the pool’s entries slice is shared, and
that’s behind sync.RWMutex.Reacquire swaps the
Device inside an existing PoolEntry rather than replacing the entry,
consumers that cached a *PoolEntry keep working across a USB cycle. Role and
serial are the identity; the handle is just an attribute.The pool assigns roles and keeps devices alive, but we’ve leaned on tests
throughout this post — TestPoolReacquireSwapsDeviceHandleInPlace,
TestPoolMatchesAirspySerialAliases — without explaining how you test a fleet of
radios in CI where there are no radios at all. That’s
Part 13:
replaying captured USB control-transfer sequences, bit-identical conversion
golden masters, and an opt-in real-hardware tier.
Why poll every 30 seconds instead of listening for kernel hotplug events? Polling is portable. The same re-enumerate loop works on Linux USBDEVFS, Windows WinUSB, and macOS IOKit without three platform-specific hotplug listeners. 30 s is short enough to recover a transient drop inside one failure cycle and long enough not to load a slow hub.
What happens to an in-use device that drops? The watchdog owns the idle
case. A device that’s actively streaming surfaces its death through the stream
itself — the reaper closes the channel, the consumer (ccdecoder retry loop,
VoicePool.Bind) sees EOF and drives its own Reacquire. The watchdog is the
backstop for radios nobody is currently touching.
Why does strict mode skip a device that’s physically present? Because an
allowlist is an allowlist, not a preference. If you named your control stick in
config and an unrelated dongle is on the bus, opening that dongle could let it
win RoleControl and bind the decoder to a radio that never got your PPM
correction — the original issue #264 failure. Strict mode refuses to guess.
Part 12 of 14 · ← Part 11 · Next → Part 13: Testing radios without radios
]]>TL;DR: A release is just a tagged, named, downloadable snapshot of your
project plus notes that tell people what changed. Use Semantic Versioning
(MAJOR.MINOR.PATCH) so the number means something, release often instead of
hoarding changes, ship pre-releases (alpha/beta/rc, or any 0.x while
you’re still stabilizing) to set expectations, keep a human-readable changelog
in the Keep a Changelog format, and automate
the build so a single git tag produces signed, checksummed artifacts.
Key takeaways
1.0.0 is implicitly a pre-release — the public API may still
change. Ship a 0.x or -rc build before you commit to v1.0.0.CHANGELOG.md with an ## [Unreleased] section you fill in as you
go, so cutting a release is just renaming a heading.SHA256SUMS) so users can verify what they downloaded.This is Part 11 of Build in the Open, a 14-part series on taking a software project from a blank idea to a public release using GitHub and Claude Code. Each post teaches a technique you can apply to any project in any language, then shows how the open-source GopherTrunk scanner does it for real.
0.x convention, and why you want one
before v1.0.0.Strip away the ceremony and a release is three things:
v0.4.5) to one exact commit.Everything else — version policy, changelogs, automation — exists to make those three things trustworthy and repeatable. If you get the tag right and the build is reproducible from it, you can always reconstruct exactly what a user is running.
Semantic Versioning (SemVer) is a contract written into
the version number MAJOR.MINOR.PATCH:
1.x.x → 2.0.0): you broke backward compatibility. Users must
read the notes before upgrading.1.2.x → 1.3.0): you added functionality, backward-compatibly.
Safe to upgrade.1.2.3 → 1.2.4): you fixed a bug, no API change. Always safe.The discipline is what makes this useful. If a “patch” quietly changes behavior, the number is lying and your users stop trusting it. When in doubt about whether something is a feature or a fix, ask: could this surprise someone who upgrades without reading? If yes, it’s at least a MINOR.
A subtle but important rule: everything below 1.0.0 is a free-for-all.
SemVer §4 says the public API should not be considered stable until 1.0.0. A
0.x version is itself a signal — “I’m still figuring out the shape of this,
expect change.” That’s not a cop-out; it’s an honest label.
A pre-release is a version you ship knowing it’s not the final cut. SemVer
gives you a suffix for this (1.0.0-alpha, 1.0.0-beta.2, 1.0.0-rc.1), and
the convention is a rough confidence ladder:
Two reasons to bother. First, it sets expectations honestly. Second — and this
is the one people skip — a pre-release exercises your release machinery on
real infrastructure before it matters. The first time you push a tag and watch
the build run is exactly when you find out your version-injection is broken or
your artifact paths are wrong. Far better to discover that on v0.99.0 than on
v1.0.0.
The instinct to batch up “enough” changes into a big release is a trap. Large releases are riskier (more surface area to regress), harder to write notes for, and slower to get feedback on. Shipping small and often means each release is easy to reason about, easy to roll back, and keeps users in the habit of upgrading. Your cadence doesn’t have to be fixed — “whenever there’s something worth shipping” is a perfectly good policy for a side project.
A CHANGELOG.md is the project’s release diary. The
Keep a Changelog format is the de-facto standard
and it’s dead simple:
## [Unreleased] section you append to as you merge changes — so the work
is already done when you cut a release.### Added, ### Changed, ### Fixed, ### Removed,
### Deprecated, ### Security.Write entries for users, not for git. “Fixed null pointer in handler” is a
commit message; “Scanner no longer crashes when a talkgroup has no name” is a
changelog entry. When you cut a release, you rename [Unreleased] to the new
version with a date and open a fresh [Unreleased]. That’s it.
GitHub Releases can also auto-generate notes from merged PR titles, which is a great complement to a hand-written changelog: the changelog tells the story, the auto-notes give the complete list.
Manual release builds are where mistakes live. The pattern that scales:
v*.*.*).Inject the version at build time rather than hard-coding it in source — that way
the binary can report exactly which release and commit it came from. In Go this
is -ldflags "-X pkg.Version=..."; other ecosystems have equivalents. And always
publish a SHA256SUMS file so anyone can verify the download wasn’t corrupted or
tampered with.
GopherTrunk is on SemVer
v0.4.5 — squarely in the honest 0.x “still stabilizing” range, with the
public API and config schema free to evolve until v1.0.0. Here’s the full
release machinery, all real:
The changelog is the source of truth. CHANGELOG.md opens by declaring it
follows Keep a Changelog and Semantic Versioning, and the top of the file is
always an ## [Unreleased] section. Contributors add a line there as part of
every PR — CONTRIBUTING.md literally lists “Add a line to CHANGELOG.md under
## [Unreleased]” as step 3 of sending a pull request. Cutting v0.4.5 was just
promoting that section to a dated heading.
A tag triggers everything. .github/workflows/release.yml is wired to
on: push: tags: ["v*.*.*"] (plus a manual workflow_dispatch button). Pushing
vX.Y.Z builds Windows, Linux, and macOS artifacts for both amd64 and arm64
in parallel, then a final release job flattens them and publishes the GitHub
Release.
Version is injected at link time. Each build computes the version, short commit SHA, and UTC build time and bakes them in via ldflags:
-ldflags "-X github.com/MattCheramie/GopherTrunk/internal/version.Version=${VERSION} \
-X github.com/MattCheramie/GopherTrunk/internal/version.Commit=${COMMIT} \
-X github.com/MattCheramie/GopherTrunk/internal/version.BuildTime=${BUILD_TIME}"
So gophertrunk version always reports exactly which release and commit you’re
running.
Rehearse before you tag. CONTRIBUTING.md’s “Cutting a release” section
tells you to dry-run first:
make release-dry-run VERSION=v0.99.0
That builds dist/dry-run/gophertrunk with the same ldflags the real workflow
uses, runs ./gophertrunk version against it, and writes a SHA256SUMS file —
so packaging or ldflags breakage surfaces before a tag is cut.
Pre-release before v1.0.0. The repo’s stated policy is that “the first
production release should be a prerelease (e.g. v0.99.0)” so the full workflow
runs end-to-end against live GitHub Actions before v1.0.0 ships. And the
release job encodes the SemVer pre-release rule in code: any v0.x tag or any
tag with a hyphen suffix (v1.0.0-rc.1) is published with prerelease: true;
only a clean v1.0.0+ lands as the “latest” stable release.
Checksums and tag protection. The final job runs sha256sum * > SHA256SUMS
over every artifact, and every release ends with the line “All artifacts are
SHA-256-checksummed in SHA256SUMS.” Tags themselves are protected: the
.github/rulesets/release-tags-protection.json ruleset matches refs/tags/v*
and blocks both deletion and update, so a published release tag can never be
silently moved to point at different code.
You don’t need a multi-OS matrix to copy this. The portable moves are: pick
SemVer, keep an [Unreleased] changelog, trigger the build off a tag, inject the
version, ship checksums, and rehearse with a pre-release.
When should I release v1.0.0?
When you’re willing to promise API stability — that you won’t make breaking
changes without bumping to 2.0.0. If you’re still reshaping the public
interface, stay on 0.x. There’s no rush; plenty of widely-used software lives
happily at 0.x for years.
Do I need a changelog if GitHub auto-generates release notes?
They serve different purposes. Auto-generated notes list every merged PR — great
for completeness. A hand-written CHANGELOG.md curates the user-facing story
and groups changes by type. The best setup uses both, which is exactly what
GopherTrunk does (generate_release_notes: true alongside CHANGELOG.md).
What’s the difference between a tag and a release? A tag is a git concept: an immutable pointer to a commit. A “release” is a GitHub feature layered on top — a tag plus a title, notes, and downloadable artifacts. You can have tags with no release, but not a release without a tag.
Why inject the version instead of writing it in a file?
A version file can drift from reality — someone forgets to bump it, or a local
build reports the wrong number. Injecting Version/Commit/BuildTime at link
time means the binary always tells the truth about exactly what produced it.
Should pre-releases show up as the “latest” download?
No. Mark them prerelease: true so users who just want the stable build aren’t
handed a release candidate. GopherTrunk’s release job does this automatically for
any 0.x or hyphen-suffixed tag.
Part 11 of 14 · ← Part 10: Websites, Support Pages & GitHub Pages · Next → Part 12: Optimizing & Securing Your Repository
]]>TL;DR — The HackRF One driver decodes the simplest of the three wire formats: signed 8-bit interleaved IQ scaled to
complex64. Identity is the tricky part — the driver guesses the model from a USB PID, then lets the firmware’s board-ID readback override it. A probe-gains bug (sdr list --probeshowed empty gains) is fixed by stamping the full identity, ladder included, onto the device at open time.
complex64 in [-1, 1].0x1d50, and
why the board-ID read at open takes precedence over the PID guess.sdr list --probe showed empty gains because we read them before
the device was fully open — and the open-time fix the tests pin down.The HackRF One is a half-duplex
transceiver from Great Scott Gadgets covering 1 MHz–6 GHz. GopherTrunk only
receives, so the driver’s surface is small: enumerate, claim, tune, set rate and
gain, flip into receive mode, and reap bulk-IN URBs into complex64. Like every
other backend it speaks the vendor protocol — here libhackrf’s — directly over
the shared pure-Go USB transport, so no CGO and no libhackrf land in the build.
Its sample format is the friendliest of the bunch. The firmware delivers
signed 8-bit interleaved IQ — I, Q, I, Q, … — on bulk endpoint 0x81 once
the transceiver is in receive mode. There’s no real-to-complex synthesis (that
was the Airspy R2/Mini in
Part 10)
and no 16-bit unpacking; just two signed bytes per complex sample.
The decode is a tight loop over internal/sdr/hackrf/hackrf.go: read a signed
byte for I, one for Q, normalize each to roughly [-1, 1] by dividing by 128:
// internal/sdr/hackrf/hackrf.go
// decodeInt8IQ converts a HackRF bulk-IN payload (signed 8-bit
// interleaved IQ) into normalised complex64 samples in [-1, 1].
func decodeInt8IQ(buf []byte) []complex64 {
n := len(buf) / 2
out := make([]complex64, n)
for i := 0; i < n; i++ {
iv := float32(int8(buf[2*i])) / 128
qv := float32(int8(buf[2*i+1])) / 128
out[i] = complex(iv, qv)
}
return out
}
The int8 conversion is load-bearing: the bytes arrive as uint8 in the slice,
and reinterpreting them as int8 is what makes 0x80 read as -128 rather than
+128. The in-package test pins that down with a (-128, +64) sample expected
near (-1, +0.5).
The HackRF won’t stream until you tell it to receive, and you must put it back to
off when you stop. That’s a two-value state machine over SET_TRANSCEIVER_MODE
(reqSetTransceiverMode):
// internal/sdr/hackrf/hackrf.go
const (
transceiverModeOff uint16 = 0
transceiverModeReceive uint16 = 1
)
func (d *Device) setMode(mode uint16) error {
return d.t.ControlOut(reqSetTransceiverMode, mode, 0, nil, controlTimeoutMs)
}
StreamIQ flips to receive, starts the bulk-IN reaper, and a detached goroutine
flips back to off on either context cancellation or an unrecoverable URB death —
the same teardown shape every driver in this series shares.
SetCenterFreq is the one place the HackRF’s wire encoding is slightly unusual:
libhackrf splits the frequency into an MHz part and an Hz remainder, two
little-endian uint32s in the data stage:
// internal/sdr/hackrf/hackrf.go
payload := make([]byte, 8)
binary.LittleEndian.PutUint32(payload[0:4], hz/1_000_000)
binary.LittleEndian.PutUint32(payload[4:8], hz%1_000_000)
return d.t.ControlOut(reqSetFreq, 0, 0, payload, controlTimeoutMs)
SetSampleRate does a little extra work: the rate goes out as a
numerator/divider pair (the driver always uses divider 1, so the host sees
exactly the requested rate), and then the baseband filter cutoff tracks the
rate — set to ~75 % of it to keep the passband flat while rejecting alias
energy near the band edge. The filter program is fire-and-forget; the rate
program is the one that must land:
// internal/sdr/hackrf/hackrf.go (shape)
// rate = (hz, divider 1); then baseband filter ≈ 0.75 × rate
bw := uint32(float64(hz) * 0.75)
_ = d.t.ControlOut(reqBasebandFilterBwSet,
uint16(bw&0xFFFF), uint16(bw>>16), nil, controlTimeoutMs)
The TestSetSampleRateProgramsFilter test scripts both transfers, asserting the
filter program follows the rate program with the 0.75 cutoff.
The HackRF has no true AGC. Its gain is three independent stages: an RF amp (on/off), an LNA (0–40 dB in 8 dB steps), and a VGA (0–62 dB in 2 dB steps). The driver maps a single tenth-dB target onto that triple, and maps “auto” (a negative value) onto a sane fixed preset rather than a non-existent AGC:
// internal/sdr/hackrf/hackrf.go
// splitGain maps an SDR-interface tenth-dB target to the HackRF's
// (LNA, VGA, AMP-on) triple. LNA must be a multiple of 8; VGA a multiple of 2.
func splitGain(tenthDB int) (lna, vga int, amp bool) {
if tenthDB < 0 {
return defaultLNAGainDB, defaultVGAGainDB, false // 16 dB LNA, 20 dB VGA
}
target := tenthDB / 10
lna = (target / 8) * 8
if lna > 40 {
lna = 40
}
rem := target - lna
vga = (rem / 2) * 2
if vga > 62 {
vga = 62
}
return lna, vga, false
}
The default preset — LNA 16 dB, VGA 20 dB, amp off — is the
hardware-friendly mid-band split the test ladder asserts on (splitGain(-1) ==
(16, 20, false), and rungs like 300 → (24, 6)).
Three HackRF variants share VID 0x1d50 under different PIDs — One (0x6089),
the Jawbreaker prototype (0x604b), and the Rad1o badge (0xcc15). Unlike
the Airspy (one PID) or RTL-SDR, enumeration here has to scan every known PID
and concatenate the results into one descriptor list:
// internal/sdr/hackrf/hackrf.go (shape)
descs := make([]usb.Descriptor, 0)
for _, pid := range []uint16{pidHackRFOne, pidHackRFJawbrk, pidHackRFRad1o} {
found, err := d.enum.List(vidHackRF, pid)
// ...append found to descs...
}
Enumeration then maps each PID to a canonical product name, since USB descriptor strings vary by vendor and firmware while the PID is stable:
// internal/sdr/hackrf/hackrf.go
var pidProductNames = map[uint16]string{
pidHackRFOne: "HackRF One",
pidHackRFJawbrk: "HackRF Jawbreaker",
pidHackRFRad1o: "Rad1o",
}
But the PID is only a guess about what the box is — a unit flashed with the
wrong firmware will enumerate under one PID while actually running another
board’s image. So at open time the driver asks the firmware directly, via
BOARD_ID_READ, and that answer takes precedence over the PID:
// internal/sdr/hackrf/hackrf.go
product := productForPID(desc.PID, desc.Product)
if bid, err := readBoardID(t); err == nil {
if name, ok := boardIDNames[bid]; ok && name != "" {
product = name // firmware self-report wins over the PID guess
}
}
boardIDNames mirrors libhackrf’s hackrf_board_id enum (2 → “HackRF One”,
3 → “Rad1o”, …). The same open also reads VERSION_STRING_READ to suffix the
tuner name with firmware (and to tag PortaPack/Mayhem builds). Both readbacks are
best-effort: older firmware that doesn’t implement them just falls through to the
PID-derived name and a plain tuner string — pinned by
TestReadVersionStringIgnoredOnError in hackrf_test.go.
--probe reported empty gainsSymptom. sdr list --probe — which actually opens each device and reports
dev.Info() — listed HackRFs (and Airspys) with an empty gain list. The
non-probing sdr list, which only enumerates, showed the ladder fine. Same
hardware, two different answers, depending on whether the device had been opened.
Root cause. The gain ladder was attached to the sdr.Info produced by
Enumerate, but the Info carried by an opened Device was built
separately at open time and never got the Gains field. So the moment a probe
opened the device and read dev.Info().Gains, it got back nil. The information
existed; it just wasn’t established on the device-side Info that --probe
reads. (The same gap bit the Airspy driver, and is called out in #454’s
probe-gains fix.)
The Go fix. Establish the full identity — board-ID, version string, and
the gain ladder — at open time, on the same Info the opened device hands back.
The ladder is shared between Enumerate and Open so a probed device reports
exactly what an enumerated one does:
// internal/sdr/hackrf/hackrf.go
// gainPresetsTenthDB ... Shared by Enumerate and Open so a probed
// (opened) device reports the same ladder an enumerated one does —
// otherwise `--probe` showed an empty list.
var gainPresetsTenthDB = []int{0, 80, 160, 240, 320, 400, 480, 560}
return &Device{
t: t,
info: sdr.Info{
// ...board-ID-resolved Product, fw-suffixed TunerName...
// Carry the gain ladder onto the opened device so dev.Info()
// (used by `sdr list --probe`) reports it, not an empty list.
Gains: gainPresetsTenthDB,
},
}, nil
The fix is pinned by a test in hackrf_test.go that opens a device through a
scripted mock and asserts the opened Info carries the ladder:
// internal/sdr/hackrf/hackrf_test.go
// The opened device must carry the gain ladder so `sdr list --probe`
// (which reads dev.Info() post-open) doesn't report an empty list.
if got := dev.Info().Gains; len(got) == 0 {
t.Errorf("opened device Info().Gains is empty; want the gain ladder")
}
That same test (TestDriverEnumerateAndOpen) scripts the BOARD_ID_READ and
VERSION_STRING_READ exchanges the open now issues — proof that the board-id and
version readbacks, the firmware suffix, and the gain ladder all get established as
one atomic open-time step rather than lazily on first use.
It’s worth dwelling on why this class of bug is easy to introduce. Enumerate
and Open each build an sdr.Info independently — they have to, because an
opened device knows things an enumerated one can’t (the board-ID, the firmware
string). The trap is that the two Info constructions drift: a field added to
one is forgotten on the other, and nothing in the type system flags it. The fix
isn’t just “stamp the ladder on at open” — it’s making the shared facts (the
gainPresetsTenthDB ladder, the canonical product name via productForPID) come
from one source that both paths read, so they can’t disagree. The open-only facts
(board-ID override, firmware suffix) layer on top.
The thread tying the decode loop to the probe-gains fix is one principle: a device’s identity and capabilities are established when it’s opened, by asking the hardware — not guessed lazily and not deferred until first use.
BOARD_ID_READ at open
overrides the PID-derived name, so a mis-flashed unit reports what’s actually
running. The PID guess only survives when the firmware can’t answer.Info. Product, tuner/firmware
string, and the gain ladder are all stamped onto the device’s Info in Open.
Nothing downstream has to re-derive or re-probe them — dev.Info() is complete
the instant Open returns, which is exactly what --probe depends on.MockTransport with no hardware, so the
identity-by-capability contract is regression-tested.That’s all four wire formats and all four open-time identity strategies covered: RTL-SDR, Airspy R2/Mini, Airspy HF+, and HackRF. The remaining question is what sits above the drivers — the pool that owns opened devices, dispatches retunes, and survives a USB unplug-and-replug mid-stream. That’s Part 12: the SDR pool and the USB hotplug watchdog.
Why divide the 8-bit samples by 128 and not 127?
Dividing by 128 maps the full signed range cleanly: -128 → -1.0 exactly, and
+127 → ~0.992. It keeps the scale a power of two and guarantees the result
never exceeds [-1, 1), which downstream DSP assumes.
Why does board-ID override the PID if both are available? The PID is what the device enumerated as; the board-ID is what the firmware reports it is. A unit flashed with another board’s image enumerates under one PID but runs another board — the firmware’s self-report is the ground truth, so it wins.
Why did probe show empty gains but plain list didn’t?
sdr list only enumerates, reading the Info from Enumerate (which had the
ladder). sdr list --probe opens each device and reads dev.Info(), which was
built separately at open and lacked the Gains field until we stamped the ladder
on at open time.
Does the HackRF have AGC? No. It has three manual stages (amp, LNA, VGA). The driver maps a negative (“auto”) target to a fixed hardware-friendly preset — amp off, LNA 16 dB, VGA 20 dB — rather than pretending an AGC exists.
Why scan multiple PIDs at enumerate instead of one?
Because the HackRF family ships under three PIDs on the same VID. A single
List(vid, pid) would miss Jawbreakers and Rad1os, so enumeration loops over all
three known PIDs and concatenates the descriptors into one ordered list that
Open later indexes into.
What’s the bias-tee for, and is it on by default?
SetBiasTee toggles the +3.3 V antenna-port bias (ANTENNA_ENABLE) for powering
an external LNA up the coax. It’s off unless explicitly enabled — the test
round-trips it on then off — so you never accidentally feed DC into a passive
antenna.
Part 11 of 14 · ← Part 10 · Next → Part 12: The SDR pool & USB hotplug watchdog
]]>TL;DR: Your project can have a real website for free. Turn on GitHub Pages,
point it at a static-site generator like Jekyll, and you get a fast, secure,
CDN-backed site built straight from your repo. Add a custom domain with a
one-line CNAME file, build a landing page that sells the project, add
support and sponsor pages so people can get help and chip in, and run a blog —
including scheduled, drip-released posts. The whole thing lives in the same
repo as your code and deploys on every push.
Key takeaways
CNAME file plus a DNS record.This is Part 10 of Build in the Open, a 14-part series on taking a software project from a blank idea to a public release using GitHub and Claude Code. Each post teaches a technique you can apply to any project in any language, then shows how the open-source GopherTrunk scanner does it for real.
CNAME file.GitHub Pages is free static-site hosting built into GitHub. You enable it in
Settings → Pages, choose a source (a branch, a /docs folder, or — better —
GitHub Actions), and GitHub serves the result over HTTPS from a CDN at
username.github.io/repo. Because the site is static — plain HTML, CSS, and
JavaScript — there’s nothing to run, nothing to patch, and nothing to pay for.
“Static” sounds limiting but rarely is. Docs, landing pages, blogs, and marketing sites are all static by nature, and a static site is the fastest and most secure thing you can ship.
Writing raw HTML for every page gets old fast. A static-site generator lets you write content in Markdown, share layouts and navigation across pages, and build the whole site with one command. Jekyll is the generator GitHub Pages supports natively — Pages can build a Jekyll site for you with no extra setup.
What a generator buys you:
Other generators (Hugo, Eleventy, Astro, MkDocs) work on Pages too, usually via a GitHub Actions build. Jekyll is just the path of least resistance.
A username.github.io URL works, but a real project wants a real domain. Pages
makes this a two-step affair:
CNAME to your site source containing just your domain,
e.g. example.org.CNAME record to
username.github.io, or A/AAAA records to GitHub’s IPs for an apex
domain).GitHub then provisions a free TLS certificate, and your site serves over HTTPS on your own domain. One file, one DNS record, done.
Beyond the docs, a few pages do real work:
.github/FUNDING.yml file and renders a Sponsor button on
your repo automatically; you can list GitHub Sponsors, Ko-fi, Patreon, and
more.A static blog is just dated files in a posts folder. The clever part is scheduling. Most generators, Jekyll included, will exclude a post dated in the future from the build. Pair that with a daily scheduled rebuild and you get a powerful pattern:
No draft branches, no daily commits, no manual publishing — the calendar does the releasing for you. (This very series is published exactly that way.)
GopherTrunk’s entire website —
gophertrunk.org — is a Jekyll site on GitHub Pages,
built from the repo’s docs/ folder. The pieces line up with everything above:
CNAME. docs/CNAME contains exactly one line —
gophertrunk.org — and that’s what serves the site on its own domain over
HTTPS..github/workflows/pages.yml) has a “Synthesize landing page from
README.md” step that transforms README.md into docs/index.md during the
build — rewriting asset paths and cross-links and stripping the duplicate hero.
The homepage and the README can never drift apart, because there’s only one
source (the doc-organization payoff from Part 9).docs/_config.yml enables jekyll-seo-tag
(titles, meta descriptions, Open Graph/Twitter cards), jekyll-sitemap
(sitemap.xml), and jekyll-feed (an Atom feed at /feed.xml) — so search
engines and readers get structured metadata for free.docs/support.md
page, and .github/FUNDING.yml lists GitHub Sponsors (github: MattCheramie)
and Ko-fi (ko_fi: Mrcheramie), which GitHub turns into the repo’s Sponsor
button.docs/_config.yml sets future: false (a
future-dated post stays out of the build until its date), and
pages.yml runs a daily cron: "0 16 * * *" rebuild. A whole series is
committed at once on consecutive future dates and goes live one post per day —
with a scripts/schedule-series.py helper to assign the dates. That’s the
mechanism publishing the post you’re reading now.You don’t need a radio project to copy this. Any repo can flip on Pages, drop a
CNAME, point Jekyll at a /docs folder, add a FUNDING.yml, and schedule a
blog — all for the price of a push.
Is GitHub Pages really free? Yes, for public repositories, including HTTPS and CDN delivery, within generous soft bandwidth and size limits. For a project site, docs, or blog you will almost certainly never hit them.
Do I have to use Jekyll? No. Jekyll is the generator Pages builds natively with zero config, but you can deploy any static site — Hugo, Eleventy, Astro, plain HTML — by building it in a GitHub Actions workflow and publishing the output. Jekyll is just the lowest- friction option.
How do I add a custom domain to GitHub Pages?
Add a CNAME file containing your domain to the site source, then create a DNS
record at your registrar pointing the domain at GitHub Pages. GitHub provisions
a free TLS certificate automatically once DNS resolves.
How do I schedule blog posts to publish on a future date?
Date the post in the future and configure your generator to exclude future-dated
content (future: false in Jekyll), then run a daily scheduled build. Each
build reveals the posts whose date has arrived — so you can write a series now and
have it release one post per day.
How do I add a Sponsor button to my repo?
Add a .github/FUNDING.yml listing your funding platforms (GitHub Sponsors,
Ko-fi, Patreon, etc.). GitHub reads it and shows a Sponsor button on the repo
automatically — no other setup required.
Part 10 of 14 · ← Part 9 · Next → Part 11: Releases — Pre-release, SemVer & Changelogs
]]>TL;DR — The Airspy R2/Mini stream bare real ADC samples, not IQ, so the host synthesizes complex baseband: a leaky DC blocker, a multiplier-free Fs/4 mix, and a half-band Hilbert pair. The headline bug (#454): the converter must carry filter state across USB packets, or you get ~78° quadrature imbalance and no image rejection — fixed by threading one stateful converter through the whole stream. The HF+ needs none of it: it delivers native int16 IQ.
iqconverter.go: leaky-HPF DC
removal → multiplier-free Fs/4 mix → polyphase half-band split →
decimate by two.Most cheap SDRs hand the host quadrature IQ: two streams, in-phase and quadrature, already mixed to baseband by the tuner. RTL-SDR does this (unsigned 8-bit I,Q); the HackRF does this (signed 8-bit I,Q); the Airspy HF+ does this (signed 16-bit I,Q). You decode a pair of integers into one complex sample and you are done.
The Airspy R2 and Airspy Mini do not. They are real-sampling receivers: a
single fast ADC digitizes a real intermediate-frequency signal, and the
firmware streams the bare ADC output — unpacked little-endian uint16, 12-bit
resolution, DC sitting at 2048 — at twice the configured IQ rate. There is
no quadrature channel coming over USB. Producing complex baseband is a host-side
job, and it is the same job an analog superheterodyne would hand to a pair of
mixers and a phasing network: take a real signal, reject its mirror image, and
land it at zero IF as I + jQ.
That 2× is not incidental. A real signal sampled at Fs carries usable
bandwidth up to Fs/2; a complex signal at Fs/2 carries the same bandwidth
across ±Fs/4. So N real input samples become N/2 complex outputs at half
the rate — which is exactly why, in the driver, a requested IQ rate of 3 MHz
selects the 6 MSPS device mode. We covered that rate-doubling foot-gun in
the Part 2
device contract; here we build the converter that justifies it.
The whole conversion lives in internal/sdr/airspy/iqconverter.go, driven from
one method per USB packet. Its job, top to bottom: decode uint16 reals,
remove DC, mix by Fs/4, run the half-band pair, emit complex64.
The ADC parks DC at 2048 and the front end adds its own slow bias drift. Left in, that DC becomes a fat spike at the center of every spectrum. We strip it with a one-pole leaky high-pass — a running estimate of the mean that we subtract before anything else touches the sample:
// internal/sdr/airspy/iqconverter.go
x := (float32(binary.LittleEndian.Uint16(buf[2*i:])) - dcBias) / dcFull
// Leaky DC blocker: removes the residual ADC bias before the mix.
x -= c.avg
c.avg += dcLeak * x
dcBias is 2048, dcFull normalizes to roughly [-1, 1), and dcLeak is
0.01 — a slow tracker that follows bias drift without eating low-frequency
signal. The accumulator c.avg is state: it carries from one packet to the
next so the DC estimate doesn’t reset (and re-spike) every 6 ms.
To get to baseband we need to multiply the real stream by a complex sinusoid.
Pick that sinusoid at exactly Fs/4 and the multiplications collapse into
nothing: e^{-j(π/2)n} walks the unit circle in steps of 90°, so its samples
are just 1, -j, -1, +j, …. No multiplies, no sine table — only a sign flip and
a branch on which polyphase lane the sample falls in. That is the phase
counter, cycling 0..3:
// internal/sdr/airspy/iqconverter.go
switch c.phase {
case 0, 2:
// In-phase branch. The Fs/4 mix alternates the sign of the
// even samples; push into the FIR and recompute its output.
if c.phase == 0 {
x = -x
}
c.pushI(x)
c.lastI = c.firI()
case 1, 3:
// Quadrature branch. The mix alternates sign and folds in the
// 0.5 half-band centre tap; the matched delay aligns it with
// the in-phase FIR's group delay, then we emit one sample.
q := 0.5 * x
if c.phase == 1 {
q = -q
}
// ...delay line, then emit complex(c.lastI, qOut)
}
phase is also state — it persists across packets so the (-j)^n rotation
never glitches at a buffer boundary.
Mixing by Fs/4 puts the wanted signal at baseband but also folds the mirror
image right on top of it. Rejecting that image is the whole game, and it falls
out of a 47-tap half-band filter, split into its two polyphase lanes:
0.5, and rather than spend a tap on it we fold that
0.5 straight into the Fs/4 mix (q := 0.5 * x above). The delay line just
lines Q up with the FIR’s group delay.// internal/sdr/airspy/iqconverter.go
// firI evaluates the symmetric half-band FIR over the current window, with
// hbKernel[0] weighting the newest sample and hbKernel[hbTaps-1] the oldest.
func (c *iqConverter) firI() float32 {
var acc float32
idx := c.iwinPos - 1
if idx < 0 {
idx += hbTaps
}
for j := 0; j < hbTaps; j++ {
acc += hbKernel[j] * c.iwin[idx]
if idx--; idx < 0 {
idx += hbTaps
}
}
return acc
}
Both lanes carry state — the in-phase iwin FIR window and the quadrature
qline delay line are circular buffers on the iqConverter struct:
// internal/sdr/airspy/iqconverter.go (shape)
type iqConverter struct {
avg float32 // leaky DC-blocker accumulator
phase int // Fs/4 mix phase, 0..3, persists across packets
iwin [hbTaps]float32 // in-phase FIR window
iwinPos int
lastI float32 // in-phase output awaiting its paired quadrature
qline [hbHalf]float32 // quadrature delay line
qpos int
}
Because we only ever emit on the odd (quadrature) phases, and only consume the
in-phase FIR’s latest output (c.lastI) when we do, the decimation by two is
implicit: every fourth real sample produces no output, every pair of lanes
collapses to one complex64. The driver allocates len(buf)/4 outputs and
returns them:
// internal/sdr/airspy/iqconverter.go
func (c *iqConverter) processRaw(buf []byte) []complex64 {
nReal := len(buf) / 2
out := make([]complex64, 0, nReal/2+1)
// ...per-sample pipeline above...
return out
}
One bulk-IN payload of N real bytes-as-uint16 yields N/2 real samples and
N/4 complex samples, at exactly the configured IQ rate.
Symptom. When the Airspy R2 first came up, nothing locked. The constellation showed a massive quadrature imbalance — about 78° off from the 90° it should be — and essentially no image rejection (~3 dB). Every downstream decoder mistuned; on a quiet band all that survived was the DC spike. The device streamed bytes fine, but the signal was garbage.
Root cause. Two compounding mistakes. First, the driver originally treated
the receiver’s real ADC stream as if it were interleaved I/Q — pairing
adjacent real samples into complex(I, Q). That is simply the wrong model for a
real-sampling front end: there is no Q channel on the wire, so the synthetic Q
was just a delayed copy of I, hence the ~78° imbalance and no image rejection.
Second, once we built the proper Fs/4-plus-half-band converter, the filter and
mix had to be stateful across USB packets. A naive implementation that reset
the FIR window, the DC accumulator, and the phase counter at the start of each
processRaw call produced a discontinuity every 6 ms — a click train at the
packet rate that smeared the spectrum.
The Go fix. All converter memory lives on the iqConverter struct, and a
single converter instance threads through an entire stream. The packet handler
just calls processRaw on the same converter, packet after packet:
// internal/sdr/airspy/airspy.go
// Fresh real-to-IQ converter per stream so filter memory never carries
// over from a previous session.
d.cnv = newIQConverter()
out := make(chan []complex64, 8)
onPacket := func(buf []byte) {
samples := d.cnv.processRaw(buf)
select {
case out <- samples:
case <-ctx.Done():
}
}
The converter is created per stream (so a retune starts from silent filter
memory, phase 0) but is shared across every packet within that stream (so the
FIR window, DC tracker, and mix phase flow continuously across boundaries). The
zero value of iqConverter is a valid reset state, which is what makes
newIQConverter() a one-liner. After the fix, image rejection came back to
~70 dB, matching what libairspy’s own IQ modes deliver.
The Airspy driver is the first place in GopherTrunk where the driver does real
signal processing, not just byte shuffling. The principle: when the hardware
hands you something other than the abstraction the rest of the system wants
([]complex64), the driver pays the cost of bridging the gap — and it does it
from first principles, not by linking someone else’s DSP library.
StreamIQ returns the same <-chan []complex64 every
other driver returns; the Fs/4 mix and half-band pair are an implementation
detail behind it.processRaw is a pure
function of (converter state, bytes), the in-package tests feed synthesized
real tones through it and assert on image rejection — no Airspy required.The Airspy HF+ family (HF+, HF+ Discovery, HF+ Dual Port) is a sibling, not a twin, and it is instructive precisely because it makes the opposite choice. It covers 9 kHz–31 MHz HF plus 60–260 MHz VHF, and it delivers native interleaved int16 IQ — so there is no real-to-complex stage at all. Decoding is the boring two-integers-to-one-complex loop:
// internal/sdr/airspyhf/airspyhf.go
func decodeInt16IQ(buf []byte) []complex64 {
n := len(buf) / 4
out := make([]complex64, n)
for i := 0; i < n; i++ {
iv := int16(binary.LittleEndian.Uint16(buf[4*i:]))
qv := int16(binary.LittleEndian.Uint16(buf[4*i+2:]))
out[i] = complex(float32(iv)/32768, float32(qv)/32768)
}
return out
}
No converter, no filter state, no 2× rate trick. The HF+ proves the point that
the R2/Mini converter is device-specific: the complex-baseband abstraction is
the same, but how much work the driver does to honor it depends entirely on what
the silicon streams.
The HF+ has two wrinkles worth calling out. First, all three variants share one
VID:PID (0x03eb:0x800c); the USB descriptor’s Product string is the only
observable model identifier, so the driver disambiguates on it:
// internal/sdr/airspyhf/airspyhf.go
func variantName(product string) string {
p := strings.ToUpper(product)
switch {
case strings.Contains(p, "DISCOVERY"):
return "Airspy HF+ Discovery"
case strings.Contains(p, "DUAL"):
return "Airspy HF+ Dual Port"
default:
return "Airspy HF+"
}
}
Second, “gain” on the HF+ is mostly attenuation reduction. The front end has
a fixed conversion stage; what the operator controls is HF_AGC (firmware-managed
LNA + mixer), HF_ATT (a 0–48 dB attenuator in 6 dB steps), and HF_LNA (a fixed
+6 dB preamp). A negative tenth-dB target enables AGC and zeroes the rest;
positive values disable AGC, compute an attenuator step, and switch the LNA in
once attenuation reduction alone has been spent:
// internal/sdr/airspyhf/airspyhf.go (shape)
att := tenthDB / hfATTStepTenthDB // 6 dB steps, clamp 0..8
remaining := tenthDB - att*hfATTStepTenthDB
lnaOn := remaining >= hfLNAGainTenthDB // +6 dB preamp
Note also that the HF+ vendor opcodes are not the R2/Mini’s — sibling
devices, sibling protocols (SET_SAMPLERATE is 4 here, 12 on the R2). The two
drivers live in separate packages for exactly that reason.
We now have three of the four wire formats covered: RTL-SDR’s unsigned 8-bit IQ, the Airspy R2/Mini’s synthesized complex baseband, and the HF+’s native int16 IQ. The simplest of all — HackRF’s signed 8-bit interleaved IQ, plus the identity-by-board-ID dance at open time — is Part 11. After that, Part 12 zooms back out to the pool and USB hotplug watchdog that keeps all of these streaming through unplug-and-replug.
Why not just pair adjacent real samples as I and Q? Because there is no Q on the wire. The Airspy R2/Mini stream a single real ADC channel; pairing reals fabricates a Q that’s just a delayed I, which is what gave us the ~78° imbalance and ~3 dB image rejection in #454. You have to synthesize quadrature with a Hilbert-pair filter.
Why a half-band filter specifically? Half-band filters have their odd taps zeroed (except the center) and a center tap of exactly 0.5. That halves the multiplies in the in-phase lane and lets us fold the center tap into the free Fs/4 mix — the structure does double duty as the anti-alias filter for the decimate-by-two.
Why is the converter created per stream but shared per packet? Per stream so a retune starts from clean filter memory and can’t inherit a stale DC estimate. Per packet so the FIR window, DC accumulator, and mix phase flow continuously and packets join without a click at the boundary.
Does the HF+ ever need the converter?
No. The HF+ delivers complex IQ natively (int16 I,Q), so its driver just
normalizes integers to [-1, 1]. The real-to-complex converter is unique to the
R2/Mini’s real-sampling front end.
Part 10 of 14 · ← Part 9 · Next → Part 11: HackRF One — signed 8-bit IQ end to end
]]>TL;DR: Documentation isn’t one thing — it’s several kinds with different
jobs and different homes. The README is your front door; standard files like
CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, CHANGELOG, and LICENSE each answer one
recurring question; everything deeper lives in an in-repo /docs folder. Use
the Diátaxis framework — tutorials, how-to guides, reference, explanation —
to decide what kind of doc you’re writing and where it belongs. Keep docs next
to the code so they version and rot together, and write each piece for one
specific reader.
Key takeaways
This is Part 9 of Build in the Open, a 14-part series on taking a software project from a blank idea to a public release using GitHub and Claude Code. Each post teaches a technique you can apply to any project in any language, then shows how the open-source GopherTrunk scanner does it for real.
/docs.A handful of files have become conventions because each answers a question someone will inevitably ask. GitHub even surfaces several of them in its UI:
You don’t need all of them on day one, but knowing the slot each fills means you never have to wonder where a given piece of information should go.
The README is the highest-traffic page you will ever write, so it earns the most care. It should answer, fast and in order:
The README’s job is to get someone oriented and then hand them off. The
moment it tries to be the complete manual, it becomes too long to be the front
door. Link out to /docs for everything past “hello world.”
Past the README, documentation gets disorganized because people mix four fundamentally different things into one page. Diátaxis is a widely used framework that names them and keeps them apart:
The power of Diátaxis is diagnostic: when a doc feels muddled, it’s usually trying to be two of these at once. A tutorial bloated with reference detail loses the beginner; a reference padded with tutorial hand-holding annoys the expert. Split them, and each gets clearer.
Wherever it’s reasonable, keep documentation in the repository, in a /docs
folder, versioned alongside the code:
The discipline that keeps docs alive is a simple rule in your CONTRIBUTING file: if your change alters user-visible behaviour, update the docs in the same PR. That turns documentation from a someday chore into part of “done.”
GopherTrunk treats docs as a first-class part of the repo, and the layout maps cleanly onto everything above:
CONTRIBUTING.md documents the build,
test, branch, and PR conventions (including the table of make targets and the
opt-in hardware-test env vars); SECURITY.md carries the threat model and
private-disclosure process; CHANGELOG.md follows Keep a Changelog with an
## [Unreleased] section; LICENSE sets the terms.docs/ folder is large and structured — around 50 markdown files.
It’s clearly organized along Diátaxis lines:
docs/learn/rf-sdr/
(from what-is-sdr.md through clock-recovery.md, digital-voice.md, and a
glossary.md) — the learning-oriented tier.docs/reference/ — the information-oriented tier you look things up in.install-linux.md,
install-macos.md, install-windows.md), getting-started pages, and
operational guides (guide-basics.md, guide-intermediate.md,
guide-advanced.md, hardening.md).architecture.md for the design, plus living-status docs
status.md and roadmap.md for where the project is and where it’s going.You don’t need 50 files to apply this. Even a five-file project benefits from a
README that hands off, the standard community files, and a /docs folder where
each page knows whether it’s a tutorial, a how-to, reference, or explanation.
What’s the minimum documentation a project needs? A README that says what the project is and how to run it, and a LICENSE so people know what they’re allowed to do. Add CONTRIBUTING and SECURITY the moment you invite outside contributors, and a CHANGELOG when you start cutting releases.
What is the Diátaxis framework? A way to organize documentation into four distinct types — tutorials (learning), how-to guides (tasks), reference (lookup), and explanation (understanding) — each written for a different reader need. Its main value is spotting when one doc is trying to do two of those jobs and should be split.
Should documentation live in the repo or on a separate site? Keep the source in the repo, next to the code, so docs version and get reviewed alongside changes. You can still publish them to a website (Part 10 covers that) — but the source of truth belongs in the diff, where it’s least likely to rot.
How do I keep docs from going stale? Make updating them part of “done.” A line in CONTRIBUTING — “update the docs in the same PR as any user-visible change” — plus reviewers who enforce it does more than any tooling. Docs that travel with the code stay closer to the truth.
Where does the README stop and /docs begin?
The README orients and hands off: what, why, get-it-running, and links onward.
Anything past the first successful run — full configuration, guides, reference,
architecture — belongs in /docs, so the front door stays short enough to be a
front door.
Part 9 of 14 · ← Part 8 · Next → Part 10: Websites, Support Pages & GitHub Pages
]]>TL;DR — This is sustained 2.4 MS/s IQ streaming off the RTL2832U: 32 async USB buffers, a deep consumer channel, and a bit-identical U8-to-complex64 lookup table. The headline bug: per-chunk allocations drove GC churn that shed 25–48% of live IQ — fixed with a zero-allocation reuse ring. Two more bugs turn silent IQ loss and a silently dead stream into explicit, observable failures.
Once the chip is tuned, the RTL2832U dumps a continuous stream of unsigned 8-bit
IQ pairs over a USB bulk-IN endpoint. At 2.4 MS/s that’s 4.8 MB/s of raw bytes
that never stops. The streaming layer’s job is to pull those bytes off the wire,
convert each U8 IQ pair into a complex64, and hand the result to the consumer
(a control-channel decoder, a trunking engine, an IQ recorder) as a channel of
[]complex64 chunks — without ever blocking the kernel’s USB reaper and without
dropping samples when the consumer hiccups.
The whole thing lives in internal/sdr/rtlsdr/purego/stream.go, with the device
state machine in device.go.
The numbers are copied verbatim from the old CGO driver so the pure-Go backend is a behavioral drop-in:
// internal/sdr/rtlsdr/purego/stream.go
const (
asyncBufCount = 32
asyncBufLen = 16 * 1024
streamChanDepth = 32
bulkInEndpoint = 0x81
)
Thirty-two async USB buffers of 16 KiB each is about 6 ms of headroom at 2.4
MS/s — enough that a brief scheduler stall doesn’t starve the bulk-IN ring. The
consumer channel is streamChanDepth = 32 chunks deep, roughly 110 ms of slack.
The CGO driver used a depth of 8; the pure-Go backend deliberately runs deeper,
specifically to absorb GC and scheduler jitter on the consumer — and that
number is part of the story below.
StreamIQ resets the USB FIFO, provisions a reuse ring (more on that in a
moment), kicks off the bulk-IN ring on the transport, and returns the channel:
// internal/sdr/rtlsdr/purego/stream.go (shape)
out := make(chan []complex64, streamChanDepth)
d.out = out
// ...provision the reuse ring...
if err := d.transport.StartBulkIn(bulkInEndpoint, asyncBufCount, asyncBufLen,
d.deliver, d.onStreamDead); err != nil {
d.out = nil
return nil, fmt.Errorf("rtlsdr: StartBulkIn: %w", err)
}
go func() { <-ctx.Done(); d.cancelStream() }()
return out, nil
Each completed URB calls deliver, which converts the U8 IQ bytes into
complex64. The conversion math is the bit-identical port of the CGO driver:
subtract a DC bias of 127.5 (mid-range of a u8) and divide by 127.5 to scale to
[-1, +1). Done naively that’s a subtract and a divide per sample, 4.8 million
times a second per dongle. Instead we precompute a 256-entry lookup table once:
// internal/sdr/rtlsdr/purego/stream.go
var u8ToF32 [256]float32
func init() {
for b := 0; b < 256; b++ {
u8ToF32[b] = (float32(b) - 127.5) / 127.5
}
}
func convertU8IQInto(dst []complex64, buf []byte) {
n := len(buf) / 2
for i := 0; i < n; i++ {
dst[i] = complex(u8ToF32[buf[2*i]], u8ToF32[buf[2*i+1]])
}
}
Each entry uses the exact same float32 expression as the original per-sample
math, so the result is bit-identical — pinned by
TestConvertU8IQ_BitIdenticalWithCGO so any drift from the CGO driver shows up
immediately. The hot path is now two table lookups per sample instead of a
subtract+divide.
The symptom. A control-channel RTL-SDR was dropping 25–48% of its IQ chunks under load. Not occasionally — sustained. The decoder downstream was clearly busy, but it should have had 110 ms of channel slack to ride out a busy moment. Something was making the consumer systematically unable to keep up.
The root cause. convertU8IQInto’s allocating wrapper was the culprit.
Originally, deliver allocated a fresh []complex64 for every chunk:
// internal/sdr/rtlsdr/purego/stream.go
func convertU8IQ(buf []byte) []complex64 {
out := make([]complex64, len(buf)/2)
convertU8IQInto(out, buf)
return out
}
At 16 KiB per URB that’s an 8192-element complex64 slice — ~64 KiB — allocated
fresh, hundreds of times a second, then thrown away as soon as the consumer
finished with it. That allocation rate drove the garbage collector hard, and the
GC pauses landed on the consumer goroutine, pushing the control-channel decoder
over its real-time budget. The decoder fell behind, the channel filled, and
deliver’s drop-on-overrun branch started shedding chunks — a quarter to half of
them. The deep channel didn’t help because the problem wasn’t a transient stall;
it was steady-state allocation pressure that the channel depth couldn’t paper
over.
The fix. A ring of preallocated complex64 buffers, reused across chunks.
StreamIQ provisions streamChanDepth + 2 of them per stream:
// internal/sdr/rtlsdr/purego/stream.go
ring := make([][]complex64, streamChanDepth+2)
for i := range ring {
ring[i] = make([]complex64, asyncBufLen/2)
}
d.ring = ring
d.ringIdx = 0
The sizing is exact: at most streamChanDepth buffers can sit queued on the
channel, plus one in the consumer, so cycling through depth + 2 slots
guarantees the producer never overwrites a buffer still in flight. deliver now
fills the current ring slot instead of allocating, and — critically — only
advances the ring index on a successful enqueue:
// internal/sdr/rtlsdr/purego/stream.go
samples := d.fillBufferLocked(buf)
select {
case out <- samples:
// Advance the ring only on a successful enqueue: a dropped chunk
// reuses the same buffer next time, so a buffer's slot is never
// recycled until that chunk has actually been handed to the consumer.
if len(d.ring) > 0 {
d.ringIdx = (d.ringIdx + 1) % len(d.ring)
}
d.streamMu.Unlock()
default:
d.streamMu.Unlock()
d.dropped.Add(1)
sdr.NotifyIQDrop(d.info)
}
fillBufferLocked writes into the ring slot via the allocation-free
convertU8IQInto, falling back to a fresh allocation only when no ring is
provisioned (direct deliver in tests) or for a packet too large to fit a slot:
// internal/sdr/rtlsdr/purego/stream.go
func (d *Device) fillBufferLocked(buf []byte) []complex64 {
n := len(buf) / 2
if len(d.ring) == 0 {
return convertU8IQ(buf)
}
dst := d.ring[d.ringIdx]
if cap(dst) < n {
return convertU8IQ(buf) // oversized packet; don't disturb the ring
}
dst = dst[:n]
convertU8IQInto(dst, buf)
return dst
}
With the ring in place the steady state allocates nothing per chunk, the GC went quiet, the consumer kept its budget, and the drop rate fell to zero. The deeper channel depth from earlier is slack on top of this — not a substitute for it.
The symptom. When the control channel did drop IQ, there was no way to tell. A decode failure looked identical whether it came from a weak signal, multipath, or the live path silently shedding chunks. Live IQ loss was indistinguishable from an RF problem.
The root cause and fix. The drop branch in deliver was genuinely silent — it
threw the chunk away and moved on. We added a lifetime drop counter and a
notification hook:
// internal/sdr/rtlsdr/purego/device.go
dropped atomic.Uint64
func (d *Device) DroppedChunks() uint64 { return d.dropped.Load() }
Now the drop branch records every discard and notifies an observer outside the lock (so the callback can’t stall the reaper):
// internal/sdr/rtlsdr/purego/stream.go (drop branch)
d.dropped.Add(1)
sdr.NotifyIQDrop(d.info)
NotifyIQDrop drives an operator-facing Prometheus counter
(iq_underruns_total) plus a rate-limited warning. A non-zero count during a
decode failure now points squarely at a live-path overrun rather than the air — a
diagnosis you simply could not make before. (The same issue-#402 work also
exposed ActualSampleRate, because the down-converter has to derive its symbol
clock from the rate the chip is actually delivering, not the requested one — but
that’s a decode-path story.)
The symptom. When a dongle fell off the USB bus mid-stream — unplugged, or an
unrecoverable ENODEV/EPROTO — the consumer goroutine would block on the IQ
channel forever. No error, no EOF, just a permanent hang.
The root cause. The USB reaper goroutine inside StartBulkIn exits when every
bulk-IN URB dies of an unrecoverable error. But it exits without anyone calling
StopBulkIn, so the consumer channel was never closed. The consumer’s range
over the channel had nothing to wake it.
The fix. A stream-death callback. StartBulkIn takes an onStreamDead
handler that fires exactly when the reaper exits abnormally, and it runs
cancelStream:
// internal/sdr/rtlsdr/purego/stream.go
func (d *Device) onStreamDead(error) {
d.cancelStream()
}
cancelStream is the same idempotent teardown that context-cancel uses — guarded
by a sync.Once, it stops the bulk-IN ring and closes the consumer channel:
// internal/sdr/rtlsdr/purego/device.go
func (d *Device) cancelStream() {
d.stopOnce.Do(func() {
_ = d.transport.StopBulkIn()
d.streamMu.Lock()
if d.out != nil {
close(d.out)
d.out = nil
}
d.streamMu.Unlock()
})
}
Now a dead stream surfaces to the consumer as a closed channel — a clean EOF — so
the decoder sees ErrIQStreamClosed, the daemon logs it once and decides whether
to retry or exit. The watchdog that does the actual reconnect is the subject of a
later post; here the point is that failure became visible instead of becoming a
hang.
The streaming layer is governed by two rules that show up over and over in real-time Go: the hot path should allocate nothing in steady state, and every failure mode should produce a signal, never silence.
The GC-churn bug is the canonical lesson in the first rule. The allocation wasn’t wrong — it was correct, simple Go — but at 2.4 MS/s its aggregate cost was a GC load heavy enough to break an unrelated real-time consumer two layers away. The fix wasn’t cleverer code; it was no allocation, achieved by reusing buffers whose lifecycle is tied precisely to the channel’s depth.
The drop counter and the stream-death callback are the second rule. A dropped chunk and a dead stream were both silent — and silence in a real-time pipeline is the worst possible failure, because it’s indistinguishable from “working.” Both fixes turn an invisible failure into an explicit, observable one.
streamChanDepth + 2), so steady-state
IQ delivery allocates nothing and the GC stays out of the consumer’s budget.dropped atomic.Uint64 plus NotifyIQDrop
turn a silent overrun into a Prometheus counter and a rate-limited warning,
fired outside the lock so telemetry can’t stall the reaper.onStreamDead → cancelStream makes an
unrecoverable USB error surface as a clean EOF, so no consumer ever blocks
forever. sync.Once makes the teardown idempotent across ctx-cancel, close, and
reaper-death.convertU8IQInto is the same math as the CGO driver,
pinned by a golden test.That closes out the RTL-SDR trilogy: chip bring-up, tuner, and now sustained
streaming. The next family streams differently — the
Airspy R2 and Mini deliver real
samples, not complex IQ, so
Part 10
takes apart the real-to-complex-baseband conversion that turns a real ADC stream
into the []complex64 the rest of the pipeline expects.
Why not just use sync.Pool instead of a hand-rolled ring?
sync.Pool doesn’t give the lifetime guarantee we need: a buffer must not be
reused until the consumer has finished with it, and that’s determined by the
channel depth, not by GC timing. The ring sized streamChanDepth + 2 encodes
exactly that invariant — and a fresh ring per stream means a slow consumer
draining the previous (closed) channel can never alias a buffer the new stream
is writing.
Why advance the ring index only on a successful send? Because a dropped chunk’s buffer was never handed to anyone, so its slot is still safe to overwrite next time. Advancing on drop would waste a slot and, worse, could recycle a slot while its chunk is still queued. Advancing only on success ties the ring’s recycling directly to delivery.
Does the drop-on-overrun policy lose data we care about? Dropping is deliberate: a slow consumer should shed live IQ rather than back-pressure the kernel’s USB reaper, which would stall every stream. The fix for issue #489 was to make sure the consumer isn’t slow in steady state; the drop-and-count path is the safety valve when it momentarily is, and the counter tells you when it fired.
Part 9 of 14 · ← Part 8 · Next → Part 10: Airspy R2/Mini & HF+ — real samples to complex baseband
]]>TL;DR: Tests exist to let you change code without fear. Build them in layers — lots of fast unit tests, fewer integration tests, a handful of end-to-end tests — and make the fast layer the gate your CI enforces on every pull request. Write tests as data (table-driven cases), pin tricky outputs with golden files, turn the race detector on, and treat coverage as a spotlight, not a score. Claude Code is excellent at the tedious parts: generating table cases, hunting edge cases, and writing the regression test that locks a bug shut.
Key takeaways
This is Part 8 of Build in the Open, a 14-part series on taking a software project from a blank idea to a public release using GitHub and Claude Code. Each post teaches a technique you can apply to any project in any language, then shows how the open-source GopherTrunk scanner does it for real.
The honest answer isn’t “to catch bugs” — it’s to let you change code without being afraid of it. A codebase with good tests is one you can refactor, upgrade, and hand to a stranger, because the tests will shout the moment something breaks. A codebase without them is one you tiptoe around.
That reframing also tells you what to test. You don’t test getters and one-line wrappers; you test the things that would hurt to get wrong:
if/switch, math, parsing, or state.Skip the trivial. A test that can only fail if the language itself is broken is just maintenance cost.
The testing pyramid is a rule of thumb for the mix of tests, from cheap and plentiful at the bottom to expensive and rare at the top:
Most pain in real projects comes from an inverted pyramid — a few brittle end-to-end tests and no unit tests underneath. Push the bulk of your coverage down to the fast layer, where a failure points straight at the broken function.
A few techniques transfer to any language and test runner.
Instead of copy-pasting a test five times with different inputs, define a list of cases — input, expected output, a name — and loop over them. Adding a case becomes one line, and the failure message tells you exactly which row broke. Every mature test suite leans on this.
When the expected output is large or fiddly (rendered HTML, a decoded frame, a
formatted report), store a known-good copy as a golden file and assert the
test output matches it. A flag like -update regenerates the goldens after an
intentional change. You review the diff in code review like any other change.
Both stand in for real dependencies, but they’re not the same:
If your language has concurrency, it has a race detector or equivalent (Go’s
-race, ThreadSanitizer, etc.). Run your tests under it. Data races are the
bugs that pass a thousand times and corrupt data on the thousand-and-first;
the detector catches them deterministically.
Coverage tells you which lines executed during the tests — not whether the assertions were meaningful. Chasing 100% rewards writing tests for trivial code and punishes nothing. Use coverage to find untested branches you care about, then decide if they’re worth a test. The number is a map, not the territory.
Some tests can’t run in CI: they need a GPU, a USB device, a paid API key, a specific OS. Don’t delete them — gate them. Make the test skip by default unless an environment variable or build flag opts it in. The test lives in the repo, documents the expected behaviour, and runs on the one machine that can, while CI stays green and fast.
This is where Part 7 pays off. Once you have a fast, reliable test command, you
wire it into a CI workflow that runs on every pull request, and you mark it a
required status check so a PR can’t merge until it’s green. That single rule
turns “we have tests” into “broken code can’t reach main.” The fast layer
(unit + the cheap integration tests) is the gate; the slow and hardware tests
stay opt-in and run out of band.
Tests are some of the highest-leverage work to hand to Claude Code, because the work is structured and the right answer is checkable:
Always read what it produces. Claude is great at breadth; you supply the judgment about which cases actually matter and whether the assertions are real.
GopherTrunk is a pure-Go SDR
trunking scanner, and its testing maps the pyramid onto a Makefile you can read
top to bottom:
make test. It runs
go test -race -count=1 ./... — every package, under the race detector, with
caching disabled — and finishes in under 30 seconds. This is the command
contributors run constantly and the one CI gates on.make integration runs the tests behind //go:build integration, booting the
wired daemon end-to-end (no real SDR) and asserting the engine, recorder, call
log, metrics, and API all agree on a synthetic call. The build tag keeps them
out of the default make test path.make integration-cc-nxdn, make integration-cc-dmr,
make integration-cc-tetra, make integration-cc-p25p2, and so on — each of
which synthesizes IQ for that protocol’s control channel and asserts the real
pipeline recovers the lock. That’s an end-to-end critical path, isolated per
protocol so a failure points right at the broken decoder.t.Parallel() are house rules. CONTRIBUTING.md
spells it out: tests are “parallel where it’s safe (t.Parallel()),
table-driven for any function with more than two interesting inputs,
t.Helper() on helper functions so failure locations surface correctly.”samples/. Known-good signal captures act
as fixtures the decoders run against — golden files for radio.make test-airspy-real sets
GOPHERTRUNK_AIRSPY_REAL=1; the package skips entirely unless that variable is
set, so the test ships in the repo but “never runs in CI,” exactly as
CONTRIBUTING.md says. Overrides like GOPHERTRUNK_AIRSPY_REAL_BIAS_TEE=1
toggle extra checks. CI runs make test, make integration, and
make test-dvsi on every PR — a green CI is required before merge.You don’t need a radio for any of this to transfer. Swap “decode a control channel” for “render an invoice” or “parse a config file”: fast unit tests as the gate, tagged integration tests for the wiring, golden files for fiddly output, and opt-in tests for whatever CI can’t reach.
How many tests is enough? Enough that you’d trust a stranger to refactor your code and find out from a failing test, not from production. That usually means solid unit coverage of your branching logic plus a few integration tests over the critical paths — not a coverage percentage you chase for its own sake.
Should I write tests before or after the code? Either works; the discipline that matters is that tests exist and run in CI. Test-first (TDD) helps when the design is unclear; test-after is fine when it isn’t. For bug fixes, always write the failing test first — it proves the bug is real and that your fix actually fixes it.
What’s the difference between a fake and a mock? A fake is a real (if simplified) working implementation you assert results against — an in-memory store, a scripted source. A mock records calls so you can assert that something was invoked. Fakes tend to produce more durable tests; heavy mocking can make tests pass while the system is broken.
How do I test something that needs hardware or a paid API?
Gate it. Make the test skip unless an environment variable or build tag opts it
in, the way GopherTrunk gates its Airspy tests behind
GOPHERTRUNK_AIRSPY_REAL=1. The test stays in the repo and runs where it can,
while CI stays fast and green.
Can Claude Code write my tests for me? It can write most of the scaffolding — table cases, edge cases, regression tests for a described bug — very well, and very fast. You still review the result and decide which cases matter. Treat it as a fast pair, not an oracle.
Part 8 of 14 · ← Part 7 · Next → Part 9: Documentation Done Right
]]>TL;DR — This is the pure-Go R820T/R828D tuner driver, built around a shadow-register cache that makes read-modify-write free. The headline bug: the RTL-SDR Blog V4 came up deaf and mistuned by ~1.8×, fixed with a crystal override plus per-band input switching. A second bug (#248) — a 17-byte I2C burst stalling on NESDR v5 — is fixed by halving the chunk size until it fits.
The R820T, R820T2, and R828D (collectively the “R82xx” family) share one I2C
register map and one PLL synthesizer. The tuner’s job is to take an RF frequency
from the antenna, mix it down to a fixed 3.57 MHz intermediate frequency, and
hand that to the RTL2832U’s ADC. So when you ask GopherTrunk to tune 154 MHz, the
tuner’s PLL doesn’t target 154 MHz — it targets 154 MHz + 3.57 MHz, and the
RTL2832U is configured (back in PrepareDemod) to expect signal at that IF
offset.
The driver is a straight port of osmocom librtlsdr’s tuner_r82xx.c — register
addresses, the init flood, the PLL math, and the frequency-range mux table are
all kept byte-identical so real-hardware captures replay-validate against the
mock USB transport. The whole driver lives in
internal/sdr/rtlsdr/tuners/r82xx.go.
The single most important design decision in the R82xx driver is the
shadow-register cache. The R82xx struct keeps a local mirror of the chip’s
registers:
// internal/sdr/rtlsdr/tuners/r82xx.go
type R82xx struct {
demod *rtl2832u.Demod
i2cAddr uint8
chipType Type
xtalHz uint32
// regs[0x05..0x1F] is the shadow for writable registers.
// regs[0x00..0x04] holds the most recently read read-only status bytes.
regs [r82xxNumRegs]byte
// ...
}
This solves a concrete hardware problem: the R820T’s writable registers can’t
be read back through the I2C bridge. Read-modify-write — “set these three bits,
leave the rest” — is impossible if you can’t read the current value. The shadow
makes it trivial, and it has a free side benefit: the chip silently drops a write
whose value matches the previous one, so eliding redundant writes saves a USB
roundtrip without changing observable behavior. Every masked write goes through
writeRegMask, which reads the shadow, applies the masked bits, and only touches
the wire if the result actually changed:
// internal/sdr/rtlsdr/tuners/r82xx.go
func (r *R82xx) writeRegMask(addr uint8, val, mask byte) error {
if addr < r82xxShadowStart {
return fmt.Errorf("r82xx writeRegMask: addr=0x%02x is read-only", addr)
}
cur := r.regs[addr]
next := (cur &^ mask) | (val & mask)
if cur == next {
return nil
}
r.regs[addr] = next
return r.writeBurstRaw(addr, []byte{next})
}
setPLL is a faithful port of r82xx_set_pll: it sweeps the mixer divider to
land the VCO inside its valid range, computes an integer + sigma-delta fractional
division, and compensates with a VCO fine-tune read back from the chip. The math
is intricate but the load-bearing detail for this post is small — the divider
sweep and the nint/vcoFra split off the reference crystal:
// internal/sdr/rtlsdr/tuners/r82xx.go (shape)
vcoFreq := uint64(freqHz) * uint64(mixDiv)
effXtal := r.effectiveXtalHz()
pllRef := uint64(effXtal)
nint := uint32(vcoFreq / (2 * pllRef))
vcoFra := uint32((vcoFreq - 2*pllRef*uint64(nint)) / 1000)
Notice effectiveXtalHz(). Every PLL division is computed off the reference
crystal. If the driver believes the crystal is 16 MHz when it’s actually 28.8
MHz, every tune is wrong by the ratio 28.8/16 = 1.8×. Hold that thought.
Before any of this runs, we have to figure out which tuner is on the board.
detect.go probes candidate I2C addresses in librtlsdr’s exact order, reading
the chip-ID byte off each. For the R82xx family that’s a 0x69 ID at address 0x34
(R820T) or 0x74 (R828D):
// internal/sdr/rtlsdr/tuners/r82xx.go
func detectR82xx(d *rtl2832u.Demod) Tuner {
for _, c := range []struct {
addr uint8
typ Type
}{
{addr: r82xxI2CAddr, typ: TypeR820T2},
{addr: r828dI2CAddr, typ: TypeR828D},
} {
out, err := d.I2CRead(c.addr, 1)
if err != nil || len(out) == 0 {
continue
}
id := r82xxBitReverse(out[0])
if id == 0x69 || id == 0x96 { // includes some bit-reversed clones
return NewR82xx(d, c.addr, c.typ)
}
}
return nil
}
The whole detection runs under a single SetI2CRepeater(true)/(false) bracket so
the bridge doesn’t flap between candidates. That detail matters more than it
looks — it sets up the second bug below.
The symptom. Plug in an RTL-SDR Blog V4 — a popular R828D-based dongle — and it would detect fine, claim its interface, accept every tune… and receive only noise. An R820T2 dongle on the exact same signal decoded cleanly. Worse, when it did seem to tune, frequencies were off by a factor of roughly 1.8.
The root cause — three of them, actually. The V4 is an R828D, and our
NewR82xx defaults every R828D to a 16 MHz crystal — which is correct for a
generic R828D. But the Blog V4 runs its R828D from the RTL2832U’s 28.8 MHz
reference crystal. There’s the 1.8× mistune, straight out of the PLL math above:
// internal/sdr/rtlsdr/tuners/r82xx.go
func NewR82xx(d *rtl2832u.Demod, i2cAddr uint8, chip Type) *R82xx {
xtal := r82xxXtalHz
if chip == TypeR828D {
xtal = r828dXtalHz // 16 MHz — wrong for the Blog V4
}
// ...
}
But fixing the crystal alone still left it deaf, because the V4 has a switched front end: an HF/VHF/UHF input bank with an on-board upconverter for HF. The stock R828D init leaves every V4 input off, so even perfectly tuned, no RF reaches the mixer. And detection can’t reliably tell a V4 from a generic R828D — the distinguishing signal is the USB iManufacturer/iProduct strings, which are sometimes blank or non-standard on real units.
The fix — three parts. First, an explicit SetBlogV4 that restores the right
crystal and arms the V4 path:
// internal/sdr/rtlsdr/tuners/r82xx.go
func (r *R82xx) SetBlogV4(lite bool) {
r.blogV4 = true
r.blogV4L = lite
r.xtalHz = r82xxXtalHz // 28.8 MHz, overriding the R828D 16 MHz default
}
Detection keys off the USB strings, but because that misses some units, the
driver also exposes a manual override all the way up at the Device level —
SetBlogV4 implements sdr.BlogV4Forcer, and the pool applies it from a config
hint before the first tune. Autodetection when it can; explicit override when it
can’t.
Second, per-band input switching. The V4 routes HF through an upconverter (so the
R828D actually sees hz + 28.8 MHz), and switches a physical input bank per band.
SetFreq adjusts the PLL target for HF and then drives the input switches:
// internal/sdr/rtlsdr/tuners/r82xx.go
target := hz
if r.blogV4 && hz <= r82xxV4HFCrossHz {
target = hz + r82xxXtalHz // HF reaches the mixer through the upconverter
}
// ...setMux(target), then:
if r.blogV4 {
if err := r.applyBlogV4Band(hz); err != nil {
return fmt.Errorf("r82xx SetFreq: v4 band: %w", err)
}
}
applyBlogV4Band drives the notch filter, the HF tracking-filter bypass, and the
HF/VHF/UHF input relays — ported verbatim from the rtlsdr-blog fork’s
r82xx_set_freq V4 block. It caches the last-selected band in a v4Band enum so
it only rewrites the input switches when the band actually changes:
// internal/sdr/rtlsdr/tuners/r82xx.go
band := v4BandFor(hz, r.blogV4L)
// HF: bypass tracking filter (re-applied every tune since setMux rewrites 0x1A/0x1B)
if band == v4BandHF { /* ...writeRegMask(0x1A,...) ... */ }
// Only rewrite the input switches on a band change.
if band == r.v4Input {
return nil
}
r.v4Input = band
// ...cable2 = HF input, GPIO5 upconverter relay, cable1 = VHF, air-in = UHF...
Third, the gain path. The V4 is a marginal-signal dongle, and there was a latent
AGC-mode bug that compounded the deafness: in AGC mode librtlsdr pins the VGA at a
fixed +16.3 dB, but SetGain is a no-op in AGC mode, so the VGA was being left at
its init default — running the front end ~17 dB low. SetGainMode now writes
the VGA in the AGC branch:
// internal/sdr/rtlsdr/tuners/r82xx.go
// AGC mode: pin the VGA at librtlsdr's fixed default (+16.3 dB).
if !manual {
if err := r.writeRegMask(0x0C, 0x0B, 0x9F); err != nil {
return err
}
}
There was even a fourth, subtler V4 issue tucked into the PLL: the rtlsdr-blog
fork lowers the VCO power reference from 2 to 1 for the R828D, and without that
the V4’s LO mistunes and receives noise while an R820T2 on the same signal
decodes cleanly. vcoPowerRef() returns 1 for TypeR828D. The V4 needed every
one of these to receive — which is exactly why it was so painful to chase.
To make the state visible, TunerDiag/IsBlogV4/XtalHz surface the effective
crystal and whether the V4 path armed, so the pool can log a boot-time line: a 16
MHz R828D means the V4 path did not arm and the LO is mistuned by 1.8×; 28.8 MHz
means SetBlogV4 ran.
The symptom. Two NESDR SMArt v5 units would fail tuner init with an EPIPE
(Linux) / ERROR_GEN_FAILURE (Windows) on the very first multi-byte I2C burst —
the 27-byte R82xx init flood. Detection succeeded; the burst write that follows it
did not.
The root cause. librtlsdr assumes the chip’s I2C-bridge FIFO can swallow a
16-byte write (NMAX_WRITES = 16). On that specific firmware revision the FIFO
depth appears to be smaller, so the 17-byte first chunk (1 address byte + 16 data
bytes) NACKs. An earlier fix added a per-chunk retry; it wasn’t enough.
The fix. writeBurstRaw halves the chunk size on a stall — 16 → 8 → 4 — until
one size succeeds:
// internal/sdr/rtlsdr/tuners/r82xx.go
func (r *R82xx) writeBurstRaw(addr uint8, data []byte) error {
var lastErr error
for chunkSize := r82xxBurstMaxData; chunkSize >= r82xxBurstMinData; chunkSize /= 2 {
err := r.writeBurstAtSize(addr, data, chunkSize)
if err == nil {
return nil
}
if !isI2CBurstStall(err) {
return err
}
lastErr = err
if chunkSize > r82xxBurstMinData {
time.Sleep(r82xxBurstRetryDelayMillis * time.Millisecond)
}
}
return fmt.Errorf("tried chunk sizes 16,8,4; all stalled: %w", lastErr)
}
Two details make this robust. The stall predicate has to be
cross-platform — the same logical stall is a raw syscall.EPIPE on Linux and a
mapped usb.ErrPipeStalled on Windows, so isI2CBurstStall checks both;
checking only EPIPE meant the whole recovery silently never fired on Windows.
And there’s a detection-side dependency: Detect deliberately toggles the I2C
repeater off before returning so that Init’s leading SetI2CRepeater(true) is
a fresh wire write — that explicit “kick” is load-bearing on NESDR v5 to arm the
bridge, even though the cache from Part 7 would otherwise elide it.
Both bugs come from the same place: real hardware deviates from the reference, and when it does, autodetection is not enough — you need explicit, observable overrides.
The Blog V4 looks like a generic R828D until it doesn’t. The NESDR v5 looks like a standard RTL-SDR until its FIFO chokes on a standard-sized write. A driver that assumes every chip matches the datasheet — or even matches librtlsdr — comes up deaf on exactly the dongles people actually buy.
SetBlogV4 / sdr.BlogV4Forcer is the manual
escape hatch for units it misses. The default path stays correct for the common
case and the override is one config hint away.IsBlogV4, XtalHz, and TunerDiag exist so a
failed override shows up as a boot-time diagnostic (“16 MHz R828D → mistuned
1.8×”) instead of a silent deaf dongle.The RTL2832U is initialized and the R82xx is tuned and locked. The only thing left is to actually move samples — to keep a 2.4 MS/s bulk-IN stream flowing without dropping IQ. Part 9 takes apart the streaming layer and the GC-churn bug that was shedding a quarter of the control channel’s live IQ.
Why does the R828D default to 16 MHz if the V4 needs 28.8?
Because a generic R828D really does run from a separate 16 MHz crystal — that
default is correct for the common case. The Blog V4 is the special case, and
SetBlogV4 is how we mark it. Defaulting to 28.8 would mistune every non-V4
R828D instead.
Why not just always chunk I2C writes at 4 bytes to dodge issue #248? Because that triples the round-trips for every tuner init on every dongle to work around one firmware revision. The halving fallback only pays the cost when a chunk actually stalls; healthy chips still write 16 bytes at a time.
Is the shadow cache ever wrong?
Only for the read-only status registers (0x00–0x04), which we refresh by reading
the chip. The writable shadow (0x05–0x1F) is authoritative because those
registers can’t be read back anyway — the shadow is the source of truth, and
Init primes it with the init-flood values before the first burst.
Part 8 of 14 · ← Part 7 · Next → Part 9: RTL-SDR III — IQ streaming & the GC-churn bug
]]>