libbladeRF  1.7.2
Nuand bladeRF library
Data Structures | Macros | Enumerations | Functions
Frequency tuning

Description

These functions provide the ability to tune the RX and TX modules.

See this page for more detailed information about how the API performs this tuning, and for example code snippets.

These functions are thread-safe.

Data Structures

struct  bladerf_quick_tune
 

Macros

#define BLADERF_FREQUENCY_MIN_XB200   0u
 
#define BLADERF_FREQUENCY_MIN   237500000u
 
#define BLADERF_FREQUENCY_MAX   3800000000u
 
#define BLADERF_RETUNE_NOW   0
 

Enumerations

enum  bladerf_tuning_mode { BLADERF_TUNING_MODE_INVALID = -1, BLADERF_TUNING_MODE_HOST, BLADERF_TUNING_MODE_FPGA }
 

Functions

API_EXPORT int CALL_CONV bladerf_select_band (struct bladerf *dev, bladerf_module module, unsigned int frequency)
 
API_EXPORT int CALL_CONV bladerf_set_frequency (struct bladerf *dev, bladerf_module module, unsigned int frequency)
 
API_EXPORT int CALL_CONV bladerf_schedule_retune (struct bladerf *dev, bladerf_module module, uint64_t timestamp, unsigned int frequency, struct bladerf_quick_tune *quick_tune)
 
API_EXPORT int CALL_CONV bladerf_cancel_scheduled_retunes (struct bladerf *dev, bladerf_module module)
 
API_EXPORT int CALL_CONV bladerf_get_frequency (struct bladerf *dev, bladerf_module module, unsigned int *frequency)
 
API_EXPORT int CALL_CONV bladerf_get_quick_tune (struct bladerf *dev, bladerf_module module, struct bladerf_quick_tune *quick_tune)
 
API_EXPORT int CALL_CONV bladerf_set_tuning_mode (struct bladerf *dev, bladerf_tuning_mode mode)
 

Macro Definition Documentation

#define BLADERF_FREQUENCY_MAX   3800000000u

Maximum tunable frequency, in Hz

Definition at line 1053 of file libbladeRF.h.

#define BLADERF_FREQUENCY_MIN   237500000u

Minimum tunable frequency (without an XB-200 attached), in Hz

Definition at line 1050 of file libbladeRF.h.

#define BLADERF_FREQUENCY_MIN_XB200   0u

Minimum tunable frequency (with an XB-200 attached), in HZ.

While this value is the lowest permitted, note that the components on the XB-200 are only rated down to 50 MHz. Be aware that performance will likely degrade as you tune to lower frequencies.

Definition at line 1047 of file libbladeRF.h.

#define BLADERF_RETUNE_NOW   0

Specifies that scheduled retune should occur immediately when using bladerf_schedule_retune().

Definition at line 1059 of file libbladeRF.h.

Enumeration Type Documentation

Frequency tuning modes

BLADERF_TUNING_MODE_HOST is the default if either of the following conditions are true:

  • libbladeRF < v1.3.0
  • FPGA < v0.2.0

BLADERF_TUNING_MODE_FPGA is the default if both of the following conditions are true:

  • libbladeRF >= v1.3.0
  • FPGA >= v0.2.0

The default mode can be overridden by setting a BLADERF_DEFAULT_TUNING_MODE environment variable to "host" or "fpga". Overriding this value with a mode not supported by the FPGA will result in failures or unexpected behavior.

Enumerator
BLADERF_TUNING_MODE_INVALID 

Indicates an invalid mode is set

BLADERF_TUNING_MODE_HOST 

Perform tuning algorithm on the host. This is slower, but provides easier accessiblity to diagnostic information.

BLADERF_TUNING_MODE_FPGA 

Perform tuning algorithm on the FPGA for faster tuning.

Definition at line 1078 of file libbladeRF.h.

Function Documentation

API_EXPORT int CALL_CONV bladerf_cancel_scheduled_retunes ( struct bladerf *  dev,
bladerf_module  module 
)

Cancel all pending scheduled retune operations for the specified module.

This will be done automatically during bladerf_close() to ensure that previously queued retunes do not continue to occur after closing and then later re-opening a device.

Parameters
devDevice handle
moduleModule to cancel pending operations on
Returns
0 on success, value from Error codes list on failure.
API_EXPORT int CALL_CONV bladerf_get_frequency ( struct bladerf *  dev,
bladerf_module  module,
unsigned int *  frequency 
)

Get module's current frequency in Hz

Parameters
devDevice handle
moduleModule to configure
frequencyPointer to the returned frequency
Returns
0 on success, value from Error codes list on failure
API_EXPORT int CALL_CONV bladerf_get_quick_tune ( struct bladerf *  dev,
bladerf_module  module,
struct bladerf_quick_tune quick_tune 
)

Fetch parameters used to tune the transceiver to the current frequency for use with bladerf_schedule_retune() to perform a "quick retune."

This allows for a faster retune, with a potential trade off of increased phase noise. Note that these parameters are sensitive to changes in the operating environment, and should be "refreshed" if planning to use the "quick retune" functionality over a long period of time.

Precondition
bladerf_set_frequency() or bladerf_schedule_retune() have previously been used to retune to the desired frequency.
Parameters
[in]devDevice handle
[in]moduleModule to query
[out]quick_tuneQuick retune parameters
Returns
0 on success, value from Error codes list on failure
API_EXPORT int CALL_CONV bladerf_schedule_retune ( struct bladerf *  dev,
bladerf_module  module,
uint64_t  timestamp,
unsigned int  frequency,
struct bladerf_quick_tune quick_tune 
)

Schedule a frequency retune to occur at specified sample timestamp value.

Precondition
bladerf_sync_config() must have been called with the BLADERF_FORMAT_SC16_Q11_META format for the associated module in order to enable timestamps. (The timestamped metadata format must be enabled in order to use this function.)
Parameters
devDevice handle
moduleModule to retune
timestampModule's sample timestamp to perform the retune operation. If this value is in the past, the retune will occur immediately. To perform the retune immediately, specify BLADERF_RETUNE_NOW.
frequencyDesired frequency, in Hz.
quick_tuneIf NULL, the frequency parameter will be used. If non-NULL, the provided "quick retune" values will be applied to the transceiver to tune it according to a previous state retrieved via bladerf_get_quick_tune().
Returns
0 on success, value from Error codes list on failure. If the underlying queue of scheduled retune requests becomes full, BLADERF_ERR_QUEUE_FULL will be returned. In this case, it should be possible to schedule a retune after the timestamp of one of the earlier requests occurs.
API_EXPORT int CALL_CONV bladerf_select_band ( struct bladerf *  dev,
bladerf_module  module,
unsigned int  frequency 
)

Select the appropriate band path given a frequency in Hz.

Most API users will not need to use this function, as bladerf_set_frequency() calls this internally after tuning the device.

The high band (LNA2 and PA2) is used for frequency >= 1.5 GHz. Otherwise, The low band (LNA1 and PA1) is used.

Frequency values outside the range of [ BLADERF_FREQUENCY_MIN, BLADERF_FREQUENCY_MAX ] will be clamped.

Parameters
devDevice handle
moduleModule to configure
frequencyTuned frequency
Returns
0 on success, value from Error codes list on failure
API_EXPORT int CALL_CONV bladerf_set_frequency ( struct bladerf *  dev,
bladerf_module  module,
unsigned int  frequency 
)

Set module's frequency in Hz.

Values outside the range of [ BLADERF_FREQUENCY_MIN, BLADERF_FREQUENCY_MAX ] will be clamped.

For best results, it is recommended to keep the RX and TX frequencies at least 1 MHz apart, and to digitally mix on the RX side if reception closer to the TX frequency is required.

This calls bladerf_select_band() internally.

Parameters
devDevice handle
moduleModule to configure
frequencyDesired frequency
Returns
0 on success, value from Error codes list on failure
API_EXPORT int CALL_CONV bladerf_set_tuning_mode ( struct bladerf *  dev,
bladerf_tuning_mode  mode 
)

Set the device's tuning mode

Parameters
devDevice handle
modeDesired tuning mode. Note that the available modes depends on the FPGA version.
Returns
0 on success, value from Error codes list on failure