Field Guide · technology

Also known as: libhackrf, HackRF library

libhackrf is the host-side C library that drives the HackRF One, the wide-band half-duplex transceiver from Great Scott Gadgets, streaming signed 8-bit IQ samples between the computer and the radio over USB.1 It is the thin driver layer every HackRF application ultimately calls, whether to receive, transmit, or reflash the device firmware.

application libhackrf HackRF One RX or TX callback USB (libusb) half-duplex: receive or transmit, not both
libhackrf exposes the HackRF One through an asynchronous callback: one buffer of 8-bit IQ per transfer, in the receive direction or the transmit direction, since the hardware is half-duplex.

How it works

After hackrf_init and hackrf_open, an application configures the radio through a uniform setter interface: hackrf_set_freq (1 MHz–6 GHz), hackrf_set_sample_rate (up to 20 MS/s), and a three-stage gain chain — the RF amp (a fixed ~11 dB LNA), the IF/LNA gain, and the baseband VGA gain — plus the antenna-port bias tee. The MAX2837/MAX5864 analog front end delivers signed 8-bit I and Q, a wider dynamic range than the RTL-SDR’s unsigned bytes but still only 8 bits, which is the HackRF’s main sample-format trade-off.

Streaming uses an asynchronous callback. For receive, hackrf_start_rx takes a callback that libhackrf invokes with each filled libusb transfer buffer; for transmit, hackrf_start_tx invokes a callback that the application fills. This inverts control in the classic callback-versus-stream way: the library drives the clock and the app must service each buffer promptly or drop samples. Crucially, the HackRF is half-duplex — it can receive or transmit but not simultaneously — so an application runs one direction at a time and calls hackrf_stop_rx/hackrf_stop_tx to switch.

In practice

The library ships with command-line tools built on top of it: hackrf_transfer (record IQ to a file or replay it out the air), hackrf_info, hackrf_sweep (a fast spectrum sweep across the whole 6 GHz range), and hackrf_spiflash/hackrf_cpldjtag for firmware updates. Higher layers wrap it rather than reimplement it: gr-osmosdr provides a GNU Radio source/sink, and SoapySDR exposes a SoapyHackRF plugin so cross-vendor applications reach the device through a common API. Because it uses libusb, the same library works on Linux, macOS, and Windows.

Relevance to SDR

libhackrf matters because the HackRF One is the accessible entry point to transmit-capable SDR and to very wide instantaneous bandwidth (20 MHz), and this library is how software reaches those capabilities. For anyone writing SDR software it is a compact example of a bidirectional host driver: the same asynchronous buffer contract serves both the RX and TX data paths, with the half-duplex constraint enforced by the API rather than assumed.

GopherTrunk is a receive-only trunking decoder and has no transmit path, so it uses only the RX side of hardware like this. As a pure-Go program it does not link the C libhackrf directly; it ingests IQ over network transports or from recorded IQ files. The producer/consumer shape is identical to libhackrf’s RX callback, though — buffers of 8-bit IQ arrive, GT converts them to complex baseband and runs its decode chain — so the wideband capture a HackRF provides is exactly the kind of input GT’s channelizer is built to split into multiple decoded channels.

Sources

  1. HackRF repository and documentation — Great Scott Gadgets, the source for libhackrf, the host API, and the hackrf_transfer/hackrf_sweep tools. ↩

See also