libhackrf
HackRF SDR platform library
Enumerations | Functions
Configuration of the RF hardware

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. More...
 
int hackrf_set_freq (hackrf_device *device, const uint64_t freq_hz)
 Set the center frequency. More...
 
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. More...
 
int hackrf_set_sample_rate_manual (hackrf_device *device, const uint32_t freq_hz, const uint32_t divider)
 Set sample rate explicitly. More...
 
int hackrf_set_sample_rate (hackrf_device *device, const double freq_hz)
 Set sample rate. More...
 
int hackrf_set_amp_enable (hackrf_device *device, const uint8_t value)
 Enable/disable 14dB RF amplifier. More...
 
int hackrf_set_lna_gain (hackrf_device *device, uint32_t value)
 Set LNA gain. More...
 
int hackrf_set_vga_gain (hackrf_device *device, uint32_t value)
 Set baseband RX gain of the MAX2837 transceier IC ("BB" or "VGA" gain setting) in decibels. More...
 
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. More...
 
int hackrf_set_antenna_enable (hackrf_device *device, const uint8_t value)
 Enable / disable bias-tee (antenna port power) More...
 
const char * hackrf_filter_path_name (const enum rf_path_filter path)
 Convert rf_path_filter into human-readable string. More...
 
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. More...
 
uint32_t hackrf_compute_baseband_filter_bw (const uint32_t bandwidth_hz)
 Compute nearest valid baseband filter bandwidth to specified value. More...
 
int hackrf_set_clkout_enable (hackrf_device *device, const uint8_t value)
 Enable / disable CLKOUT. More...
 
int hackrf_get_clkin_status (hackrf_device *device, uint8_t *status)
 Get CLKIN status. More...
 

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

TX path

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 automatially 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 separatlely.

Enumeration Type Documentation

◆ 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)

The result can be used via hackrf_set_baseband_filter_bandwidth

Parameters
bandwidth_hzdesired 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)

The result can be used via hackrf_set_baseband_filter_bandwidth

Parameters
bandwidth_hzdesired 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)
Parameters
pathenum to convert
Returns
human-readable name of filter path

◆ hackrf_get_clkin_status()

int hackrf_get_clkin_status ( hackrf_device device,
uint8_t *  status 
)

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

Requires USB API version 0x0106 or above!

Parameters
[in]devicedevice to read status from
[out]statusexternal 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 
)

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

Parameters
devicedevice to configure
valueenable (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 
)

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
devicedevice to configure
valueenable (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 
)

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
devicedevice to configure
bandwidth_hzbaseband 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 
)

Requires USB API version 0x0103 or above!

Parameters
devicedevice to configure
valueclock 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 
)

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 quariable in the future.

Parameters
devicedevice to tune
freq_hzcenter 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 
)

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
devicedevice to tune
if_freq_hztuning frequency of the MAX2837 transceiver IC in Hz. Must be in the range of 2150-2750MHz
lo_freq_hztuning 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
pathfilter 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 
)

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
devicedevice to configure
valueRX 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 
)

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
devicedevice to configure
freq_hzsample 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 
)

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
devicedevice to configure
freq_hzsample rate base frequency in Hz
dividerfrequency 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 
)

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

Parameters
devicedevice to configure
valueTX 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 
)

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

Parameters
devicedevice to configure
valueRX BB gain value in dB
Returns
HACKRF_SUCCESS on success or hackrf_error variant