Configuring gain, sample rate, filter bandwidth, etc. More...

Enumerations
enum	rf_path_filter { RF_PATH_FILTER_BYPASS = 0 , RF_PATH_FILTER_LOW_PASS = 1 , RF_PATH_FILTER_HIGH_PASS = 2 }
	RF filter path setting enum. More...

Functions
int	hackrf_set_baseband_filter_bandwidth (hackrf_device *device, const uint32_t bandwidth_hz)
	Set baseband filter bandwidth.

int	hackrf_set_freq (hackrf_device *device, const uint64_t freq_hz)
	Set the center frequency.

int	hackrf_set_freq_explicit (hackrf_device *device, const uint64_t if_freq_hz, const uint64_t lo_freq_hz, const enum rf_path_filter path)
	Set the center frequency via explicit tuning.

int	hackrf_set_sample_rate_manual (hackrf_device *device, const uint32_t freq_hz, const uint32_t divider)
	Set sample rate explicitly.

int	hackrf_set_sample_rate (hackrf_device *device, const double freq_hz)
	Set sample rate.

int	hackrf_set_amp_enable (hackrf_device *device, const uint8_t value)
	Enable/disable 14dB RF amplifier.

int	hackrf_set_lna_gain (hackrf_device *device, uint32_t value)
	Set LNA gain.

int	hackrf_set_vga_gain (hackrf_device *device, uint32_t value)
	Set baseband RX gain of the MAX2837 transceiver IC ("BB" or "VGA" gain setting) in decibels.

int	hackrf_set_txvga_gain (hackrf_device *device, uint32_t value)
	Set RF TX gain of the MAX2837 transceiver IC ("IF" or "VGA" gain setting) in decibels.

int	hackrf_set_antenna_enable (hackrf_device *device, const uint8_t value)
	Enable / disable bias-tee (antenna port power)

const char *	hackrf_filter_path_name (const enum rf_path_filter path)
	Convert rf_path_filter into human-readable string.

uint32_t	hackrf_compute_baseband_filter_bw_round_down_lt (const uint32_t bandwidth_hz)
	Compute nearest valid baseband filter bandwidth lower than a specified value.

uint32_t	hackrf_compute_baseband_filter_bw (const uint32_t bandwidth_hz)
	Compute nearest valid baseband filter bandwidth to specified value.

int	hackrf_set_clkout_enable (hackrf_device *device, const uint8_t value)
	Enable / disable CLKOUT.

int	hackrf_get_clkin_status (hackrf_device device, uint8_t status)
	Get CLKIN status.

Detailed Description

Amplifiers and gains

There are 5 different amplifiers in the HackRF One. Most of them have variable gain, but some of them can be either enabled / disabled. Please note that most of the gain settings are not precise, and they depend on the used frequency as well.

hackrf components

(image taken from https://hackrf.readthedocs.io/en/latest/hardware_components.html)

RX path

baseband gain in the MAX2837 ("BB" or "VGA") - 0-62dB in 2dB steps, configurable via the hackrf_set_vga_gain function
RX IF gain in the MAX2837 ("IF") - 0-40dB with 8dB steps, configurable via the hackrf_set_lna_gain function
RX RF amplifier near the antenna port ("RF") - 0 or ~11dB, either enabled or disabled via the hackrf_set_amp_enable (same function is used for enabling/disabling the TX RF amp in TX mode)

TX path

TX IF gain in the MAX2837 ("IF" or "VGA") - 0-47dB in 1dB steps, configurable via hackrf_set_txvga_gain
TX RF amplifier near the antenna port ("RF") - 0 or ~11dB, either enabled or disabled via the hackrf_set_amp_enable (same function is used for enabling/disabling the RX RF amp in RX mode)

Tuning

The HackRF One can tune to nearly any frequency between 1-6000MHz (and the theoretical limit is even a bit higher). This is achieved via up/downconverting the RF section of the MAX2837 transceiver IC with the RFFC5072 mixer/synthesizer's local oscillator. The mixer produces the sum and difference frequencies of the IF and LO frequencies, and a LPF or HPF filter can be used to select one of the resulting frequencies. There is also the possibility to bypass the filter and use the IF as-is. The IF and LO frequencies can be programmed independently, and the behaviour is selectable. See the function hackrf_set_freq_explicit for more details on it.

There is also the convenience function hackrf_set_freq that automatically select suitable LO and IF frequencies and RF path for a desired frequency. It should be used in most cases.

Filtering

The MAX2837 has an internal selectable baseband filter for both RX and TX. Its width can be set via hackrf_set_baseband_filter_bandwidth, but only some values are valid. Valid values can be acquired via the functions hackrf_compute_baseband_filter_bw_round_down_lt and hackrf_compute_baseband_filter_bw.

NOTE in order to avoid aliasing, the bandwidth should not exceed the sample rate. As a sensible default, the firmware auto-sets the baseband filter bandwidth to a value $\le 0.75 \cdot F_s$ whenever the sample rate is changed, thus setting a custom value should be done after setting the samplerate.

Sample rate

The sample rate of the ADC/DAC can be set between 2-20MHz via hackrf_set_sample_rate or hackrf_set_sample_rate_manual. This also automatically adjusts the baseband filter bandwidth to a suitable value.

Clocking

The HackRF one has external clock input and clock output connectors for 10MHz 3.3V clock signals. It automatically switches to the external clock if it's detected, and its status is readable with hackrf_get_clkin_status. The external clock can be enabled by the hackrf_set_clkout_enable function.

Bias-tee

The HackRF one has a built in bias-tee (also called (antenna) port power in some of the documentation) capable of delivering 50mA@3V3 for powering small powered antennas or amplifiers. It can be enabled via the hackrf_set_antenna_enable function. Please note that when the device is returning to IDLE mode, the firmware automatically disables this feature. This means it can't be enabled permanently like with the RTL-SDR, and all software using the HackRF must enable this separately.

Enumeration Type Documentation

◆ rf_path_filter

enum rf_path_filter

Used only when performing explicit tuning using hackrf_set_freq_explicit, or can be converted into a human readable string using hackrf_filter_path_name. This can select the image rejection filter (U3, U8 or none) to use - using switches U5, U6, U9 and U11. When no filter is selected, the mixer itself is bypassed.

Enumerator
RF_PATH_FILTER_BYPASS	No filter is selected, the mixer is bypassed, $f_{center} = f_{IF}$ .
RF_PATH_FILTER_LOW_PASS	LPF is selected, $f_{center} = f_{IF} - f_{LO}$ .
RF_PATH_FILTER_HIGH_PASS	HPF is selected, $f_{center} = f_{IF} + f_{LO}$ .

Function Documentation

◆ hackrf_compute_baseband_filter_bw()

uint32_t hackrf_compute_baseband_filter_bw ( const uint32_t bandwidth_hz )

extern

The result can be used via hackrf_set_baseband_filter_bandwidth

Parameters

bandwidth_hz desired filter bandwidth in Hz

Returns: nearest valid filter bandwidth in Hz

◆ hackrf_compute_baseband_filter_bw_round_down_lt()

uint32_t hackrf_compute_baseband_filter_bw_round_down_lt ( const uint32_t bandwidth_hz )

extern

The result can be used via hackrf_set_baseband_filter_bandwidth

Parameters

bandwidth_hz desired filter bandwidth in Hz

Returns: the highest valid filter bandwidth lower than bandwidth_hz in Hz

◆ hackrf_filter_path_name()

const char * hackrf_filter_path_name ( const enum rf_path_filter path )

extern

Parameters

path	enum to convert

Returns: human-readable name of filter path

◆ hackrf_get_clkin_status()

int hackrf_get_clkin_status	(	hackrf_device *	device,
		uint8_t *	status
	)

extern

Check if an external clock signal is detected on the CLKIN port.

Requires USB API version 0x0106 or above!

Parameters

[in]	device	device to read status from
[out]	status	external clock detected (0/1)

Returns: HACKRF_SUCCESS on success or hackrf_error variant

◆ hackrf_set_amp_enable()

int hackrf_set_amp_enable	(	hackrf_device *	device,
		const uint8_t	value
	)

extern

Enable / disable the ~11dB RF RX/TX amplifiers U13/U25 via controlling switches U9 and U14.

Parameters

device	device to configure
value	enable (1) or disable (0) amplifier

Returns: HACKRF_SUCCESS on success or hackrf_error variant

◆ hackrf_set_antenna_enable()

int hackrf_set_antenna_enable	(	hackrf_device *	device,
		const uint8_t	value
	)

extern

Enable or disable the 3.3V (max 50mA) bias-tee (antenna port power). Defaults to disabled.

NOTE: the firmware auto-disables this after returning to IDLE mode, so a perma-set is not possible, which means all software supporting HackRF devices must support enabling bias-tee, as setting it externally is not possible like it is with RTL-SDR for example.

Parameters

device	device to configure
value	enable (1) or disable (0) bias-tee

Returns: HACKRF_SUCCESS on success or hackrf_error variant

◆ hackrf_set_baseband_filter_bandwidth()

int hackrf_set_baseband_filter_bandwidth	(	hackrf_device *	device,
		const uint32_t	bandwidth_hz
	)

extern

Possible values: 1.75, 2.5, 3.5, 5, 5.5, 6, 7, 8, 9, 10, 12, 14, 15, 20, 24, 28MHz, default $\le 0.75 \cdot F_s$ The functions hackrf_compute_baseband_filter_bw and hackrf_compute_baseband_filter_bw_round_down_lt can be used to get a valid value nearest to a given value.

Setting the sample rate causes the filter bandwidth to be (re)set to its default $\le 0.75 \cdot F_s$ value, so setting sample rate should be done before setting filter bandwidth.

Parameters

device	device to configure
bandwidth_hz	baseband filter bandwidth in Hz

Returns: HACKRF_SUCCESS on success or hackrf_error variant

◆ hackrf_set_clkout_enable()

int hackrf_set_clkout_enable	(	hackrf_device *	device,
		const uint8_t	value
	)

extern

Requires USB API version 0x0103 or above!

Parameters

device	device to configure
value	clock output enabled (0/1)

Returns: HACKRF_SUCCESS on success or hackrf_error variant

◆ hackrf_set_freq()

int hackrf_set_freq	(	hackrf_device *	device,
		const uint64_t	freq_hz
	)

extern

Simple (auto) tuning via specifying a center frequency in Hz

This setting is not exact and depends on the PLL settings. Exact resolution is not determined, but the actual tuned frequency will be queryable in the future.

Parameters

device	device to tune
freq_hz	center frequency in Hz. Defaults to 900MHz. Should be in range 1-6000MHz, but 0-7250MHz is possible. The resolution is ~50Hz, I could not find the exact number.

Returns: HACKRF_SUCCESS on success or hackrf_error variant

◆ hackrf_set_freq_explicit()

int hackrf_set_freq_explicit	(	hackrf_device *	device,
		const uint64_t	if_freq_hz,
		const uint64_t	lo_freq_hz,
		const enum rf_path_filter	path
	)

extern

Center frequency is set to $f_{center} = f_{IF} + k\cdot f_{LO}$ where $k\in\left\{-1; 0; 1\right\}$ , depending on the value of path. See the documentation of rf_path_filter for details

Parameters

device	device to tune
if_freq_hz	tuning frequency of the MAX2837 transceiver IC in Hz. Must be in the range of 2150-2750MHz
lo_freq_hz	tuning frequency of the RFFC5072 mixer/synthesizer IC in Hz. Must be in the range 84.375-5400MHz, defaults to 1000MHz. No effect if `path` is set to RF_PATH_FILTER_BYPASS
path	filter path for mixer. See the documentation for rf_path_filter for details

Returns: HACKRF_SUCCESS on success or hackrf_error variant

◆ hackrf_set_lna_gain()

int hackrf_set_lna_gain	(	hackrf_device *	device,
		uint32_t	value
	)

extern

Set the RF RX gain of the MAX2837 transceiver IC ("IF" gain setting) in decibels. Must be in range 0-40dB, with 8dB steps.

Parameters

device	device to configure
value	RX IF gain value in dB

Returns: HACKRF_SUCCESS on success or hackrf_error variant

◆ hackrf_set_sample_rate()

int hackrf_set_sample_rate	(	hackrf_device *	device,
		const double	freq_hz
	)

extern

Sample rate should be in the range 2-20MHz, with the default being 10MHz. Lower & higher values are technically possible, but the performance is not guaranteed. This function also sets the baseband filter bandwidth to a value $\le 0.75 \cdot F_s$ , so any calls to hackrf_set_baseband_filter_bandwidth should only be made after this.

Parameters

device	device to configure
freq_hz	sample rate frequency in Hz. Should be in the range 2-20MHz

Returns: HACKRF_SUCCESS on success or hackrf_error variant

◆ hackrf_set_sample_rate_manual()

int hackrf_set_sample_rate_manual	(	hackrf_device *	device,
		const uint32_t	freq_hz,
		const uint32_t	divider
	)

extern

Sample rate should be in the range 2-20MHz, with the default being 10MHz. Lower & higher values are technically possible, but the performance is not guaranteed.

This function sets the sample rate by specifying a clock frequency in Hz and a divider, so the resulting sample rate will be freq_hz / divider. This function also sets the baseband filter bandwidth to a value $\le 0.75 \cdot F_s$ , so any calls to hackrf_set_baseband_filter_bandwidth should only be made after this.

Parameters

device	device to configure
freq_hz	sample rate base frequency in Hz
divider	frequency divider. Must be in the range 1-31

Returns: HACKRF_SUCCESS on success or hackrf_error variant

◆ hackrf_set_txvga_gain()

int hackrf_set_txvga_gain	(	hackrf_device *	device,
		uint32_t	value
	)

extern

Must be in range 0-47dB in 1dB steps.

Parameters

device	device to configure
value	TX IF gain value in dB

Returns: HACKRF_SUCCESS on success or hackrf_error variant

◆ hackrf_set_vga_gain()

int hackrf_set_vga_gain	(	hackrf_device *	device,
		uint32_t	value
	)

extern

Must be in range 0-62dB with 2dB steps.

Parameters

device	device to configure
value	RX BB gain value in dB

Returns: HACKRF_SUCCESS on success or hackrf_error variant

Enumerations

Functions

Detailed Description

Amplifiers and gains

RX path

TX path

Tuning

Filtering

Sample rate

Clocking

Bias-tee

Enumeration Type Documentation

◆ rf_path_filter

Function Documentation

◆ hackrf_compute_baseband_filter_bw()

◆ hackrf_compute_baseband_filter_bw_round_down_lt()

◆ hackrf_filter_path_name()

◆ hackrf_get_clkin_status()

◆ hackrf_set_amp_enable()

◆ hackrf_set_antenna_enable()

◆ hackrf_set_baseband_filter_bandwidth()

◆ hackrf_set_clkout_enable()

◆ hackrf_set_freq()

◆ hackrf_set_freq_explicit()

◆ hackrf_set_lna_gain()

◆ hackrf_set_sample_rate()

◆ hackrf_set_sample_rate_manual()

◆ hackrf_set_txvga_gain()

◆ hackrf_set_vga_gain()