Wiki › Devices

HackRF One

HackRF One is the app's main receiver: spectrum and waterfall from 1 MHz to 6 GHz at sample rates of 2–20 MS/s, a hardware sweep over the whole range, listening, IQ recording and a test-signal transmitter. This page explains how to assign the WinUSB driver to the device once, what every item of the Source group on the Device tab does, which loss counters live there and where the app says outright that it does not know the state of the device.

What works with a HackRF One

• Spectrum and waterfall between 1 MHz and 6 GHz. The instantaneous bandwidth equals the sample rate: 2, 4, 8, 10, 12.5, 16 or 20 MS/s.
• Hardware sweep. A range wider than 20 MHz is stepped through by the device itself, segment by segment; the full 1–6000 MHz range is stitched from hundreds of segments and one pass takes about 0.6–0.7 s. When an RBW is set, the sweep rate follows it 0.9.36: the app takes the widest rate at which the frame for that RBW fits into the block in which the device delivers its sweep (2 kHz — 10 MS/s, 1 kHz — 4 MS/s, 500 Hz — 2 MS/s). A lower rate means a longer pass, and the Resolution bandwidth group says in a line by how many times (a calculation); this has not yet been checked on a live device. Details are on the Sweep page.
• Listening and FPV video — see Receiver and FPV video.
• IQ recording in the device's own cs8 format with a SigMF sidecar — see IQ recording.
• Transmitter for test signals — see Transmitter.

Right after connecting, the device sits at 2255 MHz with a sample rate of 10 MS/s, LNA gain 32 dB and VGA gain 36 dB 0.9.25, the input amplifier and the bias tee off. The device controls are not saved between launches: every session starts from these values.

Levels from a HackRF One are shown in dBFS, that is relative to the full scale of the ADC, not in calibrated dBm. The dBFS — UNCAL badge on the trust bar is a permanent reminder.

The WinUSB driver: once, with Zadig

The app installs no drivers. It drives a HackRF One through the bundled libhackrf library over the WinUSB driver that is already part of Windows. That driver has to be assigned to the device once with the Zadig tool; after that the app opens the device by itself.

1. Connect the HackRF One with a USB cable that has data lines. To the app, a charge-only cable looks exactly like a missing device.
2. Run Zadig and select the HackRF One in it. In its own messages the app refers to this device by the USB identifier VID_1D50&PID_6089.
3. Assign the WinUSB driver to the selected device.
4. Unplug the USB cable and plug it in again.
5. In the app's start window press Refresh. The device row should appear with its serial number.

Connecting in the start window

After launch the Select a receiver window opens. Every HackRF One found is listed as a row of the form “HackRF One — serial number”. Pick the row and press Connect (or Enter). A device held by another program is listed too, but without a serial number: HackRF One — serial number unavailable (in use by another program, or no driver).

If the device cannot be opened, the app does not quit: it shows the Could not open the source window with the cause and the advice, and returns to the list. Once the cause is removed, press Refresh, then Connect — no restart needed.

The “Source” group on the “Device” tab

The Device tab (Ctrl+4) consists of three groups: Source, Record and Host. Everything that concerns the HackRF itself is in the first one. Most items have a “?” circle next to them — hover over it to read the explanation.

Readouts

Type

Where the samples come from. For a HackRF One it reads hackrf.

Sample rate

The current sample rate. It is also the instantaneous receive bandwidth.

Center

The local oscillator frequency. The DC spike sits exactly on it — see below.

Instrument

A “board · firmware” line read from the device. Green while the stream runs; yellow when it does not. At the very bottom of the group, in small type, is the full description: board, firmware, USB API version, serial number and libhackrf version.

Instrument sample rate

The Instrument sample rate list offers 2, 4, 8, 10, 12.5, 16 and 20 MS/s. A higher rate means a wider instantaneous bandwidth, but also more bytes over the USB bus. The mouse wheel over the spectrum does the same: as you narrow the span, the app takes the narrowest rate that still holds it. There is no rate below 2 MS/s; beyond that, Ctrl+wheel only stretches the picture.

Changing the rate resets the accumulated traces. The app sets the device's baseband filter by itself to suit the chosen rate; there is no separate control for it. The rate does not change during a recording — the app refuses with the Sample rate not changed: recording in progress window 0.9.25, because all samples of one recording must share one rate. The same applies during transmission.

Gain

LNA (RF)

Gain before the mixer, 0–40 dB in 8 dB steps; 32 dB by default 0.9.25. Add gain here first: it lifts the signal above the noise of the receive chain. If the noise floor jumps or ghost peaks appear, that is overload — and this is also where to reduce it.

VGA (IF)

Intermediate-frequency gain, 0–62 dB in 2 dB steps; 36 dB by default 0.9.25. It only stretches what is already there, noise included: the signal-to-noise ratio does not improve.

AMP +14 dB

The input amplifier; off by default. It acts on the whole range at once, before the filters: in a city it is easily overloaded by strong nearby transmitters and produces peaks that are not on the air.

Bias-tee

Feeds power into the antenna connector; off by default. Enable it only with a load that expects it (an external amplifier, a converter), not with an ordinary antenna; see the device's documentation for the voltage. On a board without this circuit the switch is disabled and labelled Bias-tee — not on this board 0.9.25.

Total gain

LNA + VGA, plus 14 dB when AMP is on. This is what was actually applied in the device, not what was requested: the firmware rounds in-between values down, which is why the sliders also show the result rather than the request.

After a gain change the level scale re-fits itself to the measured levels. The scale itself is covered on the Scale, auto scale and waterfall page.

Unconfirmed gain 0.9.25

The HackRF firmware writes a new gain value before it answers. If the answer does not arrive over USB, the app does not know which value is in the device now — the old one or the new one. It does not guess:

• the slider label becomes LNA (RF) ? or VGA (IF) ?, and the slider itself stays on the last confirmed value;
• Total gain shows unknown: LNA not confirmed (naming the stages concerned);
• the spur passport and the frequency response are not taken in this state — the measurement would match no known state of the device.

To clear the uncertainty, set the same stage again: the first successful write makes it known again. The input amplifier can also become unconfirmed after a transmission or a sweep — then the Receive amplifier not confirmed window appears, advising you to toggle AMP once more. While transmitting, the AMP switch on this tab writes nothing to the device: the same amplifier then serves the transmitter, and the receive value is applied after the transmission stops.

Pause, “Back to live”, “Reconnect”

Pause / Resume

Stops the processing of the stream (same as Space): the picture freezes, the audio goes silent and a recording gets a gap. USB traffic does not stop: samples keep arriving and are discarded, and their count is shown in the Discarded while paused row.

Back to live

Returns the waterfall from scrolled-back history to the present moment (L).

Reconnect

Stops the stream, closes the device, opens it again and starts the stream; a sweep that was running is brought back up, and the traces start accumulating from scratch. It is also the button to press after the cable was pulled and put back: the app does not crash on that.

Loss counters

In the Source group the losses are shown separately, because they are different faults with different causes.

Ring buffer (drops)

Samples that arrived from the device but that the app did not take out of its buffer in time. Above zero it turns red. This is a shortage of computer speed: a lower sample rate and the settings on the Performance page help.

Lost in transit

Samples lost between the device and the app, with the share in per cent. The driver does not report them, so this is an estimate from the clock: how many samples should have arrived in the last two seconds and how many did. A deficit below 0.05 % is shown as zero — below that limit a loss cannot be told apart from oscillator error. Yellow means losses have occurred; red means more than 0.1 % of the stream is being lost right now.

Discarded while paused

Appears when there was something to discard during a pause. That is your decision, not a fault, so the number is not red; but the gap is in the recording too.

Ring buffer fill

How much of the app's source buffer is occupied. Above 70 % it turns yellow: the app is barely keeping up, and drops will follow.

Samples taken before a retune to another frequency are discarded on purpose and are not counted as drops: they belong to another band. Losses during a recording have their own rows in the Record group; all the levels together are explained on the Trust bar and loss counters page.

USB advice while running

When Lost in transit turns red, an explanation appears under the counters: the samples are lost above the app, which is why the ring buffer counter shows zero. Try a lower sample rate or another USB port with no neighbours on the same controller.

A USB transfer of odd length is no longer taken as it is 0.9.36: the extra byte is dropped and the place is marked as a break — no spectrum frame is built across it, and a recording gets a mark. The Source group then shows the yellow line USB transfers of odd length: N with the advice: if the spectrum became mirrored, press Reconnect. Whether such transfers happen on a real device is not known.

If the traffic breaks off in the middle of work, the app stops the stream and shows the Device connection lost window. The advice in it 0.9.25 is written for a running device: check the cable and the USB port (preferably without a hub) and press Reconnect. Another program or Zadig is not the issue here: a device opened through WinUSB cannot be taken by another program.

When the state of the device is unknown 0.9.25

A HackRF One is half-duplex: it either receives or transmits, and a sweep and a transmission cannot run at the same time. On the transitions between these modes the app checks whether the device really came back, and says so if it did not.

The device's own signals

Not everything visible on a HackRF spectrum came from the antenna. The app marks what originates in the device itself.

• The DC spike. Exactly at the centre of the band there is a peak — local oscillator leakage and the DC component of the mixer. On the plot it carries the DC mark. The DC filter in the Resolution bandwidth group (auto, on, off) removes the DC component; the mark then becomes DC− but does not disappear: the noise around it remains, and a real signal exactly on the tuned frequency is removed together with the device's offset. To look at a signal under the spike, shift the receive centre.
• Fixed spurs. Harmonics of the reference oscillator sit at fixed frequencies. They are captured by the Passport — a measurement without an antenna, after which those bins are marked as the device's own; on a HackRF that is about 2000 frequencies.
• Spurs that move with the local oscillator. In a sweep these are searched for by the Spurs check: the app shifts the edges of a pass by whole megahertz and looks at what moved together with the oscillator.
• Overload. In a sweep the app counts the segments where the ADC is saturated and reports them in the Resolution bandwidth group: the levels there are not a measurement but clipping products.

In the author's measurement on his device, 66 of the 83 lines above 30 dB in a sweep were products of the local oscillator with harmonics of the 40 MHz reference oscillator, and the rest were those harmonics themselves. How to use the passport and the spur check is described on the Detection marks and the spur passport page.

Limits

• Levels are in dBFS. The app has no amplitude calibration for a HackRF One; only a tinySA gives dBm.
• The device is half-duplex: during a transmission there is no reception, so a recording receives no samples and a sweep cannot be started.
• The device's sample rate, frequency and gains are not saved between launches.
• The device is chosen at start-up. To move to another device, to a recording or to the demo signal, the app has to be restarted.
• The behaviour on traffic failures — unconfirmed gains, failed exits from a sweep or a transmission — has been checked against a simulated driver, not against real hardware faults.

The common list of the app's limits is on the Limits and roadmap page.

The wiki describes version 0.9.49. Your app's version is shown in the Help menu, under About. Found a mistake? Write to us.