How a HackRF-based SDR reference turned an unknown high bandwidth wired interface into a shared, runnable truth

Recap

In Part I, we described how we worked from undocumented RF protocols towards production. In this second part, we dive deeper into the approach we took with those same signals: building an executable spec. Using a Software Defined Radio (SDR)-based reference implementation, we transformed the real signal into a shared, runnable truth that aligned hardware, firmware, and software teams from ideation through production. This “living spec” enabled parallel development, made integration a confirmation rather than a discovery, and dramatically cut rework—delivering the program faster, smoother, and with greater confidence.

What Changed

  • Early Resolution: Unknowns were moved to the front of the program and resolved in software first.
  • Parallel Workstreams: Hardware, firmware, and software teams worked in parallel against the same decoded messages and golden captures.
  • Predictable Integration: Integration became a confirmation process, not a discovery of new problems.
  • Future-Proofing: The spec persisted as a risk-mitigation tool for future product variants.

Context and Challenge

The client’s product depended on a high-speed, proprietary wired link with poor documentation. Development teams faced significant challenges:

  • Long Lead Times: Physical components like circuit boards, FPGA images, and test rigs had long lead times, creating bottlenecks.
  • Field Variability: Signal behavior varied by device, manufacturing lot, and environmental conditions, threatening costly late-stage surprises.
  • Ineffective Documentation: Prior attempts to document the protocol produced static slides and assumptions, not an executable reality.

Our goal was to deliver a repeatable way to discover the true signaling behavior early, keep teams moving in parallel, and avoid late-stage redesigns.

Our Thesis: Make the Spec Executable

A traditional written specification is static and ambiguous. An executable spec, in contrast, is a small, runnable system that ingests real signal captures and outputs decoded, structured messages that the entire program can trust. We realized this vision using a HackRF One and a lightweight interface fixture, wrapping the entire decode process into a simple, one-command tool that any engineer could run.

Why the HackRF One?

  • Rapid Deployment: It’s fast to bring up, easy to script, and widely supported.
  • Fit for Purpose: It was “good enough” for discovery and building a reference decoder.
  • Cost-Effective: It’s an inexpensive tool that pays for itself if it prevents a single late-stage design change.

The Reference Implementation

The core of our solution was the reference implementation, a software-based “black box” that provided a single source of truth:

  • Inputs: It ingested live data from the HackRF or “golden capture” files representing real devices and conditions.
  • Core Logic: A robust decoding pipeline that reflected the signal’s actual behavior, including rates, framing, and basic protocols.
  • Outputs: Structured, actionable messages (JSON/UDP) that hardware, firmware, and software teams could consume identically.
  • Lifecycle: The spec was versioned in git, and Continuous Integration (CI) pipelines ran regression tests on golden captures, ensuring the decode logic remained consistent.

This living, runnable artifact was the key to aligning all teams.

How the Spec Accelerates Each Discipline

By providing an executable spec, we enabled each engineering discipline to move forward with a shared, proven truth, rather than with assumptions.

  • Hardware: Engineers could choose the right front-end and clocking components based on real, observed signal behavior, not guesswork. They could exercise early lab prototypes by replaying captures with known-good decodes, dramatically reducing the risk of surprise board spins.
  • Firmware / FPGA: Firmware and FPGA engineers implemented blocks that the spec had already validated. Their work became a matter of comparing their bit-for-bit output against the spec, making deviations obvious and easy to localize.
  • Application / Backend: Software teams could begin integrating against replayed traffic from day one, even before physical hardware was ready. They built monitoring, logging, and analytics on the same message schema that would eventually ship, maintaining velocity while hardware evolves.
  • Test / QA: QA treated the spec as the ultimate acceptance oracle. They could codify test scenarios as capture-driven tests, pin CI to golden captures to prevent regressions, and shorten failure triage by using “spec vs. device” diffs to pinpoint the fault domain.

Visualizing the Lifecycle — With and Without the Executable Spec

The diagrams below highlight the transformative impact of our approach.

Figure 1 — Traditional Flow (Written Spec)

In the traditional flow, work advances in a long, single file. Hardware starts on assumptions, firmware waits for boards, and software waits for “something that talks.” Unknowns ride the schedule until a critical integration phase, where they emerge as expensive surprises. The risk curve climbs through bring-up and spikes as assumptions are replaced by reality.

Figure 2 — Executable Spec Flow (HackRF Reference)

The HackRF-based executable spec starts at ideation and runs beside solution exploration. It captures real signals, decodes them in software, and produces shared messages and replays for all disciplines. Hardware designs with measured behaviour, firmware targets a bit-exact reference, and software integrates against golden replays from day one. Integration becomes a simple confirmation, and the risk curve drops early and stays low because every observation is re-playable and validated against the same living spec.

The first diagram reads like a relay race with long handoffs and late rework. The second shows overlapping lanes guided by a common, runnable artifact. The entire program is faster and calmer because uncertainty is converted to code and data early.

Technologies & Tools We Used

Our implementation combined off-the-shelf SDR hardware, open-source frameworks, and lightweight infrastructure.

  • HackRF One: A flexible, affordable software-defined radio that served as the foundation of our executable spec.
  • Custom PCBs for Signal Mating: Lightweight interface boards that safely adapted the wired signals for the HackRF.
  • SoapySDR: A hardware abstraction layer that provided portability.
  • GNU Radio: An open-source DSP framework for building the reference decoder.
  • Python: The glue for everything, powering scripting, automation, and testing.
  • Qt: Used to build lightweight UIs for signal visualization.
  • GitHub: The source of truth for the reference, code, and captures, with CI ensuring consistency.

These mature, open-source tools provided a safe, fast foundation for building the executable spec.

Outcomes That Matter to Leaders

  • Time-to-Truth: We achieved the first decoded message in days, not weeks.
  • Overlapped Workstreams: Software and test teams could begin their work before physical boards arrived.
  • Predictable Integration: Integration became a non-event, with fewer crisis reviews.
  • Avoided Rework: Issues surfaced in software, not at costly hardware verification stages (EVT/DVT).
  • Institutionalized Knowledge: The truth lives in code and captures, not in static slides or personal notes.

Risks, Trade-Offs, and How We Handled Them

  • Not One-Size-Fits-All: The principles of an executable spec are universal, but the implementation must be tailored to the specific product and its complexity.
  • Up-front Effort: We managed this risk by keeping the spec small and modular, assigning a dedicated maintainer, and tying it to a CI pipeline to prevent “bit rot.”
  • SDR ≠ Product Hardware: We clearly documented the known deltas between the reference and the final product hardware to prevent conflating the two.
  • Change Control: The spec was managed in Git with code reviews, versioned releases, and a clear changelog.

Mastering Precision Alignment

Turning the signal into an executable spec—realized with a HackRF-based reference—changed the character of our client’s delivery. We replaced ambiguity with a shared, runnable artifact, aligned the entire program around evidence, and turned integration into a non-event.

At Better Devices, we help companies achieve exactly this: smoother hardware/firmware/software programs, fewer late surprises, and faster, calmer delivery. If you’re facing undocumented signals, high-bandwidth protocols, or integration risks, we can help you turn uncertainty into an executable spec.

Get in touch and let’s explore how we can de-risk your next product together.