libhackrf: Configuration of the RF hardware

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.

(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, configurabe 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 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

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, .
RF_PATH_FILTER_LOW_PASS | LPF is selected, .
RF_PATH_FILTER_HIGH_PASS | HPF is selected, .

## 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_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 | ) |

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

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

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

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

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

Possible values: 1.75, 2.5, 3.5, 5, 5.5, 6, 7, 8, 9, 10, 12, 14, 15, 20, 24, 28MHz, default 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 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
| ) |  |

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

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

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

Center frequency is set to where , 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
| ) |  |

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

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

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

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

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